Agent Zero AI framework
Add file-level DOX docs & update AGENTS indexes
frdele138e33ca998
diff --git a/agents/AGENTS.md b/agents/AGENTS.mdindex cce3cbc96..d2df985b1 100644--- a/agents/AGENTS.md+++ b/agents/AGENTS.md@@ -31,4 +31,13 @@## Child DOX Index-No child DOX files.+Direct child DOX files:++| Child | Scope |+| --- | --- |+| [_example/AGENTS.md](_example/AGENTS.md) | Reference profile demonstrating profile-local prompts, tools, and extensions. |+| [agent0/AGENTS.md](agent0/AGENTS.md) | Main user-facing Agent Zero profile metadata. |+| [default/AGENTS.md](default/AGENTS.md) | Base profile metadata and inherited prompt specifics. |+| [developer/AGENTS.md](developer/AGENTS.md) | Software development specialist profile. |+| [hacker/AGENTS.md](hacker/AGENTS.md) | Cyber security and penetration testing specialist profile. |+| [researcher/AGENTS.md](researcher/AGENTS.md) | Research, data analysis, and reporting specialist profile. |diff --git a/agents/_example/AGENTS.md b/agents/_example/AGENTS.mdnew file mode 100644index 000000000..555428ee6--- /dev/null+++ b/agents/_example/AGENTS.md@@ -0,0 +1,33 @@+# Example Agent Profile DOX++## Purpose++- Own the reference profile used to demonstrate bundled profile layout.+- Show how profile-local prompts, tools, and extensions fit beside `agent.yaml`.++## Ownership++- `agent.yaml` owns the example profile metadata.+- `prompts/` owns prompt override examples.+- `tools/` owns profile-local tool examples.+- `extensions/` owns profile-local lifecycle extension examples.++## Local Contracts++- Keep this profile generic, minimal, and safe to copy into user or plugin profile work.+- Do not add product behavior here that should live in a real bundled profile.+- Profile-local tools and extensions must follow the same contracts as root tools and extensions.++## Work Guidance++- Prefer simple examples that illustrate structure over complex behavior.+- Update related skill guidance when the example profile layout changes.++## Verification++- Manually inspect YAML and prompt filenames after edits.+- Run profile-loading tests when changing discovery or profile schema assumptions.++## Child DOX Index++No child DOX files.diff --git a/agents/agent0/AGENTS.md b/agents/agent0/AGENTS.mdnew file mode 100644index 000000000..65528190a--- /dev/null+++ b/agents/agent0/AGENTS.md@@ -0,0 +1,31 @@+# Agent 0 Profile DOX++## Purpose++- Own the main user-facing Agent Zero profile metadata.+- Keep the primary assistant profile discoverable and distinct from subordinate specialist profiles.++## Ownership++- `agent.yaml` owns the profile title, description, and delegation context.+- Prompt behavior is inherited from the default profile unless a local prompt override is added.++## Local Contracts++- Keep `Agent 0` suitable as the direct conversation agent for the system.+- Do not add narrow specialist behavior that belongs in `developer/`, `researcher/`, `hacker/`, or a custom user profile.+- Do not store user-specific preferences, provider settings, or secrets in this profile.++## Work Guidance++- Keep metadata concise because it appears in profile selection and delegation contexts.+- Coordinate substantial behavior changes with default prompts and WebUI profile selection.++## Verification++- Manually inspect `agent.yaml` for valid YAML after edits.+- Run profile-loading tests when changing schema or discovery behavior.++## Child DOX Index++No child DOX files.diff --git a/agents/default/AGENTS.md b/agents/default/AGENTS.mdnew file mode 100644index 000000000..130d84cc1--- /dev/null+++ b/agents/default/AGENTS.md@@ -0,0 +1,32 @@+# Default Agent Profile DOX++## Purpose++- Own base profile metadata and default prompt specifics inherited by specialized profiles.+- Provide the shared behavior layer for bundled and custom profiles.++## Ownership++- `agent.yaml` owns default profile metadata.+- `agent.system.main.specifics.md` owns default profile-specific system prompt content.+- Additional prompt overrides under this directory become shared defaults unless a child profile overrides them.++## Local Contracts++- Keep default behavior broad, framework-compatible, and safe for inheritance.+- Avoid role-specific instructions that belong in specialist profiles.+- Prompt filenames must match the framework prompt override names they target.++## Work Guidance++- Prefer small, explicit prompt changes with clear inheritance impact.+- Check bundled specialist profiles after changing default behavior.++## Verification++- Manually inspect YAML and prompt rendering assumptions after edits.+- Run prompt/profile tests when changing inherited prompt behavior.++## Child DOX Index++No child DOX files.diff --git a/agents/developer/AGENTS.md b/agents/developer/AGENTS.mdnew file mode 100644index 000000000..b2d189fff--- /dev/null+++ b/agents/developer/AGENTS.md@@ -0,0 +1,32 @@+# Developer Agent Profile DOX++## Purpose++- Own the bundled software development specialist profile.+- Keep development, debugging, refactoring, and architecture behavior separate from general agent defaults.++## Ownership++- `agent.yaml` owns title, description, and delegation context for software development work.+- `prompts/` owns developer-specific prompt overrides when present.+- `extensions/` owns developer-specific lifecycle hooks when present.++## Local Contracts++- Keep this profile focused on software engineering tasks.+- Do not hardcode repository-local credentials, paths, or project-specific conventions.+- Prompt overrides must preserve the framework tool-call and response contracts.++## Work Guidance++- Align developer behavior with the root engineering and tool contracts.+- Prefer profile prompt edits over core prompt edits when the behavior is specific to development tasks.++## Verification++- Manually inspect `agent.yaml` for valid YAML after edits.+- Run prompt/profile tests when changing profile loading or developer prompt behavior.++## Child DOX Index++No child DOX files.diff --git a/agents/hacker/AGENTS.md b/agents/hacker/AGENTS.mdnew file mode 100644index 000000000..9daeaed00--- /dev/null+++ b/agents/hacker/AGENTS.md@@ -0,0 +1,31 @@+# Hacker Agent Profile DOX++## Purpose++- Own the bundled cyber security and penetration testing specialist profile.+- Keep security-audit behavior scoped to this profile instead of default agent behavior.++## Ownership++- `agent.yaml` owns title, description, and delegation context for security work.+- `prompts/` owns security-specific prompt overrides when present.++## Local Contracts++- Keep the profile focused on authorized security analysis, vulnerability research, and defensive audit tasks.+- Do not add secrets, target-specific credentials, or local environment assumptions.+- Preserve the framework tool-call contract and safety expectations.++## Work Guidance++- Keep security instructions operational and bounded to legitimate testing contexts.+- Coordinate broad safety changes with core prompts and relevant tests.++## Verification++- Manually inspect `agent.yaml` for valid YAML after edits.+- Run prompt/profile tests when changing profile discovery or security prompt behavior.++## Child DOX Index++No child DOX files.diff --git a/agents/researcher/AGENTS.md b/agents/researcher/AGENTS.mdnew file mode 100644index 000000000..e6ba59c70--- /dev/null+++ b/agents/researcher/AGENTS.md@@ -0,0 +1,31 @@+# Researcher Agent Profile DOX++## Purpose++- Own the bundled research, data analysis, and reporting specialist profile.+- Keep evidence-gathering and report-oriented behavior separate from general defaults.++## Ownership++- `agent.yaml` owns title, description, and delegation context for research work.+- `prompts/` owns researcher-specific prompt overrides when present.++## Local Contracts++- Keep this profile focused on information gathering, analysis, synthesis, and reporting.+- Do not bake in project-specific sources, credentials, or local paths.+- Preserve the framework tool-call and response contracts.++## Work Guidance++- Prefer prompt changes that improve citation, evidence handling, and analysis quality for research tasks.+- Coordinate broad research behavior changes with document, memory, or browser plugin contracts when relevant.++## Verification++- Manually inspect `agent.yaml` for valid YAML after edits.+- Run prompt/profile tests when changing discovery or researcher prompt behavior.++## Child DOX Index++No child DOX files.diff --git a/api/AGENTS.md b/api/AGENTS.mdindex 7e471b399..02344d435 100644--- a/api/AGENTS.md+++ b/api/AGENTS.md@@ -19,17 +19,23 @@- Keep CSRF and authentication protections intact for browser-facing state-changing endpoints.- WebSocket handlers must derive from `helpers.ws.WsHandler` and validate event data before using it.- Do not return secrets, raw environment values, private files, or unfiltered exception details to clients.+- This directory is a file-documented DOX profile: every direct `*.py` endpoint or WebSocket 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 endpoint purpose, request/response concepts, auth/CSRF/API-key/loopback assumptions, side effects, important helper dependencies, and verification guidance.+- When a Python endpoint 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 endpoint deletion or rename.## Work Guidance- Use helpers for shared behavior instead of duplicating persistence, auth, file, project, plugin, or notification logic in endpoints.- Keep request and response payloads stable; update frontend callers and tests together when payloads change.- Prefer `Response` for files, redirects, status codes, and plain-text errors; return dictionaries for JSON success payloads.+- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed endpoint behavior is described there.## Verification- Run targeted `pytest tests/test_*api*.py`, endpoint-specific tests, or WebSocket tests after changing handler behavior.- For auth, CSRF, upload/download, tunnel, or file endpoints, run the nearest security regression tests.+- Check file-level documentation coverage with a script or shell loop that verifies each `api/*.py` has a matching `api/*.py.dox.md`.## Child DOX Indexdiff --git a/api/agent_profile_set.py.dox.md b/api/agent_profile_set.py.dox.mdnew file mode 100644index 000000000..845ee9b1d--- /dev/null+++ b/api/agent_profile_set.py.dox.md@@ -0,0 +1,46 @@+# agent_profile_set.py DOX++## Purpose++- Own the `agent_profile_set.py` API endpoint.+- This module sets the active agent profile for a chat context and returns profile label metadata.+- Keep this file-level DOX profile synchronized with `agent_profile_set.py` because this directory is intentionally flat.++## Ownership++- `agent_profile_set.py` owns the runtime implementation.+- `agent_profile_set.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SetAgentProfile` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`+- Top-level functions:+- `_agent_profile_labels() -> dict[str, str]`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SetAgentProfile` is an `ApiHandler`.+- `SetAgentProfile` defines `process(...)`.+- Observed side-effect areas: filesystem writes, settings/state persistence.+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.persist_chat`, `helpers.state_monitor_integration`, `initialize`.++## Key Concepts++- Important called helpers/classes observed in the source: `str.strip`, `context.is_running`, `_agent_profile_labels`, `initialize_agent`, `save_tmp_chat`, `mark_dirty_for_context`, `subagents.get_all_agents_list`, `Response`, `agent.get_data`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/agents.py.dox.md b/api/agents.py.dox.mdnew file mode 100644index 000000000..e7f6895ac--- /dev/null+++ b/api/agents.py.dox.md@@ -0,0 +1,48 @@+# agents.py DOX++## Purpose++- Own the `agents.py` API endpoint.+- This module lists available agent profiles for selection and delegation UI flows.+- Keep this file-level DOX profile synchronized with `agents.py` because this directory is intentionally flat.++## Ownership++- `agents.py` owns the runtime implementation.+- `agents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Agents` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Agents` is an `ApiHandler`.+- `Agents` defines `process(...)`.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `subagents.get_all_agents_list`, `Exception`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_default_prompt_budget.py`+ - `tests/test_office_document_store.py`+ - `tests/test_projects.py`+ - `tests/test_skills_runtime.py`+ - `tests/test_time_travel.py`++## Child DOX Index++No child DOX files.diff --git a/api/api_files_get.py.dox.md b/api/api_files_get.py.dox.mdnew file mode 100644index 000000000..c14bf9f13--- /dev/null+++ b/api/api_files_get.py.dox.md@@ -0,0 +1,52 @@+# api_files_get.py DOX++## Purpose++- Own the `api_files_get.py` API endpoint.+- This module returns downloadable or inspectable files exposed through the external API surface.+- Keep this file-level DOX profile synchronized with `api_files_get.py` because this directory is intentionally flat.++## Ownership++- `api_files_get.py` owns the runtime implementation.+- `api_files_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `ApiFilesGet` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_csrf(cls) -> bool`+ - `requires_api_key(cls) -> bool`+ - `get_methods(cls) -> list[str]`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `ApiFilesGet` is an `ApiHandler`.+- `ApiFilesGet` defines `process(...)`.+- `ApiFilesGet` defines `get_methods(...)`.+- `ApiFilesGet` defines `requires_auth(...)`.+- `ApiFilesGet` defines `requires_csrf(...)`.+- `ApiFilesGet` defines `requires_api_key(...)`.+- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence.+- Imported dependency areas include: `base64`, `helpers`, `helpers.api`, `helpers.print_style`, `json`, `os`.++## Key Concepts++- Important called helpers/classes observed in the source: `Response`, `PrintStyle.error`, `path.startswith`, `PrintStyle`, `json.dumps`, `path.replace`, `files.get_abs_path`, `os.path.basename`, `os.path.exists`, `PrintStyle.warning`, `f.read`, `base64.b64encode.decode`, `base64.b64encode`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/api_log_get.py.dox.md b/api/api_log_get.py.dox.mdnew file mode 100644index 000000000..043a9c9cf--- /dev/null+++ b/api/api_log_get.py.dox.md@@ -0,0 +1,52 @@+# api_log_get.py DOX++## Purpose++- Own the `api_log_get.py` API endpoint.+- This module returns API/chat log data for external API clients.+- Keep this file-level DOX profile synchronized with `api_log_get.py` because this directory is intentionally flat.++## Ownership++- `api_log_get.py` owns the runtime implementation.+- `api_log_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `ApiLogGet` (`ApiHandler`)+ - `get_methods(cls) -> list[str]`+ - `requires_auth(cls) -> bool`+ - `requires_csrf(cls) -> bool`+ - `requires_api_key(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `ApiLogGet` is an `ApiHandler`.+- `ApiLogGet` defines `process(...)`.+- `ApiLogGet` defines `get_methods(...)`.+- `ApiLogGet` defines `requires_auth(...)`.+- `ApiLogGet` defines `requires_csrf(...)`.+- `ApiLogGet` defines `requires_api_key(...)`.+- Observed side-effect areas: settings/state persistence, secret handling.+- Imported dependency areas include: `agent`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `AgentContext.use`, `Response`, `context.log.output`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/api_message.py.dox.md b/api/api_message.py.dox.mdnew file mode 100644index 000000000..646939cad--- /dev/null+++ b/api/api_message.py.dox.md@@ -0,0 +1,51 @@+# api_message.py DOX++## Purpose++- Own the `api_message.py` API endpoint.+- This module accepts external API messages and dispatches them into Agent Zero chat processing.+- Keep this file-level DOX profile synchronized with `api_message.py` because this directory is intentionally flat.++## Ownership++- `api_message.py` owns the runtime implementation.+- `api_message.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `ApiMessage` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_csrf(cls) -> bool`+ - `requires_api_key(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `ApiMessage` is an `ApiHandler`.+- `ApiMessage` defines `process(...)`.+- `ApiMessage` defines `requires_auth(...)`.+- `ApiMessage` defines `requires_csrf(...)`.+- `ApiMessage` defines `requires_api_key(...)`.+- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, secret handling, scheduler state.+- Imported dependency areas include: `agent`, `base64`, `datetime`, `helpers`, `helpers.api`, `helpers.print_style`, `helpers.projects`, `helpers.security`, `initialize`, `os`, `uuid`.++## Key Concepts++- Important called helpers/classes observed in the source: `context.set_data`, `datetime.now`, `Response`, `files.get_abs_path`, `os.makedirs`, `AgentContext.use`, `context.get_data`, `initialize_agent`, `AgentContext`, `context.log.log`, `context.communicate`, `ValueError`, `uuid.uuid4`, `UserMessage`, `task.result`, `PrintStyle.error`, `safe_filename`, `base64.b64decode`, `os.path.join`, `activate_project`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_api_chat_lifetime.py`++## Child DOX Index++No child DOX files.diff --git a/api/api_reset_chat.py.dox.md b/api/api_reset_chat.py.dox.mdnew file mode 100644index 000000000..5120f46cd--- /dev/null+++ b/api/api_reset_chat.py.dox.md@@ -0,0 +1,52 @@+# api_reset_chat.py DOX++## Purpose++- Own the `api_reset_chat.py` API endpoint.+- This module resets an API-created chat context.+- Keep this file-level DOX profile synchronized with `api_reset_chat.py` because this directory is intentionally flat.++## Ownership++- `api_reset_chat.py` owns the runtime implementation.+- `api_reset_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `ApiResetChat` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_csrf(cls) -> bool`+ - `requires_api_key(cls) -> bool`+ - `get_methods(cls) -> list[str]`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `ApiResetChat` is an `ApiHandler`.+- `ApiResetChat` defines `process(...)`.+- `ApiResetChat` defines `get_methods(...)`.+- `ApiResetChat` defines `requires_auth(...)`.+- `ApiResetChat` defines `requires_csrf(...)`.+- `ApiResetChat` defines `requires_api_key(...)`.+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence.+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.print_style`, `json`.++## Key Concepts++- Important called helpers/classes observed in the source: `AgentContext.use`, `context.reset`, `persist_chat.save_tmp_chat`, `persist_chat.remove_msg_files`, `Response`, `PrintStyle.error`, `PrintStyle`, `json.dumps`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/api_terminate_chat.py.dox.md b/api/api_terminate_chat.py.dox.mdnew file mode 100644index 000000000..541a6d007--- /dev/null+++ b/api/api_terminate_chat.py.dox.md@@ -0,0 +1,52 @@+# api_terminate_chat.py DOX++## Purpose++- Own the `api_terminate_chat.py` API endpoint.+- This module terminates an API-created chat context.+- Keep this file-level DOX profile synchronized with `api_terminate_chat.py` because this directory is intentionally flat.++## Ownership++- `api_terminate_chat.py` owns the runtime implementation.+- `api_terminate_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `ApiTerminateChat` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_csrf(cls) -> bool`+ - `requires_api_key(cls) -> bool`+ - `get_methods(cls) -> list[str]`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `ApiTerminateChat` is an `ApiHandler`.+- `ApiTerminateChat` defines `process(...)`.+- `ApiTerminateChat` defines `get_methods(...)`.+- `ApiTerminateChat` defines `requires_auth(...)`.+- `ApiTerminateChat` defines `requires_csrf(...)`.+- `ApiTerminateChat` defines `requires_api_key(...)`.+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence.+- Imported dependency areas include: `agent`, `helpers.api`, `helpers.persist_chat`, `helpers.print_style`, `json`.++## Key Concepts++- Important called helpers/classes observed in the source: `AgentContext.use`, `AgentContext.remove`, `remove_chat`, `Response`, `PrintStyle.error`, `PrintStyle`, `json.dumps`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/backup_create.py.dox.md b/api/backup_create.py.dox.mdnew file mode 100644index 000000000..be6076326--- /dev/null+++ b/api/backup_create.py.dox.md@@ -0,0 +1,49 @@+# backup_create.py DOX++## Purpose++- Own the `backup_create.py` API endpoint.+- This module handles backup create requests.+- Keep this file-level DOX profile synchronized with `backup_create.py` because this directory is intentionally flat.++## Ownership++- `backup_create.py` owns the runtime implementation.+- `backup_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `BackupCreate` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_loopback(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `BackupCreate` is an `ApiHandler`.+- `BackupCreate` defines `process(...)`.+- `BackupCreate` defines `requires_auth(...)`.+- `BackupCreate` defines `requires_loopback(...)`.+- Observed side-effect areas: filesystem writes.+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `helpers.persist_chat`.++## Key Concepts++- Important called helpers/classes observed in the source: `save_tmp_chats`, `BackupService`, `send_file`, `backup_service.create_backup`, `line.strip`, `line.startswith`, `patterns_string.split`, `line.strip.startswith`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_download_toast_regressions.py`++## Child DOX Index++No child DOX files.diff --git a/api/backup_get_defaults.py.dox.md b/api/backup_get_defaults.py.dox.mdnew file mode 100644index 000000000..8f2c1966d--- /dev/null+++ b/api/backup_get_defaults.py.dox.md@@ -0,0 +1,47 @@+# backup_get_defaults.py DOX++## Purpose++- Own the `backup_get_defaults.py` API endpoint.+- This module handles backup get defaults requests.+- Keep this file-level DOX profile synchronized with `backup_get_defaults.py` because this directory is intentionally flat.++## Ownership++- `backup_get_defaults.py` owns the runtime implementation.+- `backup_get_defaults.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `BackupGetDefaults` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_loopback(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `BackupGetDefaults` is an `ApiHandler`.+- `BackupGetDefaults` defines `process(...)`.+- `BackupGetDefaults` defines `requires_auth(...)`.+- `BackupGetDefaults` defines `requires_loopback(...)`.+- Imported dependency areas include: `helpers.api`, `helpers.backup`.++## Key Concepts++- Important called helpers/classes observed in the source: `BackupService`, `backup_service.get_default_backup_metadata`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/backup_inspect.py.dox.md b/api/backup_inspect.py.dox.mdnew file mode 100644index 000000000..363dd63dc--- /dev/null+++ b/api/backup_inspect.py.dox.md@@ -0,0 +1,47 @@+# backup_inspect.py DOX++## Purpose++- Own the `backup_inspect.py` API endpoint.+- This module handles backup inspect requests.+- Keep this file-level DOX profile synchronized with `backup_inspect.py` because this directory is intentionally flat.++## Ownership++- `backup_inspect.py` owns the runtime implementation.+- `backup_inspect.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `BackupInspect` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_loopback(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `BackupInspect` is an `ApiHandler`.+- `BackupInspect` defines `process(...)`.+- `BackupInspect` defines `requires_auth(...)`.+- `BackupInspect` defines `requires_loopback(...)`.+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `werkzeug.datastructures`.++## Key Concepts++- Important called helpers/classes observed in the source: `BackupService`, `backup_service.inspect_backup`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/backup_preview_grouped.py.dox.md b/api/backup_preview_grouped.py.dox.mdnew file mode 100644index 000000000..24e075981--- /dev/null+++ b/api/backup_preview_grouped.py.dox.md@@ -0,0 +1,47 @@+# backup_preview_grouped.py DOX++## Purpose++- Own the `backup_preview_grouped.py` API endpoint.+- This module handles backup preview grouped requests.+- Keep this file-level DOX profile synchronized with `backup_preview_grouped.py` because this directory is intentionally flat.++## Ownership++- `backup_preview_grouped.py` owns the runtime implementation.+- `backup_preview_grouped.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `BackupPreviewGrouped` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_loopback(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `BackupPreviewGrouped` is an `ApiHandler`.+- `BackupPreviewGrouped` defines `process(...)`.+- `BackupPreviewGrouped` defines `requires_auth(...)`.+- `BackupPreviewGrouped` defines `requires_loopback(...)`.+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `BackupService`, `search_filter.strip`, `backup_service.test_patterns`, `search_filter.lower`, `path.strip.split`, `line.strip`, `line.startswith`, `groups.add`, `patterns_string.split`, `path.strip`, `join`, `f.lower`, `line.strip.startswith`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/backup_restore.py.dox.md b/api/backup_restore.py.dox.mdnew file mode 100644index 000000000..78e74737d--- /dev/null+++ b/api/backup_restore.py.dox.md@@ -0,0 +1,49 @@+# backup_restore.py DOX++## Purpose++- Own the `backup_restore.py` API endpoint.+- This module handles backup restore requests.+- Keep this file-level DOX profile synchronized with `backup_restore.py` because this directory is intentionally flat.++## Ownership++- `backup_restore.py` owns the runtime implementation.+- `backup_restore.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `BackupRestore` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_loopback(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `BackupRestore` is an `ApiHandler`.+- `BackupRestore` defines `process(...)`.+- `BackupRestore` defines `requires_auth(...)`.+- `BackupRestore` defines `requires_loopback(...)`.+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence.+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `helpers.persist_chat`, `json`, `werkzeug.datastructures`.++## Key Concepts++- Important called helpers/classes observed in the source: `request.form.get.lower`, `json.loads`, `BackupService`, `load_tmp_chats`, `backup_service.restore_backup`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_self_update_tag_filter.py`++## Child DOX Index++No child DOX files.diff --git a/api/backup_restore_preview.py.dox.md b/api/backup_restore_preview.py.dox.mdnew file mode 100644index 000000000..572473a0a--- /dev/null+++ b/api/backup_restore_preview.py.dox.md@@ -0,0 +1,48 @@+# backup_restore_preview.py DOX++## Purpose++- Own the `backup_restore_preview.py` API endpoint.+- This module handles backup restore preview requests.+- Keep this file-level DOX profile synchronized with `backup_restore_preview.py` because this directory is intentionally flat.++## Ownership++- `backup_restore_preview.py` owns the runtime implementation.+- `backup_restore_preview.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `BackupRestorePreview` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_loopback(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `BackupRestorePreview` is an `ApiHandler`.+- `BackupRestorePreview` defines `process(...)`.+- `BackupRestorePreview` defines `requires_auth(...)`.+- `BackupRestorePreview` defines `requires_loopback(...)`.+- Observed side-effect areas: filesystem deletion, settings/state persistence.+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `json`, `werkzeug.datastructures`.++## Key Concepts++- Important called helpers/classes observed in the source: `request.form.get.lower`, `json.loads`, `BackupService`, `backup_service.preview_restore`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/backup_test.py.dox.md b/api/backup_test.py.dox.mdnew file mode 100644index 000000000..c5f01a155--- /dev/null+++ b/api/backup_test.py.dox.md@@ -0,0 +1,47 @@+# backup_test.py DOX++## Purpose++- Own the `backup_test.py` API endpoint.+- This module handles backup test requests.+- Keep this file-level DOX profile synchronized with `backup_test.py` because this directory is intentionally flat.++## Ownership++- `backup_test.py` owns the runtime implementation.+- `backup_test.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `BackupTest` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_loopback(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `BackupTest` is an `ApiHandler`.+- `BackupTest` defines `process(...)`.+- `BackupTest` defines `requires_auth(...)`.+- `BackupTest` defines `requires_loopback(...)`.+- Imported dependency areas include: `helpers.api`, `helpers.backup`.++## Key Concepts++- Important called helpers/classes observed in the source: `BackupService`, `backup_service.test_patterns`, `line.strip`, `line.startswith`, `patterns_string.split`, `line.strip.startswith`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/banners.py.dox.md b/api/banners.py.dox.mdnew file mode 100644index 000000000..9d007e7d5--- /dev/null+++ b/api/banners.py.dox.md@@ -0,0 +1,46 @@+# banners.py DOX++## Purpose++- Own the `banners.py` API endpoint.+- This module collects alert banners and discovery cards from backend extensions.+- Keep this file-level DOX profile synchronized with `banners.py` because this directory is intentionally flat.++## Ownership++- `banners.py` owns the runtime implementation.+- `banners.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `GetBanners` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `GetBanners` is an `ApiHandler`.+- `GetBanners` defines `process(...)`.+- Imported dependency areas include: `helpers.api`, `helpers.extension`.++## Key Concepts++- Important called helpers/classes observed in the source: `call_extensions_async`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_model_config_api_keys.py`+ - `tests/test_oauth_static.py`+ - `tests/test_webui_extension_surfaces.py`++## Child DOX Index++No child DOX files.diff --git a/api/cache_reset.py.dox.md b/api/cache_reset.py.dox.mdnew file mode 100644index 000000000..a7164d5d5--- /dev/null+++ b/api/cache_reset.py.dox.md@@ -0,0 +1,53 @@+# cache_reset.py DOX++## Purpose++- Own the `cache_reset.py` API endpoint.+- This module handles cache reset API requests.+- Keep this file-level DOX profile synchronized with `cache_reset.py` because this directory is intentionally flat.++## Ownership++- `cache_reset.py` owns the runtime implementation.+- `cache_reset.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `CacheReset` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_csrf(cls) -> bool`+ - `requires_api_key(cls) -> bool`+ - `requires_loopback(cls) -> bool`+ - `get_methods(cls) -> list[str]`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `CacheReset` is an `ApiHandler`.+- `CacheReset` defines `process(...)`.+- `CacheReset` defines `get_methods(...)`.+- `CacheReset` defines `requires_auth(...)`.+- `CacheReset` defines `requires_csrf(...)`.+- `CacheReset` defines `requires_api_key(...)`.+- `CacheReset` defines `requires_loopback(...)`.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `cache.clear_all`, `cache.clear`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/chat_create.py.dox.md b/api/chat_create.py.dox.mdnew file mode 100644index 000000000..3546f4389--- /dev/null+++ b/api/chat_create.py.dox.md@@ -0,0 +1,45 @@+# chat_create.py DOX++## Purpose++- Own the `chat_create.py` API endpoint.+- This module handles chat create requests.+- Keep this file-level DOX profile synchronized with `chat_create.py` because this directory is intentionally flat.++## Ownership++- `chat_create.py` owns the runtime implementation.+- `chat_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `CreateChat` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `CreateChat` is an `ApiHandler`.+- `CreateChat` defines `process(...)`.+- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence.+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.use_context`, `mark_dirty_all`, `guids.generate_id`, `current_context.get_data`, `current_context.get_output_data`, `new_context.set_data`, `new_context.set_output_data`, `is_chat_override_allowed`, `settings.get_settings`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_browser_agent_regressions.py`++## Child DOX Index++No child DOX files.diff --git a/api/chat_export.py.dox.md b/api/chat_export.py.dox.mdnew file mode 100644index 000000000..03b5a0c91--- /dev/null+++ b/api/chat_export.py.dox.md@@ -0,0 +1,44 @@+# chat_export.py DOX++## Purpose++- Own the `chat_export.py` API endpoint.+- This module handles chat export requests.+- Keep this file-level DOX profile synchronized with `chat_export.py` because this directory is intentionally flat.++## Ownership++- `chat_export.py` owns the runtime implementation.+- `chat_export.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `ExportChat` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `ExportChat` is an `ApiHandler`.+- `ExportChat` defines `process(...)`.+- Observed side-effect areas: filesystem writes.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.use_context`, `persist_chat.export_json_chat`, `Exception`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/chat_files_path_get.py.dox.md b/api/chat_files_path_get.py.dox.mdnew file mode 100644index 000000000..63f0a2b6e--- /dev/null+++ b/api/chat_files_path_get.py.dox.md@@ -0,0 +1,44 @@+# chat_files_path_get.py DOX++## Purpose++- Own the `chat_files_path_get.py` API endpoint.+- This module handles chat files path get requests.+- Keep this file-level DOX profile synchronized with `chat_files_path_get.py` because this directory is intentionally flat.++## Ownership++- `chat_files_path_get.py` owns the runtime implementation.+- `chat_files_path_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `GetChatFilesPath` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `GetChatFilesPath` is an `ApiHandler`.+- `GetChatFilesPath` defines `process(...)`.+- Observed side-effect areas: settings/state persistence.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.use_context`, `projects.get_context_project_name`, `Exception`, `files.normalize_a0_path`, `projects.get_project_folder`, `settings.get_settings`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/chat_load.py.dox.md b/api/chat_load.py.dox.mdnew file mode 100644index 000000000..4718a9fc6--- /dev/null+++ b/api/chat_load.py.dox.md@@ -0,0 +1,44 @@+# chat_load.py DOX++## Purpose++- Own the `chat_load.py` API endpoint.+- This module handles chat load requests.+- Keep this file-level DOX profile synchronized with `chat_load.py` because this directory is intentionally flat.++## Ownership++- `chat_load.py` owns the runtime implementation.+- `chat_load.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `LoadChats` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `LoadChats` is an `ApiHandler`.+- `LoadChats` defines `process(...)`.+- Observed side-effect areas: filesystem writes.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `persist_chat.load_json_chats`, `Exception`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/chat_remove.py.dox.md b/api/chat_remove.py.dox.mdnew file mode 100644index 000000000..ac1ffc0f8--- /dev/null+++ b/api/chat_remove.py.dox.md@@ -0,0 +1,44 @@+# chat_remove.py DOX++## Purpose++- Own the `chat_remove.py` API endpoint.+- This module handles chat remove requests.+- Keep this file-level DOX profile synchronized with `chat_remove.py` because this directory is intentionally flat.++## Ownership++- `chat_remove.py` owns the runtime implementation.+- `chat_remove.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `RemoveChat` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `RemoveChat` is an `ApiHandler`.+- `RemoveChat` defines `process(...)`.+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state.+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.task_scheduler`.++## Key Concepts++- Important called helpers/classes observed in the source: `scheduler.cancel_tasks_by_context`, `AgentContext.use`, `AgentContext.remove`, `persist_chat.remove_chat`, `scheduler.get_tasks_by_context_id`, `mark_dirty_all`, `context.reset`, `scheduler.reload`, `scheduler.remove_task_by_uuid`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/chat_reset.py.dox.md b/api/chat_reset.py.dox.mdnew file mode 100644index 000000000..39a886a53--- /dev/null+++ b/api/chat_reset.py.dox.md@@ -0,0 +1,44 @@+# chat_reset.py DOX++## Purpose++- Own the `chat_reset.py` API endpoint.+- This module handles chat reset requests.+- Keep this file-level DOX profile synchronized with `chat_reset.py` because this directory is intentionally flat.++## Ownership++- `chat_reset.py` owns the runtime implementation.+- `chat_reset.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Reset` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Reset` is an `ApiHandler`.+- `Reset` defines `process(...)`.+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state.+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.task_scheduler`.++## Key Concepts++- Important called helpers/classes observed in the source: `TaskScheduler.get.cancel_tasks_by_context`, `self.use_context`, `context.reset`, `persist_chat.save_tmp_chat`, `persist_chat.remove_msg_files`, `mark_dirty_all`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/csrf_token.py.dox.md b/api/csrf_token.py.dox.mdnew file mode 100644index 000000000..3570d2471--- /dev/null+++ b/api/csrf_token.py.dox.md@@ -0,0 +1,57 @@+# csrf_token.py DOX++## Purpose++- Own the `csrf_token.py` API endpoint.+- This module issues or refreshes CSRF tokens for browser API clients.+- Keep this file-level DOX profile synchronized with `csrf_token.py` because this directory is intentionally flat.++## Ownership++- `csrf_token.py` owns the runtime implementation.+- `csrf_token.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `GetCsrfToken` (`ApiHandler`)+ - `get_methods(cls) -> list[str]`+ - `requires_csrf(cls) -> bool`+ - `async process(self, input: Input, request: Request) -> Output`+ - `async check_allowed_origin(self, request: Request)`+ - `async is_allowed_origin(self, request: Request)`+ - `get_origin_from_request(self, request: Request)`+ - `async get_allowed_origins(self) -> list[str]`+ - `get_default_allowed_origins(self) -> list[str]`+- Notable constants/configuration names: `ALLOWED_ORIGINS_KEY`.++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `GetCsrfToken` is an `ApiHandler`.+- `GetCsrfToken` defines `process(...)`.+- `GetCsrfToken` defines `get_methods(...)`.+- `GetCsrfToken` defines `requires_csrf(...)`.+- Observed side-effect areas: filesystem writes, network calls, secret handling, tunnel state.+- Imported dependency areas include: `fnmatch`, `helpers`, `helpers.api`, `secrets`, `urllib.parse`.++## Key Concepts++- Important called helpers/classes observed in the source: `login.is_login_required`, `self.initialize_allowed_origins`, `self.get_origin_from_request`, `urlparse`, `dotenv.get_dotenv_value`, `self.get_default_allowed_origins`, `dotenv.save_dotenv_value`, `self.check_allowed_origin`, `secrets.token_urlsafe`, `runtime.get_runtime_id`, `self.is_allowed_origin`, `self.get_allowed_origins`, `origin.strip`, `join`, `fnmatch.fnmatch`, `split`, `tunnel_api_process`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_http_auth_csrf.py`+ - `tests/test_self_update_tag_filter.py`+ - `tests/test_ws_security.py`++## Child DOX Index++No child DOX files.diff --git a/api/ctx_window_get.py.dox.md b/api/ctx_window_get.py.dox.mdnew file mode 100644index 000000000..2de01bf37--- /dev/null+++ b/api/ctx_window_get.py.dox.md@@ -0,0 +1,44 @@+# ctx_window_get.py DOX++## Purpose++- Own the `ctx_window_get.py` API endpoint.+- This module handles ctx window get API requests.+- Keep this file-level DOX profile synchronized with `ctx_window_get.py` because this directory is intentionally flat.++## Ownership++- `ctx_window_get.py` owns the runtime implementation.+- `ctx_window_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `GetCtxWindow` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `GetCtxWindow` is an `ApiHandler`.+- `GetCtxWindow` defines `process(...)`.+- Observed side-effect areas: secret handling.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.use_context`, `agent.get_data`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/delete_work_dir_file.py.dox.md b/api/delete_work_dir_file.py.dox.mdnew file mode 100644index 000000000..536b70fcb--- /dev/null+++ b/api/delete_work_dir_file.py.dox.md@@ -0,0 +1,46 @@+# delete_work_dir_file.py DOX++## Purpose++- Own the `delete_work_dir_file.py` API endpoint.+- This module handles workdir file operations for delete work dir file.+- Keep this file-level DOX profile synchronized with `delete_work_dir_file.py` because this directory is intentionally flat.++## Ownership++- `delete_work_dir_file.py` owns the runtime implementation.+- `delete_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `DeleteWorkDirFile` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`+- Top-level functions:+- `async delete_file(file_path: str)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `DeleteWorkDirFile` is an `ApiHandler`.+- `DeleteWorkDirFile` defines `process(...)`.+- Observed side-effect areas: filesystem deletion.+- Imported dependency areas include: `api`, `helpers`, `helpers.api`, `helpers.file_browser`.++## Key Concepts++- Important called helpers/classes observed in the source: `FileBrowser`, `browser.delete_file`, `file_path.startswith`, `runtime.call_development_function`, `extension.call_extensions_async`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/delete_work_dir_files.py.dox.md b/api/delete_work_dir_files.py.dox.mdnew file mode 100644index 000000000..2c68d3ca2--- /dev/null+++ b/api/delete_work_dir_files.py.dox.md@@ -0,0 +1,47 @@+# delete_work_dir_files.py DOX++## Purpose++- Own the `delete_work_dir_files.py` API endpoint.+- This module handles workdir file operations for delete work dir files.+- Keep this file-level DOX profile synchronized with `delete_work_dir_files.py` because this directory is intentionally flat.++## Ownership++- `delete_work_dir_files.py` owns the runtime implementation.+- `delete_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `DeleteWorkDirFiles` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`+- Top-level functions:+- `async delete_files(paths: list[str]) -> dict`+- `collapse_nested_paths(paths: list[str]) -> list[str]`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `DeleteWorkDirFiles` is an `ApiHandler`.+- `DeleteWorkDirFiles` defines `process(...)`.+- Observed side-effect areas: filesystem deletion.+- Imported dependency areas include: `api`, `api.download_work_dir_files`, `helpers`, `helpers.api`, `helpers.file_browser`.++## Key Concepts++- Important called helpers/classes observed in the source: `FileBrowser`, `collapse_nested_paths`, `browser.delete_file`, `normalize_paths`, `runtime.call_development_function`, `path.strip`, `extension.call_extensions_async`, `item.count`, `clean_path.startswith`, `parent.rstrip`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/download_work_dir_file.py.dox.md b/api/download_work_dir_file.py.dox.mdnew file mode 100644index 000000000..87085765a--- /dev/null+++ b/api/download_work_dir_file.py.dox.md@@ -0,0 +1,53 @@+# download_work_dir_file.py DOX++## Purpose++- Own the `download_work_dir_file.py` API endpoint.+- This module handles workdir file operations for download work dir file.+- Keep this file-level DOX profile synchronized with `download_work_dir_file.py` because this directory is intentionally flat.++## Ownership++- `download_work_dir_file.py` owns the runtime implementation.+- `download_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `DownloadFile` (`ApiHandler`)+ - `get_methods(cls)`+ - `async process(self, input: Input, request: Request) -> Output`+- Top-level functions:+- `stream_file_download(file_source, download_name, chunk_size=...)`: Create a streaming response for file downloads that shows progress in browser.+- `make_disposition(download_name: str) -> str`+- `resolve_download_path(path: str) -> str`: Resolve a requested download path and keep it within the runtime base dir.+- `async fetch_file(path)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `DownloadFile` is an `ApiHandler`.+- `DownloadFile` defines `process(...)`.+- `DownloadFile` defines `get_methods(...)`.+- Observed side-effect areas: filesystem reads, network calls.+- Imported dependency areas include: `api`, `base64`, `flask`, `helpers`, `helpers.api`, `io`, `mimetypes`, `os`, `pathlib`, `urllib.parse`.++## Key Concepts++- Important called helpers/classes observed in the source: `mimetypes.guess_type`, `Response`, `quote`, `Path.resolve`, `Path`, `candidate.is_absolute`, `os.path.getsize`, `generate`, `download_name.encode.decode`, `candidate.resolve`, `resolve`, `resolved.relative_to`, `Exception`, `file.read`, `base64.b64encode.decode`, `file_source.tell`, `file_source.seek`, `ValueError`, `file_path.startswith`, `runtime.call_development_function`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_download_toast_regressions.py`+ - `tests/test_office_canvas_setup.py`++## Child DOX Index++No child DOX files.diff --git a/api/download_work_dir_files.py.dox.md b/api/download_work_dir_files.py.dox.mdnew file mode 100644index 000000000..478669fa8--- /dev/null+++ b/api/download_work_dir_files.py.dox.md@@ -0,0 +1,54 @@+# download_work_dir_files.py DOX++## Purpose++- Own the `download_work_dir_files.py` API endpoint.+- This module handles workdir file operations for download work dir files.+- Keep this file-level DOX profile synchronized with `download_work_dir_files.py` because this directory is intentionally flat.++## Ownership++- `download_work_dir_files.py` owns the runtime implementation.+- `download_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `DownloadFiles` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`+- Top-level functions:+- `normalize_paths(paths) -> list[str]`+- `selected_archive_name(count: int) -> str`+- `create_selected_zip(paths: list[str], current_path: str=...) -> str`+- `resolve_download_path(path: str, base_dir: Path) -> Path`+- `collapse_nested_paths(paths: list[Path]) -> list[Path]`+- `archive_root_name(source_path: Path, current_dir: Path | None, base_dir: Path) -> str`+- `unique_archive_name(name: str, used_names: set[str]) -> str`+- `write_zip_entry(zip_file: zipfile.ZipFile, source_path: Path, arc_root: str) -> None`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `DownloadFiles` is an `ApiHandler`.+- `DownloadFiles` defines `process(...)`.+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.+- Imported dependency areas include: `api.download_work_dir_file`, `base64`, `flask`, `helpers`, `helpers.api`, `helpers.localization`, `io`, `os`, `pathlib`, `tempfile`, `zipfile`.++## Key Concepts++- Important called helpers/classes observed in the source: `Localization.get.now.strftime`, `Path.resolve`, `normalize_paths`, `collapse_nested_paths`, `Path`, `os.path.splitext`, `source_path.is_dir`, `zip_file.write`, `selected_archive_name`, `runtime.is_development`, `stream_file_download`, `ValueError`, `raw_path.strip`, `resolve_download_path`, `current_dir.is_file`, `resolved.exists`, `FileNotFoundError`, `tempfile.NamedTemporaryFile`, `zipfile.ZipFile`, `candidate.is_absolute`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_download_toast_regressions.py`++## Child DOX Index++No child DOX files.diff --git a/api/edit_work_dir_file.py.dox.md b/api/edit_work_dir_file.py.dox.mdnew file mode 100644index 000000000..e5615517b--- /dev/null+++ b/api/edit_work_dir_file.py.dox.md@@ -0,0 +1,50 @@+# edit_work_dir_file.py DOX++## Purpose++- Own the `edit_work_dir_file.py` API endpoint.+- This module handles workdir file operations for edit work dir file.+- Keep this file-level DOX profile synchronized with `edit_work_dir_file.py` because this directory is intentionally flat.++## Ownership++- `edit_work_dir_file.py` owns the runtime implementation.+- `edit_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `EditWorkDirFile` (`ApiHandler`)+ - `get_methods(cls)`+ - `async process(self, input: Input, request: Request) -> Output`+- Top-level functions:+- `async load_file(file_path: str) -> dict`+- `save_file(file_path: str, content: str) -> bool`+- Notable constants/configuration names: `MAX_EDIT_FILE_SIZE`, `BINARY_SAMPLE_SIZE`.++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `EditWorkDirFile` is an `ApiHandler`.+- `EditWorkDirFile` defines `process(...)`.+- `EditWorkDirFile` defines `get_methods(...)`.+- Observed side-effect areas: filesystem reads, filesystem writes.+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.file_browser`, `mimetypes`, `os`.++## Key Concepts++- Important called helpers/classes observed in the source: `FileBrowser`, `browser.get_full_path`, `os.path.isdir`, `os.path.getsize`, `files.is_probably_binary_file`, `mimetypes.guess_type`, `browser.save_text_file`, `error_str.strip`, `Exception`, `os.path.basename`, `error_str.split`, `file.read`, `line.split.strip`, `file_path.startswith`, `content.encode`, `runtime.call_development_function`, `extension.call_extensions_async`, `self._extract_error_message`, `line.split`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/file_info.py.dox.md b/api/file_info.py.dox.mdnew file mode 100644index 000000000..e3612589d--- /dev/null+++ b/api/file_info.py.dox.md@@ -0,0 +1,47 @@+# file_info.py DOX++## Purpose++- Own the `file_info.py` API endpoint.+- This module handles file info API requests.+- Keep this file-level DOX profile synchronized with `file_info.py` because this directory is intentionally flat.++## Ownership++- `file_info.py` owns the runtime implementation.+- `file_info.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `FileInfoApi` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`+- `FileInfo` (`TypedDict`)+- Top-level functions:+- `async get_file_info(path: str) -> FileInfo`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `FileInfoApi` is an `ApiHandler`.+- `FileInfoApi` defines `process(...)`.+- Observed side-effect areas: filesystem reads.+- Imported dependency areas include: `helpers`, `helpers.api`, `os`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `files.get_abs_path`, `os.path.exists`, `os.path.dirname`, `os.path.basename`, `runtime.call_development_function`, `os.path.isdir`, `os.path.isfile`, `os.path.islink`, `os.path.getsize`, `os.path.getmtime`, `os.path.getctime`, `os.path.splitext`, `os.stat`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/get_work_dir_files.py.dox.md b/api/get_work_dir_files.py.dox.mdnew file mode 100644index 000000000..3d3048650--- /dev/null+++ b/api/get_work_dir_files.py.dox.md@@ -0,0 +1,47 @@+# get_work_dir_files.py DOX++## Purpose++- Own the `get_work_dir_files.py` API endpoint.+- This module handles workdir file operations for get work dir files.+- Keep this file-level DOX profile synchronized with `get_work_dir_files.py` because this directory is intentionally flat.++## Ownership++- `get_work_dir_files.py` owns the runtime implementation.+- `get_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `GetWorkDirFiles` (`ApiHandler`)+ - `get_methods(cls)`+ - `async process(self, input: dict, request: Request) -> dict | Response`+- Top-level functions:+- `async get_files(path)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `GetWorkDirFiles` is an `ApiHandler`.+- `GetWorkDirFiles` defines `process(...)`.+- `GetWorkDirFiles` defines `get_methods(...)`.+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.file_browser`.++## Key Concepts++- Important called helpers/classes observed in the source: `FileBrowser`, `browser.get_files`, `runtime.call_development_function`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/health.py.dox.md b/api/health.py.dox.mdnew file mode 100644index 000000000..236812f56--- /dev/null+++ b/api/health.py.dox.md@@ -0,0 +1,52 @@+# health.py DOX++## Purpose++- Own the `health.py` API endpoint.+- This module reports process health for probes and startup checks.+- Keep this file-level DOX profile synchronized with `health.py` because this directory is intentionally flat.++## Ownership++- `health.py` owns the runtime implementation.+- `health.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `HealthCheck` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `requires_csrf(cls) -> bool`+ - `get_methods(cls) -> list[str]`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `HealthCheck` is an `ApiHandler`.+- `HealthCheck` defines `process(...)`.+- `HealthCheck` defines `get_methods(...)`.+- `HealthCheck` defines `requires_auth(...)`.+- `HealthCheck` defines `requires_csrf(...)`.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `git.get_git_info`, `errors.error_text`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_oauth_providers.py`+ - `tests/test_office_document_store.py`+ - `tests/test_self_update_tag_filter.py`++## Child DOX Index++No child DOX files.diff --git a/api/history_get.py.dox.md b/api/history_get.py.dox.mdnew file mode 100644index 000000000..8f2f1ddca--- /dev/null+++ b/api/history_get.py.dox.md@@ -0,0 +1,44 @@+# history_get.py DOX++## Purpose++- Own the `history_get.py` API endpoint.+- This module handles history get API requests.+- Keep this file-level DOX profile synchronized with `history_get.py` because this directory is intentionally flat.++## Ownership++- `history_get.py` owns the runtime implementation.+- `history_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `GetHistory` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `GetHistory` is an `ApiHandler`.+- `GetHistory` defines `process(...)`.+- Observed side-effect areas: secret handling.+- Imported dependency areas include: `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.use_context`, `agent.history.output_text`, `agent.history.get_tokens`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/image_get.py.dox.md b/api/image_get.py.dox.mdnew file mode 100644index 000000000..b9b0da35b--- /dev/null+++ b/api/image_get.py.dox.md@@ -0,0 +1,53 @@+# image_get.py DOX++## Purpose++- Own the `image_get.py` API endpoint.+- This module serves allowed image references and fallback file-type icons.+- Keep this file-level DOX profile synchronized with `image_get.py` because this directory is intentionally flat.++## Ownership++- `image_get.py` owns the runtime implementation.+- `image_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `ImageGet` (`ApiHandler`)+ - `get_methods(cls) -> list[str]`+ - `async process(self, input: dict, request: Request) -> dict | Response`+- Top-level functions:+- `_resolve_allowed_image_path(path: str) -> str`: Resolve a requested image path and keep it inside Agent Zero's base dir.+- `_set_image_headers(response: Response, filename: str, file_ext: str) -> None`+- `_send_file_type_icon(file_ext, filename=...)`: Return appropriate icon for file type+- `_send_fallback_icon(icon_name)`: Return fallback icon from public directory+- Notable constants/configuration names: `IMAGE_EXTENSIONS`, `SVG_EXTENSIONS`, `SVG_CONTENT_SECURITY_POLICY`.++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `ImageGet` is an `ApiHandler`.+- `ImageGet` defines `process(...)`.+- `ImageGet` defines `get_methods(...)`.+- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, settings/state persistence.+- Imported dependency areas include: `base64`, `helpers`, `helpers.api`, `io`, `mimetypes`, `os`, `pathlib`, `urllib.parse`.++## Key Concepts++- Important called helpers/classes observed in the source: `runtime.is_development`, `Path.resolve`, `candidate.resolve`, `quote`, `_send_fallback_icon`, `files.get_abs_path`, `send_file`, `os.path.splitext.lower`, `os.path.basename`, `Path`, `candidate.is_absolute`, `resolved.relative_to`, `os.path.exists`, `ValueError`, `_set_image_headers`, `_send_file_type_icon`, `files.fix_dev_path`, `_resolve_allowed_image_path`, `files.exists`, `files.get_base_dir`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_image_get_security.py`++## Child DOX Index++No child DOX files.diff --git a/api/load_webui_extensions.py.dox.md b/api/load_webui_extensions.py.dox.mdnew file mode 100644index 000000000..c2d41e06a--- /dev/null+++ b/api/load_webui_extensions.py.dox.md@@ -0,0 +1,44 @@+# load_webui_extensions.py DOX++## Purpose++- Own the `load_webui_extensions.py` API endpoint.+- This module returns frontend extension manifests/files for a WebUI extension point.+- Keep this file-level DOX profile synchronized with `load_webui_extensions.py` because this directory is intentionally flat.++## Ownership++- `load_webui_extensions.py` owns the runtime implementation.+- `load_webui_extensions.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `LoadWebuiExtensions` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `LoadWebuiExtensions` is an `ApiHandler`.+- `LoadWebuiExtensions` defines `process(...)`.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `extension.get_webui_extensions`, `Response`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_webui_extension_surfaces.py`++## Child DOX Index++No child DOX files.diff --git a/api/logout.py.dox.md b/api/logout.py.dox.mdnew file mode 100644index 000000000..e125a43e7--- /dev/null+++ b/api/logout.py.dox.md@@ -0,0 +1,47 @@+# logout.py DOX++## Purpose++- Own the `logout.py` API endpoint.+- This module clears login/session state for the current client.+- Keep this file-level DOX profile synchronized with `logout.py` because this directory is intentionally flat.++## Ownership++- `logout.py` owns the runtime implementation.+- `logout.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `ApiLogout` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `ApiLogout` is an `ApiHandler`.+- `ApiLogout` defines `process(...)`.+- `ApiLogout` defines `requires_auth(...)`.+- Observed side-effect areas: secret handling.+- Imported dependency areas include: `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `session.clear`, `session.pop`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_office_document_store.py`++## Child DOX Index++No child DOX files.diff --git a/api/mcp_server_get_detail.py.dox.md b/api/mcp_server_get_detail.py.dox.mdnew file mode 100644index 000000000..e4539d725--- /dev/null+++ b/api/mcp_server_get_detail.py.dox.md@@ -0,0 +1,43 @@+# mcp_server_get_detail.py DOX++## Purpose++- Own the `mcp_server_get_detail.py` API endpoint.+- This module handles MCP server server get detail requests.+- Keep this file-level DOX profile synchronized with `mcp_server_get_detail.py` because this directory is intentionally flat.++## Ownership++- `mcp_server_get_detail.py` owns the runtime implementation.+- `mcp_server_get_detail.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `McpServerGetDetail` (`ApiHandler`)+ - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `McpServerGetDetail` is an `ApiHandler`.+- `McpServerGetDetail` defines `process(...)`.+- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_server_detail`, `MCPConfig.get_instance`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/mcp_server_get_log.py.dox.md b/api/mcp_server_get_log.py.dox.mdnew file mode 100644index 000000000..3baf7453e--- /dev/null+++ b/api/mcp_server_get_log.py.dox.md@@ -0,0 +1,43 @@+# mcp_server_get_log.py DOX++## Purpose++- Own the `mcp_server_get_log.py` API endpoint.+- This module handles MCP server server get log requests.+- Keep this file-level DOX profile synchronized with `mcp_server_get_log.py` because this directory is intentionally flat.++## Ownership++- `mcp_server_get_log.py` owns the runtime implementation.+- `mcp_server_get_log.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `McpServerGetLog` (`ApiHandler`)+ - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `McpServerGetLog` is an `ApiHandler`.+- `McpServerGetLog` defines `process(...)`.+- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_server_log`, `MCPConfig.get_instance`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/mcp_servers_apply.py.dox.md b/api/mcp_servers_apply.py.dox.mdnew file mode 100644index 000000000..1a0a0d326--- /dev/null+++ b/api/mcp_servers_apply.py.dox.md@@ -0,0 +1,44 @@+# mcp_servers_apply.py DOX++## Purpose++- Own the `mcp_servers_apply.py` API endpoint.+- This module handles MCP server servers apply requests.+- Keep this file-level DOX profile synchronized with `mcp_servers_apply.py` because this directory is intentionally flat.++## Ownership++- `mcp_servers_apply.py` owns the runtime implementation.+- `mcp_servers_apply.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `McpServersApply` (`ApiHandler`)+ - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `McpServersApply` is an `ApiHandler`.+- `McpServersApply` defines `process(...)`.+- Observed side-effect areas: settings/state persistence.+- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `helpers.settings`, `time`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `set_settings_delta`, `time.sleep`, `MCPConfig.get_instance.get_servers_status`, `MCPConfig.get_instance`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/mcp_servers_status.py.dox.md b/api/mcp_servers_status.py.dox.mdnew file mode 100644index 000000000..6a66a3eb3--- /dev/null+++ b/api/mcp_servers_status.py.dox.md@@ -0,0 +1,43 @@+# mcp_servers_status.py DOX++## Purpose++- Own the `mcp_servers_status.py` API endpoint.+- This module handles MCP server servers status requests.+- Keep this file-level DOX profile synchronized with `mcp_servers_status.py` because this directory is intentionally flat.++## Ownership++- `mcp_servers_status.py` owns the runtime implementation.+- `mcp_servers_status.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `McpServersStatuss` (`ApiHandler`)+ - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `McpServersStatuss` is an `ApiHandler`.+- `McpServersStatuss` defines `process(...)`.+- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_servers_status`, `MCPConfig.get_instance`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/message.py.dox.md b/api/message.py.dox.mdnew file mode 100644index 000000000..9ec63fc71--- /dev/null+++ b/api/message.py.dox.md@@ -0,0 +1,54 @@+# message.py DOX++## Purpose++- Own the `message.py` API endpoint.+- This module submits a user message and runs agent processing synchronously through the UI API.+- Keep this file-level DOX profile synchronized with `message.py` because this directory is intentionally flat.++## Ownership++- `message.py` owns the runtime implementation.+- `message.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Message` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`+ - `async respond(self, task: DeferredTask, context: AgentContext)`+ - `async communicate(self, input: dict, request: Request)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Message` is an `ApiHandler`.+- `Message` defines `process(...)`.+- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, scheduler state.+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.defer`, `helpers.security`, `os`.++## Key Concepts++- Important called helpers/classes observed in the source: `request.content_type.startswith`, `self.use_context`, `mq.log_user_message`, `self.communicate`, `self.respond`, `task.result`, `request.files.getlist`, `files.get_abs_path`, `request.get_json`, `extension.call_extensions_async`, `context.communicate`, `os.makedirs`, `UserMessage`, `safe_filename`, `attachment.save`, `context.get_agent`, `os.path.join`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/email_parser_test.py`+ - `tests/rate_limiter_test.py`+ - `tests/test_api_chat_lifetime.py`+ - `tests/test_browser_agent_regressions.py`+ - `tests/test_chat_compaction.py`+ - `tests/test_docker_release_plan.py`+ - `tests/test_document_query_fallback.py`+ - `tests/test_download_toast_regressions.py`++## Child DOX Index++No child DOX files.diff --git a/api/message_async.py.dox.md b/api/message_async.py.dox.mdnew file mode 100644index 000000000..6a6ba0093--- /dev/null+++ b/api/message_async.py.dox.md@@ -0,0 +1,42 @@+# message_async.py DOX++## Purpose++- Own the `message_async.py` API endpoint.+- This module submits a user message for asynchronous agent processing.+- Keep this file-level DOX profile synchronized with `message_async.py` because this directory is intentionally flat.++## Ownership++- `message_async.py` owns the runtime implementation.+- `message_async.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `MessageAsync` (`Message`)+ - `async respond(self, task: DeferredTask, context: AgentContext)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- Observed side-effect areas: scheduler state.+- Imported dependency areas include: `agent`, `api.message`, `helpers.defer`.++## 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 authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/message_queue_add.py.dox.md b/api/message_queue_add.py.dox.mdnew file mode 100644index 000000000..f727a70f1--- /dev/null+++ b/api/message_queue_add.py.dox.md@@ -0,0 +1,44 @@+# message_queue_add.py DOX++## Purpose++- Own the `message_queue_add.py` API endpoint.+- This module handles message queue add API requests.+- Keep this file-level DOX profile synchronized with `message_queue_add.py` because this directory is intentionally flat.++## Ownership++- `message_queue_add.py` owns the runtime implementation.+- `message_queue_add.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `MessageQueueAdd` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `MessageQueueAdd` is an `ApiHandler`.+- `MessageQueueAdd` defines `process(...)`.+- Observed side-effect areas: settings/state persistence.+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`.++## Key Concepts++- Important called helpers/classes observed in the source: `input.get.strip`, `mq.add`, `mark_dirty_for_context`, `Response`, `mq.get_queue`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/message_queue_remove.py.dox.md b/api/message_queue_remove.py.dox.mdnew file mode 100644index 000000000..8bf876b05--- /dev/null+++ b/api/message_queue_remove.py.dox.md@@ -0,0 +1,44 @@+# message_queue_remove.py DOX++## Purpose++- Own the `message_queue_remove.py` API endpoint.+- This module handles message queue remove API requests.+- Keep this file-level DOX profile synchronized with `message_queue_remove.py` because this directory is intentionally flat.++## Ownership++- `message_queue_remove.py` owns the runtime implementation.+- `message_queue_remove.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `MessageQueueRemove` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `MessageQueueRemove` is an `ApiHandler`.+- `MessageQueueRemove` defines `process(...)`.+- Observed side-effect areas: filesystem deletion, settings/state persistence.+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`.++## Key Concepts++- Important called helpers/classes observed in the source: `mq.remove`, `mark_dirty_for_context`, `Response`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/message_queue_send.py.dox.md b/api/message_queue_send.py.dox.mdnew file mode 100644index 000000000..4f7294a94--- /dev/null+++ b/api/message_queue_send.py.dox.md@@ -0,0 +1,44 @@+# message_queue_send.py DOX++## Purpose++- Own the `message_queue_send.py` API endpoint.+- This module handles message queue send API requests.+- Keep this file-level DOX profile synchronized with `message_queue_send.py` because this directory is intentionally flat.++## Ownership++- `message_queue_send.py` owns the runtime implementation.+- `message_queue_send.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `MessageQueueSend` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `MessageQueueSend` is an `ApiHandler`.+- `MessageQueueSend` defines `process(...)`.+- Observed side-effect areas: settings/state persistence.+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`.++## Key Concepts++- Important called helpers/classes observed in the source: `mq.send_message`, `mark_dirty_for_context`, `Response`, `mq.has_queue`, `mq.send_all_aggregated`, `mq.pop_item`, `mq.pop_first`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/notification_create.py.dox.md b/api/notification_create.py.dox.mdnew file mode 100644index 000000000..a83b82cf4--- /dev/null+++ b/api/notification_create.py.dox.md@@ -0,0 +1,46 @@+# notification_create.py DOX++## Purpose++- Own the `notification_create.py` API endpoint.+- This module handles notification notification create requests.+- Keep this file-level DOX profile synchronized with `notification_create.py` because this directory is intentionally flat.++## Ownership++- `notification_create.py` owns the runtime implementation.+- `notification_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `NotificationCreate` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `NotificationCreate` is an `ApiHandler`.+- `NotificationCreate` defines `process(...)`.+- `NotificationCreate` defines `requires_auth(...)`.+- Imported dependency areas include: `flask`, `helpers.api`, `helpers.notification`.++## Key Concepts++- Important called helpers/classes observed in the source: `NotificationManager.send_notification`, `NotificationType`, `notification.output`, `notification_type.lower`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_download_toast_regressions.py`++## Child DOX Index++No child DOX files.diff --git a/api/notifications_clear.py.dox.md b/api/notifications_clear.py.dox.mdnew file mode 100644index 000000000..dc5503b73--- /dev/null+++ b/api/notifications_clear.py.dox.md@@ -0,0 +1,45 @@+# notifications_clear.py DOX++## Purpose++- Own the `notifications_clear.py` API endpoint.+- This module handles notification notifications clear requests.+- Keep this file-level DOX profile synchronized with `notifications_clear.py` because this directory is intentionally flat.++## Ownership++- `notifications_clear.py` owns the runtime implementation.+- `notifications_clear.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `NotificationsClear` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `NotificationsClear` is an `ApiHandler`.+- `NotificationsClear` defines `process(...)`.+- `NotificationsClear` defines `requires_auth(...)`.+- Imported dependency areas include: `agent`, `flask`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.clear_all`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/notifications_history.py.dox.md b/api/notifications_history.py.dox.mdnew file mode 100644index 000000000..a14b5bc86--- /dev/null+++ b/api/notifications_history.py.dox.md@@ -0,0 +1,45 @@+# notifications_history.py DOX++## Purpose++- Own the `notifications_history.py` API endpoint.+- This module handles notification notifications history requests.+- Keep this file-level DOX profile synchronized with `notifications_history.py` because this directory is intentionally flat.++## Ownership++- `notifications_history.py` owns the runtime implementation.+- `notifications_history.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `NotificationsHistory` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `NotificationsHistory` is an `ApiHandler`.+- `NotificationsHistory` defines `process(...)`.+- `NotificationsHistory` defines `requires_auth(...)`.+- Imported dependency areas include: `agent`, `flask`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.output_all`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/notifications_mark_read.py.dox.md b/api/notifications_mark_read.py.dox.mdnew file mode 100644index 000000000..a06cbbdcf--- /dev/null+++ b/api/notifications_mark_read.py.dox.md@@ -0,0 +1,45 @@+# notifications_mark_read.py DOX++## Purpose++- Own the `notifications_mark_read.py` API endpoint.+- This module handles notification notifications mark read requests.+- Keep this file-level DOX profile synchronized with `notifications_mark_read.py` because this directory is intentionally flat.++## Ownership++- `notifications_mark_read.py` owns the runtime implementation.+- `notifications_mark_read.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `NotificationsMarkRead` (`ApiHandler`)+ - `requires_auth(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `NotificationsMarkRead` is an `ApiHandler`.+- `NotificationsMarkRead` defines `process(...)`.+- `NotificationsMarkRead` defines `requires_auth(...)`.+- Imported dependency areas include: `agent`, `flask`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.mark_read_by_ids`, `notification_manager.mark_all_read`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/nudge.py.dox.md b/api/nudge.py.dox.mdnew file mode 100644index 000000000..f1be2cf3d--- /dev/null+++ b/api/nudge.py.dox.md@@ -0,0 +1,44 @@+# nudge.py DOX++## Purpose++- Own the `nudge.py` API endpoint.+- This module handles nudge API requests.+- Keep this file-level DOX profile synchronized with `nudge.py` because this directory is intentionally flat.++## Ownership++- `nudge.py` owns the runtime implementation.+- `nudge.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Nudge` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Nudge` is an `ApiHandler`.+- `Nudge` defines `process(...)`.+- Imported dependency areas include: `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.use_context`, `context.nudge`, `context.log.log`, `Exception`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_browser_agent_regressions.py`++## Child DOX Index++No child DOX files.diff --git a/api/pause.py.dox.md b/api/pause.py.dox.mdnew file mode 100644index 000000000..37d0528e9--- /dev/null+++ b/api/pause.py.dox.md@@ -0,0 +1,45 @@+# pause.py DOX++## Purpose++- Own the `pause.py` API endpoint.+- This module handles pause API requests.+- Keep this file-level DOX profile synchronized with `pause.py` because this directory is intentionally flat.++## Ownership++- `pause.py` owns the runtime implementation.+- `pause.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Pause` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Pause` is an `ApiHandler`.+- `Pause` defines `process(...)`.+- Imported dependency areas include: `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.use_context`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_multi_tab_isolation.py`+ - `tests/test_snapshot_schema_v1.py`++## Child DOX Index++No child DOX files.diff --git a/api/plugins.py.dox.md b/api/plugins.py.dox.mdnew file mode 100644index 000000000..e64b22dc9--- /dev/null+++ b/api/plugins.py.dox.md@@ -0,0 +1,52 @@+# plugins.py DOX++## Purpose++- Own the `plugins.py` API endpoint.+- This module manages plugin actions and plugin settings through the core API.+- 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:+- `Plugins` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Plugins` is an `ApiHandler`.+- `Plugins` defines `process(...)`.+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, plugin state, settings/state persistence.+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.localization`, `json`, `os`, `subprocess`, `sys`.++## Key Concepts++- Important called helpers/classes observed in the source: `Response`, `plugins.find_plugin_assets`, `plugins.get_plugin_meta`, `plugins.get_default_plugin_config`, `plugins.save_plugin_config`, `plugins.toggle_plugin`, `plugins.find_plugin_dir`, `files.get_abs_path`, `Localization.get.now_iso`, `plugins.determine_plugin_asset_path`, `self._get_config`, `self._get_toggle_status`, `self._list_configs`, `self._delete_config`, `self._delete_plugin`, `self._get_default_config`, `self._save_config`, `self._toggle_plugin`, `self._get_doc`, `self._run_execute_script`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- 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.diff --git a/api/plugins_list.py.dox.md b/api/plugins_list.py.dox.mdnew file mode 100644index 000000000..599b5a307--- /dev/null+++ b/api/plugins_list.py.dox.md@@ -0,0 +1,46 @@+# plugins_list.py DOX++## Purpose++- Own the `plugins_list.py` API endpoint.+- This module returns plugin inventory and activation metadata for plugin UI surfaces.+- Keep this file-level DOX profile synchronized with `plugins_list.py` because this directory is intentionally flat.++## Ownership++- `plugins_list.py` owns the runtime implementation.+- `plugins_list.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `PluginsList` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `PluginsList` is an `ApiHandler`.+- `PluginsList` defines `process(...)`.+- Observed side-effect areas: plugin state, settings/state persistence.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `plugins.get_enhanced_plugins_list`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_plugin_activation_ui.py`+ - `tests/test_speech_plugin_split.py`++## Child DOX Index++No child DOX files.diff --git a/api/poll.py.dox.md b/api/poll.py.dox.mdnew file mode 100644index 000000000..851a03318--- /dev/null+++ b/api/poll.py.dox.md@@ -0,0 +1,52 @@+# poll.py DOX++## Purpose++- Own the `poll.py` API endpoint.+- This module returns chat/log/status changes for polling clients.+- Keep this file-level DOX profile synchronized with `poll.py` because this directory is intentionally flat.++## Ownership++- `poll.py` owns the runtime implementation.+- `poll.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Poll` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Poll` is an `ApiHandler`.+- `Poll` defines `process(...)`.+- Observed side-effect areas: settings/state persistence.+- Imported dependency areas include: `helpers.api`, `helpers.state_snapshot`.++## Key Concepts++- Important called helpers/classes observed in the source: `build_snapshot`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_multi_tab_isolation.py`+ - `tests/test_oauth_github_copilot.py`+ - `tests/test_oauth_providers.py`+ - `tests/test_office_document_store.py`+ - `tests/test_snapshot_parity.py`+ - `tests/test_snapshot_schema_v1.py`+ - `tests/test_timezone_regressions.py`+ - `tests/test_tunnel_remote_link.py`++## Child DOX Index++No child DOX files.diff --git a/api/projects.py.dox.md b/api/projects.py.dox.mdnew file mode 100644index 000000000..d55500c21--- /dev/null+++ b/api/projects.py.dox.md@@ -0,0 +1,59 @@+# projects.py DOX++## Purpose++- Own the `projects.py` API endpoint.+- This module manages project create, update, delete, clone, and metadata flows.+- 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:+- `Projects` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`+ - `get_active_projects_list(self)`+ - `get_active_projects_options(self)`+ - `create_project(self, project: dict | None)`+ - `clone_project(self, project: dict | None)`+ - `load_project(self, name: str | None)`+ - `update_project(self, project: dict | None)`+ - `delete_project(self, name: str | None)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Projects` is an `ApiHandler`.+- `Projects` defines `process(...)`.+- Observed side-effect areas: filesystem deletion, settings/state persistence.+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.notification`.++## Key Concepts++- Important called helpers/classes observed in the source: `projects.get_active_projects_list`, `projects.BasicProjectData`, `projects.create_project`, `projects.load_edit_project_data`, `NotificationManager.send_notification`, `projects.EditProjectData`, `projects.update_project`, `projects.delete_project`, `projects.activate_project`, `projects.deactivate_project`, `projects.load_basic_project_data`, `projects.get_file_structure`, `self.use_context`, `Exception`, `projects.clone_git_project`, `self.get_active_projects_list`, `self.get_active_projects_options`, `self.load_project`, `self.create_project`, `self.clone_project`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- 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.diff --git a/api/rename_work_dir_file.py.dox.md b/api/rename_work_dir_file.py.dox.mdnew file mode 100644index 000000000..624bedc54--- /dev/null+++ b/api/rename_work_dir_file.py.dox.md@@ -0,0 +1,47 @@+# rename_work_dir_file.py DOX++## Purpose++- Own the `rename_work_dir_file.py` API endpoint.+- This module handles workdir file operations for rename work dir file.+- Keep this file-level DOX profile synchronized with `rename_work_dir_file.py` because this directory is intentionally flat.++## Ownership++- `rename_work_dir_file.py` owns the runtime implementation.+- `rename_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `RenameWorkDirFile` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`+- Top-level functions:+- `async rename_item(file_path: str, new_name: str) -> bool`+- `async create_folder(parent_path: str, folder_name: str) -> bool`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `RenameWorkDirFile` is an `ApiHandler`.+- `RenameWorkDirFile` defines `process(...)`.+- Observed side-effect areas: filesystem writes.+- Imported dependency areas include: `api`, `helpers`, `helpers.api`, `helpers.file_browser`, `posixpath`.++## Key Concepts++- Important called helpers/classes observed in the source: `FileBrowser`, `browser.rename_item`, `browser.create_folder`, `strip`, `runtime.call_development_function`, `posixpath.join`, `file_path.startswith`, `extension.call_extensions_async`, `str.rstrip`, `posixpath.dirname`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/restart.py.dox.md b/api/restart.py.dox.mdnew file mode 100644index 000000000..4e3156f6e--- /dev/null+++ b/api/restart.py.dox.md@@ -0,0 +1,48 @@+# restart.py DOX++## Purpose++- Own the `restart.py` API endpoint.+- This module requests server restart or reload behavior.+- Keep this file-level DOX profile synchronized with `restart.py` because this directory is intentionally flat.++## Ownership++- `restart.py` owns the runtime implementation.+- `restart.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Restart` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Restart` is an `ApiHandler`.+- `Restart` defines `process(...)`.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `process.reload`, `Response`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_browser_agent_regressions.py`+ - `tests/test_download_toast_regressions.py`+ - `tests/test_self_update_tag_filter.py`+ - `tests/test_timezone_regressions.py`+ - `tests/test_ws_manager.py`++## Child DOX Index++No child DOX files.diff --git a/api/rfc.py.dox.md b/api/rfc.py.dox.mdnew file mode 100644index 000000000..6598649ea--- /dev/null+++ b/api/rfc.py.dox.md@@ -0,0 +1,47 @@+# rfc.py DOX++## Purpose++- Own the `rfc.py` API endpoint.+- This module dispatches remote function calls through the RFC helper layer.+- 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:+- `RFC` (`ApiHandler`)+ - `requires_csrf(cls) -> bool`+ - `requires_auth(cls) -> bool`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `RFC` is an `ApiHandler`.+- `RFC` defines `process(...)`.+- `RFC` defines `requires_auth(...)`.+- `RFC` defines `requires_csrf(...)`.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `runtime.handle_rfc`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/scheduler_task_create.py.dox.md b/api/scheduler_task_create.py.dox.mdnew file mode 100644index 000000000..332118085--- /dev/null+++ b/api/scheduler_task_create.py.dox.md@@ -0,0 +1,44 @@+# scheduler_task_create.py DOX++## Purpose++- Own the `scheduler_task_create.py` API endpoint.+- This module handles scheduler task create requests.+- Keep this file-level DOX profile synchronized with `scheduler_task_create.py` because this directory is intentionally flat.++## Ownership++- `scheduler_task_create.py` owns the runtime implementation.+- `scheduler_task_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SchedulerTaskCreate` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SchedulerTaskCreate` is an `ApiHandler`.+- `SchedulerTaskCreate` defines `process(...)`.+- Observed side-effect areas: filesystem writes, secret handling, scheduler state.+- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.projects`, `helpers.task_scheduler`, `random`.++## Key Concepts++- Important called helpers/classes observed in the source: `PrintStyle`, `scheduler.get_task_by_uuid`, `serialize_task`, `Localization.get.set_timezone`, `scheduler.reload`, `ValueError`, `ScheduledTask.create`, `scheduler.add_task`, `requested_project_slug.strip`, `load_basic_project_data`, `random.randint`, `schedule.split`, `TaskSchedule`, `PlannedTask.create`, `AdHocTask.create`, `printer.error`, `type`, `parse_task_plan`, `parse_task_schedule`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/scheduler_task_delete.py.dox.md b/api/scheduler_task_delete.py.dox.mdnew file mode 100644index 000000000..2112e95ee--- /dev/null+++ b/api/scheduler_task_delete.py.dox.md@@ -0,0 +1,44 @@+# scheduler_task_delete.py DOX++## Purpose++- Own the `scheduler_task_delete.py` API endpoint.+- This module handles scheduler task delete requests.+- Keep this file-level DOX profile synchronized with `scheduler_task_delete.py` because this directory is intentionally flat.++## Ownership++- `scheduler_task_delete.py` owns the runtime implementation.+- `scheduler_task_delete.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SchedulerTaskDelete` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SchedulerTaskDelete` is an `ApiHandler`.+- `SchedulerTaskDelete` defines `process(...)`.+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state.+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.localization`, `helpers.task_scheduler`.++## Key Concepts++- Important called helpers/classes observed in the source: `scheduler.get_task_by_uuid`, `Localization.get.set_timezone`, `scheduler.reload`, `self.use_context`, `scheduler.cancel_running_task`, `AgentContext.remove`, `persist_chat.remove_chat`, `scheduler.remove_task_by_uuid`, `context.reset`, `scheduler.update_task`, `scheduler.save`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/scheduler_task_run.py.dox.md b/api/scheduler_task_run.py.dox.mdnew file mode 100644index 000000000..f4aa4b158--- /dev/null+++ b/api/scheduler_task_run.py.dox.md@@ -0,0 +1,44 @@+# scheduler_task_run.py DOX++## Purpose++- Own the `scheduler_task_run.py` API endpoint.+- This module handles scheduler task run requests.+- Keep this file-level DOX profile synchronized with `scheduler_task_run.py` because this directory is intentionally flat.++## Ownership++- `scheduler_task_run.py` owns the runtime implementation.+- `scheduler_task_run.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SchedulerTaskRun` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SchedulerTaskRun` is an `ApiHandler`.+- `SchedulerTaskRun` defines `process(...)`.+- Observed side-effect areas: settings/state persistence, scheduler state.+- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`.++## Key Concepts++- Important called helpers/classes observed in the source: `PrintStyle`, `scheduler.get_task_by_uuid`, `Localization.get.set_timezone`, `scheduler.reload`, `self._printer.error`, `scheduler.serialize_task`, `scheduler.run_task_by_uuid`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/scheduler_task_update.py.dox.md b/api/scheduler_task_update.py.dox.mdnew file mode 100644index 000000000..a7c9bfced--- /dev/null+++ b/api/scheduler_task_update.py.dox.md@@ -0,0 +1,44 @@+# scheduler_task_update.py DOX++## Purpose++- Own the `scheduler_task_update.py` API endpoint.+- This module handles scheduler task update requests.+- Keep this file-level DOX profile synchronized with `scheduler_task_update.py` because this directory is intentionally flat.++## Ownership++- `scheduler_task_update.py` owns the runtime implementation.+- `scheduler_task_update.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SchedulerTaskUpdate` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SchedulerTaskUpdate` is an `ApiHandler`.+- `SchedulerTaskUpdate` defines `process(...)`.+- Observed side-effect areas: settings/state persistence, secret handling, scheduler state.+- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.task_scheduler`.++## Key Concepts++- Important called helpers/classes observed in the source: `scheduler.get_task_by_uuid`, `serialize_task`, `Localization.get.set_timezone`, `scheduler.reload`, `TaskState`, `scheduler.update_task`, `parse_task_schedule`, `parse_task_plan`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/scheduler_tasks_list.py.dox.md b/api/scheduler_tasks_list.py.dox.mdnew file mode 100644index 000000000..5e5533206--- /dev/null+++ b/api/scheduler_tasks_list.py.dox.md@@ -0,0 +1,44 @@+# scheduler_tasks_list.py DOX++## Purpose++- Own the `scheduler_tasks_list.py` API endpoint.+- This module handles scheduler tasks list requests.+- Keep this file-level DOX profile synchronized with `scheduler_tasks_list.py` because this directory is intentionally flat.++## Ownership++- `scheduler_tasks_list.py` owns the runtime implementation.+- `scheduler_tasks_list.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SchedulerTasksList` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SchedulerTasksList` is an `ApiHandler`.+- `SchedulerTasksList` defines `process(...)`.+- Observed side-effect areas: scheduler state.+- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`, `traceback`.++## Key Concepts++- Important called helpers/classes observed in the source: `scheduler.serialize_all_tasks`, `Localization.get.set_timezone`, `scheduler.reload`, `PrintStyle.error`, `traceback.format_exc`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/scheduler_tick.py.dox.md b/api/scheduler_tick.py.dox.mdnew file mode 100644index 000000000..d19ae305c--- /dev/null+++ b/api/scheduler_tick.py.dox.md@@ -0,0 +1,50 @@+# scheduler_tick.py DOX++## Purpose++- Own the `scheduler_tick.py` API endpoint.+- This module handles scheduler tick requests.+- Keep this file-level DOX profile synchronized with `scheduler_tick.py` because this directory is intentionally flat.++## Ownership++- `scheduler_tick.py` owns the runtime implementation.+- `scheduler_tick.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SchedulerTick` (`ApiHandler`)+ - `requires_loopback(cls) -> bool`+ - `requires_auth(cls) -> bool`+ - `requires_csrf(cls) -> bool`+ - `async process(self, input: Input, request: Request) -> Output`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SchedulerTick` is an `ApiHandler`.+- `SchedulerTick` defines `process(...)`.+- `SchedulerTick` defines `requires_auth(...)`.+- `SchedulerTick` defines `requires_csrf(...)`.+- `SchedulerTick` defines `requires_loopback(...)`.+- Observed side-effect areas: settings/state persistence, scheduler state.+- Imported dependency areas include: `datetime`, `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`.++## Key Concepts++- Important called helpers/classes observed in the source: `datetime.now.strftime`, `PrintStyle`, `scheduler.get_tasks`, `scheduler.serialize_all_tasks`, `Localization.get.set_timezone`, `scheduler.reload`, `scheduler.tick`, `datetime.now`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/self_update_get.py.dox.md b/api/self_update_get.py.dox.mdnew file mode 100644index 000000000..261cac93f--- /dev/null+++ b/api/self_update_get.py.dox.md@@ -0,0 +1,45 @@+# self_update_get.py DOX++## Purpose++- Own the `self_update_get.py` API endpoint.+- This module handles self update get API requests.+- Keep this file-level DOX profile synchronized with `self_update_get.py` because this directory is intentionally flat.++## Ownership++- `self_update_get.py` owns the runtime implementation.+- `self_update_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SelfUpdateGet` (`ApiHandler`)+ - `get_methods(cls) -> list[str]`+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SelfUpdateGet` is an `ApiHandler`.+- `SelfUpdateGet` defines `process(...)`.+- `SelfUpdateGet` defines `get_methods(...)`.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `self_update.get_update_info`, `runtime.is_dockerized`, `self_update.load_pending_update`, `self_update.load_last_status`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/self_update_schedule.py.dox.md b/api/self_update_schedule.py.dox.mdnew file mode 100644index 000000000..b865070c9--- /dev/null+++ b/api/self_update_schedule.py.dox.md@@ -0,0 +1,45 @@+# self_update_schedule.py DOX++## Purpose++- Own the `self_update_schedule.py` API endpoint.+- This module handles self update schedule API requests.+- Keep this file-level DOX profile synchronized with `self_update_schedule.py` because this directory is intentionally flat.++## Ownership++- `self_update_schedule.py` owns the runtime implementation.+- `self_update_schedule.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SelfUpdateSchedule` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SelfUpdateSchedule` is an `ApiHandler`.+- `SelfUpdateSchedule` defines `process(...)`.+- Observed side-effect areas: filesystem writes, subprocess/runtime control.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `runtime.is_dockerized`, `self_update.schedule_update`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_self_update_tag_filter.py`++## Child DOX Index++No child DOX files.diff --git a/api/self_update_tags.py.dox.md b/api/self_update_tags.py.dox.mdnew file mode 100644index 000000000..fdf78cd23--- /dev/null+++ b/api/self_update_tags.py.dox.md@@ -0,0 +1,43 @@+# self_update_tags.py DOX++## Purpose++- Own the `self_update_tags.py` API endpoint.+- This module handles self update tags API requests.+- Keep this file-level DOX profile synchronized with `self_update_tags.py` because this directory is intentionally flat.++## Ownership++- `self_update_tags.py` owns the runtime implementation.+- `self_update_tags.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SelfUpdateTags` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SelfUpdateTags` is an `ApiHandler`.+- `SelfUpdateTags` defines `process(...)`.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `str.strip.lower`, `self_update.get_repo_version_info.get.strip.lower`, `self_update.get_available_branch_values`, `self_update.get_selector_tag_options`, `str.strip`, `self_update.get_repo_version_info.get.strip`, `runtime.is_dockerized`, `self_update.get_repo_version_info`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/settings_get.py.dox.md b/api/settings_get.py.dox.mdnew file mode 100644index 000000000..e584283fd--- /dev/null+++ b/api/settings_get.py.dox.md@@ -0,0 +1,46 @@+# settings_get.py DOX++## Purpose++- Own the `settings_get.py` API endpoint.+- This module returns current application settings.+- Keep this file-level DOX profile synchronized with `settings_get.py` because this directory is intentionally flat.++## Ownership++- `settings_get.py` owns the runtime implementation.+- `settings_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `GetSettings` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`+ - `get_methods(cls) -> list[str]`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `GetSettings` is an `ApiHandler`.+- `GetSettings` defines `process(...)`.+- `GetSettings` defines `get_methods(...)`.+- Observed side-effect areas: settings/state persistence.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `settings.get_settings`, `settings.convert_out`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/settings_set.py.dox.md b/api/settings_set.py.dox.mdnew file mode 100644index 000000000..0f08f9862--- /dev/null+++ b/api/settings_set.py.dox.md@@ -0,0 +1,44 @@+# settings_set.py DOX++## Purpose++- Own the `settings_set.py` API endpoint.+- This module persists application settings updates.+- Keep this file-level DOX profile synchronized with `settings_set.py` because this directory is intentionally flat.++## Ownership++- `settings_set.py` owns the runtime implementation.+- `settings_set.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SetSettings` (`ApiHandler`)+ - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SetSettings` is an `ApiHandler`.+- `SetSettings` defines `process(...)`.+- Observed side-effect areas: settings/state persistence.+- Imported dependency areas include: `helpers`, `helpers.api`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `settings.convert_in`, `settings.set_settings`, `settings.convert_out`, `settings.Settings`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/settings_workdir_file_structure.py.dox.md b/api/settings_workdir_file_structure.py.dox.mdnew file mode 100644index 000000000..e52a742ef--- /dev/null+++ b/api/settings_workdir_file_structure.py.dox.md@@ -0,0 +1,46 @@+# settings_workdir_file_structure.py DOX++## Purpose++- Own the `settings_workdir_file_structure.py` API endpoint.+- This module handles settings workdir file structure API requests.+- Keep this file-level DOX profile synchronized with `settings_workdir_file_structure.py` because this directory is intentionally flat.++## Ownership++- `settings_workdir_file_structure.py` owns the runtime implementation.+- `settings_workdir_file_structure.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SettingsWorkdirFileStructure` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`+ - `get_methods(cls) -> list[str]`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SettingsWorkdirFileStructure` is an `ApiHandler`.+- `SettingsWorkdirFileStructure` defines `process(...)`.+- `SettingsWorkdirFileStructure` defines `get_methods(...)`.+- Observed side-effect areas: filesystem reads, settings/state persistence.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `files.get_abs_path_development`, `Exception`, `file_tree.file_tree`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/skills.py.dox.md b/api/skills.py.dox.mdnew file mode 100644index 000000000..8da5af317--- /dev/null+++ b/api/skills.py.dox.md@@ -0,0 +1,54 @@+# skills.py DOX++## Purpose++- Own the `skills.py` API endpoint.+- This module lists and manages available skills for settings and agent-facing skill flows.+- 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:+- `Skills` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`+ - `list_skills(self, input: Input)`+ - `delete_skill(self, input: Input)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Skills` is an `ApiHandler`.+- `Skills` defines `process(...)`.+- Observed side-effect areas: filesystem reads, filesystem deletion.+- Imported dependency areas include: `helpers`, `helpers.api`.++## Key Concepts++- Important called helpers/classes observed in the source: `skills.list_skills`, `result.sort`, `str.strip`, `skills.delete_skill`, `projects.get_project_folder`, `runtime.is_development`, `Exception`, `self.list_skills`, `strip`, `files.normalize_a0_path`, `files.get_abs_path`, `self.delete_skill`, `files.is_in_dir`, `projects.get_project_meta`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- 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.diff --git a/api/skills_import.py.dox.md b/api/skills_import.py.dox.mdnew file mode 100644index 000000000..4940e833a--- /dev/null+++ b/api/skills_import.py.dox.md@@ -0,0 +1,44 @@+# skills_import.py DOX++## Purpose++- Own the `skills_import.py` API endpoint.+- This module handles skills import API requests.+- 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:+- `SkillsImport` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SkillsImport` is an `ApiHandler`.+- `SkillsImport` defines `process(...)`.+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.+- Imported dependency areas include: `__future__`, `helpers`, `helpers.api`, `helpers.skills_import`, `os`, `pathlib`, `time`, `uuid`, `werkzeug.datastructures`, `werkzeug.utils`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.use_context`, `strip.lower`, `Path`, `tmp_dir.mkdir`, `secure_filename`, `time.strftime`, `skills_file.save`, `strip`, `files.get_abs_path`, `base.lower.endswith`, `import_skills`, `files.deabsolute_path`, `uuid.uuid4`, `tmp_path.unlink`, `base.lower`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/skills_import_preview.py.dox.md b/api/skills_import_preview.py.dox.mdnew file mode 100644index 000000000..107f55b2a--- /dev/null+++ b/api/skills_import_preview.py.dox.md@@ -0,0 +1,44 @@+# skills_import_preview.py DOX++## Purpose++- Own the `skills_import_preview.py` API endpoint.+- This module handles skills import preview API requests.+- Keep this file-level DOX profile synchronized with `skills_import_preview.py` because this directory is intentionally flat.++## Ownership++- `skills_import_preview.py` owns the runtime implementation.+- `skills_import_preview.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SkillsImportPreview` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `SkillsImportPreview` is an `ApiHandler`.+- `SkillsImportPreview` defines `process(...)`.+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.+- Imported dependency areas include: `__future__`, `helpers`, `helpers.api`, `helpers.skills_import`, `os`, `pathlib`, `time`, `uuid`, `werkzeug.datastructures`, `werkzeug.utils`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.use_context`, `strip.lower`, `Path`, `tmp_dir.mkdir`, `secure_filename`, `time.strftime`, `skills_file.save`, `strip`, `files.get_abs_path`, `base.lower.endswith`, `import_skills`, `files.deabsolute_path`, `uuid.uuid4`, `tmp_path.unlink`, `base.lower`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/subagents.py.dox.md b/api/subagents.py.dox.mdnew file mode 100644index 000000000..85777218f--- /dev/null+++ b/api/subagents.py.dox.md@@ -0,0 +1,49 @@+# subagents.py DOX++## Purpose++- Own the `subagents.py` API endpoint.+- This module returns subordinate agent profile data for UI and delegation flows.+- 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:+- `Subagents` (`ApiHandler`)+ - `async process(self, input: Input, request: Request) -> Output`+ - `get_subagents_list(self)`+ - `load_agent(self, name: str | None)`+ - `save_agent(self, name: str | None, data: dict | None)`+ - `delete_agent(self, name: str | None)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Subagents` is an `ApiHandler`.+- `Subagents` defines `process(...)`.+- Observed side-effect areas: filesystem writes, filesystem deletion.+- Imported dependency areas include: `helpers`, `helpers.api`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `subagents.get_agents_list`, `subagents.load_agent_data`, `subagents.SubAgent`, `subagents.save_agent_data`, `subagents.delete_agent_data`, `self.use_context`, `Exception`, `self.get_subagents_list`, `self.load_agent`, `self.save_agent`, `self.delete_agent`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_skills_runtime.py`++## Child DOX Index++No child DOX files.diff --git a/api/tunnel.py.dox.md b/api/tunnel.py.dox.mdnew file mode 100644index 000000000..3618edc6e--- /dev/null+++ b/api/tunnel.py.dox.md@@ -0,0 +1,48 @@+# tunnel.py DOX++## Purpose++- Own the `tunnel.py` API endpoint.+- This module manages tunnel provider status, start, and stop actions.+- Keep this file-level DOX profile synchronized with `tunnel.py` because this directory is intentionally flat.++## Ownership++- `tunnel.py` owns the runtime implementation.+- `tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Tunnel` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`+- Top-level functions:+- `async process(input: dict) -> dict | Response`+- `stop()`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `Tunnel` is an `ApiHandler`.+- `Tunnel` defines `process(...)`.+- Observed side-effect areas: tunnel state.+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.tunnel_manager`.++## Key Concepts++- Important called helpers/classes observed in the source: `TunnelManager.get_instance`, `tunnel_manager.stop_tunnel`, `runtime.get_web_ui_port`, `tunnel_manager.start_tunnel`, `tunnel_manager.get_last_error`, `process`, `tunnel_manager.get_notifications`, `stop`, `tunnel_manager.get_tunnel_url`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_tunnel_remote_link.py`++## Child DOX Index++No child DOX files.diff --git a/api/tunnel_proxy.py.dox.md b/api/tunnel_proxy.py.dox.mdnew file mode 100644index 000000000..b713482c9--- /dev/null+++ b/api/tunnel_proxy.py.dox.md@@ -0,0 +1,46 @@+# tunnel_proxy.py DOX++## Purpose++- Own the `tunnel_proxy.py` API endpoint.+- This module proxies tunnel-related HTTP traffic through the configured tunnel provider.+- Keep this file-level DOX profile synchronized with `tunnel_proxy.py` because this directory is intentionally flat.++## Ownership++- `tunnel_proxy.py` owns the runtime implementation.+- `tunnel_proxy.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `TunnelProxy` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`+- Top-level functions:+- `async process(input: dict) -> dict | Response`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `TunnelProxy` is an `ApiHandler`.+- `TunnelProxy` defines `process(...)`.+- Observed side-effect areas: network calls, settings/state persistence, tunnel state.+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.tunnel_manager`, `requests`.++## Key Concepts++- Important called helpers/classes observed in the source: `runtime.get_arg`, `requests.post`, `process`, `dotenv.get_dotenv_value`, `response.json`, `local_process`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/upload.py.dox.md b/api/upload.py.dox.mdnew file mode 100644index 000000000..9fccb571f--- /dev/null+++ b/api/upload.py.dox.md@@ -0,0 +1,47 @@+# upload.py DOX++## Purpose++- Own the `upload.py` API endpoint.+- This module accepts general uploads into runtime upload storage.+- Keep this file-level DOX profile synchronized with `upload.py` because this directory is intentionally flat.++## Ownership++- `upload.py` owns the runtime implementation.+- `upload.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `UploadFile` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`+ - `allowed_file(self, filename)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `UploadFile` is an `ApiHandler`.+- `UploadFile` defines `process(...)`.+- Observed side-effect areas: filesystem reads, settings/state persistence.+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.security`.++## Key Concepts++- Important called helpers/classes observed in the source: `request.files.getlist`, `Exception`, `self.allowed_file`, `safe_filename`, `file.save`, `files.get_abs_path`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `tests/test_browser_agent_regressions.py`+ - `tests/test_image_get_security.py`++## Child DOX Index++No child DOX files.diff --git a/api/upload_work_dir_files.py.dox.md b/api/upload_work_dir_files.py.dox.mdnew file mode 100644index 000000000..6cf9370ae--- /dev/null+++ b/api/upload_work_dir_files.py.dox.md@@ -0,0 +1,47 @@+# upload_work_dir_files.py DOX++## Purpose++- Own the `upload_work_dir_files.py` API endpoint.+- This module handles workdir file operations for upload work dir files.+- Keep this file-level DOX profile synchronized with `upload_work_dir_files.py` because this directory is intentionally flat.++## Ownership++- `upload_work_dir_files.py` owns the runtime implementation.+- `upload_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `UploadWorkDirFiles` (`ApiHandler`)+ - `async process(self, input: dict, request: Request) -> dict | Response`+- Top-level functions:+- `async upload_files(uploaded_files: list[FileStorage], current_path: str)`+- `async upload_file(current_path: str, filename: str, base64_content: str)`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `UploadWorkDirFiles` is an `ApiHandler`.+- `UploadWorkDirFiles` defines `process(...)`.+- Observed side-effect areas: filesystem writes.+- Imported dependency areas include: `api`, `base64`, `helpers`, `helpers.api`, `helpers.file_browser`, `os`, `posixpath`, `werkzeug.datastructures`.++## Key Concepts++- Important called helpers/classes observed in the source: `runtime.is_development`, `FileBrowser`, `browser.save_file_b64`, `request.files.getlist`, `browser.save_files`, `Exception`, `upload_files`, `runtime.call_development_function`, `file.stream.read`, `base64.b64encode.decode`, `extension.call_extensions_async`, `base64.b64encode`, `posixpath.join`, `str.rstrip`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/ws_dev_test.py.dox.md b/api/ws_dev_test.py.dox.mdnew file mode 100644index 000000000..aaad42608--- /dev/null+++ b/api/ws_dev_test.py.dox.md@@ -0,0 +1,44 @@+# ws_dev_test.py DOX++## Purpose++- Own the `ws_dev_test.py` API endpoint.+- This module provides a development WebSocket test namespace.+- Keep this file-level DOX profile synchronized with `ws_dev_test.py` because this directory is intentionally flat.++## Ownership++- `ws_dev_test.py` owns the runtime implementation.+- `ws_dev_test.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `WsDevTest` (`WsHandler`)+ - `async process(self, event: str, data: dict, sid: str) -> dict[str, Any] | WsResult | None`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `WsDevTest` is a `WsHandler`.+- `WsDevTest` defines `process(...)`.+- Observed side-effect areas: filesystem writes, network calls, WebSocket state.+- Imported dependency areas include: `asyncio`, `helpers`, `helpers.print_style`, `helpers.ws`, `helpers.ws_manager`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `event.startswith`, `self.manager.register_diagnostic_watcher`, `self.manager.unregister_diagnostic_watcher`, `PrintStyle.info`, `PrintStyle.debug`, `PrintStyle.warning`, `runtime.is_development`, `WsResult.error`, `self.broadcast`, `asyncio.sleep`, `self.emit_to`, `self.dispatch_to_all_sids`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/ws_hello.py.dox.md b/api/ws_hello.py.dox.mdnew file mode 100644index 000000000..863b99167--- /dev/null+++ b/api/ws_hello.py.dox.md@@ -0,0 +1,44 @@+# ws_hello.py DOX++## Purpose++- Own the `ws_hello.py` API endpoint.+- This module provides a small WebSocket hello/test namespace.+- Keep this file-level DOX profile synchronized with `ws_hello.py` because this directory is intentionally flat.++## Ownership++- `ws_hello.py` owns the runtime implementation.+- `ws_hello.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `WsHello` (`WsHandler`)+ - `async process(self, event: str, data: dict, sid: str) -> dict | None`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `WsHello` is a `WsHandler`.+- `WsHello` defines `process(...)`.+- Observed side-effect areas: WebSocket state.+- Imported dependency areas include: `helpers.print_style`, `helpers.ws`.++## Key Concepts++- Important called helpers/classes observed in the source: `PrintStyle.info`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/api/ws_webui.py.dox.md b/api/ws_webui.py.dox.mdnew file mode 100644index 000000000..a9cebf317--- /dev/null+++ b/api/ws_webui.py.dox.md@@ -0,0 +1,49 @@+# ws_webui.py DOX++## Purpose++- Own the `ws_webui.py` API endpoint.+- This module owns the primary WebUI WebSocket namespace and event bridge.+- Keep this file-level DOX profile synchronized with `ws_webui.py` because this directory is intentionally flat.++## Ownership++- `ws_webui.py` owns the runtime implementation.+- `ws_webui.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `WsWebui` (`WsHandler`)+ - `async on_connect(self, sid: str) -> None`+ - `async on_disconnect(self, sid: str) -> None`+ - `async process(self, event: str, data: dict, sid: str) -> dict | None`++## Runtime Contracts++- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.+- `WsWebui` is a `WsHandler`.+- `WsWebui` defines `process(...)`.+- Observed side-effect areas: network calls, WebSocket state, settings/state persistence.+- Imported dependency areas include: `helpers`, `helpers.ws`.++## Key Concepts++- Important called helpers/classes observed in the source: `extension.call_extensions_async`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.+- Update frontend callers, plugin callers, and tests together when payload shape changes.+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.++## Verification++- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.+- Related tests observed by source search:+ - `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.diff --git a/docker/AGENTS.md b/docker/AGENTS.mdindex 0b58f32e8..757608953 100644--- a/docker/AGENTS.md+++ b/docker/AGENTS.md@@ -31,4 +31,9 @@## Child DOX Index-No child DOX files.+Direct child DOX files:++| Child | Scope |+| --- | --- |+| [base/AGENTS.md](base/AGENTS.md) | Base image Dockerfile, copied filesystem, and installation scripts. |+| [run/AGENTS.md](run/AGENTS.md) | Runnable image Dockerfile, compose example, entrypoints, and install scripts. |diff --git a/docker/base/AGENTS.md b/docker/base/AGENTS.mdnew file mode 100644index 000000000..bcfb986d7--- /dev/null+++ b/docker/base/AGENTS.md@@ -0,0 +1,34 @@+# Docker Base Image DOX++## Purpose++- Own the Agent Zero base image build context.+- Build the operating system, package, Python, SearXNG, SSH, and bootstrap layers reused by runnable images.++## Ownership++- `Dockerfile` owns base image layering and installation order.+- `build.txt` owns maintainer build and push command notes.+- `fs/ins/` owns installation scripts copied into the image.+- Files under `fs/` are copied to container root during the base build.++## Local Contracts++- Preserve cache-friendly package and runtime installation stages.+- Keep locale and timezone defaults compatible with the root Docker contract.+- Do not add secrets, user data, or local environment files to the image context.+- Installation scripts must be noninteractive and suitable for multi-architecture buildx runs.++## Work Guidance++- Keep base dependencies here only when they are common to runnable Agent Zero images.+- Coordinate Python runtime changes with root Docker documentation and runnable image setup.++## Verification++- Build `docker/base` when changing Dockerfile or install scripts.+- Run a runnable image smoke check when base runtime behavior changes.++## Child DOX Index++No child DOX files.diff --git a/docker/run/AGENTS.md b/docker/run/AGENTS.mdnew file mode 100644index 000000000..f2bacfdf2--- /dev/null+++ b/docker/run/AGENTS.md@@ -0,0 +1,36 @@+# Docker Runtime Image DOX++## Purpose++- Own the runnable Agent Zero image context and local compose example.+- Install Agent Zero from a selected branch onto the base image and prepare runtime entrypoints.++## Ownership++- `Dockerfile` owns branch-based image assembly, exposed ports, and container startup command.+- `docker-compose.yml` owns the local compose service example.+- `build.txt` owns maintainer build and push command notes.+- `fs/exe/` owns runtime entrypoint, supervisor, self-update, Node eval, and service scripts.+- `fs/ins/` owns preinstall, installation, virtualenv, Playwright, SSH, and postinstall scripts.+- Files under `fs/` are copied to container root during the runtime build.++## Local Contracts++- `BRANCH` is required for branch-based Docker builds.+- Preserve exposed ports for SSH, HTTP, and tunneled services unless docs and workflows are updated together.+- Keep the two-runtime Python model aligned with the root contract.+- Do not bake secrets, local `.env` values, or user data into the image.++## Work Guidance++- Keep startup scripts explicit about framework runtime versus execution runtime.+- Coordinate tag, branch, and publishing changes with GitHub workflow automation.++## Verification++- Build `docker/run` when changing Dockerfile or install scripts.+- Smoke-test container startup after entrypoint, supervisor, port, or compose changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/AGENTS.md b/extensions/python/AGENTS.mdindex 53538a8e1..270a98afd 100644--- a/extensions/python/AGENTS.md+++ b/extensions/python/AGENTS.md@@ -31,4 +31,37 @@## Child DOX Index-No child DOX files.+Direct child DOX files:++| Child | Scope |+| --- | --- |+| [_functions/AGENTS.md](_functions/AGENTS.md) | Implicit `@extensible` backend hook implementations. |+| [agent_init/AGENTS.md](agent_init/AGENTS.md) | Agent context initialization hooks. |+| [banners/AGENTS.md](banners/AGENTS.md) | Backend banner and discovery-card contributions. |+| [before_main_llm_call/AGENTS.md](before_main_llm_call/AGENTS.md) | Pre-main-model-call behavior. |+| [error_format/AGENTS.md](error_format/AGENTS.md) | Error formatting and masking behavior. |+| [hist_add_before/AGENTS.md](hist_add_before/AGENTS.md) | Pre-history-insertion masking behavior. |+| [hist_add_tool_result/AGENTS.md](hist_add_tool_result/AGENTS.md) | Tool-result history side effects. |+| [job_loop/AGENTS.md](job_loop/AGENTS.md) | Periodic backend maintenance jobs. |+| [message_loop_end/AGENTS.md](message_loop_end/AGENTS.md) | End-of-message-loop history and persistence behavior. |+| [message_loop_prompts_after/AGENTS.md](message_loop_prompts_after/AGENTS.md) | Prompt extras appended after message-loop prompt construction. |+| [message_loop_prompts_before/AGENTS.md](message_loop_prompts_before/AGENTS.md) | Pre-prompt-construction message-loop gates. |+| [message_loop_start/AGENTS.md](message_loop_start/AGENTS.md) | Start-of-message-loop iteration state. |+| [monologue_end/AGENTS.md](monologue_end/AGENTS.md) | End-of-monologue UI and cleanup behavior. |+| [monologue_start/AGENTS.md](monologue_start/AGENTS.md) | Start-of-monologue behavior such as chat renaming. |+| [process_chain_end/AGENTS.md](process_chain_end/AGENTS.md) | Process-chain completion and queued-message handling. |+| [reasoning_stream/AGENTS.md](reasoning_stream/AGENTS.md) | Full reasoning stream handling. |+| [reasoning_stream_chunk/AGENTS.md](reasoning_stream_chunk/AGENTS.md) | Reasoning stream chunk masking. |+| [reasoning_stream_end/AGENTS.md](reasoning_stream_end/AGENTS.md) | Reasoning stream finalization. |+| [response_stream/AGENTS.md](response_stream/AGENTS.md) | Full assistant response stream handling. |+| [response_stream_chunk/AGENTS.md](response_stream_chunk/AGENTS.md) | Assistant response chunk masking. |+| [response_stream_end/AGENTS.md](response_stream_end/AGENTS.md) | Assistant response stream finalization. |+| [startup_migration/AGENTS.md](startup_migration/AGENTS.md) | Startup migrations. |+| [system_prompt/AGENTS.md](system_prompt/AGENTS.md) | Core system prompt section construction. |+| [tool_execute_after/AGENTS.md](tool_execute_after/AGENTS.md) | Post-tool-execution processing. |+| [tool_execute_before/AGENTS.md](tool_execute_before/AGENTS.md) | Pre-tool-execution processing. |+| [user_message_ui/AGENTS.md](user_message_ui/AGENTS.md) | User-visible UI message hooks. |+| [util_model_call_before/AGENTS.md](util_model_call_before/AGENTS.md) | Pre-utility-model-call masking. |+| [webui_ws_connect/AGENTS.md](webui_ws_connect/AGENTS.md) | WebUI WebSocket connect behavior. |+| [webui_ws_disconnect/AGENTS.md](webui_ws_disconnect/AGENTS.md) | WebUI WebSocket disconnect behavior. |+| [webui_ws_event/AGENTS.md](webui_ws_event/AGENTS.md) | Incoming WebUI WebSocket event behavior. |diff --git a/extensions/python/_functions/AGENTS.md b/extensions/python/_functions/AGENTS.mdnew file mode 100644index 000000000..0b21bd510--- /dev/null+++ b/extensions/python/_functions/AGENTS.md@@ -0,0 +1,29 @@+# Python Function Extensions DOX++## Purpose++- Own implicit `@extensible` backend hook implementations.+- Preserve nested module, class/function, method, and `start`/`end` extension layout.++## Ownership++- Each nested path mirrors a Python module and qualname segment.+- Leaf `start/` and `end/` directories own ordered extension files for that extensible function point.++## Local Contracts++- Do not flatten nested qualname paths into retired legacy folder names.+- Extension functions must match the implicit hook's supplied arguments.+- Preserve ordering prefixes where exception handling, watchdog registration, or cleanup depends on them.++## Work Guidance++- Keep implicit hook extensions narrow and colocated with the exact function point they extend.++## Verification++- Run targeted tests for the affected function point after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/agent_init/AGENTS.md b/extensions/python/agent_init/AGENTS.mdnew file mode 100644index 000000000..3121c8244--- /dev/null+++ b/extensions/python/agent_init/AGENTS.md@@ -0,0 +1,26 @@+# Agent Init Extensions DOX++## Purpose++- Own backend extensions that run when an agent context initializes.++## Ownership++- Ordered Python files own initial UI message setup and profile settings load behavior.++## Local Contracts++- Keep initialization idempotent for contexts that may be restored or reloaded.+- Preserve ordering between initial message creation and profile settings loading.++## Work Guidance++- Coordinate changes with profile loading, settings resolution, and startup smoke checks.++## Verification++- Smoke-test new chat/context initialization after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/banners/AGENTS.md b/extensions/python/banners/AGENTS.mdnew file mode 100644index 000000000..d49581a27--- /dev/null+++ b/extensions/python/banners/AGENTS.md@@ -0,0 +1,27 @@+# Banner Extensions DOX++## Purpose++- Own backend banner and discovery-card contributions.++## Ownership++- Ordered Python files append alert banners or discovery cards to the mutable `banners` list.++## Local Contracts++- Banner IDs must be unique and stable.+- Use supported banner/card fields and types only.+- Do not expose secrets, local paths, or raw system diagnostics in banner text.++## Work Guidance++- Gate setup or warning banners on current configuration/status where possible.++## Verification++- Smoke-test welcome-screen banner rendering, ordering, dismissal, and CTA behavior after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/before_main_llm_call/AGENTS.md b/extensions/python/before_main_llm_call/AGENTS.mdnew file mode 100644index 000000000..36214e3b3--- /dev/null+++ b/extensions/python/before_main_llm_call/AGENTS.md@@ -0,0 +1,26 @@+# Before Main LLM Call Extensions DOX++## Purpose++- Own backend behavior that runs immediately before the main LLM call.++## Ownership++- Ordered Python files own pre-call logging or context preparation for streaming/model execution.++## Local Contracts++- Do not mutate prompt or history data unless the hook contract explicitly passes mutable state for that purpose.+- Avoid logging secrets, hidden prompt sections, or private user data.++## Work Guidance++- Keep this hook light because it sits on the main model hot path.++## Verification++- Run targeted model-call or streaming tests after behavior changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/error_format/AGENTS.md b/extensions/python/error_format/AGENTS.mdnew file mode 100644index 000000000..6dd136a73--- /dev/null+++ b/extensions/python/error_format/AGENTS.md@@ -0,0 +1,26 @@+# Error Format Extensions DOX++## Purpose++- Own backend error formatting and masking before errors are shown or logged.++## Ownership++- Ordered Python files own mutation of error-format data passed by the hook.++## Local Contracts++- Preserve secret masking and safe user-facing error messages.+- Do not expose raw tokens, credentials, hidden prompts, or private payloads.++## Work Guidance++- Keep masking rules conservative and synchronized with tool/model error surfaces.++## Verification++- Test or inspect representative masked and unmasked error paths after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/hist_add_before/AGENTS.md b/extensions/python/hist_add_before/AGENTS.mdnew file mode 100644index 000000000..7553e0618--- /dev/null+++ b/extensions/python/hist_add_before/AGENTS.md@@ -0,0 +1,26 @@+# History Add Before Extensions DOX++## Purpose++- Own preprocessing before messages are added to agent history.++## Ownership++- Ordered Python files own history content masking before persistence or model reuse.++## Local Contracts++- Preserve secret and sensitive-content masking before history storage.+- Do not remove fields required by downstream history organization or replay.++## Work Guidance++- Coordinate history mutation changes with message persistence and memory behavior.++## Verification++- Test message history insertion for masked content after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/hist_add_tool_result/AGENTS.md b/extensions/python/hist_add_tool_result/AGENTS.mdnew file mode 100644index 000000000..0c92126a9--- /dev/null+++ b/extensions/python/hist_add_tool_result/AGENTS.md@@ -0,0 +1,26 @@+# History Tool Result Extensions DOX++## Purpose++- Own processing after tool results are added to history.++## Ownership++- Ordered Python files own tool-call file persistence and related history side effects.++## Local Contracts++- Preserve tool result traceability without leaking secrets.+- Keep file artifacts inside expected runtime/user-owned paths.++## Work Guidance++- Coordinate changes with tool output storage and chat persistence behavior.++## Verification++- Smoke-test a tool call that produces persisted output after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/job_loop/AGENTS.md b/extensions/python/job_loop/AGENTS.mdnew file mode 100644index 000000000..afa7597a3--- /dev/null+++ b/extensions/python/job_loop/AGENTS.md@@ -0,0 +1,26 @@+# Job Loop Extensions DOX++## Purpose++- Own periodic backend maintenance jobs.++## Ownership++- Ordered Python files own cleanup of expired API chats, cache trimming, and future job-loop tasks.++## Local Contracts++- Jobs must be idempotent and safe to run repeatedly.+- Keep cleanup scoped to owned caches, temporary contexts, or documented runtime state.++## Work Guidance++- Avoid expensive work on every loop; use timestamps or thresholds when practical.++## Verification++- Run targeted cleanup/cache tests or smoke-test job-loop startup after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/message_loop_end/AGENTS.md b/extensions/python/message_loop_end/AGENTS.mdnew file mode 100644index 000000000..8927890a9--- /dev/null+++ b/extensions/python/message_loop_end/AGENTS.md@@ -0,0 +1,26 @@+# Message Loop End Extensions DOX++## Purpose++- Own backend behavior that runs after a message loop completes.++## Ownership++- Ordered Python files own history organization and chat persistence at loop end.++## Local Contracts++- Preserve history consistency before saving chats.+- Do not skip persistence for successful loops unless the hook contract explicitly permits it.++## Work Guidance++- Coordinate changes with chat serialization, history organization, and WebUI refresh behavior.++## Verification++- Smoke-test sending a message, reloading the chat, and checking persisted history after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/message_loop_prompts_after/AGENTS.md b/extensions/python/message_loop_prompts_after/AGENTS.mdnew file mode 100644index 000000000..c19db6eb0--- /dev/null+++ b/extensions/python/message_loop_prompts_after/AGENTS.md@@ -0,0 +1,27 @@+# Message Loop Prompts After Extensions DOX++## Purpose++- Own prompt extras appended after primary message-loop prompt construction.++## Ownership++- Ordered Python files own current datetime, skill recall/load context, agent info, and workdir extras injection.++## Local Contracts++- Keep injected content bounded and clearly attributed.+- Preserve ordering where later prompt extras depend on earlier recall or load results.+- Do not expose secrets or private files from workdir extras.++## Work Guidance++- Coordinate prompt-extra changes with skill, workdir, and profile contracts.++## Verification++- Inspect rendered prompt extras or run prompt-construction tests after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/message_loop_prompts_before/AGENTS.md b/extensions/python/message_loop_prompts_before/AGENTS.mdnew file mode 100644index 000000000..3483592c7--- /dev/null+++ b/extensions/python/message_loop_prompts_before/AGENTS.md@@ -0,0 +1,26 @@+# Message Loop Prompts Before Extensions DOX++## Purpose++- Own preprocessing before message-loop prompt construction.++## Ownership++- Ordered Python files own history organization waits and related prompt-preparation gates.++## Local Contracts++- Preserve history consistency before prompts are assembled.+- Avoid blocking indefinitely on background organization tasks.++## Work Guidance++- Keep waiting behavior observable and bounded.++## Verification++- Smoke-test prompt construction after chats with pending history organization.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/message_loop_start/AGENTS.md b/extensions/python/message_loop_start/AGENTS.mdnew file mode 100644index 000000000..a0c6c1790--- /dev/null+++ b/extensions/python/message_loop_start/AGENTS.md@@ -0,0 +1,26 @@+# Message Loop Start Extensions DOX++## Purpose++- Own backend behavior that runs at the start of each message loop iteration.++## Ownership++- Ordered Python files own iteration counters and future loop-start state setup.++## Local Contracts++- Keep per-loop counters deterministic and scoped to the active context.+- Do not reset state owned by monologue-level hooks.++## Work Guidance++- Coordinate loop-start state changes with logging, streaming, and process-chain behavior.++## Verification++- Smoke-test multi-turn conversations after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/monologue_end/AGENTS.md b/extensions/python/monologue_end/AGENTS.mdnew file mode 100644index 000000000..b842ba071--- /dev/null+++ b/extensions/python/monologue_end/AGENTS.md@@ -0,0 +1,26 @@+# Monologue End Extensions DOX++## Purpose++- Own backend behavior that runs when a monologue ends.++## Ownership++- Ordered Python files own waiting-for-input UI message behavior and future monologue-end cleanup.++## Local Contracts++- Preserve clear UI state when the agent stops for user input.+- Do not leave loading/processing indicators stale.++## Work Guidance++- Coordinate changes with WebUI loading state and message-loop persistence.++## Verification++- Smoke-test an agent response that returns to waiting-for-input state.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/monologue_start/AGENTS.md b/extensions/python/monologue_start/AGENTS.mdnew file mode 100644index 000000000..93615ed68--- /dev/null+++ b/extensions/python/monologue_start/AGENTS.md@@ -0,0 +1,26 @@+# Monologue Start Extensions DOX++## Purpose++- Own backend behavior that runs when a monologue starts.++## Ownership++- Ordered Python files own automatic chat renaming and future monologue-start setup.++## Local Contracts++- Keep automatic rename behavior bounded and non-destructive.+- Do not override explicit user chat names without the intended guard conditions.++## Work Guidance++- Coordinate rename behavior with chat persistence and WebUI refresh.++## Verification++- Smoke-test new chat naming and existing named chat behavior after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/process_chain_end/AGENTS.md b/extensions/python/process_chain_end/AGENTS.mdnew file mode 100644index 000000000..c70340417--- /dev/null+++ b/extensions/python/process_chain_end/AGENTS.md@@ -0,0 +1,26 @@+# Process Chain End Extensions DOX++## Purpose++- Own backend behavior after process-chain execution completes.++## Ownership++- Ordered Python files own queued-message processing and future process-chain completion behavior.++## Local Contracts++- Preserve queue ordering and avoid duplicate message processing.+- Keep queue side effects synchronized with chat persistence and WebUI state.++## Work Guidance++- Coordinate changes with message queue components and external integration plugins.++## Verification++- Smoke-test queued messages and final response handling after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/reasoning_stream/AGENTS.md b/extensions/python/reasoning_stream/AGENTS.mdnew file mode 100644index 000000000..6cd3e6b2e--- /dev/null+++ b/extensions/python/reasoning_stream/AGENTS.md@@ -0,0 +1,26 @@+# Reasoning Stream Extensions DOX++## Purpose++- Own handling of full reasoning stream updates.++## Ownership++- Ordered Python files own logging reasoning content from stream state.++## Local Contracts++- Preserve masking and privacy rules for reasoning content.+- Keep stream logging compatible with chunk and end hooks.++## Work Guidance++- Coordinate reasoning stream changes with UI log rendering and hidden-content policy.++## Verification++- Smoke-test reasoning stream display/logging when the active model provides reasoning.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/reasoning_stream_chunk/AGENTS.md b/extensions/python/reasoning_stream_chunk/AGENTS.mdnew file mode 100644index 000000000..4e7461224--- /dev/null+++ b/extensions/python/reasoning_stream_chunk/AGENTS.md@@ -0,0 +1,26 @@+# Reasoning Stream Chunk Extensions DOX++## Purpose++- Own handling of incremental reasoning stream chunks.++## Ownership++- Ordered Python files own chunk-level masking before reasoning is displayed or stored.++## Local Contracts++- Mask secrets and sensitive content before chunk data reaches logs or UI.+- Keep chunk mutation compatible with final stream-end masking.++## Work Guidance++- Keep chunk processing lightweight for streaming performance.++## Verification++- Smoke-test streamed reasoning with representative sensitive patterns after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/reasoning_stream_end/AGENTS.md b/extensions/python/reasoning_stream_end/AGENTS.mdnew file mode 100644index 000000000..d702b22ad--- /dev/null+++ b/extensions/python/reasoning_stream_end/AGENTS.md@@ -0,0 +1,26 @@+# Reasoning Stream End Extensions DOX++## Purpose++- Own finalization of reasoning stream content.++## Ownership++- Ordered Python files own final reasoning masking and end-of-stream cleanup.++## Local Contracts++- Preserve final masking even if earlier chunk masking missed content.+- Keep end-state consistent with reasoning stream log entries.++## Work Guidance++- Coordinate final masking changes with chunk masking and UI rendering.++## Verification++- Smoke-test reasoning stream completion with sensitive-content cases.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/response_stream/AGENTS.md b/extensions/python/response_stream/AGENTS.mdnew file mode 100644index 000000000..53a42df09--- /dev/null+++ b/extensions/python/response_stream/AGENTS.md@@ -0,0 +1,27 @@+# Response Stream Extensions DOX++## Purpose++- Own handling of full assistant response stream updates.++## Ownership++- Ordered Python files own response logging, include-alias replacement, and live response updates.++## Local Contracts++- Keep streaming output synchronized with UI log items.+- Preserve include-alias replacement semantics where prompts/tools rely on them.+- Do not expose unmasked secrets in live responses.++## Work Guidance++- Coordinate stream changes with chunk/end hooks and message rendering.++## Verification++- Smoke-test streamed responses, live updates, and include alias replacement after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/response_stream_chunk/AGENTS.md b/extensions/python/response_stream_chunk/AGENTS.mdnew file mode 100644index 000000000..9ceff97a6--- /dev/null+++ b/extensions/python/response_stream_chunk/AGENTS.md@@ -0,0 +1,26 @@+# Response Stream Chunk Extensions DOX++## Purpose++- Own handling of incremental assistant response chunks.++## Ownership++- Ordered Python files own chunk-level response masking.++## Local Contracts++- Mask secrets before response chunks reach UI or persisted logs.+- Keep chunk processing compatible with final response stream masking.++## Work Guidance++- Keep per-chunk work lightweight for streaming responsiveness.++## Verification++- Smoke-test streaming responses with sensitive patterns after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/response_stream_end/AGENTS.md b/extensions/python/response_stream_end/AGENTS.mdnew file mode 100644index 000000000..963620e5d--- /dev/null+++ b/extensions/python/response_stream_end/AGENTS.md@@ -0,0 +1,26 @@+# Response Stream End Extensions DOX++## Purpose++- Own finalization of assistant response stream content.++## Ownership++- Ordered Python files own final masking and stream-end log updates.++## Local Contracts++- Preserve final masking before response content is considered complete.+- Keep log state consistent with streamed chunks and final response text.++## Work Guidance++- Coordinate finalization changes with live response and message rendering behavior.++## Verification++- Smoke-test response completion and persisted message display after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/startup_migration/AGENTS.md b/extensions/python/startup_migration/AGENTS.mdnew file mode 100644index 000000000..a4c9e202a--- /dev/null+++ b/extensions/python/startup_migration/AGENTS.md@@ -0,0 +1,27 @@+# Startup Migration Extensions DOX++## Purpose++- Own backend startup migrations.++## Ownership++- Ordered Python files in this folder own idempotent migration steps that run during startup.++## Local Contracts++- Migrations must be safe to run repeatedly.+- Preserve user data and create backups or reversible paths when changing durable state.+- Keep long-running work bounded and observable.++## Work Guidance++- Add migrations only for durable state changes that cannot be handled lazily elsewhere.++## Verification++- Smoke-test startup on a clean checkout and on representative existing user state when practical.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/system_prompt/AGENTS.md b/extensions/python/system_prompt/AGENTS.mdnew file mode 100644index 000000000..bc4ee6448--- /dev/null+++ b/extensions/python/system_prompt/AGENTS.md@@ -0,0 +1,27 @@+# System Prompt Extensions DOX++## Purpose++- Own construction of core system prompt sections.++## Ownership++- Ordered Python files own main, tools, MCP, secrets, skills, and project prompt sections.++## Local Contracts++- Preserve ordering where sections depend on earlier context.+- Keep secret-related prompt sections masked and scoped.+- Prompt additions must be bounded and compatible with tool-call contracts.++## Work Guidance++- Coordinate broad system prompt changes with profiles, skills, tools, plugins, and prompt tests.++## Verification++- Inspect rendered system prompts or run prompt-construction tests after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/tool_execute_after/AGENTS.md b/extensions/python/tool_execute_after/AGENTS.mdnew file mode 100644index 000000000..54c4557c5--- /dev/null+++ b/extensions/python/tool_execute_after/AGENTS.md@@ -0,0 +1,26 @@+# Tool Execute After Extensions DOX++## Purpose++- Own backend processing immediately after tool execution.++## Ownership++- Ordered Python files own post-tool secret masking and future tool-result postprocessing.++## Local Contracts++- Mask secrets before tool results reach history, UI, or model-visible context.+- Do not alter tool `break_loop` or response semantics unless the hook contract owns that behavior.++## Work Guidance++- Coordinate with tool implementations and history hooks when changing tool result data.++## Verification++- Smoke-test tool execution with sensitive output after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/tool_execute_before/AGENTS.md b/extensions/python/tool_execute_before/AGENTS.mdnew file mode 100644index 000000000..6d5f6f8bf--- /dev/null+++ b/extensions/python/tool_execute_before/AGENTS.md@@ -0,0 +1,27 @@+# Tool Execute Before Extensions DOX++## Purpose++- Own backend processing immediately before tool execution.++## Ownership++- Ordered Python files own prior tool-output replacement and secret unmasking before execution.++## Local Contracts++- Unmask only values required by the target tool.+- Preserve safety checks and do not expose secrets to logs or unrelated tools.+- Keep ordering stable where replacement must occur before unmasking or execution.++## Work Guidance++- Coordinate with secret handling, tool argument preparation, and plugin tool gates.++## Verification++- Smoke-test tool execution with masked secret arguments and prior-output references after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/user_message_ui/AGENTS.md b/extensions/python/user_message_ui/AGENTS.mdnew file mode 100644index 000000000..55428a4d7--- /dev/null+++ b/extensions/python/user_message_ui/AGENTS.md@@ -0,0 +1,26 @@+# User Message UI Extensions DOX++## Purpose++- Own backend behavior triggered around user-visible UI messages.++## Ownership++- Ordered Python files own update-check messaging and future user-message UI hooks.++## Local Contracts++- Keep proactive UI messages relevant, non-spammy, and safe for display.+- Do not expose local diagnostics or update data that should stay internal.++## Work Guidance++- Gate recurring messages so they do not repeat unnecessarily across chats or tabs.++## Verification++- Smoke-test UI message rendering after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/util_model_call_before/AGENTS.md b/extensions/python/util_model_call_before/AGENTS.mdnew file mode 100644index 000000000..dc0bd77f8--- /dev/null+++ b/extensions/python/util_model_call_before/AGENTS.md@@ -0,0 +1,26 @@+# Utility Model Call Before Extensions DOX++## Purpose++- Own preprocessing before utility model calls.++## Ownership++- Ordered Python files own secret masking and future utility-call preparation.++## Local Contracts++- Mask secrets before utility prompts leave the framework.+- Keep utility model inputs compatible with callers expecting structured outputs.++## Work Guidance++- Coordinate masking changes with main model call and error-format masking behavior.++## Verification++- Test utility model calls that include masked secret patterns after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/webui_ws_connect/AGENTS.md b/extensions/python/webui_ws_connect/AGENTS.mdnew file mode 100644index 000000000..f722ae7b2--- /dev/null+++ b/extensions/python/webui_ws_connect/AGENTS.md@@ -0,0 +1,26 @@+# WebUI WebSocket Connect Extensions DOX++## Purpose++- Own backend behavior when a WebUI WebSocket client connects.++## Ownership++- Ordered Python files own state-sync behavior for new WebSocket connections.++## Local Contracts++- Preserve WebSocket auth/session assumptions.+- Send only state the connected client is allowed to receive.++## Work Guidance++- Coordinate connect behavior with frontend WebSocket client and sync store.++## Verification++- Smoke-test WebUI connection and initial state sync after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/webui_ws_disconnect/AGENTS.md b/extensions/python/webui_ws_disconnect/AGENTS.mdnew file mode 100644index 000000000..703652891--- /dev/null+++ b/extensions/python/webui_ws_disconnect/AGENTS.md@@ -0,0 +1,26 @@+# WebUI WebSocket Disconnect Extensions DOX++## Purpose++- Own backend behavior when a WebUI WebSocket client disconnects.++## Ownership++- Ordered Python files own state-sync cleanup for disconnect events.++## Local Contracts++- Cleanup must be idempotent and safe for repeated disconnect events.+- Do not remove shared state still needed by other active clients.++## Work Guidance++- Coordinate disconnect behavior with frontend reconnect and sync indicators.++## Verification++- Smoke-test disconnect and reconnect behavior after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/python/webui_ws_event/AGENTS.md b/extensions/python/webui_ws_event/AGENTS.mdnew file mode 100644index 000000000..a47e147b2--- /dev/null+++ b/extensions/python/webui_ws_event/AGENTS.md@@ -0,0 +1,26 @@+# WebUI WebSocket Event Extensions DOX++## Purpose++- Own backend behavior for incoming WebUI WebSocket events.++## Ownership++- Ordered Python files own state-sync event handling and future WebSocket event extensions.++## Local Contracts++- Validate event names and payloads before acting on them.+- Preserve auth/session boundaries for all WebSocket events.++## Work Guidance++- Coordinate event changes with frontend WebSocket client and sync store.++## Verification++- Smoke-test relevant WebSocket events after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/AGENTS.md b/extensions/webui/AGENTS.mdindex 11f949ca5..d2421a144 100644--- a/extensions/webui/AGENTS.md+++ b/extensions/webui/AGENTS.md@@ -31,4 +31,17 @@## Child DOX Index-No child DOX files.+Direct child DOX files:++| Child | Scope |+| --- | --- |+| [fetch_api_call_after/AGENTS.md](fetch_api_call_after/AGENTS.md) | Frontend hooks after raw `fetchApi()` calls. |+| [fetch_api_call_before/AGENTS.md](fetch_api_call_before/AGENTS.md) | Frontend hooks before raw `fetchApi()` calls. |+| [get_message_handler/AGENTS.md](get_message_handler/AGENTS.md) | Message rendering handler extensions. |+| [initFw_end/AGENTS.md](initFw_end/AGENTS.md) | Post-WebUI-framework-initialization extensions. |+| [json_api_call_after/AGENTS.md](json_api_call_after/AGENTS.md) | Frontend hooks after `callJsonApi()` calls. |+| [json_api_call_before/AGENTS.md](json_api_call_before/AGENTS.md) | Frontend hooks before `callJsonApi()` calls. |+| [right_canvas_register_surfaces/AGENTS.md](right_canvas_register_surfaces/AGENTS.md) | Built-in right-canvas surface registrations. |+| [set_messages_after_loop/AGENTS.md](set_messages_after_loop/AGENTS.md) | Frontend hooks after message DOM updates. |+| [set_messages_before_loop/AGENTS.md](set_messages_before_loop/AGENTS.md) | Frontend hooks before message DOM updates. |+| [webui_ws_push/AGENTS.md](webui_ws_push/AGENTS.md) | WebUI WebSocket push-event behavior. |diff --git a/extensions/webui/fetch_api_call_after/AGENTS.md b/extensions/webui/fetch_api_call_after/AGENTS.mdnew file mode 100644index 000000000..963be5f11--- /dev/null+++ b/extensions/webui/fetch_api_call_after/AGENTS.md@@ -0,0 +1,26 @@+# Fetch API Call After Extensions DOX++## Purpose++- Own frontend extension hooks that run after raw `fetchApi()` calls.++## Ownership++- Files in this folder own after-call behavior for CSRF-aware raw fetch flows.++## Local Contracts++- JavaScript modules must export a default function when present.+- Do not consume response bodies unless the hook contract explicitly passes a clone or mutable context for that purpose.++## Work Guidance++- Keep after-call extensions lightweight and safe for all fetch callers.++## Verification++- Smoke-test frontend API calls after adding behavior here.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/fetch_api_call_before/AGENTS.md b/extensions/webui/fetch_api_call_before/AGENTS.mdnew file mode 100644index 000000000..c715757d5--- /dev/null+++ b/extensions/webui/fetch_api_call_before/AGENTS.md@@ -0,0 +1,26 @@+# Fetch API Call Before Extensions DOX++## Purpose++- Own frontend extension hooks that run before raw `fetchApi()` calls.++## Ownership++- Files in this folder own before-call behavior for CSRF-aware raw fetch flows.++## Local Contracts++- JavaScript modules must export a default function when present.+- Preserve CSRF, auth, and redirect behavior owned by `/js/api.js`.++## Work Guidance++- Avoid broad request mutation that surprises unrelated API callers.++## Verification++- Smoke-test affected frontend API calls after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/get_message_handler/AGENTS.md b/extensions/webui/get_message_handler/AGENTS.mdnew file mode 100644index 000000000..ea0a36977--- /dev/null+++ b/extensions/webui/get_message_handler/AGENTS.md@@ -0,0 +1,27 @@+# Get Message Handler Extensions DOX++## Purpose++- Own frontend extensions that provide or modify message rendering handlers.++## Ownership++- Files in this folder own handler registration behavior for rendered chat messages.++## Local Contracts++- JavaScript modules must export a default function when present.+- Preserve mutable context contracts used by `/js/messages.js`.+- Do not render unsanitized model or user content.++## Work Guidance++- Coordinate handler changes with message components and plugin message extensions.++## Verification++- Smoke-test message rendering for affected message types after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/initFw_end/AGENTS.md b/extensions/webui/initFw_end/AGENTS.mdnew file mode 100644index 000000000..5f18507b4--- /dev/null+++ b/extensions/webui/initFw_end/AGENTS.md@@ -0,0 +1,27 @@+# Init Framework End Extensions DOX++## Purpose++- Own frontend extensions that run after WebUI framework initialization.++## Ownership++- JavaScript files own post-bootstrap global setup such as self-update helpers.++## Local Contracts++- JavaScript modules must export a default function.+- Setup must be idempotent across reloads and cache resets.+- Do not register duplicate global listeners.++## Work Guidance++- Coordinate initialization changes with `/js/initFw.js` and component lifecycle directives.++## Verification++- Smoke-test WebUI startup and browser console after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/json_api_call_after/AGENTS.md b/extensions/webui/json_api_call_after/AGENTS.mdnew file mode 100644index 000000000..96f356b8d--- /dev/null+++ b/extensions/webui/json_api_call_after/AGENTS.md@@ -0,0 +1,26 @@+# JSON API Call After Extensions DOX++## Purpose++- Own frontend extension hooks that run after `callJsonApi()` calls.++## Ownership++- JavaScript files own after-call behavior such as cache reset handling.++## Local Contracts++- JavaScript modules must export a default function.+- Preserve JSON API response contracts and avoid hiding errors from callers.++## Work Guidance++- Keep global side effects narrow and tied to explicit API results or mutable contexts.++## Verification++- Smoke-test JSON API callers affected by extension changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/json_api_call_before/AGENTS.md b/extensions/webui/json_api_call_before/AGENTS.mdnew file mode 100644index 000000000..b14f04ea9--- /dev/null+++ b/extensions/webui/json_api_call_before/AGENTS.md@@ -0,0 +1,26 @@+# JSON API Call Before Extensions DOX++## Purpose++- Own frontend extension hooks that run before `callJsonApi()` calls.++## Ownership++- Files in this folder own before-call behavior for JSON API requests.++## Local Contracts++- JavaScript modules must export a default function when present.+- Preserve CSRF/auth behavior and JSON payload shape expected by `/js/api.js`.++## Work Guidance++- Avoid broad request mutation that affects unrelated plugin or core API calls.++## Verification++- Smoke-test affected JSON API calls after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/right_canvas_register_surfaces/AGENTS.md b/extensions/webui/right_canvas_register_surfaces/AGENTS.mdnew file mode 100644index 000000000..d62eb20da--- /dev/null+++ b/extensions/webui/right_canvas_register_surfaces/AGENTS.md@@ -0,0 +1,27 @@+# Right Canvas Surface Extensions DOX++## Purpose++- Own frontend registration of built-in right-canvas surfaces.++## Ownership++- JavaScript files own registration of remote link, space agent, and future core canvas surfaces.++## Local Contracts++- JavaScript modules must export a default function.+- Surface IDs must be unique and stable.+- Registered surfaces must point to valid components or handlers.++## Work Guidance++- Coordinate surface registration changes with `webui/components/canvas/` and related plugin panels.++## Verification++- Smoke-test opening each registered right-canvas surface after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/set_messages_after_loop/AGENTS.md b/extensions/webui/set_messages_after_loop/AGENTS.mdnew file mode 100644index 000000000..724987ba7--- /dev/null+++ b/extensions/webui/set_messages_after_loop/AGENTS.md@@ -0,0 +1,26 @@+# Set Messages After Loop Extensions DOX++## Purpose++- Own frontend extensions that run after message DOM updates complete.++## Ownership++- Files in this folder own after-render message behavior.++## Local Contracts++- JavaScript modules must export a default function when present.+- Preserve message DOM stability and avoid duplicate controls on repeated renders.++## Work Guidance++- Use stable markers when injecting controls into message elements.++## Verification++- Smoke-test message rerendering and extension-injected controls after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/set_messages_before_loop/AGENTS.md b/extensions/webui/set_messages_before_loop/AGENTS.mdnew file mode 100644index 000000000..d417ba566--- /dev/null+++ b/extensions/webui/set_messages_before_loop/AGENTS.md@@ -0,0 +1,26 @@+# Set Messages Before Loop Extensions DOX++## Purpose++- Own frontend extensions that run before message DOM updates.++## Ownership++- Files in this folder own pre-render message behavior.++## Local Contracts++- JavaScript modules must export a default function when present.+- Do not remove DOM state needed by message rendering unless the mutable context owns it.++## Work Guidance++- Coordinate pre-render behavior with `/js/messages.js` and message components.++## Verification++- Smoke-test message updates after changes.++## Child DOX Index++No child DOX files.diff --git a/extensions/webui/webui_ws_push/AGENTS.md b/extensions/webui/webui_ws_push/AGENTS.mdnew file mode 100644index 000000000..58d838730--- /dev/null+++ b/extensions/webui/webui_ws_push/AGENTS.md@@ -0,0 +1,27 @@+# WebUI WebSocket Push Extensions DOX++## Purpose++- Own frontend behavior for WebUI WebSocket push events.++## Ownership++- JavaScript files own push-event side effects such as cache clearing.++## Local Contracts++- JavaScript modules must export a default function.+- Validate event payload shape before acting.+- Keep cache or state resets scoped to the event type.++## Work Guidance++- Coordinate push behavior with backend WebSocket event extensions and frontend stores.++## Verification++- Smoke-test relevant WebSocket push events after changes.++## Child DOX Index++No child DOX files.diff --git a/helpers/AGENTS.md b/helpers/AGENTS.mdindex bb70bf289..dc7584d32 100644--- a/helpers/AGENTS.md+++ b/helpers/AGENTS.md@@ -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 Indexdiff --git a/helpers/api.py.dox.md b/helpers/api.py.dox.mdnew file mode 100644index 000000000..d9d6bb546--- /dev/null+++ b/helpers/api.py.dox.md@@ -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.diff --git a/helpers/attachment_manager.py.dox.md b/helpers/attachment_manager.py.dox.mdnew file mode 100644index 000000000..46dd4a930--- /dev/null+++ b/helpers/attachment_manager.py.dox.md@@ -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.diff --git a/helpers/backup.py.dox.md b/helpers/backup.py.dox.mdnew file mode 100644index 000000000..a72c49377--- /dev/null+++ b/helpers/backup.py.dox.md@@ -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.diff --git a/helpers/browser.py.dox.md b/helpers/browser.py.dox.mdnew file mode 100644index 000000000..0ac4afcca--- /dev/null+++ b/helpers/browser.py.dox.md@@ -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.diff --git a/helpers/cache.py.dox.md b/helpers/cache.py.dox.mdnew file mode 100644index 000000000..abe865f75--- /dev/null+++ b/helpers/cache.py.dox.md@@ -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.diff --git a/helpers/call_llm.py.dox.md b/helpers/call_llm.py.dox.mdnew file mode 100644index 000000000..0ba5bd966--- /dev/null+++ b/helpers/call_llm.py.dox.md@@ -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.diff --git a/helpers/chat_media.py.dox.md b/helpers/chat_media.py.dox.mdnew file mode 100644index 000000000..5aa9af9fb--- /dev/null+++ b/helpers/chat_media.py.dox.md@@ -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.diff --git a/helpers/cli_tunnel.py.dox.md b/helpers/cli_tunnel.py.dox.mdnew file mode 100644index 000000000..da8fc4a0c--- /dev/null+++ b/helpers/cli_tunnel.py.dox.md@@ -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.diff --git a/helpers/cloudflare_tunnel.py.dox.md b/helpers/cloudflare_tunnel.py.dox.mdnew file mode 100644index 000000000..e2172dcae--- /dev/null+++ b/helpers/cloudflare_tunnel.py.dox.md@@ -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.diff --git a/helpers/context.py.dox.md b/helpers/context.py.dox.mdnew file mode 100644index 000000000..8b6e76a51--- /dev/null+++ b/helpers/context.py.dox.md@@ -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.diff --git a/helpers/context_utils.py.dox.md b/helpers/context_utils.py.dox.mdnew file mode 100644index 000000000..725340ecd--- /dev/null+++ b/helpers/context_utils.py.dox.md@@ -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.diff --git a/helpers/crypto.py.dox.md b/helpers/crypto.py.dox.mdnew file mode 100644index 000000000..a66e730ca--- /dev/null+++ b/helpers/crypto.py.dox.md@@ -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.diff --git a/helpers/defer.py.dox.md b/helpers/defer.py.dox.mdnew file mode 100644index 000000000..cccc3da9f--- /dev/null+++ b/helpers/defer.py.dox.md@@ -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.diff --git a/helpers/dirty_json.py b/helpers/dirty_json.pyindex 8b731bee4..8e7b21012 100644--- a/helpers/dirty_json.py+++ b/helpers/dirty_json.py@@ -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_charself._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 quotereturn 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_chardiff --git a/helpers/dirty_json.py.dox.md b/helpers/dirty_json.py.dox.mdnew file mode 100644index 000000000..030a5c652--- /dev/null+++ b/helpers/dirty_json.py.dox.md@@ -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.diff --git a/helpers/docker.py.dox.md b/helpers/docker.py.dox.mdnew file mode 100644index 000000000..e932e7bcc--- /dev/null+++ b/helpers/docker.py.dox.md@@ -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.diff --git a/helpers/document_query.py.dox.md b/helpers/document_query.py.dox.mdnew file mode 100644index 000000000..7d205d988--- /dev/null+++ b/helpers/document_query.py.dox.md@@ -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.diff --git a/helpers/dotenv.py.dox.md b/helpers/dotenv.py.dox.mdnew file mode 100644index 000000000..2e142d657--- /dev/null+++ b/helpers/dotenv.py.dox.md@@ -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.diff --git a/helpers/duckduckgo_search.py.dox.md b/helpers/duckduckgo_search.py.dox.mdnew file mode 100644index 000000000..5090f5042--- /dev/null+++ b/helpers/duckduckgo_search.py.dox.md@@ -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.diff --git a/helpers/email_client.py.dox.md b/helpers/email_client.py.dox.mdnew file mode 100644index 000000000..976e32cd9--- /dev/null+++ b/helpers/email_client.py.dox.md@@ -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.diff --git a/helpers/ephemeral_images.py.dox.md b/helpers/ephemeral_images.py.dox.mdnew file mode 100644index 000000000..62b7a36a0--- /dev/null+++ b/helpers/ephemeral_images.py.dox.md@@ -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.diff --git a/helpers/errors.py.dox.md b/helpers/errors.py.dox.mdnew file mode 100644index 000000000..c551fc8d5--- /dev/null+++ b/helpers/errors.py.dox.md@@ -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.diff --git a/helpers/extension.py.dox.md b/helpers/extension.py.dox.mdnew file mode 100644index 000000000..4271cc57c--- /dev/null+++ b/helpers/extension.py.dox.md@@ -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.diff --git a/helpers/extract_tools.py.dox.md b/helpers/extract_tools.py.dox.mdnew file mode 100644index 000000000..9c65b8ced--- /dev/null+++ b/helpers/extract_tools.py.dox.md@@ -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.diff --git a/helpers/faiss_monkey_patch.py.dox.md b/helpers/faiss_monkey_patch.py.dox.mdnew file mode 100644index 000000000..bfbacf50a--- /dev/null+++ b/helpers/faiss_monkey_patch.py.dox.md@@ -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.diff --git a/helpers/fasta2a_client.py.dox.md b/helpers/fasta2a_client.py.dox.mdnew file mode 100644index 000000000..e5ef5b6a8--- /dev/null+++ b/helpers/fasta2a_client.py.dox.md@@ -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.diff --git a/helpers/fasta2a_server.py.dox.md b/helpers/fasta2a_server.py.dox.mdnew file mode 100644index 000000000..cd8e00755--- /dev/null+++ b/helpers/fasta2a_server.py.dox.md@@ -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.diff --git a/helpers/file_browser.py.dox.md b/helpers/file_browser.py.dox.mdnew file mode 100644index 000000000..3f8f2e43a--- /dev/null+++ b/helpers/file_browser.py.dox.md@@ -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.diff --git a/helpers/file_tree.py.dox.md b/helpers/file_tree.py.dox.mdnew file mode 100644index 000000000..db3625d70--- /dev/null+++ b/helpers/file_tree.py.dox.md@@ -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.diff --git a/helpers/files.py.dox.md b/helpers/files.py.dox.mdnew file mode 100644index 000000000..b4f153240--- /dev/null+++ b/helpers/files.py.dox.md@@ -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.diff --git a/helpers/functions.py.dox.md b/helpers/functions.py.dox.mdnew file mode 100644index 000000000..c2e00daac--- /dev/null+++ b/helpers/functions.py.dox.md@@ -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.diff --git a/helpers/git.py.dox.md b/helpers/git.py.dox.mdnew file mode 100644index 000000000..857c3966c--- /dev/null+++ b/helpers/git.py.dox.md@@ -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.diff --git a/helpers/guids.py.dox.md b/helpers/guids.py.dox.mdnew file mode 100644index 000000000..9fea993bf--- /dev/null+++ b/helpers/guids.py.dox.md@@ -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.diff --git a/helpers/history.py.dox.md b/helpers/history.py.dox.mdnew file mode 100644index 000000000..0e07d4a9e--- /dev/null+++ b/helpers/history.py.dox.md@@ -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.diff --git a/helpers/images.py.dox.md b/helpers/images.py.dox.mdnew file mode 100644index 000000000..1d2cd0320--- /dev/null+++ b/helpers/images.py.dox.md@@ -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.diff --git a/helpers/integration_commands.py.dox.md b/helpers/integration_commands.py.dox.mdnew file mode 100644index 000000000..b7462926e--- /dev/null+++ b/helpers/integration_commands.py.dox.md@@ -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.diff --git a/helpers/job_loop.py.dox.md b/helpers/job_loop.py.dox.mdnew file mode 100644index 000000000..b0414749d--- /dev/null+++ b/helpers/job_loop.py.dox.md@@ -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.diff --git a/helpers/kvp.py.dox.md b/helpers/kvp.py.dox.mdnew file mode 100644index 000000000..d7e6e0de0--- /dev/null+++ b/helpers/kvp.py.dox.md@@ -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.diff --git a/helpers/localization.py.dox.md b/helpers/localization.py.dox.mdnew file mode 100644index 000000000..b33e410b8--- /dev/null+++ b/helpers/localization.py.dox.md@@ -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.diff --git a/helpers/log.py.dox.md b/helpers/log.py.dox.mdnew file mode 100644index 000000000..ce74dec69--- /dev/null+++ b/helpers/log.py.dox.md@@ -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.diff --git a/helpers/login.py.dox.md b/helpers/login.py.dox.mdnew file mode 100644index 000000000..344895198--- /dev/null+++ b/helpers/login.py.dox.md@@ -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.diff --git a/helpers/mcp_handler.py.dox.md b/helpers/mcp_handler.py.dox.mdnew file mode 100644index 000000000..fc98db4f0--- /dev/null+++ b/helpers/mcp_handler.py.dox.md@@ -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.diff --git a/helpers/mcp_server.py.dox.md b/helpers/mcp_server.py.dox.mdnew file mode 100644index 000000000..4151d3d89--- /dev/null+++ b/helpers/mcp_server.py.dox.md@@ -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.diff --git a/helpers/media_artifacts.py.dox.md b/helpers/media_artifacts.py.dox.mdnew file mode 100644index 000000000..9f4d0c39f--- /dev/null+++ b/helpers/media_artifacts.py.dox.md@@ -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.diff --git a/helpers/message_queue.py.dox.md b/helpers/message_queue.py.dox.mdnew file mode 100644index 000000000..df300ed67--- /dev/null+++ b/helpers/message_queue.py.dox.md@@ -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.diff --git a/helpers/messages.py.dox.md b/helpers/messages.py.dox.mdnew file mode 100644index 000000000..e61772114--- /dev/null+++ b/helpers/messages.py.dox.md@@ -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.diff --git a/helpers/microsoft_tunnel.py.dox.md b/helpers/microsoft_tunnel.py.dox.mdnew file mode 100644index 000000000..32ee7027c--- /dev/null+++ b/helpers/microsoft_tunnel.py.dox.md@@ -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.diff --git a/helpers/migration.py.dox.md b/helpers/migration.py.dox.mdnew file mode 100644index 000000000..c548951ab--- /dev/null+++ b/helpers/migration.py.dox.md@@ -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.diff --git a/helpers/modules.py.dox.md b/helpers/modules.py.dox.mdnew file mode 100644index 000000000..9f42143ed--- /dev/null+++ b/helpers/modules.py.dox.md@@ -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.diff --git a/helpers/network.py.dox.md b/helpers/network.py.dox.mdnew file mode 100644index 000000000..792836311--- /dev/null+++ b/helpers/network.py.dox.md@@ -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.diff --git a/helpers/notification.py.dox.md b/helpers/notification.py.dox.mdnew file mode 100644index 000000000..d8f198f4a--- /dev/null+++ b/helpers/notification.py.dox.md@@ -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.diff --git a/helpers/performance.py.dox.md b/helpers/performance.py.dox.mdnew file mode 100644index 000000000..36181986d--- /dev/null+++ b/helpers/performance.py.dox.md@@ -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.diff --git a/helpers/perplexity_search.py.dox.md b/helpers/perplexity_search.py.dox.mdnew file mode 100644index 000000000..1144ec0e9--- /dev/null+++ b/helpers/perplexity_search.py.dox.md@@ -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.diff --git a/helpers/persist_chat.py.dox.md b/helpers/persist_chat.py.dox.mdnew file mode 100644index 000000000..bf251b8e7--- /dev/null+++ b/helpers/persist_chat.py.dox.md@@ -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.diff --git a/helpers/plugins.py.dox.md b/helpers/plugins.py.dox.mdnew file mode 100644index 000000000..4447d8850--- /dev/null+++ b/helpers/plugins.py.dox.md@@ -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.diff --git a/helpers/print_catch.py.dox.md b/helpers/print_catch.py.dox.mdnew file mode 100644index 000000000..16c630d70--- /dev/null+++ b/helpers/print_catch.py.dox.md@@ -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.diff --git a/helpers/print_style.py.dox.md b/helpers/print_style.py.dox.mdnew file mode 100644index 000000000..193a9bb26--- /dev/null+++ b/helpers/print_style.py.dox.md@@ -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.diff --git a/helpers/process.py.dox.md b/helpers/process.py.dox.mdnew file mode 100644index 000000000..217a7b3aa--- /dev/null+++ b/helpers/process.py.dox.md@@ -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.diff --git a/helpers/projects.py.dox.md b/helpers/projects.py.dox.mdnew file mode 100644index 000000000..08b674859--- /dev/null+++ b/helpers/projects.py.dox.md@@ -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.diff --git a/helpers/providers.py.dox.md b/helpers/providers.py.dox.mdnew file mode 100644index 000000000..083ccecfc--- /dev/null+++ b/helpers/providers.py.dox.md@@ -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.diff --git a/helpers/rate_limiter.py.dox.md b/helpers/rate_limiter.py.dox.mdnew file mode 100644index 000000000..22572ec2b--- /dev/null+++ b/helpers/rate_limiter.py.dox.md@@ -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.diff --git a/helpers/rfc.py.dox.md b/helpers/rfc.py.dox.mdnew file mode 100644index 000000000..dbe29b918--- /dev/null+++ b/helpers/rfc.py.dox.md@@ -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.diff --git a/helpers/rfc_exchange.py.dox.md b/helpers/rfc_exchange.py.dox.mdnew file mode 100644index 000000000..c960dabd9--- /dev/null+++ b/helpers/rfc_exchange.py.dox.md@@ -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.diff --git a/helpers/rfc_files.py.dox.md b/helpers/rfc_files.py.dox.mdnew file mode 100644index 000000000..d05d75828--- /dev/null+++ b/helpers/rfc_files.py.dox.md@@ -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.diff --git a/helpers/runtime.py.dox.md b/helpers/runtime.py.dox.mdnew file mode 100644index 000000000..e9e5ae922--- /dev/null+++ b/helpers/runtime.py.dox.md@@ -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.diff --git a/helpers/searxng.py.dox.md b/helpers/searxng.py.dox.mdnew file mode 100644index 000000000..889e62df1--- /dev/null+++ b/helpers/searxng.py.dox.md@@ -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.diff --git a/helpers/secrets.py.dox.md b/helpers/secrets.py.dox.mdnew file mode 100644index 000000000..2824362aa--- /dev/null+++ b/helpers/secrets.py.dox.md@@ -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.diff --git a/helpers/security.py.dox.md b/helpers/security.py.dox.mdnew file mode 100644index 000000000..882286b52--- /dev/null+++ b/helpers/security.py.dox.md@@ -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.diff --git a/helpers/self_update.py.dox.md b/helpers/self_update.py.dox.mdnew file mode 100644index 000000000..b1e552539--- /dev/null+++ b/helpers/self_update.py.dox.md@@ -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.diff --git a/helpers/serveo_tunnel.py.dox.md b/helpers/serveo_tunnel.py.dox.mdnew file mode 100644index 000000000..c209237f1--- /dev/null+++ b/helpers/serveo_tunnel.py.dox.md@@ -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.diff --git a/helpers/server_startup.py.dox.md b/helpers/server_startup.py.dox.mdnew file mode 100644index 000000000..a8417341c--- /dev/null+++ b/helpers/server_startup.py.dox.md@@ -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.diff --git a/helpers/settings.py.dox.md b/helpers/settings.py.dox.mdnew file mode 100644index 000000000..ef35d05c0--- /dev/null+++ b/helpers/settings.py.dox.md@@ -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.diff --git a/helpers/skills.py.dox.md b/helpers/skills.py.dox.mdnew file mode 100644index 000000000..dd23b4aba--- /dev/null+++ b/helpers/skills.py.dox.md@@ -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.diff --git a/helpers/skills_cli.py.dox.md b/helpers/skills_cli.py.dox.mdnew file mode 100644index 000000000..02aa7922d--- /dev/null+++ b/helpers/skills_cli.py.dox.md@@ -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.diff --git a/helpers/skills_import.py.dox.md b/helpers/skills_import.py.dox.mdnew file mode 100644index 000000000..9da611849--- /dev/null+++ b/helpers/skills_import.py.dox.md@@ -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.diff --git a/helpers/state_migration.py.dox.md b/helpers/state_migration.py.dox.mdnew file mode 100644index 000000000..9af4faa8c--- /dev/null+++ b/helpers/state_migration.py.dox.md@@ -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.diff --git a/helpers/state_monitor.py.dox.md b/helpers/state_monitor.py.dox.mdnew file mode 100644index 000000000..a84115652--- /dev/null+++ b/helpers/state_monitor.py.dox.md@@ -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.diff --git a/helpers/state_monitor_integration.py.dox.md b/helpers/state_monitor_integration.py.dox.mdnew file mode 100644index 000000000..15c7e3530--- /dev/null+++ b/helpers/state_monitor_integration.py.dox.md@@ -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.diff --git a/helpers/state_snapshot.py.dox.md b/helpers/state_snapshot.py.dox.mdnew file mode 100644index 000000000..ac27b97c5--- /dev/null+++ b/helpers/state_snapshot.py.dox.md@@ -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.diff --git a/helpers/strings.py.dox.md b/helpers/strings.py.dox.mdnew file mode 100644index 000000000..ccc055650--- /dev/null+++ b/helpers/strings.py.dox.md@@ -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.diff --git a/helpers/subagents.py.dox.md b/helpers/subagents.py.dox.mdnew file mode 100644index 000000000..9b954ff80--- /dev/null+++ b/helpers/subagents.py.dox.md@@ -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.diff --git a/helpers/system_packages.py.dox.md b/helpers/system_packages.py.dox.mdnew file mode 100644index 000000000..f1078d3b7--- /dev/null+++ b/helpers/system_packages.py.dox.md@@ -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.diff --git a/helpers/tailscale_tunnel.py.dox.md b/helpers/tailscale_tunnel.py.dox.mdnew file mode 100644index 000000000..90afd506e--- /dev/null+++ b/helpers/tailscale_tunnel.py.dox.md@@ -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.diff --git a/helpers/task_scheduler.py.dox.md b/helpers/task_scheduler.py.dox.mdnew file mode 100644index 000000000..7292b4faf--- /dev/null+++ b/helpers/task_scheduler.py.dox.md@@ -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.diff --git a/helpers/timed_input.py.dox.md b/helpers/timed_input.py.dox.mdnew file mode 100644index 000000000..5bcc3ce95--- /dev/null+++ b/helpers/timed_input.py.dox.md@@ -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.diff --git a/helpers/tokens.py.dox.md b/helpers/tokens.py.dox.mdnew file mode 100644index 000000000..c42637a8e--- /dev/null+++ b/helpers/tokens.py.dox.md@@ -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.diff --git a/helpers/tool.py.dox.md b/helpers/tool.py.dox.mdnew file mode 100644index 000000000..5577d7fbc--- /dev/null+++ b/helpers/tool.py.dox.md@@ -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.diff --git a/helpers/tunnel_common.py.dox.md b/helpers/tunnel_common.py.dox.mdnew file mode 100644index 000000000..2aa35d8ca--- /dev/null+++ b/helpers/tunnel_common.py.dox.md@@ -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.diff --git a/helpers/tunnel_manager.py.dox.md b/helpers/tunnel_manager.py.dox.mdnew file mode 100644index 000000000..c90749a20--- /dev/null+++ b/helpers/tunnel_manager.py.dox.md@@ -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.diff --git a/helpers/ui_server.py.dox.md b/helpers/ui_server.py.dox.mdnew file mode 100644index 000000000..5f634884e--- /dev/null+++ b/helpers/ui_server.py.dox.md@@ -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.diff --git a/helpers/update_check.py.dox.md b/helpers/update_check.py.dox.mdnew file mode 100644index 000000000..f25ef598a--- /dev/null+++ b/helpers/update_check.py.dox.md@@ -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.diff --git a/helpers/vector_db.py.dox.md b/helpers/vector_db.py.dox.mdnew file mode 100644index 000000000..bc88f84a1--- /dev/null+++ b/helpers/vector_db.py.dox.md@@ -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.diff --git a/helpers/virtual_desktop.py.dox.md b/helpers/virtual_desktop.py.dox.mdnew file mode 100644index 000000000..34e7b2510--- /dev/null+++ b/helpers/virtual_desktop.py.dox.md@@ -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.diff --git a/helpers/virtual_desktop_routes.py.dox.md b/helpers/virtual_desktop_routes.py.dox.mdnew file mode 100644index 000000000..b784fca80--- /dev/null+++ b/helpers/virtual_desktop_routes.py.dox.md@@ -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.diff --git a/helpers/wait.py.dox.md b/helpers/wait.py.dox.mdnew file mode 100644index 000000000..a647c28ef--- /dev/null+++ b/helpers/wait.py.dox.md@@ -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.diff --git a/helpers/watchdog.py.dox.md b/helpers/watchdog.py.dox.mdnew file mode 100644index 000000000..920b4703c--- /dev/null+++ b/helpers/watchdog.py.dox.md@@ -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.diff --git a/helpers/ws.py.dox.md b/helpers/ws.py.dox.mdnew file mode 100644index 000000000..5eb7279f6--- /dev/null+++ b/helpers/ws.py.dox.md@@ -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.diff --git a/helpers/ws_manager.py.dox.md b/helpers/ws_manager.py.dox.mdnew file mode 100644index 000000000..3d8f6da61--- /dev/null+++ b/helpers/ws_manager.py.dox.md@@ -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.diff --git a/helpers/yaml.py.dox.md b/helpers/yaml.py.dox.mdnew file mode 100644index 000000000..41f1da445--- /dev/null+++ b/helpers/yaml.py.dox.md@@ -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.diff --git a/plugins/AGENTS.md b/plugins/AGENTS.mdindex ba9e518d3..2a60a0c5d 100644--- a/plugins/AGENTS.md+++ b/plugins/AGENTS.md@@ -60,4 +60,35 @@## Child DOX Index-No child DOX files.+Direct child DOX files:++| Child | Scope |+| --- | --- |+| [_a0_connector/AGENTS.md](_a0_connector/AGENTS.md) | HTTP and WebSocket connector integration with remote tools and runtime bridges. |+| [_browser/AGENTS.md](_browser/AGENTS.md) | Playwright browser tool, helpers, viewer, and browser panel UI. |+| [_chat_branching/AGENTS.md](_chat_branching/AGENTS.md) | Chat branching from an existing message. |+| [_chat_compaction/AGENTS.md](_chat_compaction/AGENTS.md) | Full-chat compaction into a summary message. |+| [_code_execution/AGENTS.md](_code_execution/AGENTS.md) | Terminal, Python, and Node.js execution tools and shell runtimes. |+| [_desktop/AGENTS.md](_desktop/AGENTS.md) | Linux desktop runtime, sessions, and desktop surface. |+| [_discovery/AGENTS.md](_discovery/AGENTS.md) | Welcome-screen plugin discovery cards and promotions. |+| [_document_query/AGENTS.md](_document_query/AGENTS.md) | Document parsing, indexing, and Q&A tools. |+| [_editor/AGENTS.md](_editor/AGENTS.md) | Native Markdown editor surface and sessions. |+| [_email_integration/AGENTS.md](_email_integration/AGENTS.md) | IMAP/Exchange polling and SMTP reply integration. |+| [_error_retry/AGENTS.md](_error_retry/AGENTS.md) | Critical exception retry lifecycle hooks. |+| [_infection_check/AGENTS.md](_infection_check/AGENTS.md) | Prompt-injection safety analysis before tool execution. |+| [_kokoro_tts/AGENTS.md](_kokoro_tts/AGENTS.md) | Kokoro text-to-speech integration. |+| [_memory/AGENTS.md](_memory/AGENTS.md) | Persistent vector memory, knowledge import, tools, and dashboard. |+| [_model_config/AGENTS.md](_model_config/AGENTS.md) | Model selection, presets, API-key checks, and scoped overrides. |+| [_oauth/AGENTS.md](_oauth/AGENTS.md) | OAuth-backed model-provider connections and local proxy routes. |+| [_office/AGENTS.md](_office/AGENTS.md) | LibreOffice office artifacts and office canvas sessions. |+| [_onboarding/AGENTS.md](_onboarding/AGENTS.md) | First-time model onboarding wizard. |+| [_plugin_installer/AGENTS.md](_plugin_installer/AGENTS.md) | Plugin install and update flows from ZIP, Git, and Plugin Index. |+| [_plugin_scan/AGENTS.md](_plugin_scan/AGENTS.md) | LLM-guided security scanner for third-party plugins. |+| [_plugin_validator/AGENTS.md](_plugin_validator/AGENTS.md) | Plugin manifest, structure, convention, and security validator. |+| [_promptinclude/AGENTS.md](_promptinclude/AGENTS.md) | Promptinclude scanning and prompt injection. |+| [_skills/AGENTS.md](_skills/AGENTS.md) | Active and hidden skill configuration and prompt injection. |+| [_telegram_integration/AGENTS.md](_telegram_integration/AGENTS.md) | Telegram bot integration and per-user chat sessions. |+| [_text_editor/AGENTS.md](_text_editor/AGENTS.md) | Native text read, write, and patch tool. |+| [_time_travel/AGENTS.md](_time_travel/AGENTS.md) | Workspace history, diff, travel, snapshot, and revert flows. |+| [_whatsapp_integration/AGENTS.md](_whatsapp_integration/AGENTS.md) | WhatsApp Baileys bridge integration. |+| [_whisper_stt/AGENTS.md](_whisper_stt/AGENTS.md) | Whisper speech-to-text integration. |diff --git a/plugins/_a0_connector/AGENTS.md b/plugins/_a0_connector/AGENTS.mdnew file mode 100644index 000000000..3a9e483c2--- /dev/null+++ b/plugins/_a0_connector/AGENTS.md@@ -0,0 +1,31 @@+# A0 Connector Plugin DOX++## Purpose++- Own the current Agent Zero connector plugin for HTTP and WebSocket integration.+- Provide remote execution, text-editing freshness, and connector runtime bridges.++## Ownership++- `plugin.yaml` owns plugin metadata and settings scope.+- `api/` owns connector WebSocket and API entry points.+- `helpers/` owns chat context, event bridge, execution config, freshness, version, and WebSocket runtime helpers.+- `tools/`, `prompts/`, `skills/`, `extensions/`, and `webui/` own connector-facing agent and UI contributions.++## Local Contracts++- Preserve session-auth and `auth.handlers` activation assumptions.+- Keep remote tool prompts synchronized with remote tool behavior.+- Do not bypass WebSocket authentication or leak connector session data.++## Work Guidance++- Coordinate connector runtime changes with API, tools, prompts, and WebUI viewer behavior together.++## Verification++- Run connector-specific tests or smoke-test HTTP and `/ws` integration when changing runtime behavior.++## Child DOX Index++No child DOX files.diff --git a/plugins/_browser/AGENTS.md b/plugins/_browser/AGENTS.mdnew file mode 100644index 000000000..96d9f905c--- /dev/null+++ b/plugins/_browser/AGENTS.md@@ -0,0 +1,32 @@+# Browser Plugin DOX++## Purpose++- Own the built-in Playwright browser tool and WebUI browser viewer.+- Bridge browser automation, page inspection helpers, and browser panel UI.++## Ownership++- `plugin.yaml` and `default_config.yaml` own metadata and browser settings defaults.+- `tools/browser.py` owns the agent-facing browser tool.+- `helpers/` owns Playwright runtime, selectors, URL helpers, extension management, and connector runtime logic.+- `api/` owns status, extension, and browser WebSocket handlers.+- `assets/`, `prompts/`, `skills/`, `extensions/`, and `webui/` own browser scripts, prompts, skill guidance, hook contributions, and UI.++## Local Contracts++- Keep browser actions safe around external pages, credentials, and user data.+- Preserve Playwright lifecycle cleanup and WebSocket viewer compatibility.+- Do not hardcode user-specific browser paths or secrets.++## Work Guidance++- Coordinate tool, helper, and panel changes so browser state shown in the UI matches tool behavior.++## Verification++- Smoke-test browser launch, navigation, DOM capture, and WebUI viewer after runtime changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_chat_branching/AGENTS.md b/plugins/_chat_branching/AGENTS.mdnew file mode 100644index 000000000..b10df9993--- /dev/null+++ b/plugins/_chat_branching/AGENTS.md@@ -0,0 +1,31 @@+# Chat Branching Plugin DOX++## Purpose++- Own branching a chat from any existing message.+- Keep log and history trimming behavior consistent when creating a branched conversation.++## Ownership++- `plugin.yaml` and `README.md` own metadata and user-facing behavior notes.+- `api/branch_chat.py` owns branch creation, clone, trim, persist, and refresh behavior.+- `extensions/` owns WebUI button injection.+- `webui/` owns plugin thumbnail assets.++## Local Contracts++- Preserve UUID-based linking between log entries and history messages.+- Branched chats must include history only up to the selected message.+- Do not mutate the source chat while creating a branch.++## Work Guidance++- Coordinate UI button injection with message rendering extension points.++## Verification++- Smoke-test branching from several message positions and confirm source chat remains unchanged.++## Child DOX Index++No child DOX files.diff --git a/plugins/_chat_compaction/AGENTS.md b/plugins/_chat_compaction/AGENTS.mdnew file mode 100644index 000000000..c1d7b418a--- /dev/null+++ b/plugins/_chat_compaction/AGENTS.md@@ -0,0 +1,32 @@+# Chat Compaction Plugin DOX++## Purpose++- Own compacting an entire chat history into a single optimized summary message.+- Keep compaction prompt, helper, API, and modal behavior aligned.++## Ownership++- `plugin.yaml` and `default_config.yaml` own metadata and compaction defaults.+- `api/compact_chat.py` owns the compaction endpoint.+- `helpers/compactor.py` owns summary generation and history rewrite logic.+- `prompts/` owns compaction system and message prompts.+- `webui/` owns the compaction modal and store.++## Local Contracts++- Preserve chat history integrity and persistence after compaction.+- Keep generated summaries bounded by configured model and token limits.+- Do not discard original context data unless the compaction flow explicitly owns that behavior.++## Work Guidance++- Coordinate prompt changes with helper behavior and UI confirmation text.++## Verification++- Smoke-test compacting a chat and reloading it after persistence.++## Child DOX Index++No child DOX files.diff --git a/plugins/_code_execution/AGENTS.md b/plugins/_code_execution/AGENTS.mdnew file mode 100644index 000000000..2de8457f1--- /dev/null+++ b/plugins/_code_execution/AGENTS.md@@ -0,0 +1,30 @@+# Code Execution Plugin DOX++## Purpose++- Own terminal, Python, and Node.js code execution through persistent local or SSH-backed sessions.++## Ownership++- `tools/` owns the code execution and input tools.+- `helpers/` owns local shell, SSH shell, and TTY session management.+- `prompts/` owns execution prompt and runtime response fragments.+- `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own settings, metadata, hooks, and UI config.++## Local Contracts++- Keep session concurrency, timeout, streaming, and reset behavior predictable.+- Explicitly target local versus SSH execution runtimes.+- Do not hardcode secrets, SSH credentials, or local user paths.++## Work Guidance++- Preserve long-running command output retrieval and busy-session guards when changing execution flow.++## Verification++- Smoke-test terminal, Python, Node.js, output polling, and reset paths after tool changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_desktop/AGENTS.md b/plugins/_desktop/AGENTS.mdnew file mode 100644index 000000000..2f2b300fd--- /dev/null+++ b/plugins/_desktop/AGENTS.md@@ -0,0 +1,30 @@+# Desktop Plugin DOX++## Purpose++- Own the Agent Zero Linux desktop runtime, Xpra/Xfce session integration, and live desktop surface.++## Ownership++- `helpers/` owns desktop routes, session lifecycle, state, and prompt context.+- `api/desktop_session.py` owns desktop session API behavior.+- `hooks.py` owns route registration and plugin lifecycle hooks.+- `prompts/`, `assets/`, `skills/`, `extensions/`, and `webui/` own desktop context, assets, skill guidance, hooks, and panel UI.++## Local Contracts++- Preserve session startup, cleanup, and route protection for desktop access.+- Keep desktop state injected into prompts accurate and bounded.+- Do not expose desktop routes without the expected auth protections.++## Work Guidance++- Coordinate runtime and panel changes so live UI reflects actual desktop session state.++## Verification++- Smoke-test desktop startup, panel connection, route access, and session cleanup after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_discovery/AGENTS.md b/plugins/_discovery/AGENTS.mdnew file mode 100644index 000000000..d2440d5ab--- /dev/null+++ b/plugins/_discovery/AGENTS.md@@ -0,0 +1,29 @@+# Plugin Discovery DOX++## Purpose++- Own contextual plugin discovery cards and welcome-screen promotions.++## Ownership++- `plugin.yaml` owns metadata and always-enabled status.+- `extensions/` owns backend or WebUI discovery contributions.+- `webui/discovery-store.js` owns discovery UI state and actions.++## Local Contracts++- Discovery cards must be accurate, dismissible where appropriate, and avoid advertising already-complete setup.+- CTA actions must match supported welcome-screen action contracts.+- Keep card IDs unique and plugin-prefixed.++## Work Guidance++- Prefer backend status checks before surfacing setup or integration prompts.++## Verification++- Smoke-test welcome-screen discovery cards, ordering, dismissal, and CTA behavior after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_document_query/AGENTS.md b/plugins/_document_query/AGENTS.mdnew file mode 100644index 000000000..c39208f94--- /dev/null+++ b/plugins/_document_query/AGENTS.md@@ -0,0 +1,30 @@+# Document Query Plugin DOX++## Purpose++- Own document loading, parsing, indexing, and Q&A over local and remote documents.++## Ownership++- `tools/document_query.py` owns the agent-facing query tool.+- `helpers/` owns fetching, parser routing, indexing, and query orchestration.+- `prompts/` owns document-query tool and optimization prompts.+- `hooks.py`, `default_config.yaml`, `plugin.yaml`, `skills/`, `extensions/`, and `webui/` own dependency bootstrap, settings, metadata, skill guidance, hooks, and UI.++## Local Contracts++- Respect configured size, timeout, retry, parser concurrency, and OCR limits.+- Fetch local and remote resources safely and avoid leaking document contents beyond intended prompt/tool use.+- Keep optional dependency installation targeted to the framework runtime.++## Work Guidance++- Coordinate parser changes with timeout handling and fallback behavior.++## Verification++- Smoke-test representative PDF, text/HTML, image/OCR, and remote-document queries after parser changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_editor/AGENTS.md b/plugins/_editor/AGENTS.mdnew file mode 100644index 000000000..92969d629--- /dev/null+++ b/plugins/_editor/AGENTS.md@@ -0,0 +1,30 @@+# Editor Plugin DOX++## Purpose++- Own the native Markdown editor surface for canvas and floating modal workflows.++## Ownership++- `api/` owns editor session and WebSocket handlers.+- `helpers/` owns markdown session and open-file context helpers.+- `prompts/` owns agent-visible open-file context.+- `webui/` owns editor panel, preview, store, and main surface.+- `extensions/` owns editor hook contributions.++## Local Contracts++- Keep editor session state synchronized across API, WebSocket, and WebUI panel behavior.+- Do not expose unsaved content or local paths beyond intended chat/context surfaces.++## Work Guidance++- Coordinate editor preview and session changes with canvas surface registration.++## Verification++- Smoke-test opening, editing, previewing, and reconnecting editor sessions after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_email_integration/AGENTS.md b/plugins/_email_integration/AGENTS.mdnew file mode 100644index 000000000..8d3d09c7e--- /dev/null+++ b/plugins/_email_integration/AGENTS.md@@ -0,0 +1,30 @@+# Email Integration Plugin DOX++## Purpose++- Own communicating with Agent Zero through email inboxes and SMTP replies.++## Ownership++- `helpers/handler.py` owns mailbox polling, state, dispatch, routing, and reply flow.+- `helpers/imap_client.py` and `helpers/smtp_client.py` own inbound and outbound mail transports.+- `helpers/dispatcher.py`, `prompts/`, and attachment helpers own routing decisions and message formatting.+- `api/`, `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own tests, settings, metadata, hooks, and config UI.++## Local Contracts++- Treat mailbox credentials and downloaded attachments as sensitive.+- Preserve UID/state tracking so restarts do not duplicate old mail.+- Keep SMTP replies threaded and safe around user-visible errors.++## Work Guidance++- Coordinate polling, dispatch prompts, and WebUI settings when adding account or routing behavior.++## Verification++- Smoke-test connection checks, polling, attachment handling, dispatch routing, and SMTP replies when practical.++## Child DOX Index++No child DOX files.diff --git a/plugins/_error_retry/AGENTS.md b/plugins/_error_retry/AGENTS.mdnew file mode 100644index 000000000..ae1a15541--- /dev/null+++ b/plugins/_error_retry/AGENTS.md@@ -0,0 +1,30 @@+# Error Retry Plugin DOX++## Purpose++- Own retry behavior for unexpected critical exceptions in agent loops.++## Ownership++- `extensions/` owns retry counter reset and critical-exception retry hooks.+- `default_config.yaml` owns retry count defaults.+- `webui/config.html` owns settings UI.+- `plugin.yaml` and `README.md` own metadata and behavior notes.++## Local Contracts++- Do not retry controlled flow exceptions such as `HandledException` and `RepairableException`.+- Keep retry counts scoped per monologue.+- Preserve clear agent-facing history injection when retrying a critical exception.++## Work Guidance++- Keep retry behavior conservative and observable through logs/UI.++## Verification++- Test or simulate critical, handled, and repairable exception paths after hook changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_infection_check/AGENTS.md b/plugins/_infection_check/AGENTS.mdnew file mode 100644index 000000000..6f88ee127--- /dev/null+++ b/plugins/_infection_check/AGENTS.md@@ -0,0 +1,29 @@+# Infection Check Plugin DOX++## Purpose++- Own prompt-injection safety checks over streamed reasoning/response content before tool execution.++## Ownership++- `helpers/checker.py` owns safety analysis orchestration and gate behavior.+- `extensions/` owns stream collection and tool-execution blocking hooks.+- `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own settings, metadata, behavior notes, and config UI.++## Local Contracts++- Preserve configured `thoughts` and `complete` analysis modes.+- Tool execution must wait for required safety verdicts.+- Do not log or expose chain-of-thought or sensitive prompt content beyond intended warning flows.++## Work Guidance++- Keep termination and clarification loops bounded and explicit.++## Verification++- Smoke-test ok, clarify, and terminate verdicts around tool execution after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_kokoro_tts/AGENTS.md b/plugins/_kokoro_tts/AGENTS.mdnew file mode 100644index 000000000..8e7ffc6bf--- /dev/null+++ b/plugins/_kokoro_tts/AGENTS.md@@ -0,0 +1,31 @@+# Kokoro TTS Plugin DOX++## Purpose++- Own built-in Kokoro text-to-speech integration and browser TTS fallback coordination.++## Ownership++- `api/` owns synthesize and status endpoints.+- `helpers/` owns runtime and migration behavior.+- `hooks.py` owns provider registration/lifecycle behavior.+- `webui/` owns settings and speech UI integration.+- `default_config.yaml`, `plugin.yaml`, and `README.md` own defaults, metadata, and behavior notes.++## Local Contracts++- Keep Kokoro dependencies on Docker/bootstrap paths, not opportunistic runtime installs.+- Preserve browser-native fallback when the plugin is disabled or unavailable.+- Do not expose generated speech artifacts outside intended response paths.++## Work Guidance++- Coordinate status endpoint behavior with frontend fallback decisions.++## Verification++- Smoke-test status, synthesis, configured voice/speed, and disabled fallback behavior after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_memory/AGENTS.md b/plugins/_memory/AGENTS.mdnew file mode 100644index 000000000..622026f57--- /dev/null+++ b/plugins/_memory/AGENTS.md@@ -0,0 +1,31 @@+# Memory Plugin DOX++## Purpose++- Own persistent memory, knowledge import, vector indexing, and memory management UI.++## Ownership++- `helpers/memory.py` owns FAISS store loading, embedding metadata, and knowledge preload.+- `helpers/knowledge_import.py` and `helpers/memory_consolidation.py` own import and consolidation behavior.+- `tools/` owns memory save/load/delete/forget and behavior adjustment tools.+- `api/` and `webui/` own memory dashboard and knowledge reindex/import flows.+- `prompts/`, `default_config.yaml`, and `plugin.yaml` own memory prompts, defaults, and metadata.++## Local Contracts++- Keep memory scoped by configured subdirectory/context.+- Preserve embedding metadata needed to rebuild indexes safely.+- Avoid storing transient action-history noise as durable memory.++## Work Guidance++- Coordinate tool, prompt, and consolidation changes so saved memories remain useful and bounded.++## Verification++- Smoke-test save, recall, delete, dashboard search/update, and knowledge import/reindex after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_model_config/AGENTS.md b/plugins/_model_config/AGENTS.mdnew file mode 100644index 000000000..be2979411--- /dev/null+++ b/plugins/_model_config/AGENTS.md@@ -0,0 +1,30 @@+# Model Configuration Plugin DOX++## Purpose++- Own LLM model selection, presets, API-key checks, scoped overrides, and model settings UI.++## Ownership++- `helpers/model_config.py` owns config resolution, presets, overrides, and runtime model object construction.+- `api/` owns model config, override, preset, search, and API-key endpoints.+- `webui/` owns model settings, summaries, switcher, and API-key UI.+- `default_config.yaml`, `default_presets.yaml`, `provider_metadata.yaml`, `hooks.py`, and `plugin.yaml` own defaults, metadata, hooks, and manifest.++## Local Contracts++- Preserve global, project, agent, and chat override resolution order.+- Keep provider metadata and API-key checks safe around secrets.+- Coordinate OAuth-backed providers with `_oauth` instead of hardcoding provider-specific auth here.++## Work Guidance++- Keep backend model config shape and frontend settings fields synchronized.++## Verification++- Run model-config and onboarding-related tests when model provider, preset, or API-key behavior changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_office/AGENTS.md b/plugins/_office/AGENTS.mdnew file mode 100644index 000000000..2e0c54b0e--- /dev/null+++ b/plugins/_office/AGENTS.md@@ -0,0 +1,30 @@+# LibreOffice Plugin DOX++## Purpose++- Own ODF-first LibreOffice office artifact workflows for Writer, Calc, and Impress files.++## Ownership++- `tools/office_artifact.py` owns the agent-facing office artifact tool.+- `helpers/` owns artifact editing, canvas context, document storage, LibreOffice runtime, and presentation writing.+- `api/` owns office session and WebSocket handlers.+- `hooks.py`, `prompts/`, `skills/`, `extensions/`, and `webui/` own lifecycle behavior, prompts, skill guidance, hooks, and office panel UI.++## Local Contracts++- Preserve document storage integrity and live session synchronization.+- Keep LibreOffice operations bounded to intended workspaces and artifact paths.+- Do not expose document contents or temporary files beyond intended UI/tool flows.++## Work Guidance++- Coordinate tool, session, and panel changes so canvas state reflects document state.++## Verification++- Smoke-test creating, editing, previewing, and reconnecting office artifact sessions after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_onboarding/AGENTS.md b/plugins/_onboarding/AGENTS.mdnew file mode 100644index 000000000..3bfcd8d2c--- /dev/null+++ b/plugins/_onboarding/AGENTS.md@@ -0,0 +1,28 @@+# Onboarding Plugin DOX++## Purpose++- Own the built-in first-time onboarding wizard for model configuration.++## Ownership++- `plugin.yaml` owns metadata and always-enabled status.+- `webui/` owns onboarding providers, wizard store, modal/page markup, and thumbnail.++## Local Contracts++- Keep onboarding provider choices synchronized with model configuration and provider metadata.+- Do not ask for or expose API keys outside approved settings/API flows.+- Avoid blocking already-configured users with unnecessary onboarding prompts.++## Work Guidance++- Coordinate provider changes with `_model_config` and `_oauth` when account-backed providers are involved.++## Verification++- Smoke-test first-run onboarding, provider selection, completion, and skip/close behavior after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_plugin_installer/AGENTS.md b/plugins/_plugin_installer/AGENTS.mdnew file mode 100644index 000000000..6e213ec7e--- /dev/null+++ b/plugins/_plugin_installer/AGENTS.md@@ -0,0 +1,30 @@+# Plugin Installer DOX++## Purpose++- Own installing and updating plugins from ZIP uploads, Git repositories, and the community Plugin Index.++## Ownership++- `helpers/install.py` owns archive extraction, Git install/update, validation, hook execution, and install finalization.+- `api/plugin_install.py` owns install/update/index API dispatch.+- `webui/` owns Plugin Hub, ZIP, Git, detail, and shared install UI.+- `plugin.yaml` and `README.md` own metadata and behavior notes.++## Local Contracts++- Install third-party plugins into `usr/plugins/`, not bundled `plugins/`.+- Reject unsafe archive paths, missing manifests, invalid manifests, and plugin name conflicts.+- Run plugin install hooks and refresh plugin state after successful changes.++## Work Guidance++- Keep installer validation aligned with plugin contracts and Plugin Index expectations.++## Verification++- Smoke-test ZIP install, Git install, Plugin Hub install, and Git update paths after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_plugin_scan/AGENTS.md b/plugins/_plugin_scan/AGENTS.mdnew file mode 100644index 000000000..c51293e84--- /dev/null+++ b/plugins/_plugin_scan/AGENTS.md@@ -0,0 +1,30 @@+# Plugin Scanner DOX++## Purpose++- Own LLM-guided security scanning for third-party Agent Zero plugins.++## Ownership++- `helpers/prompt.py` owns scan prompt construction from selectable checks.+- `api/` owns scan queue, start, and synchronous run endpoints.+- `webui/` owns scan checks, prompt template, store, UI, and thumbnail.+- `plugin.yaml` and `README.md` own metadata and behavior notes.++## Local Contracts++- Keep scan prompts explicit about source handling, security categories, and report expectations.+- Temporary scan contexts must be isolated and cleaned up as intended.+- Do not install or execute scanned plugin code as part of scanning unless explicitly designed and documented.++## Work Guidance++- Coordinate check schema changes with prompt builder and frontend selection UI.++## Verification++- Smoke-test a synchronous scan and selected-check scan after prompt or API changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_plugin_validator/AGENTS.md b/plugins/_plugin_validator/AGENTS.mdnew file mode 100644index 000000000..abd194f30--- /dev/null+++ b/plugins/_plugin_validator/AGENTS.md@@ -0,0 +1,30 @@+# Plugin Validator DOX++## Purpose++- Own structured validation of Agent Zero plugins against manifest, structure, code-pattern, and security conventions.++## Ownership++- `helpers/prompt.py` owns validation prompt construction.+- `api/` owns ZIP preparation, queue, start, and synchronous run endpoints.+- `webui/` owns validation checks, guidance, prompt template, store, UI, and thumbnail.+- `plugin.yaml` and `README.md` own metadata and behavior notes.++## Local Contracts++- Keep validation criteria aligned with `plugins/AGENTS.md`, WebUI contracts, and Plugin Index requirements.+- Temporary validation source directories and contexts must be cleaned up as intended.+- Do not confuse runtime `plugin.yaml` with Plugin Index `index.yaml`.++## Work Guidance++- Coordinate checklist changes with prompt builder and frontend check selection.++## Verification++- Smoke-test local, Git, and ZIP validation paths when API or prompt behavior changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_promptinclude/AGENTS.md b/plugins/_promptinclude/AGENTS.mdnew file mode 100644index 000000000..8fab1b39f--- /dev/null+++ b/plugins/_promptinclude/AGENTS.md@@ -0,0 +1,30 @@+# Prompt Include Plugin DOX++## Purpose++- Own automatic prompt injection of persistent behavioral rules and preferences from `*.promptinclude.md` files.++## Ownership++- `helpers/scanner.py` owns workspace scanning, ignore handling, token budgeting, and trimming.+- `prompts/` owns prompt-inclusion fragments.+- `extensions/` owns prompt injection hooks.+- `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own defaults, metadata, behavior notes, and settings UI.++## Local Contracts++- Respect gitignore-style filtering, per-file budgets, and total token budgets.+- Include only intended promptinclude files from configured workspaces.+- Keep scan result status fields accurate for skipped, cropped, and included files.++## Work Guidance++- Coordinate scanner changes with prompt fragments so included content is clearly attributed.++## Verification++- Smoke-test include, ignore, crop, and over-budget cases after scanner changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_skills/AGENTS.md b/plugins/_skills/AGENTS.mdnew file mode 100644index 000000000..1371f2bf9--- /dev/null+++ b/plugins/_skills/AGENTS.md@@ -0,0 +1,31 @@+# Skills Plugin DOX++## Purpose++- Own active and hidden skill configuration injected into prompt extras on each turn.++## Ownership++- `hooks.py` owns skill prompt injection and plugin lifecycle behavior.+- `api/skills_catalog.py` owns skill catalog access.+- `prompts/agent.system.active_skills.md` owns injected active-skill prompt content.+- `webui/` owns skill settings UI and store.+- `default_config.yaml`, `plugin.yaml`, `README.md`, and `LICENSE` own defaults, metadata, docs, and license.++## Local Contracts++- Keep active skill lists bounded by configured caps.+- Store configured skills in normalized portable paths.+- Hidden skills affect catalog/search/load visibility but must not be injected as active prompt content.++## Work Guidance++- Coordinate active-skill resolution changes with core skill loading and settings UI.++## Verification++- Run skill runtime/catalog tests or smoke-test active, hidden, global, project, and chat-scope behavior after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_telegram_integration/AGENTS.md b/plugins/_telegram_integration/AGENTS.mdnew file mode 100644index 000000000..bbbc062f0--- /dev/null+++ b/plugins/_telegram_integration/AGENTS.md@@ -0,0 +1,30 @@+# Telegram Integration Plugin DOX++## Purpose++- Own Telegram bot integration for Agent Zero with polling, webhook, per-user sessions, and file exchange.++## Ownership++- `helpers/bot_manager.py` owns bot lifecycle.+- `helpers/handler.py` and `helpers/telegram_client.py` own message routing, replies, and Telegram API interaction.+- `helpers/dependencies.py` and `requirements.txt` own framework-runtime dependency bootstrap.+- `api/`, `prompts/`, `extensions/`, `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own tests/webhook endpoints, prompt fragments, hooks, settings, metadata, docs, and UI.++## Local Contracts++- Treat bot tokens, chat IDs, attachments, and user data as sensitive.+- Keep allowed-user, group-mode, project, model, and `/send` controls enforced.+- Install Telegram dependencies into the framework runtime only when required.++## Work Guidance++- Coordinate bot lifecycle changes with job-loop hooks and settings reload behavior.++## Verification++- Smoke-test connection checks, polling or webhook delivery, per-user context reuse, attachments, and replies when practical.++## Child DOX Index++No child DOX files.diff --git a/plugins/_text_editor/AGENTS.md b/plugins/_text_editor/AGENTS.mdnew file mode 100644index 000000000..f18d552d3--- /dev/null+++ b/plugins/_text_editor/AGENTS.md@@ -0,0 +1,30 @@+# Text Editor Plugin DOX++## Purpose++- Own the native LLM-friendly text editing tool for reading, writing, and patching text files.++## Ownership++- `tools/text_editor.py` owns method dispatch and agent-facing tool behavior.+- `helpers/` owns file operations, patch requests, context patching, stale-read tracking, and patch state.+- `prompts/` owns read/write/patch success and error messages.+- `default_config.yaml`, `plugin.yaml`, `README.md`, `extensions/`, and `webui/` own defaults, metadata, docs, hooks, and config UI.++## Local Contracts++- Preserve stale-read protection before patch operations.+- Validate patch structures before applying edits.+- Read back changed regions after writes or patches where the tool contract requires confirmation.++## Work Guidance++- Coordinate helper changes with prompt responses so the agent receives actionable edit feedback.++## Verification++- Smoke-test read, write, patch, stale-read rejection, and error handling after tool changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_time_travel/AGENTS.md b/plugins/_time_travel/AGENTS.mdnew file mode 100644index 000000000..0998d949f--- /dev/null+++ b/plugins/_time_travel/AGENTS.md@@ -0,0 +1,30 @@+# Time Travel Plugin DOX++## Purpose++- Own Agent Zero workspace history, diff inspection, travel, snapshots, and revert for active `/a0/usr` workspaces.++## Ownership++- `helpers/time_travel.py` owns history storage, diff, travel, snapshot, preview, and revert mechanics.+- `api/` owns history list, diff, preview, revert, snapshot, and travel endpoints.+- `webui/` owns the time-travel panel, store, main surface, and thumbnail.+- `plugin.yaml` and `extensions/` own metadata and hook contributions.++## Local Contracts++- Keep history operations scoped to Agent Zero-owned workspaces.+- Revert and travel operations must avoid unintended writes outside managed workspace paths.+- Preserve enough metadata for clear preview and diff inspection before destructive actions.++## Work Guidance++- Coordinate API and UI changes so users can inspect effects before applying travel or revert operations.++## Verification++- Smoke-test snapshot, list, diff, preview, travel, and revert flows after changes.++## Child DOX Index++No child DOX files.diff --git a/plugins/_whatsapp_integration/AGENTS.md b/plugins/_whatsapp_integration/AGENTS.mdnew file mode 100644index 000000000..ebb14eef4--- /dev/null+++ b/plugins/_whatsapp_integration/AGENTS.md@@ -0,0 +1,31 @@+# WhatsApp Integration Plugin DOX++## Purpose++- Own WhatsApp communication through a Baileys-based Node.js bridge.++## Ownership++- `helpers/bridge_manager.py` owns bridge lifecycle.+- `helpers/handler.py` and `helpers/wa_client.py` own message routing and bridge API interaction.+- `helpers/storage_paths.py`, attachment helpers, and number utilities own storage, attachment, and phone-number handling.+- `whatsapp-bridge/` owns the Node.js bridge package.+- `api/`, `prompts/`, `extensions/`, `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own QR/start/disconnect/test endpoints, prompt fragments, hooks, settings, metadata, docs, and UI.++## Local Contracts++- Treat WhatsApp sessions, QR data, phone numbers, attachments, and bridge state as sensitive.+- Keep allowed-number and group-response controls enforced.+- Do not leave unmanaged bridge services outside plugin-owned runtime paths.++## Work Guidance++- Coordinate Node bridge changes with Python bridge client and settings UI.++## Verification++- Smoke-test dependency install, bridge start, QR pairing, allowed-number filtering, message routing, and replies when practical.++## Child DOX Index++No child DOX files.diff --git a/plugins/_whisper_stt/AGENTS.md b/plugins/_whisper_stt/AGENTS.mdnew file mode 100644index 000000000..4509ccb5a--- /dev/null+++ b/plugins/_whisper_stt/AGENTS.md@@ -0,0 +1,31 @@+# Whisper STT Plugin DOX++## Purpose++- Own built-in Whisper speech-to-text integration, microphone runtime settings, and transcription delivery behavior.++## Ownership++- `api/` owns transcribe and status endpoints.+- `helpers/` owns runtime and migration behavior.+- `hooks.py` owns provider registration/lifecycle behavior.+- `webui/` owns settings, main speech UI, store, and styling.+- `default_config.yaml`, `plugin.yaml`, and `README.md` own defaults, metadata, and behavior notes.++## Local Contracts++- Keep dependency installation and model bootstrap on Docker/bootstrap paths.+- Preserve configured message mode, language, silence threshold, silence duration, and waiting timeout behavior.+- Do not expose raw audio or transcriptions beyond intended UI/API paths.++## Work Guidance++- Coordinate status endpoint behavior with frontend microphone and transcription state.++## Verification++- Smoke-test status, transcription, model/language settings, send/draft modes, and silence handling after changes.++## Child DOX Index++No child DOX files.diff --git a/skills/AGENTS.md b/skills/AGENTS.mdindex 92f7a9dd0..28cc26b15 100644--- a/skills/AGENTS.md+++ b/skills/AGENTS.md@@ -31,4 +31,17 @@## Child DOX Index-No child DOX files.+Direct child DOX files:++| Child | Scope |+| --- | --- |+| [a0-contribute-plugin/AGENTS.md](a0-contribute-plugin/AGENTS.md) | Publishing plugins to the community Plugin Index. |+| [a0-create-agent/AGENTS.md](a0-create-agent/AGENTS.md) | Creating Agent Zero agent profiles. |+| [a0-create-plugin/AGENTS.md](a0-create-plugin/AGENTS.md) | Creating or extending Agent Zero plugins. |+| [a0-debug-plugin/AGENTS.md](a0-debug-plugin/AGENTS.md) | Diagnosing plugin loading, API, frontend, and extension issues. |+| [a0-development/AGENTS.md](a0-development/AGENTS.md) | Broad Agent Zero framework development guidance. |+| [a0-manage-plugin/AGENTS.md](a0-manage-plugin/AGENTS.md) | Plugin install, update, scan, enable, disable, and removal workflows. |+| [a0-plugin-router/AGENTS.md](a0-plugin-router/AGENTS.md) | Routing plugin-related user requests to specialist skills. |+| [a0-review-plugin/AGENTS.md](a0-review-plugin/AGENTS.md) | Full plugin audit workflow and checklists. |+| [build-skill/AGENTS.md](build-skill/AGENTS.md) | Building and improving Agent Zero skills. |+| [scheduled-tasks/AGENTS.md](scheduled-tasks/AGENTS.md) | Managing scheduled, planned, and adhoc tasks. |diff --git a/skills/a0-contribute-plugin/AGENTS.md b/skills/a0-contribute-plugin/AGENTS.mdnew file mode 100644index 000000000..2067e5306--- /dev/null+++ b/skills/a0-contribute-plugin/AGENTS.md@@ -0,0 +1,29 @@+# Plugin Contribution Skill DOX++## Purpose++- Own the workflow for publishing an Agent Zero plugin to the community Plugin Index.+- Keep contribution guidance aligned with current Plugin Hub and `a0-plugins` repository requirements.++## Ownership++- `SKILL.md` owns trigger metadata and the contribution procedure.++## Local Contracts++- Keep repository, `index.yaml`, manifest, license, validation, and PR guidance current.+- Do not hardcode user credentials, personal repository names, or private URLs.+- Keep handoffs to plugin review and management skills accurate.++## Work Guidance++- Update this skill when Plugin Index CI rules, manifest expectations, or submission flow changes.+- Prefer concise command examples that a user can adapt.++## Verification++- Manually read `SKILL.md` for broken links, stale paths, and invalid relative references.++## Child DOX Index++No child DOX files.diff --git a/skills/a0-create-agent/AGENTS.md b/skills/a0-create-agent/AGENTS.mdnew file mode 100644index 000000000..bb455953b--- /dev/null+++ b/skills/a0-create-agent/AGENTS.md@@ -0,0 +1,29 @@+# Agent Creation Skill DOX++## Purpose++- Own the workflow for creating Agent Zero agent profiles.+- Keep guidance for user, plugin-distributed, and project-scoped profiles accurate.++## Ownership++- `SKILL.md` owns trigger metadata, intake flow, profile blueprint schema, and file creation guidance.++## Local Contracts++- Default new user profiles to `usr/agents/`, not bundled `agents/`.+- Keep `agent.yaml`, prompt inheritance, tools, and extension guidance synchronized with profile loader behavior.+- Do not encourage storing secrets or provider credentials in profiles.++## Work Guidance++- Keep intake lightweight and progressive for user-facing profile creation.+- Update examples when the bundled `_example/` or profile schema changes.++## Verification++- Manually read `SKILL.md` for stale paths and blueprint/schema drift.++## Child DOX Index++No child DOX files.diff --git a/skills/a0-create-plugin/AGENTS.md b/skills/a0-create-plugin/AGENTS.mdnew file mode 100644index 000000000..758c25df9--- /dev/null+++ b/skills/a0-create-plugin/AGENTS.md@@ -0,0 +1,29 @@+# Plugin Creation Skill DOX++## Purpose++- Own the workflow for creating, extending, or modifying Agent Zero plugins.+- Keep full-stack plugin conventions accurate for API, tools, extensions, settings UI, and WebUI integration.++## Ownership++- `SKILL.md` owns trigger metadata, plugin scaffold guidance, manifest rules, and frontend/backend patterns.++## Local Contracts++- New custom plugins must default to `usr/plugins/`.+- Keep plugin manifest, settings, extension layout, Store Gating, and notification guidance synchronized with `plugins/AGENTS.md` and WebUI contracts.+- Do not recommend hardcoding secrets, bypassing auth, or persistent unmanaged side effects.++## Work Guidance++- Update this skill when plugin loader, Plugin Hub, settings modal, extension, or WebUI patterns change.+- Keep code examples short and aligned with current helper APIs.++## Verification++- Manually read `SKILL.md` for stale paths and broken handoffs to related plugin skills.++## Child DOX Index++No child DOX files.diff --git a/skills/a0-debug-plugin/AGENTS.md b/skills/a0-debug-plugin/AGENTS.mdnew file mode 100644index 000000000..42abc66c3--- /dev/null+++ b/skills/a0-debug-plugin/AGENTS.md@@ -0,0 +1,28 @@+# Plugin Debug Skill DOX++## Purpose++- Own the troubleshooting workflow for Agent Zero plugin loading, activation, API, frontend, extension, settings, and hook problems.++## Ownership++- `SKILL.md` owns diagnostic order, commands, and common failure cases.++## Local Contracts++- Keep route formats, import guidance, extension layouts, toggle files, and settings resolution aligned with runtime behavior.+- Do not recommend destructive cleanup unless the user explicitly asks and the target is clear.+- Keep diagnostics safe around secrets and local user data.++## Work Guidance++- Add checks when new plugin surfaces or loader failure modes are introduced.+- Prefer targeted commands that identify the first failing layer.++## Verification++- Manually read `SKILL.md` for stale commands and plugin path assumptions.++## Child DOX Index++No child DOX files.diff --git a/skills/a0-development/AGENTS.md b/skills/a0-development/AGENTS.mdnew file mode 100644index 000000000..b53fd4cc0--- /dev/null+++ b/skills/a0-development/AGENTS.md@@ -0,0 +1,29 @@+# Development Skill DOX++## Purpose++- Own the broad Agent Zero development guide used by agents extending the framework.+- Keep architecture, tools, extensions, API, agents, prompts, projects, and skills guidance in sync with the repository.++## Ownership++- `SKILL.md` owns the development overview, path conventions, and implementation references.++## Local Contracts++- Keep paths and examples current with source files and DOX contracts.+- Route plugin-specific tasks to the plugin router or specialist plugin skills.+- Do not duplicate long contracts that belong in narrower AGENTS.md files when a reference is enough.++## Work Guidance++- Update this skill after durable framework workflow, extension, tool, API, prompt, or profile changes.+- Keep examples operational and compatible with the current helper classes.++## Verification++- Manually read `SKILL.md` for stale architecture references and broken related-skill links.++## Child DOX Index++No child DOX files.diff --git a/skills/a0-manage-plugin/AGENTS.md b/skills/a0-manage-plugin/AGENTS.mdnew file mode 100644index 000000000..144b4636f--- /dev/null+++ b/skills/a0-manage-plugin/AGENTS.md@@ -0,0 +1,28 @@+# Plugin Management Skill DOX++## Purpose++- Own the workflow for browsing, scanning, installing, updating, enabling, disabling, and uninstalling Agent Zero plugins.++## Ownership++- `SKILL.md` owns management routing, Plugin Hub usage, security scan guidance, and lifecycle commands.++## Local Contracts++- Keep Plugin Hub URLs, install API behavior, scan expectations, and activation semantics current.+- Warn about third-party plugin execution risk before install workflows.+- Do not recommend unmanaged deletion outside plugin-owned paths.++## Work Guidance++- Update this skill when installer, scanner, validator, Plugin Index, or toggle behavior changes.+- Keep diagnostics and install examples consistent with plugin helper APIs.++## Verification++- Manually read `SKILL.md` for stale endpoints, paths, and security guidance.++## Child DOX Index++No child DOX files.diff --git a/skills/a0-plugin-router/AGENTS.md b/skills/a0-plugin-router/AGENTS.mdnew file mode 100644index 000000000..72d8f5331--- /dev/null+++ b/skills/a0-plugin-router/AGENTS.md@@ -0,0 +1,29 @@+# Plugin Router Skill DOX++## Purpose++- Own routing for Agent Zero plugin-related user requests.+- Keep handoffs to plugin creation, review, contribution, management, and debugging skills accurate.++## Ownership++- `SKILL.md` owns intent classification, routing table, and concise plugin system overview.++## Local Contracts++- Keep related skill names and responsibilities synchronized with the actual skill directories.+- Keep plugin root, discovery, manifest, and extension layout summaries aligned with `plugins/AGENTS.md`.+- Ask only when plugin intent is ambiguous.++## Work Guidance++- Update this skill when plugin lifecycle skills are renamed, added, or reorganized.+- Keep the overview brief enough to serve routing, not replace specialist skills.++## Verification++- Manually read `SKILL.md` for stale skill paths and routing gaps.++## Child DOX Index++No child DOX files.diff --git a/skills/a0-review-plugin/AGENTS.md b/skills/a0-review-plugin/AGENTS.mdnew file mode 100644index 000000000..be2637ef0--- /dev/null+++ b/skills/a0-review-plugin/AGENTS.md@@ -0,0 +1,30 @@+# Plugin Review Skill DOX++## Purpose++- Own the full audit workflow for Agent Zero plugins.+- Keep manifest, structure, code-pattern, security, and duplicate-detection checks current.++## Ownership++- `SKILL.md` owns the review workflow and phase order.+- `checklists.md` owns detailed review criteria loaded when needed.++## Local Contracts++- Keep review checks aligned with current plugin contracts, WebUI patterns, and Plugin Index expectations.+- Treat user plugins as `usr/plugins/` artifacts unless explicitly reviewing bundled core plugins.+- Do not expose secrets or private plugin data in review output.++## Work Guidance++- Update both `SKILL.md` and `checklists.md` when plugin conventions or security expectations change.+- Keep findings actionable and grouped by review phase.++## Verification++- Manually read changed skill files for stale paths, duplicated checks, and broken references.++## Child DOX Index++No child DOX files.diff --git a/skills/build-skill/AGENTS.md b/skills/build-skill/AGENTS.mdnew file mode 100644index 000000000..c591f6511--- /dev/null+++ b/skills/build-skill/AGENTS.md@@ -0,0 +1,30 @@+# Build Skill DOX++## Purpose++- Own the workflow for creating, improving, auditing, and refactoring Agent Zero skills.+- Keep skill format guidance aligned with runtime discovery and loading.++## Ownership++- `SKILL.md` owns standard skill shape, writing rules, placement rules, and validation guidance.++## Local Contracts++- Every skill folder must contain `SKILL.md`.+- Keep frontmatter and directory-shape guidance synchronized with skill loader behavior.+- Prefer plugin-scoped skills when the workflow is owned by a plugin.++## Work Guidance++- Update this skill when skill metadata, discovery, or validation behavior changes.+- Keep examples concise and avoid duplicating long reference material in the skill body.++## Verification++- Manually read `SKILL.md` for stale test commands and format assumptions.+- Run skill runtime tests when changing skill loader contracts.++## Child DOX Index++No child DOX files.diff --git a/skills/scheduled-tasks/AGENTS.md b/skills/scheduled-tasks/AGENTS.mdnew file mode 100644index 000000000..2902a7c93--- /dev/null+++ b/skills/scheduled-tasks/AGENTS.md@@ -0,0 +1,29 @@+# Scheduled Tasks Skill DOX++## Purpose++- Own the workflow for managing Agent Zero scheduled, planned, and adhoc tasks.+- Keep scheduler tool usage and date/time guidance accurate.++## Ownership++- `SKILL.md` owns scheduler action descriptions, schedule field guidance, safety rules, and examples.++## Local Contracts++- Inspect existing tasks before create, update, delete, or run operations.+- Use cron-like `schedule` fields for recurring tasks and ISO datetimes in `plan` for planned tasks.+- Do not create recursive scheduling prompts or run scheduled tasks unless the user asks.++## Work Guidance++- Update this skill when scheduler tool actions, field names, or timezone behavior changes.+- Keep examples valid JSON tool arguments.++## Verification++- Manually read `SKILL.md` for stale scheduler action names and date guidance.++## Child DOX Index++No child DOX files.diff --git a/tests/test_dirty_json.py b/tests/test_dirty_json.pyindex 011b23d5f..2715366e9 100644--- a/tests/test_dirty_json.py+++ b/tests/test_dirty_json.py@@ -54,3 +54,42 @@ def test_completed_remains_true_after_trailing_content() -> None:}assert parser.completed is True+++def test_value_keeps_unescaped_markdown_quotes_until_structural_delimiter() -> None:+ payload = (+ "{\n"+ ' "tool_name": "response",\n'+ ' "tool_args": {\n'+ ' "text": "The rule:\\n\\n> *"'+ 'Create a child AGENTS.md when a folder becomes a boundary."'+ '*\\n\\nAdding `css/AGENTS.md` that says *"'+ 'this folder contains CSS"'+ '* is duplication."\n'+ " }\n"+ "}"+ )++ parsed = DirtyJson.parse_string(payload)++ assert parsed["tool_args"] == {+ "text": (+ "The rule:\n\n"+ '> *"Create a child AGENTS.md when a folder becomes a boundary."*\n\n'+ 'Adding `css/AGENTS.md` that says *"this folder contains CSS"* is duplication.'+ )+ }+++def test_value_keeps_unescaped_quotes_on_single_line() -> None:+ parsed = DirtyJson.parse_string(+ '{"text":"He said "hello" before closing","ok":true}'+ )++ assert parsed == {"text": 'He said "hello" before closing', "ok": True}+++def test_value_can_still_end_before_quoted_key_when_comma_is_missing() -> None:+ parsed = DirtyJson.parse_string('{"first":"one" "second":"two"}')++ assert parsed == {"first": "one", "second": "two"}diff --git a/tools/AGENTS.md b/tools/AGENTS.mdindex ed3cc8a37..0218740e0 100644--- a/tools/AGENTS.md+++ b/tools/AGENTS.md@@ -18,17 +18,23 @@- Use `await self.agent.handle_intervention(...)` when a long-running or external result should respect pause/intervention flow.- Sanitize or mask secrets before logging, returning, or storing tool outputs.- Do not perform destructive filesystem or network actions without the tool contract making that behavior explicit.+- This directory is a file-documented DOX profile: every direct `*.py` tool module must have a same-directory `*.py.dox.md` file named by appending `.dox.md` to the full Python filename.+- The `*.py.dox.md` file owns tool purpose, tool arguments/concepts, output and `break_loop` behavior, side effects, important helper dependencies, prompt-contract notes, and verification guidance.+- When a tool module is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change.+- Do not leave stale file-level DOX after tool deletion or rename.## Work Guidance- Keep tool output concise enough for message history while preserving actionable detail.- Put reusable parsing, provider, filesystem, or network logic in `helpers/`.- Update prompt tool instructions when changing tool names, arguments, or behavior.+- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed tool behavior is described there.## Verification- Run targeted tool tests after changing a tool or its prompt contract.- Run prompt/snapshot tests when tool instructions or output shape changes.+- Check file-level documentation coverage with a script or shell loop that verifies each `tools/*.py` has a matching `tools/*.py.dox.md`.## Child DOX Indexdiff --git a/tools/a2a_chat.py.dox.md b/tools/a2a_chat.py.dox.mdnew file mode 100644index 000000000..78d6ae143--- /dev/null+++ b/tools/a2a_chat.py.dox.md@@ -0,0 +1,51 @@+# a2a_chat.py DOX++## Purpose++- Own the `a2a_chat.py` agent tool.+- This module lets the agent message an external A2A agent and extract the assistant reply.+- Keep this file-level DOX profile synchronized with `a2a_chat.py` because this directory is intentionally flat.++## Ownership++- `a2a_chat.py` owns the runtime implementation.+- `a2a_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `A2AChatTool` (`Tool`)+ - `async execute(self, **kwargs)`+- Top-level functions:+- `_session_key(agent_url: str) -> str`: Keep root and explicit /a2a URLs in the same conversation cache.+- `_text_from_part(part: Any) -> str`+- `_text_from_message(message: Any) -> str`+- `_extract_latest_assistant_text(task_response: Any) -> str`+- Notable constants/configuration names: `A2A_EMPTY_RESPONSE_ERROR`.++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `A2AChatTool` is a `Tool`.+- `A2AChatTool` defines `execute(...)`.+- Observed side-effect areas: filesystem writes, scheduler state.+- Imported dependency areas include: `helpers.fasta2a_client`, `helpers.print_style`, `helpers.tool`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `agent_url.rstrip`, `normalized.endswith`, `_text_from_message`, `normalized.rstrip`, `message.strip`, `join`, `_session_key`, `value.strip`, `_text_from_part`, `is_client_available`, `Response`, `self.agent.get_data`, `sessions.pop`, `_extract_latest_assistant_text`, `PrintStyle.error`, `connect_to_agent`, `conn.send_message`, `conn.wait_for_completion`, `self.agent.set_data`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/test_tool_action_contracts.py`++## Child DOX Index++No child DOX files.diff --git a/tools/call_subordinate.py.dox.md b/tools/call_subordinate.py.dox.mdnew file mode 100644index 000000000..544873f0b--- /dev/null+++ b/tools/call_subordinate.py.dox.md@@ -0,0 +1,46 @@+# call_subordinate.py DOX++## Purpose++- Own the `call_subordinate.py` agent tool.+- This module delegates work to a subordinate Agent Zero profile and returns its result.+- Keep this file-level DOX profile synchronized with `call_subordinate.py` because this directory is intentionally flat.++## Ownership++- `call_subordinate.py` owns the runtime implementation.+- `call_subordinate.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Delegation` (`Tool`)+ - `async execute(self, message=..., reset=..., **kwargs)`+ - `get_log_object(self)`++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `Delegation` is a `Tool`.+- `Delegation` defines `execute(...)`.+- Observed side-effect areas: filesystem writes, settings/state persistence.+- Imported dependency areas include: `agent`, `extensions.python.hist_add_tool_result`, `helpers.tool`, `initialize`.++## Key Concepts++- Important called helpers/classes observed in the source: `self.agent.get_data`, `subordinate.hist_add_user_message`, `subordinate.history.new_topic`, `Response`, `self.agent.context.log.log`, `initialize_agent`, `Agent`, `sub.set_data`, `self.agent.set_data`, `UserMessage`, `subordinate.monologue`, `self.agent.read_prompt`, `str.lower.strip`, `str.lower`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/test_default_prompt_budget.py`++## Child DOX Index++No child DOX files.diff --git a/tools/document_query.py.dox.md b/tools/document_query.py.dox.mdnew file mode 100644index 000000000..dea7310d7--- /dev/null+++ b/tools/document_query.py.dox.md@@ -0,0 +1,41 @@+# document_query.py DOX++## Purpose++- Own the `document_query.py` agent tool.+- This module loads and queries documents through the document query plugin compatibility path.+- Keep this file-level DOX profile synchronized with `document_query.py` because this directory is intentionally flat.++## Ownership++- `document_query.py` owns the runtime implementation.+- `document_query.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- Observed side-effect areas: plugin state.+- Imported dependency areas include: `plugins._document_query.tools.document_query`.++## Key Concepts++- This module is primarily declarative or delegates behavior through classes/imported objects.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/test_document_query_fallback.py`+ - `tests/test_document_query_plugin.py`++## Child DOX Index++No child DOX files.diff --git a/tools/notify_user.py.dox.md b/tools/notify_user.py.dox.mdnew file mode 100644index 000000000..17cc9a44f--- /dev/null+++ b/tools/notify_user.py.dox.md@@ -0,0 +1,44 @@+# notify_user.py DOX++## Purpose++- Own the `notify_user.py` agent tool.+- This module sends a user-facing notification from the agent.+- Keep this file-level DOX profile synchronized with `notify_user.py` because this directory is intentionally flat.++## Ownership++- `notify_user.py` owns the runtime implementation.+- `notify_user.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `NotifyUserTool` (`Tool`)+ - `async execute(self, **kwargs)`++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `NotifyUserTool` is a `Tool`.+- `NotifyUserTool` defines `execute(...)`.+- Imported dependency areas include: `agent`, `helpers.notification`, `helpers.tool`.++## Key Concepts++- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager.add_notification`, `Response`, `NotificationType`, `NotificationPriority`, `AgentContext.get_notification_manager`, `self.agent.read_prompt`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/test_tool_action_contracts.py`++## Child DOX Index++No child DOX files.diff --git a/tools/response.py.dox.md b/tools/response.py.dox.mdnew file mode 100644index 000000000..a2d18ac0d--- /dev/null+++ b/tools/response.py.dox.md@@ -0,0 +1,53 @@+# response.py DOX++## Purpose++- Own the `response.py` agent tool.+- This module emits the final or intermediate agent response to the user.+- Keep this file-level DOX profile synchronized with `response.py` because this directory is intentionally flat.++## Ownership++- `response.py` owns the runtime implementation.+- `response.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `ResponseTool` (`Tool`)+ - `async execute(self, **kwargs)`+ - `async before_execution(self, **kwargs)`+ - `async after_execution(self, response, **kwargs)`++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `ResponseTool` is a `Tool`.+- `ResponseTool` defines `execute(...)`.+- Imported dependency areas include: `helpers.tool`.++## Key Concepts++- Important called helpers/classes observed in the source: `Response`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/chunk_parser_test.py`+ - `tests/rate_limiter_test.py`+ - `tests/test_browser_agent_regressions.py`+ - `tests/test_chat_compaction.py`+ - `tests/test_dirty_json.py`+ - `tests/test_download_toast_regressions.py`+ - `tests/test_fasta2a_client.py`+ - `tests/test_fastmcp_openapi_security.py`++## Child DOX Index++No child DOX files.diff --git a/tools/scheduler.py.dox.md b/tools/scheduler.py.dox.mdnew file mode 100644index 000000000..a36f2bc07--- /dev/null+++ b/tools/scheduler.py.dox.md@@ -0,0 +1,63 @@+# scheduler.py DOX++## Purpose++- Own the `scheduler.py` agent tool.+- This module creates, updates, lists, runs, waits for, and deletes scheduled/planned/adhoc tasks.+- Keep this file-level DOX profile synchronized with `scheduler.py` because this directory is intentionally flat.++## Ownership++- `scheduler.py` owns the runtime implementation.+- `scheduler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SchedulerTool` (`Tool`)+ - `async execute(self, **kwargs)`+ - `async list_tasks(self, **kwargs) -> Response`+ - `async find_task_by_name(self, **kwargs) -> Response`+ - `async show_task(self, **kwargs) -> Response`+ - `async run_task(self, **kwargs) -> Response`+ - `async delete_task(self, **kwargs) -> Response`+ - `async update_task(self, **kwargs) -> Response`+ - `async create_scheduled_task(self, **kwargs) -> Response`+- Top-level functions:+- `_current_action(tool: Tool, kwargs: dict) -> str`+- `_normalize_timezone(value: Any) -> str | None`+- `_schedule_timezone(kwargs: dict) -> str | None`+- `_task_schedule_from_input(schedule: Any, timezone: str | None=...) -> TaskSchedule`+- `_validate_task_schedule(task_schedule: TaskSchedule) -> str`+- `_task_plan_from_input(plan: Any) -> tuple[TaskPlan | None, str]`+- Notable constants/configuration names: `DEFAULT_WAIT_TIMEOUT`, `LOCAL_TIMEZONE_ALIASES`.++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `SchedulerTool` is a `Tool`.+- `SchedulerTool` defines `execute(...)`.+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.+- Imported dependency areas include: `agent`, `asyncio`, `datetime`, `helpers`, `helpers.localization`, `helpers.projects`, `helpers.task_scheduler`, `helpers.tool`, `json`, `pytz`, `random`, `re`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `str.strip.lower.replace`, `str.strip`, `_normalize_timezone`, `TaskSchedule`, `task_schedule.to_crontab`, `timezone_name.lower`, `Localization.get.get_timezone`, `pytz.timezone`, `schedule.split`, `re.match`, `parse_datetime`, `TaskPlan.create`, `_current_action`, `get_context_project_name`, `TaskScheduler.get.get_tasks`, `Response`, `TaskScheduler.get.find_task_by_name`, `TaskScheduler.get.get_task_by_uuid`, `scheduler.get_task_by_uuid`, `self._resolve_project_metadata`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/test_task_scheduler_timezone.py`+ - `tests/test_timezone_regressions.py`+ - `tests/test_tool_action_contracts.py`+ - `tests/test_tool_request_normalization.py`++## Child DOX Index++No child DOX files.diff --git a/tools/search_engine.py.dox.md b/tools/search_engine.py.dox.mdnew file mode 100644index 000000000..102ee68c4--- /dev/null+++ b/tools/search_engine.py.dox.md@@ -0,0 +1,46 @@+# search_engine.py DOX++## Purpose++- Own the `search_engine.py` agent tool.+- This module runs web search through the configured search helper.+- Keep this file-level DOX profile synchronized with `search_engine.py` because this directory is intentionally flat.++## Ownership++- `search_engine.py` owns the runtime implementation.+- `search_engine.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SearchEngine` (`Tool`)+ - `async execute(self, query=..., **kwargs)`+ - `async searxng_search(self, question)`+ - `format_result_searxng(self, result, source)`+- Notable constants/configuration names: `SEARCH_ENGINE_RESULTS`.++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `SearchEngine` is a `Tool`.+- `SearchEngine` defines `execute(...)`.+- Imported dependency areas include: `asyncio`, `helpers`, `helpers.errors`, `helpers.print_style`, `helpers.searxng`, `helpers.tool`, `os`.++## Key Concepts++- Important called helpers/classes observed in the source: `Response`, `self.format_result_searxng`, `join.strip`, `self.searxng_search`, `self.agent.handle_intervention`, `searxng`, `handle_error`, `join`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.++## Child DOX Index++No child DOX files.diff --git a/tools/skills_tool.py.dox.md b/tools/skills_tool.py.dox.mdnew file mode 100644index 000000000..e93b91e50--- /dev/null+++ b/tools/skills_tool.py.dox.md@@ -0,0 +1,51 @@+# skills_tool.py DOX++## Purpose++- Own the `skills_tool.py` agent tool.+- This module searches, loads, and lists Agent Zero skills for the agent.+- Keep this file-level DOX profile synchronized with `skills_tool.py` because this directory is intentionally flat.++## Ownership++- `skills_tool.py` owns the runtime implementation.+- `skills_tool.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `SkillsTool` (`Tool`)+ - `get_log_object(self)`+ - `async before_execution(self, **kwargs)`+ - `async execute(self, **kwargs) -> Response`+- Top-level functions:+- `max_loaded_skills() -> int`+- Notable constants/configuration names: `DATA_NAME_LOADED_SKILLS`.++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `SkillsTool` is a `Tool`.+- `SkillsTool` defines `execute(...)`.+- Observed side-effect areas: filesystem reads, filesystem deletion, settings/state persistence.+- Imported dependency areas include: `__future__`, `helpers`, `helpers.print_style`, `helpers.tool`, `pathlib`, `typing`.++## Key Concepts++- Important called helpers/classes observed in the source: `str.strip.lower.replace`, `skill_name.strip`, `super.get_log_object`, `self._normalize_skill_name`, `self.get_log_object`, `skills_helper.list_skills`, `join`, `skills_helper.search_skills`, `skills_helper.find_skill`, `skill.path.resolve`, `Path`, `resolved.read_text`, `skill_name.startswith`, `skill_name.endswith`, `self._current_action`, `self.agent.context.log.log`, `Response`, `strip`, `loaded.remove`, `target.is_absolute`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/test_document_query_plugin.py`+ - `tests/test_tool_action_contracts.py`++## Child DOX Index++No child DOX files.diff --git a/tools/unknown.py.dox.md b/tools/unknown.py.dox.mdnew file mode 100644index 000000000..1264ab30f--- /dev/null+++ b/tools/unknown.py.dox.md@@ -0,0 +1,48 @@+# unknown.py DOX++## Purpose++- Own the `unknown.py` agent tool.+- This module handles unknown or malformed tool-call requests.+- Keep this file-level DOX profile synchronized with `unknown.py` because this directory is intentionally flat.++## Ownership++- `unknown.py` owns the runtime implementation.+- `unknown.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `Unknown` (`Tool`)+ - `async execute(self, **kwargs)`++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `Unknown` is a `Tool`.+- `Unknown` defines `execute(...)`.+- Imported dependency areas include: `extensions.python.system_prompt._11_tools_prompt`, `helpers.tool`.++## Key Concepts++- Important called helpers/classes observed in the source: `Response`, `build_tools_prompt`, `self.agent.read_prompt`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/test_file_tree_visualize.py`+ - `tests/test_oauth_providers.py`+ - `tests/test_socketio_unknown_namespace.py`+ - `tests/test_tunnel_remote_link.py`+ - `tests/test_ws_manager.py`++## Child DOX Index++No child DOX files.diff --git a/tools/vision_load.py.dox.md b/tools/vision_load.py.dox.mdnew file mode 100644index 000000000..da9531242--- /dev/null+++ b/tools/vision_load.py.dox.md@@ -0,0 +1,50 @@+# vision_load.py DOX++## Purpose++- Own the `vision_load.py` agent tool.+- This module loads images into model-visible content for vision-capable models.+- Keep this file-level DOX profile synchronized with `vision_load.py` because this directory is intentionally flat.++## Ownership++- `vision_load.py` owns the runtime implementation.+- `vision_load.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `VisionLoad` (`Tool`)+ - `async execute(self, paths: list[str]=..., **kwargs) -> Response`+ - `async after_execution(self, response: Response, **kwargs)`+- Notable constants/configuration names: `TOKENS_ESTIMATE`.++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `VisionLoad` is a `Tool`.+- `VisionLoad` defines `execute(...)`.+- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence, secret handling.+- Imported dependency areas include: `helpers`, `helpers.print_style`, `helpers.tool`, `mimetypes`.++## Key Concepts++- Important called helpers/classes observed in the source: `self._get_max_embeds`, `Response`, `str.strip`, `self._context_id`, `chat_media.infer_source`, `chat_media.category_for_source`, `chat_media.save_image_base64`, `chat_media.save_image_data_url`, `chat_media.materialize_image_ref`, `str.strip.lower`, `ephemeral_images.is_ref`, `cls._is_data_image_url`, `self._is_data_image_url`, `plugins.get_plugin_config`, `images.to_data_url`, `normalized.startswith`, `ephemeral_images.display_ref`, `join`, `self.agent.hist_add_tool_result`, `history.RawMessage`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/test_browser_agent_regressions.py`+ - `tests/test_host_browser_connector.py`+ - `tests/test_office_desktop_state.py`+ - `tests/test_vision_load_image_refs.py`++## Child DOX Index++No child DOX files.diff --git a/tools/wait.py.dox.md b/tools/wait.py.dox.mdnew file mode 100644index 000000000..1f2a461f8--- /dev/null+++ b/tools/wait.py.dox.md@@ -0,0 +1,54 @@+# wait.py DOX++## Purpose++- Own the `wait.py` agent tool.+- This module lets the agent wait for a managed duration while respecting intervention flow.+- Keep this file-level DOX profile synchronized with `wait.py` because this directory is intentionally flat.++## Ownership++- `wait.py` owns the runtime implementation.+- `wait.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.+- Classes:+- `WaitTool` (`Tool`)+ - `async execute(self, **kwargs) -> Response`+ - `get_log_object(self)`+ - `get_heading(self, text: str=..., done: bool=...)`++## Runtime Contracts++- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.+- `WaitTool` is a `Tool`.+- `WaitTool` defines `execute(...)`.+- Observed side-effect areas: settings/state persistence.+- Imported dependency areas include: `asyncio`, `datetime`, `helpers.localization`, `helpers.print_style`, `helpers.tool`, `helpers.wait`.++## Key Concepts++- Important called helpers/classes observed in the source: `Localization.get.now`, `PrintStyle.info`, `self.agent.read_prompt`, `Response`, `self.agent.context.log.log`, `self.agent.handle_intervention`, `timedelta`, `managed_wait`, `Localization.get.localtime_str_to_utc_dt`, `wait_duration.total_seconds`, `Localization.get.serialize_datetime`, `self.get_heading`, `ValueError`.+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.++## Work Guidance++- Keep tool output concise, model-readable, and safe for history persistence.+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.+- Respect intervention flow for long-running, external, or user-visible operations.++## Verification++- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.+- Related tests observed by source search:+ - `tests/email_parser_test.py`+ - `tests/rate_limiter_test.py`+ - `tests/test_api_chat_lifetime.py`+ - `tests/test_browser_agent_regressions.py`+ - `tests/test_chat_compaction.py`+ - `tests/test_default_prompt_budget.py`+ - `tests/test_document_query_plugin.py`+ - `tests/test_download_toast_regressions.py`++## Child DOX Index++No child DOX files.diff --git a/webui/AGENTS.md b/webui/AGENTS.mdindex cb0d16344..27cce4b4f 100644--- a/webui/AGENTS.md+++ b/webui/AGENTS.md@@ -48,3 +48,5 @@ Direct child DOX files:| [components/AGENTS.md](components/AGENTS.md) | Alpine component HTML, component stores, and component-local styles. || [css/AGENTS.md](css/AGENTS.md) | Shared WebUI stylesheet modules. || [js/AGENTS.md](js/AGENTS.md) | Shared frontend JavaScript modules and client-side infrastructure. |+| [public/AGENTS.md](public/AGENTS.md) | First-party static WebUI images, icons, splash art, and PWA assets. |+| [vendor/AGENTS.md](vendor/AGENTS.md) | Vendored third-party browser libraries. |diff --git a/webui/components/AGENTS.md b/webui/components/AGENTS.mdindex 5390fb3bc..606f4ab65 100644--- a/webui/components/AGENTS.md+++ b/webui/components/AGENTS.md@@ -56,4 +56,21 @@## Child DOX Index-No child DOX files.+Direct child DOX files:++| Child | Scope |+| --- | --- |+| [_examples/AGENTS.md](_examples/AGENTS.md) | Reference component and store examples. |+| [canvas/AGENTS.md](canvas/AGENTS.md) | Right-canvas component surface and store. |+| [chat/AGENTS.md](chat/AGENTS.md) | Chat composer, attachments, queue, navigation, and top-section components. |+| [dropdown/AGENTS.md](dropdown/AGENTS.md) | Shared dropdown component. |+| [messages/AGENTS.md](messages/AGENTS.md) | Message rendering helpers, action buttons, process groups, and resize behavior. |+| [modals/AGENTS.md](modals/AGENTS.md) | Modal component workflows loaded through the shared modal stack. |+| [notifications/AGENTS.md](notifications/AGENTS.md) | Toasts, notification modal, icons, and notification store. |+| [plugins/AGENTS.md](plugins/AGENTS.md) | Plugin settings, info, list, execution, and toggle components. |+| [projects/AGENTS.md](projects/AGENTS.md) | Project creation, selection, edit, secrets, model, skill, and file-structure components. |+| [settings/AGENTS.md](settings/AGENTS.md) | Settings shell and built-in settings subsections. |+| [sidebar/AGENTS.md](sidebar/AGENTS.md) | Left sidebar layout, chat/task lists, top actions, and preferences. |+| [sync/AGENTS.md](sync/AGENTS.md) | WebUI sync status component and store. |+| [tooltips/AGENTS.md](tooltips/AGENTS.md) | Shared tooltip store and behavior. |+| [welcome/AGENTS.md](welcome/AGENTS.md) | Welcome screen, discovery cards, banners, and welcome state. |diff --git a/webui/components/_examples/AGENTS.md b/webui/components/_examples/AGENTS.mdnew file mode 100644index 000000000..882ae3eea--- /dev/null+++ b/webui/components/_examples/AGENTS.md@@ -0,0 +1,27 @@+# Component Examples DOX++## Purpose++- Own reference component and store examples for WebUI component authors.++## Ownership++- `_example-component.html` owns the component markup example.+- `_example-store.js` owns the store pattern example.++## Local Contracts++- Keep examples aligned with current component loader, Store Gating, and `createStore` patterns.+- Do not add product behavior or dependencies here.++## Work Guidance++- Prefer small examples that demonstrate current conventions clearly.++## Verification++- Manually inspect examples after component contract changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/canvas/AGENTS.md b/webui/components/canvas/AGENTS.mdnew file mode 100644index 000000000..3ec1d5006--- /dev/null+++ b/webui/components/canvas/AGENTS.md@@ -0,0 +1,28 @@+# Canvas Components DOX++## Purpose++- Own the right-canvas component surface and its state.++## Ownership++- `right-canvas.html` owns canvas markup.+- `right-canvas-store.js` owns canvas state, surface registration, and actions.+- `right-canvas.css` owns canvas-specific styling.++## Local Contracts++- Keep registered surfaces compatible with WebUI extension hooks.+- Preserve responsive layout and avoid overlapping the chat/sidebar shells.++## Work Guidance++- Use existing surface and extension helpers before adding new canvas infrastructure.++## Verification++- Smoke-test right-canvas open, close, resize, and registered surfaces after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/chat/AGENTS.md b/webui/components/chat/AGENTS.mdnew file mode 100644index 000000000..220667ecb--- /dev/null+++ b/webui/components/chat/AGENTS.md@@ -0,0 +1,32 @@+# Chat Components DOX++## Purpose++- Own chat composer, attachments, message queue, navigation, and top-section component groups.++## Ownership++- `input/` owns composer input, progress, banners, and bottom action bars.+- `attachments/` owns drag/drop and attachment preview UI.+- `message-queue/` owns queued message display and store state.+- `navigation/` owns chat navigation state.+- `top-section/` owns chat header/top area.++## Local Contracts++- Preserve Store Gating for all store-backed chat components.+- Use shared API, WebSocket, notification, and attachment helpers where available.+- Do not bypass CSRF or WebSocket state-sync expectations.++## Work Guidance++- Keep composer and attachment changes responsive across desktop and mobile.+- Coordinate payload changes with backend chat, upload, and WebSocket handlers.++## Verification++- Smoke-test sending, queued messages, attachments, drag/drop, and navigation after visible changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/dropdown/AGENTS.md b/webui/components/dropdown/AGENTS.mdnew file mode 100644index 000000000..a6e9f284e--- /dev/null+++ b/webui/components/dropdown/AGENTS.md@@ -0,0 +1,26 @@+# Dropdown Component DOX++## Purpose++- Own the shared dropdown component used by WebUI controls.++## Ownership++- `dropdown.html` owns dropdown markup, behavior hooks, and component-local styling.++## Local Contracts++- Keep keyboard, focus, and click-outside behavior compatible with existing callers.+- Avoid caller-specific assumptions in the shared dropdown.++## Work Guidance++- Prefer component attributes and slots over hardcoded option sets.++## Verification++- Smoke-test each caller that uses the dropdown after behavior changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/messages/AGENTS.md b/webui/components/messages/AGENTS.mdnew file mode 100644index 000000000..78c340802--- /dev/null+++ b/webui/components/messages/AGENTS.md@@ -0,0 +1,29 @@+# Message Components DOX++## Purpose++- Own message rendering helpers, action buttons, process groups, and resize behavior.++## Ownership++- `action-buttons/` owns simple message action controls.+- `process-group/` owns grouped process-step DOM and styling helpers.+- `resize/` owns message resize state.++## Local Contracts++- Keep message DOM helpers compatible with extension points that modify rendered messages.+- Sanitize or safely render model/user-provided content through shared rendering paths.+- Avoid layout shifts that break long-running message streaming.++## Work Guidance++- Coordinate changes with `webui/js/messages.js` and frontend extension hooks.++## Verification++- Smoke-test message rendering, action buttons, process groups, and resizing after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/modals/AGENTS.md b/webui/components/modals/AGENTS.mdnew file mode 100644index 000000000..45783107e--- /dev/null+++ b/webui/components/modals/AGENTS.md@@ -0,0 +1,30 @@+# Modal Components DOX++## Purpose++- Own WebUI modal component content loaded through the shared modal stack.++## Ownership++- Each direct child folder owns one modal workflow and its store.+- Modal HTML files own body content, titles, scoped styles, and `data-modal-footer` content.+- Modal store files own modal-local state and cleanup.++## Local Contracts++- Use `openModal(path)` and `closeModal()` from `/js/modals.js`.+- Keep footer content marked with `data-modal-footer` when using pinned modal actions.+- Do not introduce a parallel overlay, backdrop, or teleport modal system.++## Work Guidance++- Keep modal state cleanup explicit because stores may outlive DOM nodes.+- Preserve stacked modal, Escape, click-outside, scroll, and footer behavior.++## Verification++- Smoke-test open, close, Escape, click-outside, scrolling, stacked modals, and pinned footers after modal changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/notifications/AGENTS.md b/webui/components/notifications/AGENTS.mdnew file mode 100644index 000000000..071bf076f--- /dev/null+++ b/webui/components/notifications/AGENTS.md@@ -0,0 +1,30 @@+# Notification Components DOX++## Purpose++- Own WebUI toast, modal, icon, and notification store behavior.++## Ownership++- `notification-store.js` owns notification state and public helper actions.+- `notification-toast-stack.html` owns toast rendering.+- `notification-modal.html` owns notification detail modal UI.+- `notification-icons.html` owns shared notification icon markup.++## Local Contracts++- Use the notification system for user-facing success, warning, info, and error feedback.+- Keep public helper names stable for core and plugin callers.+- Avoid exposing secrets or raw auth payloads in notification text.++## Work Guidance++- Coordinate helper changes with plugin UI contracts and existing frontend imports.++## Verification++- Smoke-test toast display, dismiss, modal details, and notification severity styling.++## Child DOX Index++No child DOX files.diff --git a/webui/components/plugins/AGENTS.md b/webui/components/plugins/AGENTS.mdnew file mode 100644index 000000000..219c01176--- /dev/null+++ b/webui/components/plugins/AGENTS.md@@ -0,0 +1,30 @@+# Plugin Components DOX++## Purpose++- Own core WebUI plugin settings, info, list, execution, and toggle components.++## Ownership++- Root plugin component files own shared plugin settings and info screens.+- `list/` owns plugin list and execute modal components.+- `toggle/` owns scoped plugin activation UI.+- Store files own plugin modal and settings state.++## Local Contracts++- Keep plugin settings modals bound through `$store.pluginSettingsPrototype` conventions.+- Preserve global and scoped toggle semantics using `.toggle-1` and `.toggle-0`.+- Use notification helpers for plugin UI feedback.++## Work Guidance++- Coordinate plugin API payload changes with `helpers/plugins.py` and plugin API handlers.++## Verification++- Smoke-test plugin list, settings, scoped toggles, plugin info, and execute modal after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/projects/AGENTS.md b/webui/components/projects/AGENTS.mdnew file mode 100644index 000000000..d5a9855c9--- /dev/null+++ b/webui/components/projects/AGENTS.md@@ -0,0 +1,30 @@+# Project Components DOX++## Purpose++- Own WebUI project creation, selection, editing, secrets, model, skill, and file-structure components.++## Ownership++- `projects-store.js` owns project state and actions.+- `project-create.html`, `project-list.html`, and `project-selector.html` own project creation and navigation UI.+- `project-edit*.html` files own project editing subsections.+- `project-file-structure-test.html` owns file-structure test UI.++## Local Contracts++- Keep project API payloads synchronized with backend project handlers.+- Do not expose project secrets in logs, URLs, or long-lived frontend state unnecessarily.+- Preserve scoped settings interactions with plugins, models, and skills.++## Work Guidance++- Verify project edit flows when changing shared project store state.++## Verification++- Smoke-test create, select, edit, secrets, LLM, skills, and file-structure flows after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/settings/AGENTS.md b/webui/components/settings/AGENTS.mdnew file mode 100644index 000000000..f44e4a596--- /dev/null+++ b/webui/components/settings/AGENTS.md@@ -0,0 +1,29 @@+# Settings Components DOX++## Purpose++- Own WebUI settings shell and built-in settings subsections.++## Ownership++- `settings.html` and `settings-store.js` own the settings shell and state.+- Subdirectories own settings areas such as agent, external, developer, MCP, backup, plugins, secrets, skills, tunnel, and A2A.++## Local Contracts++- Keep settings payloads synchronized with backend APIs and plugin settings contracts.+- Do not store secrets in localStorage, URLs, or console output.+- Preserve Store Gating and modal footer conventions in settings components.++## Work Guidance++- Prefer subsection-local stores for complex settings areas.+- Coordinate plugin settings UI changes with `webui/components/plugins/` and `plugins/AGENTS.md`.++## Verification++- Smoke-test changed settings tabs and save/reload behavior after visible or API changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/sidebar/AGENTS.md b/webui/components/sidebar/AGENTS.mdnew file mode 100644index 000000000..5cacb10d9--- /dev/null+++ b/webui/components/sidebar/AGENTS.md@@ -0,0 +1,31 @@+# Sidebar Components DOX++## Purpose++- Own left sidebar layout, chat/task lists, top actions, and bottom preferences components.++## Ownership++- `left-sidebar.html` and `sidebar-store.js` own sidebar shell and shared state.+- `top-section/` owns header and quick actions.+- `chats/` owns chat list UI and state.+- `tasks/` owns task list UI and state.+- `bottom/` owns lower sidebar controls and preferences panel.++## Local Contracts++- Preserve responsive sidebar behavior and collapsed/expanded state.+- Keep chat and task list updates compatible with WebSocket state sync.+- Avoid text or controls overflowing fixed sidebar widths.++## Work Guidance++- Coordinate navigation and state changes with WebSocket sync and chat/project stores.++## Verification++- Smoke-test sidebar collapse, chat list, task list, quick actions, and preferences after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/sync/AGENTS.md b/webui/components/sync/AGENTS.mdnew file mode 100644index 000000000..d47d46b80--- /dev/null+++ b/webui/components/sync/AGENTS.md@@ -0,0 +1,27 @@+# Sync Components DOX++## Purpose++- Own WebUI state synchronization status UI and store.++## Ownership++- `sync-store.js` owns sync status state.+- `sync-status.html` owns sync indicator markup.++## Local Contracts++- Keep sync state compatible with WebSocket state-sync events.+- Avoid noisy user-facing alerts for transient sync state unless existing UX expects them.++## Work Guidance++- Coordinate sync changes with WebSocket client and backend WebSocket extensions.++## Verification++- Smoke-test connection, reconnect, and state refresh indicators after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/tooltips/AGENTS.md b/webui/components/tooltips/AGENTS.mdnew file mode 100644index 000000000..6fb50e7fe--- /dev/null+++ b/webui/components/tooltips/AGENTS.md@@ -0,0 +1,26 @@+# Tooltip Components DOX++## Purpose++- Own shared tooltip state and behavior for WebUI controls.++## Ownership++- `tooltip-store.js` owns tooltip state, positioning, and actions.++## Local Contracts++- Keep tooltip positioning compatible with desktop and mobile layouts.+- Do not make tooltips required for completing a workflow.++## Work Guidance++- Prefer concise tooltip text and stable positioning around icon-only controls.++## Verification++- Smoke-test hover/focus tooltip behavior after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/components/welcome/AGENTS.md b/webui/components/welcome/AGENTS.mdnew file mode 100644index 000000000..4237418aa--- /dev/null+++ b/webui/components/welcome/AGENTS.md@@ -0,0 +1,28 @@+# Welcome Components DOX++## Purpose++- Own the WebUI welcome screen, discovery cards, banners, and related state.++## Ownership++- `welcome-screen.html` owns welcome screen markup and layout.+- `welcome-store.js` owns welcome state, banners, cards, and actions.++## Local Contracts++- Keep banner and discovery card behavior compatible with Python `banners` extensions.+- Supported banner/card CTA actions must stay synchronized with plugin discovery contracts.+- Do not show setup prompts for already configured plugins when backend status can prevent it.++## Work Guidance++- Coordinate visual card or CTA changes with plugin discovery and onboarding surfaces.++## Verification++- Smoke-test alert banners, feature cards, dismissal, priority ordering, and CTA actions after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/public/AGENTS.md b/webui/public/AGENTS.mdnew file mode 100644index 000000000..cdf8bfddc--- /dev/null+++ b/webui/public/AGENTS.md@@ -0,0 +1,32 @@+# WebUI Public Assets DOX++## Purpose++- Own first-party static images, icons, splash art, and PWA assets served by the WebUI.+- Keep visual assets stable for core UI surfaces and settings sections.++## Ownership++- SVG files own first-party icons and settings/category symbols.+- Raster files own splash, thumbnail, and app-icon imagery.+- Asset filenames are part of the frontend reference contract when used by HTML, CSS, JS, or plugins.++## Local Contracts++- Do not add secrets, user uploads, generated runtime files, or private branding assets here.+- Keep asset paths stable or update every frontend reference in the same change.+- Prefer optimized web formats and reasonable file sizes for assets loaded during startup.++## Work Guidance++- Use this folder for shared first-party assets, not component-specific images that belong with a plugin or component.+- Check contrast and legibility for icon changes in both light and dark UI contexts when relevant.++## Verification++- Manually smoke-test pages that reference changed assets.+- Run frontend checks when asset references are covered by tests.++## Child DOX Index++No child DOX files.diff --git a/webui/vendor/AGENTS.md b/webui/vendor/AGENTS.mdnew file mode 100644index 000000000..28ad931ce--- /dev/null+++ b/webui/vendor/AGENTS.md@@ -0,0 +1,42 @@+# WebUI Vendor Assets DOX++## Purpose++- Own vendored third-party browser libraries served by the WebUI.+- Keep external library updates intentional, isolated, and reviewable.++## Ownership++- Each direct child directory owns one vendored library or library bundle.+- Vendored files should be treated as upstream artifacts, with local edits avoided unless clearly documented.++## Local Contracts++- Do not edit vendored files for application behavior when a wrapper or caller can own the change.+- Preserve license, version, and distribution assumptions for third-party assets.+- Do not add package-manager caches, build outputs, or unrelated downloaded artifacts.++## Work Guidance++- Prefer replacing a vendor bundle with a clean upstream build over hand-editing minified files.+- Coordinate library path changes with all HTML, CSS, and JS imports.++## Verification++- Manually smoke-test UI paths that load an updated vendor library.+- Run frontend checks when imports or wrappers are covered.++## Child DOX Index++Direct child DOX files:++| Child | Scope |+| --- | --- |+| [_ace/AGENTS.md](_ace/AGENTS.md) | Minimal Ace editor subset used by core editor surfaces. |+| [ace-min/AGENTS.md](ace-min/AGENTS.md) | Full minified Ace distribution and supporting assets. |+| [alpine/AGENTS.md](alpine/AGENTS.md) | Vendored Alpine.js core and collapse plugin. |+| [dompurify/AGENTS.md](dompurify/AGENTS.md) | Vendored DOMPurify sanitizer module. |+| [flatpickr/AGENTS.md](flatpickr/AGENTS.md) | Vendored Flatpickr date/time picker assets. |+| [google/AGENTS.md](google/AGENTS.md) | Vendored Google Material Symbols font and stylesheet. |+| [katex/AGENTS.md](katex/AGENTS.md) | Vendored KaTeX rendering assets. |+| [marked/AGENTS.md](marked/AGENTS.md) | Vendored Marked markdown parser module. |diff --git a/webui/vendor/_ace/AGENTS.md b/webui/vendor/_ace/AGENTS.mdnew file mode 100644index 000000000..716d83274--- /dev/null+++ b/webui/vendor/_ace/AGENTS.md@@ -0,0 +1,27 @@+# Ace Minimal Vendor DOX++## Purpose++- Own the minimal Ace editor files used by focused WebUI editor flows.++## Ownership++- JavaScript mode, theme, worker, and loader files are vendored Ace artifacts.+- `ace.min.css` owns local Ace styling required by the bundled files.++## Local Contracts++- Avoid hand-editing Ace source files; replace from a known upstream build when updating.+- Keep filenames stable for existing WebUI imports.++## Work Guidance++- Prefer adding only the modes and themes actually needed by core UI surfaces.++## Verification++- Smoke-test editor surfaces that load this subset after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/vendor/ace-min/AGENTS.md b/webui/vendor/ace-min/AGENTS.mdnew file mode 100644index 000000000..ec6faa949--- /dev/null+++ b/webui/vendor/ace-min/AGENTS.md@@ -0,0 +1,28 @@+# Ace Min Vendor DOX++## Purpose++- Own the full minified Ace editor distribution and static assets.++## Ownership++- `ace.js`, extensions, modes, themes, workers, keybindings, and image assets are vendored Ace artifacts.++## Local Contracts++- Treat files as upstream-generated assets.+- Do not hand-edit minified or generated files for product behavior.+- Preserve referenced asset filenames unless all imports are updated.++## Work Guidance++- Replace this directory with a clean upstream distribution when updating Ace.+- Keep unrelated generated files and local caches out of this vendor bundle.++## Verification++- Smoke-test editor and code-input surfaces after vendor updates.++## Child DOX Index++No child DOX files.diff --git a/webui/vendor/alpine/AGENTS.md b/webui/vendor/alpine/AGENTS.mdnew file mode 100644index 000000000..64cb52cb2--- /dev/null+++ b/webui/vendor/alpine/AGENTS.md@@ -0,0 +1,27 @@+# Alpine Vendor DOX++## Purpose++- Own vendored Alpine.js browser runtime files used by the WebUI.++## Ownership++- `alpine.min.js` owns the Alpine core runtime.+- `alpine.collapse.min.js` owns the collapse plugin runtime.++## Local Contracts++- Do not modify vendored Alpine runtime files directly.+- Keep load order compatible with `webui/js/initFw.js` and component initialization.++## Work Guidance++- Update Alpine as a deliberate vendor bump and smoke-test component lifecycle directives.++## Verification++- Smoke-test WebUI startup, component loading, and store initialization after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/vendor/dompurify/AGENTS.md b/webui/vendor/dompurify/AGENTS.mdnew file mode 100644index 000000000..693d2ad0f--- /dev/null+++ b/webui/vendor/dompurify/AGENTS.md@@ -0,0 +1,27 @@+# DOMPurify Vendor DOX++## Purpose++- Own the vendored DOMPurify sanitizer module used for safe HTML rendering.++## Ownership++- `purify.es.mjs` owns the browser module imported by WebUI sanitization paths.++## Local Contracts++- Do not weaken sanitizer behavior through local edits.+- Keep import paths synchronized with markdown and message rendering code.++## Work Guidance++- Replace with a clean upstream module when updating.+- Coordinate sanitizer updates with security-sensitive rendering tests.++## Verification++- Run or manually exercise HTML/markdown rendering paths after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/vendor/flatpickr/AGENTS.md b/webui/vendor/flatpickr/AGENTS.mdnew file mode 100644index 000000000..5e94ab2e8--- /dev/null+++ b/webui/vendor/flatpickr/AGENTS.md@@ -0,0 +1,27 @@+# Flatpickr Vendor DOX++## Purpose++- Own vendored Flatpickr date and time picker assets.++## Ownership++- `flatpickr.min.js` owns picker runtime behavior.+- `flatpickr.min.css` owns picker vendor styling.++## Local Contracts++- Do not hand-edit minified vendor files for application behavior.+- Keep scheduler and date-input imports synchronized with file paths.++## Work Guidance++- Replace from a clean upstream release when updating.++## Verification++- Smoke-test scheduler or date/time inputs after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/vendor/google/AGENTS.md b/webui/vendor/google/AGENTS.mdnew file mode 100644index 000000000..effd8c15b--- /dev/null+++ b/webui/vendor/google/AGENTS.md@@ -0,0 +1,27 @@+# Google Icons Vendor DOX++## Purpose++- Own vendored Google Material Symbols font and stylesheet assets.++## Ownership++- `google-icons.css` owns the font-face and icon class definitions.+- `google-icons.ttf` owns the font binary used by the WebUI.++## Local Contracts++- Keep font filenames and CSS references synchronized.+- Do not add unrelated remote font assets or tracking references.++## Work Guidance++- Replace font and stylesheet together when updating icon coverage.++## Verification++- Smoke-test visible icon surfaces after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/vendor/katex/AGENTS.md b/webui/vendor/katex/AGENTS.mdnew file mode 100644index 000000000..983d15276--- /dev/null+++ b/webui/vendor/katex/AGENTS.md@@ -0,0 +1,28 @@+# KaTeX Vendor DOX++## Purpose++- Own vendored KaTeX assets used for math rendering.++## Ownership++- `katex.min.js` owns core rendering behavior.+- `katex.auto-render.min.js` owns auto-render support.+- `katex.min.css` owns KaTeX styling.++## Local Contracts++- Do not hand-edit minified vendor files.+- Keep markdown/message rendering imports synchronized with asset paths.++## Work Guidance++- Replace from a clean upstream release when updating KaTeX.++## Verification++- Smoke-test markdown or message content containing math after changes.++## Child DOX Index++No child DOX files.diff --git a/webui/vendor/marked/AGENTS.md b/webui/vendor/marked/AGENTS.mdnew file mode 100644index 000000000..e171735ba--- /dev/null+++ b/webui/vendor/marked/AGENTS.md@@ -0,0 +1,26 @@+# Marked Vendor DOX++## Purpose++- Own the vendored Marked markdown parser module.++## Ownership++- `marked.esm.js` owns markdown parsing behavior imported by WebUI rendering code.++## Local Contracts++- Do not hand-edit the vendored parser for application behavior.+- Keep parser updates coordinated with sanitization and message rendering expectations.++## Work Guidance++- Replace with a clean upstream module when updating.++## Verification++- Smoke-test markdown rendering after changes.++## Child DOX Index++No child DOX files.