@samitouri / QOSami_Agents_Zero / commits / e138e33c

Add file-level DOX docs & update AGENTS indexes

Add comprehensive file-level DOX documentation across the repo and update directory AGENTS.md indexes. Many new `*.py.dox.md` files were added under api, helpers, tools, plugins, extensions, webui, and other dirs to document endpoint purpose, ownership, runtime contracts, work guidance, and verification. Several AGENTS.md files were created or updated (agents profiles, api, docker, extensions, helpers, plugins, skills, webui components, etc.) to list child DOX files and clarify documentation/work guidance. Also add example and bundled profile DOX files (agent0, default, developer, hacker, researcher) and minor updates to helpers/dirty_json.py and its tests. These changes improve on-disk documentation coverage and establish the convention that each direct runtime file should have a matching `*.dox.md` describing its contracts and verification steps.

frdel committed Jun 8, 2026 at 12:41 UTC e138e33ca998484c435ed87e9fc300ae9e1c5933
312 files changed +13246 -10
agents/AGENTS.md
+10 -1
@@ -31,4 +31,13 @@
31
32 ## Child DOX Index
33
34 -No child DOX files.
34 +Direct child DOX files:
35 +
36 +| Child | Scope |
37 +| --- | --- |
38 +| [_example/AGENTS.md](_example/AGENTS.md) | Reference profile demonstrating profile-local prompts, tools, and extensions. |
39 +| [agent0/AGENTS.md](agent0/AGENTS.md) | Main user-facing Agent Zero profile metadata. |
40 +| [default/AGENTS.md](default/AGENTS.md) | Base profile metadata and inherited prompt specifics. |
41 +| [developer/AGENTS.md](developer/AGENTS.md) | Software development specialist profile. |
42 +| [hacker/AGENTS.md](hacker/AGENTS.md) | Cyber security and penetration testing specialist profile. |
43 +| [researcher/AGENTS.md](researcher/AGENTS.md) | Research, data analysis, and reporting specialist profile. |
agents/_example/AGENTS.md new
+33
@@ -0,0 +1,33 @@
1 +# Example Agent Profile DOX
2 +
3 +## Purpose
4 +
5 +- Own the reference profile used to demonstrate bundled profile layout.
6 +- Show how profile-local prompts, tools, and extensions fit beside `agent.yaml`.
7 +
8 +## Ownership
9 +
10 +- `agent.yaml` owns the example profile metadata.
11 +- `prompts/` owns prompt override examples.
12 +- `tools/` owns profile-local tool examples.
13 +- `extensions/` owns profile-local lifecycle extension examples.
14 +
15 +## Local Contracts
16 +
17 +- Keep this profile generic, minimal, and safe to copy into user or plugin profile work.
18 +- Do not add product behavior here that should live in a real bundled profile.
19 +- Profile-local tools and extensions must follow the same contracts as root tools and extensions.
20 +
21 +## Work Guidance
22 +
23 +- Prefer simple examples that illustrate structure over complex behavior.
24 +- Update related skill guidance when the example profile layout changes.
25 +
26 +## Verification
27 +
28 +- Manually inspect YAML and prompt filenames after edits.
29 +- Run profile-loading tests when changing discovery or profile schema assumptions.
30 +
31 +## Child DOX Index
32 +
33 +No child DOX files.
agents/agent0/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# Agent 0 Profile DOX
2 +
3 +## Purpose
4 +
5 +- Own the main user-facing Agent Zero profile metadata.
6 +- Keep the primary assistant profile discoverable and distinct from subordinate specialist profiles.
7 +
8 +## Ownership
9 +
10 +- `agent.yaml` owns the profile title, description, and delegation context.
11 +- Prompt behavior is inherited from the default profile unless a local prompt override is added.
12 +
13 +## Local Contracts
14 +
15 +- Keep `Agent 0` suitable as the direct conversation agent for the system.
16 +- Do not add narrow specialist behavior that belongs in `developer/`, `researcher/`, `hacker/`, or a custom user profile.
17 +- Do not store user-specific preferences, provider settings, or secrets in this profile.
18 +
19 +## Work Guidance
20 +
21 +- Keep metadata concise because it appears in profile selection and delegation contexts.
22 +- Coordinate substantial behavior changes with default prompts and WebUI profile selection.
23 +
24 +## Verification
25 +
26 +- Manually inspect `agent.yaml` for valid YAML after edits.
27 +- Run profile-loading tests when changing schema or discovery behavior.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
agents/default/AGENTS.md new
+32
@@ -0,0 +1,32 @@
1 +# Default Agent Profile DOX
2 +
3 +## Purpose
4 +
5 +- Own base profile metadata and default prompt specifics inherited by specialized profiles.
6 +- Provide the shared behavior layer for bundled and custom profiles.
7 +
8 +## Ownership
9 +
10 +- `agent.yaml` owns default profile metadata.
11 +- `agent.system.main.specifics.md` owns default profile-specific system prompt content.
12 +- Additional prompt overrides under this directory become shared defaults unless a child profile overrides them.
13 +
14 +## Local Contracts
15 +
16 +- Keep default behavior broad, framework-compatible, and safe for inheritance.
17 +- Avoid role-specific instructions that belong in specialist profiles.
18 +- Prompt filenames must match the framework prompt override names they target.
19 +
20 +## Work Guidance
21 +
22 +- Prefer small, explicit prompt changes with clear inheritance impact.
23 +- Check bundled specialist profiles after changing default behavior.
24 +
25 +## Verification
26 +
27 +- Manually inspect YAML and prompt rendering assumptions after edits.
28 +- Run prompt/profile tests when changing inherited prompt behavior.
29 +
30 +## Child DOX Index
31 +
32 +No child DOX files.
agents/developer/AGENTS.md new
+32
@@ -0,0 +1,32 @@
1 +# Developer Agent Profile DOX
2 +
3 +## Purpose
4 +
5 +- Own the bundled software development specialist profile.
6 +- Keep development, debugging, refactoring, and architecture behavior separate from general agent defaults.
7 +
8 +## Ownership
9 +
10 +- `agent.yaml` owns title, description, and delegation context for software development work.
11 +- `prompts/` owns developer-specific prompt overrides when present.
12 +- `extensions/` owns developer-specific lifecycle hooks when present.
13 +
14 +## Local Contracts
15 +
16 +- Keep this profile focused on software engineering tasks.
17 +- Do not hardcode repository-local credentials, paths, or project-specific conventions.
18 +- Prompt overrides must preserve the framework tool-call and response contracts.
19 +
20 +## Work Guidance
21 +
22 +- Align developer behavior with the root engineering and tool contracts.
23 +- Prefer profile prompt edits over core prompt edits when the behavior is specific to development tasks.
24 +
25 +## Verification
26 +
27 +- Manually inspect `agent.yaml` for valid YAML after edits.
28 +- Run prompt/profile tests when changing profile loading or developer prompt behavior.
29 +
30 +## Child DOX Index
31 +
32 +No child DOX files.
agents/hacker/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# Hacker Agent Profile DOX
2 +
3 +## Purpose
4 +
5 +- Own the bundled cyber security and penetration testing specialist profile.
6 +- Keep security-audit behavior scoped to this profile instead of default agent behavior.
7 +
8 +## Ownership
9 +
10 +- `agent.yaml` owns title, description, and delegation context for security work.
11 +- `prompts/` owns security-specific prompt overrides when present.
12 +
13 +## Local Contracts
14 +
15 +- Keep the profile focused on authorized security analysis, vulnerability research, and defensive audit tasks.
16 +- Do not add secrets, target-specific credentials, or local environment assumptions.
17 +- Preserve the framework tool-call contract and safety expectations.
18 +
19 +## Work Guidance
20 +
21 +- Keep security instructions operational and bounded to legitimate testing contexts.
22 +- Coordinate broad safety changes with core prompts and relevant tests.
23 +
24 +## Verification
25 +
26 +- Manually inspect `agent.yaml` for valid YAML after edits.
27 +- Run prompt/profile tests when changing profile discovery or security prompt behavior.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
agents/researcher/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# Researcher Agent Profile DOX
2 +
3 +## Purpose
4 +
5 +- Own the bundled research, data analysis, and reporting specialist profile.
6 +- Keep evidence-gathering and report-oriented behavior separate from general defaults.
7 +
8 +## Ownership
9 +
10 +- `agent.yaml` owns title, description, and delegation context for research work.
11 +- `prompts/` owns researcher-specific prompt overrides when present.
12 +
13 +## Local Contracts
14 +
15 +- Keep this profile focused on information gathering, analysis, synthesis, and reporting.
16 +- Do not bake in project-specific sources, credentials, or local paths.
17 +- Preserve the framework tool-call and response contracts.
18 +
19 +## Work Guidance
20 +
21 +- Prefer prompt changes that improve citation, evidence handling, and analysis quality for research tasks.
22 +- Coordinate broad research behavior changes with document, memory, or browser plugin contracts when relevant.
23 +
24 +## Verification
25 +
26 +- Manually inspect `agent.yaml` for valid YAML after edits.
27 +- Run prompt/profile tests when changing discovery or researcher prompt behavior.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
api/AGENTS.md
+6
@@ -19,17 +19,23 @@
19 - Keep CSRF and authentication protections intact for browser-facing state-changing endpoints.
20 - WebSocket handlers must derive from `helpers.ws.WsHandler` and validate event data before using it.
21 - Do not return secrets, raw environment values, private files, or unfiltered exception details to clients.
22 +- 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.
23 +- 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.
24 +- When a Python endpoint is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change.
25 +- Do not leave stale file-level DOX after endpoint deletion or rename.
26
27 ## Work Guidance
28
29 - Use helpers for shared behavior instead of duplicating persistence, auth, file, project, plugin, or notification logic in endpoints.
30 - Keep request and response payloads stable; update frontend callers and tests together when payloads change.
31 - Prefer `Response` for files, redirects, status codes, and plain-text errors; return dictionaries for JSON success payloads.
32 +- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed endpoint behavior is described there.
33
34 ## Verification
35
36 - Run targeted `pytest tests/test_*api*.py`, endpoint-specific tests, or WebSocket tests after changing handler behavior.
37 - For auth, CSRF, upload/download, tunnel, or file endpoints, run the nearest security regression tests.
38 +- Check file-level documentation coverage with a script or shell loop that verifies each `api/*.py` has a matching `api/*.py.dox.md`.
39
40 ## Child DOX Index
41
api/agent_profile_set.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# agent_profile_set.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `agent_profile_set.py` API endpoint.
6 +- This module sets the active agent profile for a chat context and returns profile label metadata.
7 +- Keep this file-level DOX profile synchronized with `agent_profile_set.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `agent_profile_set.py` owns the runtime implementation.
12 +- `agent_profile_set.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SetAgentProfile` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +- Top-level functions:
17 +- `_agent_profile_labels() -> dict[str, str]`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `SetAgentProfile` is an `ApiHandler`.
24 +- `SetAgentProfile` defines `process(...)`.
25 +- Observed side-effect areas: filesystem writes, settings/state persistence.
26 +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.persist_chat`, `helpers.state_monitor_integration`, `initialize`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
36 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
37 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
38 +
39 +## Verification
40 +
41 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
42 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
api/agents.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# agents.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `agents.py` API endpoint.
6 +- This module lists available agent profiles for selection and delegation UI flows.
7 +- Keep this file-level DOX profile synchronized with `agents.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `agents.py` owns the runtime implementation.
12 +- `agents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Agents` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `Agents` is an `ApiHandler`.
22 +- `Agents` defines `process(...)`.
23 +- Imported dependency areas include: `helpers`, `helpers.api`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `subagents.get_all_agents_list`, `Exception`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- Related tests observed by source search:
40 + - `tests/test_default_prompt_budget.py`
41 + - `tests/test_office_document_store.py`
42 + - `tests/test_projects.py`
43 + - `tests/test_skills_runtime.py`
44 + - `tests/test_time_travel.py`
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
api/api_files_get.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# api_files_get.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `api_files_get.py` API endpoint.
6 +- This module returns downloadable or inspectable files exposed through the external API surface.
7 +- Keep this file-level DOX profile synchronized with `api_files_get.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `api_files_get.py` owns the runtime implementation.
12 +- `api_files_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ApiFilesGet` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_csrf(cls) -> bool`
17 + - `requires_api_key(cls) -> bool`
18 + - `get_methods(cls) -> list[str]`
19 + - `async process(self, input: dict, request: Request) -> dict | Response`
20 +
21 +## Runtime Contracts
22 +
23 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
24 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
25 +- `ApiFilesGet` is an `ApiHandler`.
26 +- `ApiFilesGet` defines `process(...)`.
27 +- `ApiFilesGet` defines `get_methods(...)`.
28 +- `ApiFilesGet` defines `requires_auth(...)`.
29 +- `ApiFilesGet` defines `requires_csrf(...)`.
30 +- `ApiFilesGet` defines `requires_api_key(...)`.
31 +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence.
32 +- Imported dependency areas include: `base64`, `helpers`, `helpers.api`, `helpers.print_style`, `json`, `os`.
33 +
34 +## Key Concepts
35 +
36 +- 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`.
37 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
38 +
39 +## Work Guidance
40 +
41 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
42 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
43 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
44 +
45 +## Verification
46 +
47 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
48 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
api/api_log_get.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# api_log_get.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `api_log_get.py` API endpoint.
6 +- This module returns API/chat log data for external API clients.
7 +- Keep this file-level DOX profile synchronized with `api_log_get.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `api_log_get.py` owns the runtime implementation.
12 +- `api_log_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ApiLogGet` (`ApiHandler`)
15 + - `get_methods(cls) -> list[str]`
16 + - `requires_auth(cls) -> bool`
17 + - `requires_csrf(cls) -> bool`
18 + - `requires_api_key(cls) -> bool`
19 + - `async process(self, input: dict, request: Request) -> dict | Response`
20 +
21 +## Runtime Contracts
22 +
23 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
24 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
25 +- `ApiLogGet` is an `ApiHandler`.
26 +- `ApiLogGet` defines `process(...)`.
27 +- `ApiLogGet` defines `get_methods(...)`.
28 +- `ApiLogGet` defines `requires_auth(...)`.
29 +- `ApiLogGet` defines `requires_csrf(...)`.
30 +- `ApiLogGet` defines `requires_api_key(...)`.
31 +- Observed side-effect areas: settings/state persistence, secret handling.
32 +- Imported dependency areas include: `agent`, `helpers.api`.
33 +
34 +## Key Concepts
35 +
36 +- Important called helpers/classes observed in the source: `AgentContext.use`, `Response`, `context.log.output`.
37 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
38 +
39 +## Work Guidance
40 +
41 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
42 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
43 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
44 +
45 +## Verification
46 +
47 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
48 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
api/api_message.py.dox.md new
+51
@@ -0,0 +1,51 @@
1 +# api_message.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `api_message.py` API endpoint.
6 +- This module accepts external API messages and dispatches them into Agent Zero chat processing.
7 +- Keep this file-level DOX profile synchronized with `api_message.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `api_message.py` owns the runtime implementation.
12 +- `api_message.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ApiMessage` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_csrf(cls) -> bool`
17 + - `requires_api_key(cls) -> bool`
18 + - `async process(self, input: dict, request: Request) -> dict | Response`
19 +
20 +## Runtime Contracts
21 +
22 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
23 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
24 +- `ApiMessage` is an `ApiHandler`.
25 +- `ApiMessage` defines `process(...)`.
26 +- `ApiMessage` defines `requires_auth(...)`.
27 +- `ApiMessage` defines `requires_csrf(...)`.
28 +- `ApiMessage` defines `requires_api_key(...)`.
29 +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, secret handling, scheduler state.
30 +- Imported dependency areas include: `agent`, `base64`, `datetime`, `helpers`, `helpers.api`, `helpers.print_style`, `helpers.projects`, `helpers.security`, `initialize`, `os`, `uuid`.
31 +
32 +## Key Concepts
33 +
34 +- 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`.
35 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
36 +
37 +## Work Guidance
38 +
39 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
40 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
41 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
42 +
43 +## Verification
44 +
45 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
46 +- Related tests observed by source search:
47 + - `tests/test_api_chat_lifetime.py`
48 +
49 +## Child DOX Index
50 +
51 +No child DOX files.
api/api_reset_chat.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# api_reset_chat.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `api_reset_chat.py` API endpoint.
6 +- This module resets an API-created chat context.
7 +- Keep this file-level DOX profile synchronized with `api_reset_chat.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `api_reset_chat.py` owns the runtime implementation.
12 +- `api_reset_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ApiResetChat` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_csrf(cls) -> bool`
17 + - `requires_api_key(cls) -> bool`
18 + - `get_methods(cls) -> list[str]`
19 + - `async process(self, input: dict, request: Request) -> dict | Response`
20 +
21 +## Runtime Contracts
22 +
23 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
24 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
25 +- `ApiResetChat` is an `ApiHandler`.
26 +- `ApiResetChat` defines `process(...)`.
27 +- `ApiResetChat` defines `get_methods(...)`.
28 +- `ApiResetChat` defines `requires_auth(...)`.
29 +- `ApiResetChat` defines `requires_csrf(...)`.
30 +- `ApiResetChat` defines `requires_api_key(...)`.
31 +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence.
32 +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.print_style`, `json`.
33 +
34 +## Key Concepts
35 +
36 +- 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`.
37 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
38 +
39 +## Work Guidance
40 +
41 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
42 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
43 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
44 +
45 +## Verification
46 +
47 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
48 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
api/api_terminate_chat.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# api_terminate_chat.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `api_terminate_chat.py` API endpoint.
6 +- This module terminates an API-created chat context.
7 +- Keep this file-level DOX profile synchronized with `api_terminate_chat.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `api_terminate_chat.py` owns the runtime implementation.
12 +- `api_terminate_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ApiTerminateChat` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_csrf(cls) -> bool`
17 + - `requires_api_key(cls) -> bool`
18 + - `get_methods(cls) -> list[str]`
19 + - `async process(self, input: dict, request: Request) -> dict | Response`
20 +
21 +## Runtime Contracts
22 +
23 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
24 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
25 +- `ApiTerminateChat` is an `ApiHandler`.
26 +- `ApiTerminateChat` defines `process(...)`.
27 +- `ApiTerminateChat` defines `get_methods(...)`.
28 +- `ApiTerminateChat` defines `requires_auth(...)`.
29 +- `ApiTerminateChat` defines `requires_csrf(...)`.
30 +- `ApiTerminateChat` defines `requires_api_key(...)`.
31 +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence.
32 +- Imported dependency areas include: `agent`, `helpers.api`, `helpers.persist_chat`, `helpers.print_style`, `json`.
33 +
34 +## Key Concepts
35 +
36 +- Important called helpers/classes observed in the source: `AgentContext.use`, `AgentContext.remove`, `remove_chat`, `Response`, `PrintStyle.error`, `PrintStyle`, `json.dumps`.
37 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
38 +
39 +## Work Guidance
40 +
41 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
42 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
43 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
44 +
45 +## Verification
46 +
47 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
48 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
api/backup_create.py.dox.md new
+49
@@ -0,0 +1,49 @@
1 +# backup_create.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `backup_create.py` API endpoint.
6 +- This module handles backup create requests.
7 +- Keep this file-level DOX profile synchronized with `backup_create.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `backup_create.py` owns the runtime implementation.
12 +- `backup_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `BackupCreate` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_loopback(cls) -> bool`
17 + - `async process(self, input: dict, request: Request) -> dict | Response`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `BackupCreate` is an `ApiHandler`.
24 +- `BackupCreate` defines `process(...)`.
25 +- `BackupCreate` defines `requires_auth(...)`.
26 +- `BackupCreate` defines `requires_loopback(...)`.
27 +- Observed side-effect areas: filesystem writes.
28 +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `helpers.persist_chat`.
29 +
30 +## Key Concepts
31 +
32 +- 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`.
33 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
34 +
35 +## Work Guidance
36 +
37 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
38 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
39 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
40 +
41 +## Verification
42 +
43 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
44 +- Related tests observed by source search:
45 + - `tests/test_download_toast_regressions.py`
46 +
47 +## Child DOX Index
48 +
49 +No child DOX files.
api/backup_get_defaults.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# backup_get_defaults.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `backup_get_defaults.py` API endpoint.
6 +- This module handles backup get defaults requests.
7 +- Keep this file-level DOX profile synchronized with `backup_get_defaults.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `backup_get_defaults.py` owns the runtime implementation.
12 +- `backup_get_defaults.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `BackupGetDefaults` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_loopback(cls) -> bool`
17 + - `async process(self, input: dict, request: Request) -> dict | Response`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `BackupGetDefaults` is an `ApiHandler`.
24 +- `BackupGetDefaults` defines `process(...)`.
25 +- `BackupGetDefaults` defines `requires_auth(...)`.
26 +- `BackupGetDefaults` defines `requires_loopback(...)`.
27 +- Imported dependency areas include: `helpers.api`, `helpers.backup`.
28 +
29 +## Key Concepts
30 +
31 +- Important called helpers/classes observed in the source: `BackupService`, `backup_service.get_default_backup_metadata`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/backup_inspect.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# backup_inspect.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `backup_inspect.py` API endpoint.
6 +- This module handles backup inspect requests.
7 +- Keep this file-level DOX profile synchronized with `backup_inspect.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `backup_inspect.py` owns the runtime implementation.
12 +- `backup_inspect.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `BackupInspect` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_loopback(cls) -> bool`
17 + - `async process(self, input: dict, request: Request) -> dict | Response`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `BackupInspect` is an `ApiHandler`.
24 +- `BackupInspect` defines `process(...)`.
25 +- `BackupInspect` defines `requires_auth(...)`.
26 +- `BackupInspect` defines `requires_loopback(...)`.
27 +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `werkzeug.datastructures`.
28 +
29 +## Key Concepts
30 +
31 +- Important called helpers/classes observed in the source: `BackupService`, `backup_service.inspect_backup`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/backup_preview_grouped.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# backup_preview_grouped.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `backup_preview_grouped.py` API endpoint.
6 +- This module handles backup preview grouped requests.
7 +- Keep this file-level DOX profile synchronized with `backup_preview_grouped.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `backup_preview_grouped.py` owns the runtime implementation.
12 +- `backup_preview_grouped.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `BackupPreviewGrouped` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_loopback(cls) -> bool`
17 + - `async process(self, input: dict, request: Request) -> dict | Response`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `BackupPreviewGrouped` is an `ApiHandler`.
24 +- `BackupPreviewGrouped` defines `process(...)`.
25 +- `BackupPreviewGrouped` defines `requires_auth(...)`.
26 +- `BackupPreviewGrouped` defines `requires_loopback(...)`.
27 +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `typing`.
28 +
29 +## Key Concepts
30 +
31 +- 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`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/backup_restore.py.dox.md new
+49
@@ -0,0 +1,49 @@
1 +# backup_restore.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `backup_restore.py` API endpoint.
6 +- This module handles backup restore requests.
7 +- Keep this file-level DOX profile synchronized with `backup_restore.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `backup_restore.py` owns the runtime implementation.
12 +- `backup_restore.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `BackupRestore` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_loopback(cls) -> bool`
17 + - `async process(self, input: dict, request: Request) -> dict | Response`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `BackupRestore` is an `ApiHandler`.
24 +- `BackupRestore` defines `process(...)`.
25 +- `BackupRestore` defines `requires_auth(...)`.
26 +- `BackupRestore` defines `requires_loopback(...)`.
27 +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence.
28 +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `helpers.persist_chat`, `json`, `werkzeug.datastructures`.
29 +
30 +## Key Concepts
31 +
32 +- Important called helpers/classes observed in the source: `request.form.get.lower`, `json.loads`, `BackupService`, `load_tmp_chats`, `backup_service.restore_backup`.
33 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
34 +
35 +## Work Guidance
36 +
37 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
38 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
39 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
40 +
41 +## Verification
42 +
43 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
44 +- Related tests observed by source search:
45 + - `tests/test_self_update_tag_filter.py`
46 +
47 +## Child DOX Index
48 +
49 +No child DOX files.
api/backup_restore_preview.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# backup_restore_preview.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `backup_restore_preview.py` API endpoint.
6 +- This module handles backup restore preview requests.
7 +- Keep this file-level DOX profile synchronized with `backup_restore_preview.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `backup_restore_preview.py` owns the runtime implementation.
12 +- `backup_restore_preview.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `BackupRestorePreview` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_loopback(cls) -> bool`
17 + - `async process(self, input: dict, request: Request) -> dict | Response`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `BackupRestorePreview` is an `ApiHandler`.
24 +- `BackupRestorePreview` defines `process(...)`.
25 +- `BackupRestorePreview` defines `requires_auth(...)`.
26 +- `BackupRestorePreview` defines `requires_loopback(...)`.
27 +- Observed side-effect areas: filesystem deletion, settings/state persistence.
28 +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `json`, `werkzeug.datastructures`.
29 +
30 +## Key Concepts
31 +
32 +- Important called helpers/classes observed in the source: `request.form.get.lower`, `json.loads`, `BackupService`, `backup_service.preview_restore`.
33 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
34 +
35 +## Work Guidance
36 +
37 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
38 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
39 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
40 +
41 +## Verification
42 +
43 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
44 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
api/backup_test.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# backup_test.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `backup_test.py` API endpoint.
6 +- This module handles backup test requests.
7 +- Keep this file-level DOX profile synchronized with `backup_test.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `backup_test.py` owns the runtime implementation.
12 +- `backup_test.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `BackupTest` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_loopback(cls) -> bool`
17 + - `async process(self, input: dict, request: Request) -> dict | Response`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `BackupTest` is an `ApiHandler`.
24 +- `BackupTest` defines `process(...)`.
25 +- `BackupTest` defines `requires_auth(...)`.
26 +- `BackupTest` defines `requires_loopback(...)`.
27 +- Imported dependency areas include: `helpers.api`, `helpers.backup`.
28 +
29 +## Key Concepts
30 +
31 +- Important called helpers/classes observed in the source: `BackupService`, `backup_service.test_patterns`, `line.strip`, `line.startswith`, `patterns_string.split`, `line.strip.startswith`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/banners.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# banners.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `banners.py` API endpoint.
6 +- This module collects alert banners and discovery cards from backend extensions.
7 +- Keep this file-level DOX profile synchronized with `banners.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `banners.py` owns the runtime implementation.
12 +- `banners.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `GetBanners` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `GetBanners` is an `ApiHandler`.
22 +- `GetBanners` defines `process(...)`.
23 +- Imported dependency areas include: `helpers.api`, `helpers.extension`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `call_extensions_async`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- Related tests observed by source search:
40 + - `tests/test_model_config_api_keys.py`
41 + - `tests/test_oauth_static.py`
42 + - `tests/test_webui_extension_surfaces.py`
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
api/cache_reset.py.dox.md new
+53
@@ -0,0 +1,53 @@
1 +# cache_reset.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `cache_reset.py` API endpoint.
6 +- This module handles cache reset API requests.
7 +- Keep this file-level DOX profile synchronized with `cache_reset.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `cache_reset.py` owns the runtime implementation.
12 +- `cache_reset.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `CacheReset` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_csrf(cls) -> bool`
17 + - `requires_api_key(cls) -> bool`
18 + - `requires_loopback(cls) -> bool`
19 + - `get_methods(cls) -> list[str]`
20 + - `async process(self, input: dict, request: Request) -> dict | Response`
21 +
22 +## Runtime Contracts
23 +
24 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
25 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
26 +- `CacheReset` is an `ApiHandler`.
27 +- `CacheReset` defines `process(...)`.
28 +- `CacheReset` defines `get_methods(...)`.
29 +- `CacheReset` defines `requires_auth(...)`.
30 +- `CacheReset` defines `requires_csrf(...)`.
31 +- `CacheReset` defines `requires_api_key(...)`.
32 +- `CacheReset` defines `requires_loopback(...)`.
33 +- Imported dependency areas include: `helpers`, `helpers.api`.
34 +
35 +## Key Concepts
36 +
37 +- Important called helpers/classes observed in the source: `cache.clear_all`, `cache.clear`.
38 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
39 +
40 +## Work Guidance
41 +
42 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
43 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
44 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
45 +
46 +## Verification
47 +
48 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
49 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
50 +
51 +## Child DOX Index
52 +
53 +No child DOX files.
api/chat_create.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# chat_create.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `chat_create.py` API endpoint.
6 +- This module handles chat create requests.
7 +- Keep this file-level DOX profile synchronized with `chat_create.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `chat_create.py` owns the runtime implementation.
12 +- `chat_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `CreateChat` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `CreateChat` is an `ApiHandler`.
22 +- `CreateChat` defines `process(...)`.
23 +- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence.
24 +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- Related tests observed by source search:
41 + - `tests/test_browser_agent_regressions.py`
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
api/chat_export.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# chat_export.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `chat_export.py` API endpoint.
6 +- This module handles chat export requests.
7 +- Keep this file-level DOX profile synchronized with `chat_export.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `chat_export.py` owns the runtime implementation.
12 +- `chat_export.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ExportChat` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `ExportChat` is an `ApiHandler`.
22 +- `ExportChat` defines `process(...)`.
23 +- Observed side-effect areas: filesystem writes.
24 +- Imported dependency areas include: `helpers`, `helpers.api`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `self.use_context`, `persist_chat.export_json_chat`, `Exception`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/chat_files_path_get.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# chat_files_path_get.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `chat_files_path_get.py` API endpoint.
6 +- This module handles chat files path get requests.
7 +- Keep this file-level DOX profile synchronized with `chat_files_path_get.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `chat_files_path_get.py` owns the runtime implementation.
12 +- `chat_files_path_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `GetChatFilesPath` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `GetChatFilesPath` is an `ApiHandler`.
22 +- `GetChatFilesPath` defines `process(...)`.
23 +- Observed side-effect areas: settings/state persistence.
24 +- Imported dependency areas include: `helpers`, `helpers.api`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/chat_load.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# chat_load.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `chat_load.py` API endpoint.
6 +- This module handles chat load requests.
7 +- Keep this file-level DOX profile synchronized with `chat_load.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `chat_load.py` owns the runtime implementation.
12 +- `chat_load.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `LoadChats` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `LoadChats` is an `ApiHandler`.
22 +- `LoadChats` defines `process(...)`.
23 +- Observed side-effect areas: filesystem writes.
24 +- Imported dependency areas include: `helpers`, `helpers.api`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `persist_chat.load_json_chats`, `Exception`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/chat_remove.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# chat_remove.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `chat_remove.py` API endpoint.
6 +- This module handles chat remove requests.
7 +- Keep this file-level DOX profile synchronized with `chat_remove.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `chat_remove.py` owns the runtime implementation.
12 +- `chat_remove.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `RemoveChat` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `RemoveChat` is an `ApiHandler`.
22 +- `RemoveChat` defines `process(...)`.
23 +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state.
24 +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.task_scheduler`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/chat_reset.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# chat_reset.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `chat_reset.py` API endpoint.
6 +- This module handles chat reset requests.
7 +- Keep this file-level DOX profile synchronized with `chat_reset.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `chat_reset.py` owns the runtime implementation.
12 +- `chat_reset.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Reset` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `Reset` is an `ApiHandler`.
22 +- `Reset` defines `process(...)`.
23 +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state.
24 +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.task_scheduler`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/csrf_token.py.dox.md new
+57
@@ -0,0 +1,57 @@
1 +# csrf_token.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `csrf_token.py` API endpoint.
6 +- This module issues or refreshes CSRF tokens for browser API clients.
7 +- Keep this file-level DOX profile synchronized with `csrf_token.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `csrf_token.py` owns the runtime implementation.
12 +- `csrf_token.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `GetCsrfToken` (`ApiHandler`)
15 + - `get_methods(cls) -> list[str]`
16 + - `requires_csrf(cls) -> bool`
17 + - `async process(self, input: Input, request: Request) -> Output`
18 + - `async check_allowed_origin(self, request: Request)`
19 + - `async is_allowed_origin(self, request: Request)`
20 + - `get_origin_from_request(self, request: Request)`
21 + - `async get_allowed_origins(self) -> list[str]`
22 + - `get_default_allowed_origins(self) -> list[str]`
23 +- Notable constants/configuration names: `ALLOWED_ORIGINS_KEY`.
24 +
25 +## Runtime Contracts
26 +
27 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
28 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
29 +- `GetCsrfToken` is an `ApiHandler`.
30 +- `GetCsrfToken` defines `process(...)`.
31 +- `GetCsrfToken` defines `get_methods(...)`.
32 +- `GetCsrfToken` defines `requires_csrf(...)`.
33 +- Observed side-effect areas: filesystem writes, network calls, secret handling, tunnel state.
34 +- Imported dependency areas include: `fnmatch`, `helpers`, `helpers.api`, `secrets`, `urllib.parse`.
35 +
36 +## Key Concepts
37 +
38 +- 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`.
39 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
40 +
41 +## Work Guidance
42 +
43 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
44 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
45 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
46 +
47 +## Verification
48 +
49 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
50 +- Related tests observed by source search:
51 + - `tests/test_http_auth_csrf.py`
52 + - `tests/test_self_update_tag_filter.py`
53 + - `tests/test_ws_security.py`
54 +
55 +## Child DOX Index
56 +
57 +No child DOX files.
api/ctx_window_get.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# ctx_window_get.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `ctx_window_get.py` API endpoint.
6 +- This module handles ctx window get API requests.
7 +- Keep this file-level DOX profile synchronized with `ctx_window_get.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `ctx_window_get.py` owns the runtime implementation.
12 +- `ctx_window_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `GetCtxWindow` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `GetCtxWindow` is an `ApiHandler`.
22 +- `GetCtxWindow` defines `process(...)`.
23 +- Observed side-effect areas: secret handling.
24 +- Imported dependency areas include: `helpers`, `helpers.api`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `self.use_context`, `agent.get_data`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/delete_work_dir_file.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# delete_work_dir_file.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `delete_work_dir_file.py` API endpoint.
6 +- This module handles workdir file operations for delete work dir file.
7 +- Keep this file-level DOX profile synchronized with `delete_work_dir_file.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `delete_work_dir_file.py` owns the runtime implementation.
12 +- `delete_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `DeleteWorkDirFile` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +- Top-level functions:
17 +- `async delete_file(file_path: str)`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `DeleteWorkDirFile` is an `ApiHandler`.
24 +- `DeleteWorkDirFile` defines `process(...)`.
25 +- Observed side-effect areas: filesystem deletion.
26 +- Imported dependency areas include: `api`, `helpers`, `helpers.api`, `helpers.file_browser`.
27 +
28 +## Key Concepts
29 +
30 +- Important called helpers/classes observed in the source: `FileBrowser`, `browser.delete_file`, `file_path.startswith`, `runtime.call_development_function`, `extension.call_extensions_async`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
36 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
37 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
38 +
39 +## Verification
40 +
41 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
42 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
api/delete_work_dir_files.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# delete_work_dir_files.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `delete_work_dir_files.py` API endpoint.
6 +- This module handles workdir file operations for delete work dir files.
7 +- Keep this file-level DOX profile synchronized with `delete_work_dir_files.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `delete_work_dir_files.py` owns the runtime implementation.
12 +- `delete_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `DeleteWorkDirFiles` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +- Top-level functions:
17 +- `async delete_files(paths: list[str]) -> dict`
18 +- `collapse_nested_paths(paths: list[str]) -> list[str]`
19 +
20 +## Runtime Contracts
21 +
22 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
23 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
24 +- `DeleteWorkDirFiles` is an `ApiHandler`.
25 +- `DeleteWorkDirFiles` defines `process(...)`.
26 +- Observed side-effect areas: filesystem deletion.
27 +- Imported dependency areas include: `api`, `api.download_work_dir_files`, `helpers`, `helpers.api`, `helpers.file_browser`.
28 +
29 +## Key Concepts
30 +
31 +- 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`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/download_work_dir_file.py.dox.md new
+53
@@ -0,0 +1,53 @@
1 +# download_work_dir_file.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `download_work_dir_file.py` API endpoint.
6 +- This module handles workdir file operations for download work dir file.
7 +- Keep this file-level DOX profile synchronized with `download_work_dir_file.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `download_work_dir_file.py` owns the runtime implementation.
12 +- `download_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `DownloadFile` (`ApiHandler`)
15 + - `get_methods(cls)`
16 + - `async process(self, input: Input, request: Request) -> Output`
17 +- Top-level functions:
18 +- `stream_file_download(file_source, download_name, chunk_size=...)`: Create a streaming response for file downloads that shows progress in browser.
19 +- `make_disposition(download_name: str) -> str`
20 +- `resolve_download_path(path: str) -> str`: Resolve a requested download path and keep it within the runtime base dir.
21 +- `async fetch_file(path)`
22 +
23 +## Runtime Contracts
24 +
25 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
26 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
27 +- `DownloadFile` is an `ApiHandler`.
28 +- `DownloadFile` defines `process(...)`.
29 +- `DownloadFile` defines `get_methods(...)`.
30 +- Observed side-effect areas: filesystem reads, network calls.
31 +- Imported dependency areas include: `api`, `base64`, `flask`, `helpers`, `helpers.api`, `io`, `mimetypes`, `os`, `pathlib`, `urllib.parse`.
32 +
33 +## Key Concepts
34 +
35 +- 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`.
36 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
37 +
38 +## Work Guidance
39 +
40 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
41 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
42 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
43 +
44 +## Verification
45 +
46 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
47 +- Related tests observed by source search:
48 + - `tests/test_download_toast_regressions.py`
49 + - `tests/test_office_canvas_setup.py`
50 +
51 +## Child DOX Index
52 +
53 +No child DOX files.
api/download_work_dir_files.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# download_work_dir_files.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `download_work_dir_files.py` API endpoint.
6 +- This module handles workdir file operations for download work dir files.
7 +- Keep this file-level DOX profile synchronized with `download_work_dir_files.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `download_work_dir_files.py` owns the runtime implementation.
12 +- `download_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `DownloadFiles` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +- Top-level functions:
17 +- `normalize_paths(paths) -> list[str]`
18 +- `selected_archive_name(count: int) -> str`
19 +- `create_selected_zip(paths: list[str], current_path: str=...) -> str`
20 +- `resolve_download_path(path: str, base_dir: Path) -> Path`
21 +- `collapse_nested_paths(paths: list[Path]) -> list[Path]`
22 +- `archive_root_name(source_path: Path, current_dir: Path | None, base_dir: Path) -> str`
23 +- `unique_archive_name(name: str, used_names: set[str]) -> str`
24 +- `write_zip_entry(zip_file: zipfile.ZipFile, source_path: Path, arc_root: str) -> None`
25 +
26 +## Runtime Contracts
27 +
28 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
29 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
30 +- `DownloadFiles` is an `ApiHandler`.
31 +- `DownloadFiles` defines `process(...)`.
32 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
33 +- Imported dependency areas include: `api.download_work_dir_file`, `base64`, `flask`, `helpers`, `helpers.api`, `helpers.localization`, `io`, `os`, `pathlib`, `tempfile`, `zipfile`.
34 +
35 +## Key Concepts
36 +
37 +- 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`.
38 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
39 +
40 +## Work Guidance
41 +
42 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
43 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
44 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
45 +
46 +## Verification
47 +
48 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
49 +- Related tests observed by source search:
50 + - `tests/test_download_toast_regressions.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
api/edit_work_dir_file.py.dox.md new
+50
@@ -0,0 +1,50 @@
1 +# edit_work_dir_file.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `edit_work_dir_file.py` API endpoint.
6 +- This module handles workdir file operations for edit work dir file.
7 +- Keep this file-level DOX profile synchronized with `edit_work_dir_file.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `edit_work_dir_file.py` owns the runtime implementation.
12 +- `edit_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `EditWorkDirFile` (`ApiHandler`)
15 + - `get_methods(cls)`
16 + - `async process(self, input: Input, request: Request) -> Output`
17 +- Top-level functions:
18 +- `async load_file(file_path: str) -> dict`
19 +- `save_file(file_path: str, content: str) -> bool`
20 +- Notable constants/configuration names: `MAX_EDIT_FILE_SIZE`, `BINARY_SAMPLE_SIZE`.
21 +
22 +## Runtime Contracts
23 +
24 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
25 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
26 +- `EditWorkDirFile` is an `ApiHandler`.
27 +- `EditWorkDirFile` defines `process(...)`.
28 +- `EditWorkDirFile` defines `get_methods(...)`.
29 +- Observed side-effect areas: filesystem reads, filesystem writes.
30 +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.file_browser`, `mimetypes`, `os`.
31 +
32 +## Key Concepts
33 +
34 +- 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`.
35 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
36 +
37 +## Work Guidance
38 +
39 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
40 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
41 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
42 +
43 +## Verification
44 +
45 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
46 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
47 +
48 +## Child DOX Index
49 +
50 +No child DOX files.
api/file_info.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# file_info.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `file_info.py` API endpoint.
6 +- This module handles file info API requests.
7 +- Keep this file-level DOX profile synchronized with `file_info.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `file_info.py` owns the runtime implementation.
12 +- `file_info.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `FileInfoApi` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +- `FileInfo` (`TypedDict`)
17 +- Top-level functions:
18 +- `async get_file_info(path: str) -> FileInfo`
19 +
20 +## Runtime Contracts
21 +
22 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
23 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
24 +- `FileInfoApi` is an `ApiHandler`.
25 +- `FileInfoApi` defines `process(...)`.
26 +- Observed side-effect areas: filesystem reads.
27 +- Imported dependency areas include: `helpers`, `helpers.api`, `os`, `typing`.
28 +
29 +## Key Concepts
30 +
31 +- 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`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/get_work_dir_files.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# get_work_dir_files.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `get_work_dir_files.py` API endpoint.
6 +- This module handles workdir file operations for get work dir files.
7 +- Keep this file-level DOX profile synchronized with `get_work_dir_files.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `get_work_dir_files.py` owns the runtime implementation.
12 +- `get_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `GetWorkDirFiles` (`ApiHandler`)
15 + - `get_methods(cls)`
16 + - `async process(self, input: dict, request: Request) -> dict | Response`
17 +- Top-level functions:
18 +- `async get_files(path)`
19 +
20 +## Runtime Contracts
21 +
22 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
23 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
24 +- `GetWorkDirFiles` is an `ApiHandler`.
25 +- `GetWorkDirFiles` defines `process(...)`.
26 +- `GetWorkDirFiles` defines `get_methods(...)`.
27 +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.file_browser`.
28 +
29 +## Key Concepts
30 +
31 +- Important called helpers/classes observed in the source: `FileBrowser`, `browser.get_files`, `runtime.call_development_function`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/health.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# health.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `health.py` API endpoint.
6 +- This module reports process health for probes and startup checks.
7 +- Keep this file-level DOX profile synchronized with `health.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `health.py` owns the runtime implementation.
12 +- `health.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `HealthCheck` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `requires_csrf(cls) -> bool`
17 + - `get_methods(cls) -> list[str]`
18 + - `async process(self, input: dict, request: Request) -> dict | Response`
19 +
20 +## Runtime Contracts
21 +
22 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
23 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
24 +- `HealthCheck` is an `ApiHandler`.
25 +- `HealthCheck` defines `process(...)`.
26 +- `HealthCheck` defines `get_methods(...)`.
27 +- `HealthCheck` defines `requires_auth(...)`.
28 +- `HealthCheck` defines `requires_csrf(...)`.
29 +- Imported dependency areas include: `helpers`, `helpers.api`.
30 +
31 +## Key Concepts
32 +
33 +- Important called helpers/classes observed in the source: `git.get_git_info`, `errors.error_text`.
34 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
35 +
36 +## Work Guidance
37 +
38 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
39 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
40 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
41 +
42 +## Verification
43 +
44 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
45 +- Related tests observed by source search:
46 + - `tests/test_oauth_providers.py`
47 + - `tests/test_office_document_store.py`
48 + - `tests/test_self_update_tag_filter.py`
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
api/history_get.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# history_get.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `history_get.py` API endpoint.
6 +- This module handles history get API requests.
7 +- Keep this file-level DOX profile synchronized with `history_get.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `history_get.py` owns the runtime implementation.
12 +- `history_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `GetHistory` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `GetHistory` is an `ApiHandler`.
22 +- `GetHistory` defines `process(...)`.
23 +- Observed side-effect areas: secret handling.
24 +- Imported dependency areas include: `helpers.api`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `self.use_context`, `agent.history.output_text`, `agent.history.get_tokens`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/image_get.py.dox.md new
+53
@@ -0,0 +1,53 @@
1 +# image_get.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `image_get.py` API endpoint.
6 +- This module serves allowed image references and fallback file-type icons.
7 +- Keep this file-level DOX profile synchronized with `image_get.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `image_get.py` owns the runtime implementation.
12 +- `image_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ImageGet` (`ApiHandler`)
15 + - `get_methods(cls) -> list[str]`
16 + - `async process(self, input: dict, request: Request) -> dict | Response`
17 +- Top-level functions:
18 +- `_resolve_allowed_image_path(path: str) -> str`: Resolve a requested image path and keep it inside Agent Zero's base dir.
19 +- `_set_image_headers(response: Response, filename: str, file_ext: str) -> None`
20 +- `_send_file_type_icon(file_ext, filename=...)`: Return appropriate icon for file type
21 +- `_send_fallback_icon(icon_name)`: Return fallback icon from public directory
22 +- Notable constants/configuration names: `IMAGE_EXTENSIONS`, `SVG_EXTENSIONS`, `SVG_CONTENT_SECURITY_POLICY`.
23 +
24 +## Runtime Contracts
25 +
26 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
27 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
28 +- `ImageGet` is an `ApiHandler`.
29 +- `ImageGet` defines `process(...)`.
30 +- `ImageGet` defines `get_methods(...)`.
31 +- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, settings/state persistence.
32 +- Imported dependency areas include: `base64`, `helpers`, `helpers.api`, `io`, `mimetypes`, `os`, `pathlib`, `urllib.parse`.
33 +
34 +## Key Concepts
35 +
36 +- 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`.
37 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
38 +
39 +## Work Guidance
40 +
41 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
42 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
43 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
44 +
45 +## Verification
46 +
47 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
48 +- Related tests observed by source search:
49 + - `tests/test_image_get_security.py`
50 +
51 +## Child DOX Index
52 +
53 +No child DOX files.
api/load_webui_extensions.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# load_webui_extensions.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `load_webui_extensions.py` API endpoint.
6 +- This module returns frontend extension manifests/files for a WebUI extension point.
7 +- Keep this file-level DOX profile synchronized with `load_webui_extensions.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `load_webui_extensions.py` owns the runtime implementation.
12 +- `load_webui_extensions.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `LoadWebuiExtensions` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `LoadWebuiExtensions` is an `ApiHandler`.
22 +- `LoadWebuiExtensions` defines `process(...)`.
23 +- Imported dependency areas include: `helpers`, `helpers.api`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `extension.get_webui_extensions`, `Response`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- Related tests observed by source search:
40 + - `tests/test_webui_extension_surfaces.py`
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/logout.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# logout.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `logout.py` API endpoint.
6 +- This module clears login/session state for the current client.
7 +- Keep this file-level DOX profile synchronized with `logout.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `logout.py` owns the runtime implementation.
12 +- `logout.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ApiLogout` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `async process(self, input: dict, request: Request) -> dict`
17 +
18 +## Runtime Contracts
19 +
20 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
21 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
22 +- `ApiLogout` is an `ApiHandler`.
23 +- `ApiLogout` defines `process(...)`.
24 +- `ApiLogout` defines `requires_auth(...)`.
25 +- Observed side-effect areas: secret handling.
26 +- Imported dependency areas include: `helpers.api`.
27 +
28 +## Key Concepts
29 +
30 +- Important called helpers/classes observed in the source: `session.clear`, `session.pop`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
36 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
37 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
38 +
39 +## Verification
40 +
41 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
42 +- Related tests observed by source search:
43 + - `tests/test_office_document_store.py`
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/mcp_server_get_detail.py.dox.md new
+43
@@ -0,0 +1,43 @@
1 +# mcp_server_get_detail.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `mcp_server_get_detail.py` API endpoint.
6 +- This module handles MCP server server get detail requests.
7 +- Keep this file-level DOX profile synchronized with `mcp_server_get_detail.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `mcp_server_get_detail.py` owns the runtime implementation.
12 +- `mcp_server_get_detail.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `McpServerGetDetail` (`ApiHandler`)
15 + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `McpServerGetDetail` is an `ApiHandler`.
22 +- `McpServerGetDetail` defines `process(...)`.
23 +- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_server_detail`, `MCPConfig.get_instance`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
40 +
41 +## Child DOX Index
42 +
43 +No child DOX files.
api/mcp_server_get_log.py.dox.md new
+43
@@ -0,0 +1,43 @@
1 +# mcp_server_get_log.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `mcp_server_get_log.py` API endpoint.
6 +- This module handles MCP server server get log requests.
7 +- Keep this file-level DOX profile synchronized with `mcp_server_get_log.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `mcp_server_get_log.py` owns the runtime implementation.
12 +- `mcp_server_get_log.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `McpServerGetLog` (`ApiHandler`)
15 + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `McpServerGetLog` is an `ApiHandler`.
22 +- `McpServerGetLog` defines `process(...)`.
23 +- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_server_log`, `MCPConfig.get_instance`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
40 +
41 +## Child DOX Index
42 +
43 +No child DOX files.
api/mcp_servers_apply.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# mcp_servers_apply.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `mcp_servers_apply.py` API endpoint.
6 +- This module handles MCP server servers apply requests.
7 +- Keep this file-level DOX profile synchronized with `mcp_servers_apply.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `mcp_servers_apply.py` owns the runtime implementation.
12 +- `mcp_servers_apply.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `McpServersApply` (`ApiHandler`)
15 + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `McpServersApply` is an `ApiHandler`.
22 +- `McpServersApply` defines `process(...)`.
23 +- Observed side-effect areas: settings/state persistence.
24 +- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `helpers.settings`, `time`, `typing`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `set_settings_delta`, `time.sleep`, `MCPConfig.get_instance.get_servers_status`, `MCPConfig.get_instance`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/mcp_servers_status.py.dox.md new
+43
@@ -0,0 +1,43 @@
1 +# mcp_servers_status.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `mcp_servers_status.py` API endpoint.
6 +- This module handles MCP server servers status requests.
7 +- Keep this file-level DOX profile synchronized with `mcp_servers_status.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `mcp_servers_status.py` owns the runtime implementation.
12 +- `mcp_servers_status.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `McpServersStatuss` (`ApiHandler`)
15 + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `McpServersStatuss` is an `ApiHandler`.
22 +- `McpServersStatuss` defines `process(...)`.
23 +- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_servers_status`, `MCPConfig.get_instance`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
40 +
41 +## Child DOX Index
42 +
43 +No child DOX files.
api/message.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# message.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `message.py` API endpoint.
6 +- This module submits a user message and runs agent processing synchronously through the UI API.
7 +- Keep this file-level DOX profile synchronized with `message.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `message.py` owns the runtime implementation.
12 +- `message.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Message` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 + - `async respond(self, task: DeferredTask, context: AgentContext)`
17 + - `async communicate(self, input: dict, request: Request)`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `Message` is an `ApiHandler`.
24 +- `Message` defines `process(...)`.
25 +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, scheduler state.
26 +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.defer`, `helpers.security`, `os`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
36 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
37 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
38 +
39 +## Verification
40 +
41 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
42 +- Related tests observed by source search:
43 + - `tests/email_parser_test.py`
44 + - `tests/rate_limiter_test.py`
45 + - `tests/test_api_chat_lifetime.py`
46 + - `tests/test_browser_agent_regressions.py`
47 + - `tests/test_chat_compaction.py`
48 + - `tests/test_docker_release_plan.py`
49 + - `tests/test_document_query_fallback.py`
50 + - `tests/test_download_toast_regressions.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
api/message_async.py.dox.md new
+42
@@ -0,0 +1,42 @@
1 +# message_async.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `message_async.py` API endpoint.
6 +- This module submits a user message for asynchronous agent processing.
7 +- Keep this file-level DOX profile synchronized with `message_async.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `message_async.py` owns the runtime implementation.
12 +- `message_async.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `MessageAsync` (`Message`)
15 + - `async respond(self, task: DeferredTask, context: AgentContext)`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- Observed side-effect areas: scheduler state.
22 +- Imported dependency areas include: `agent`, `api.message`, `helpers.defer`.
23 +
24 +## Key Concepts
25 +
26 +- This module is primarily declarative or delegates behavior through classes/imported objects.
27 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
28 +
29 +## Work Guidance
30 +
31 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
32 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
33 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
34 +
35 +## Verification
36 +
37 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
38 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
39 +
40 +## Child DOX Index
41 +
42 +No child DOX files.
api/message_queue_add.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# message_queue_add.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `message_queue_add.py` API endpoint.
6 +- This module handles message queue add API requests.
7 +- Keep this file-level DOX profile synchronized with `message_queue_add.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `message_queue_add.py` owns the runtime implementation.
12 +- `message_queue_add.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `MessageQueueAdd` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `MessageQueueAdd` is an `ApiHandler`.
22 +- `MessageQueueAdd` defines `process(...)`.
23 +- Observed side-effect areas: settings/state persistence.
24 +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `input.get.strip`, `mq.add`, `mark_dirty_for_context`, `Response`, `mq.get_queue`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/message_queue_remove.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# message_queue_remove.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `message_queue_remove.py` API endpoint.
6 +- This module handles message queue remove API requests.
7 +- Keep this file-level DOX profile synchronized with `message_queue_remove.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `message_queue_remove.py` owns the runtime implementation.
12 +- `message_queue_remove.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `MessageQueueRemove` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `MessageQueueRemove` is an `ApiHandler`.
22 +- `MessageQueueRemove` defines `process(...)`.
23 +- Observed side-effect areas: filesystem deletion, settings/state persistence.
24 +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `mq.remove`, `mark_dirty_for_context`, `Response`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/message_queue_send.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# message_queue_send.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `message_queue_send.py` API endpoint.
6 +- This module handles message queue send API requests.
7 +- Keep this file-level DOX profile synchronized with `message_queue_send.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `message_queue_send.py` owns the runtime implementation.
12 +- `message_queue_send.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `MessageQueueSend` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `MessageQueueSend` is an `ApiHandler`.
22 +- `MessageQueueSend` defines `process(...)`.
23 +- Observed side-effect areas: settings/state persistence.
24 +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/notification_create.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# notification_create.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `notification_create.py` API endpoint.
6 +- This module handles notification notification create requests.
7 +- Keep this file-level DOX profile synchronized with `notification_create.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `notification_create.py` owns the runtime implementation.
12 +- `notification_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `NotificationCreate` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `async process(self, input: dict, request: Request) -> dict | Response`
17 +
18 +## Runtime Contracts
19 +
20 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
21 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
22 +- `NotificationCreate` is an `ApiHandler`.
23 +- `NotificationCreate` defines `process(...)`.
24 +- `NotificationCreate` defines `requires_auth(...)`.
25 +- Imported dependency areas include: `flask`, `helpers.api`, `helpers.notification`.
26 +
27 +## Key Concepts
28 +
29 +- Important called helpers/classes observed in the source: `NotificationManager.send_notification`, `NotificationType`, `notification.output`, `notification_type.lower`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
35 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
36 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
37 +
38 +## Verification
39 +
40 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
41 +- Related tests observed by source search:
42 + - `tests/test_download_toast_regressions.py`
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
api/notifications_clear.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# notifications_clear.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `notifications_clear.py` API endpoint.
6 +- This module handles notification notifications clear requests.
7 +- Keep this file-level DOX profile synchronized with `notifications_clear.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `notifications_clear.py` owns the runtime implementation.
12 +- `notifications_clear.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `NotificationsClear` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `async process(self, input: dict, request: Request) -> dict | Response`
17 +
18 +## Runtime Contracts
19 +
20 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
21 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
22 +- `NotificationsClear` is an `ApiHandler`.
23 +- `NotificationsClear` defines `process(...)`.
24 +- `NotificationsClear` defines `requires_auth(...)`.
25 +- Imported dependency areas include: `agent`, `flask`, `helpers.api`.
26 +
27 +## Key Concepts
28 +
29 +- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.clear_all`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
35 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
36 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
37 +
38 +## Verification
39 +
40 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
41 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
api/notifications_history.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# notifications_history.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `notifications_history.py` API endpoint.
6 +- This module handles notification notifications history requests.
7 +- Keep this file-level DOX profile synchronized with `notifications_history.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `notifications_history.py` owns the runtime implementation.
12 +- `notifications_history.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `NotificationsHistory` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `async process(self, input: dict, request: Request) -> dict | Response`
17 +
18 +## Runtime Contracts
19 +
20 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
21 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
22 +- `NotificationsHistory` is an `ApiHandler`.
23 +- `NotificationsHistory` defines `process(...)`.
24 +- `NotificationsHistory` defines `requires_auth(...)`.
25 +- Imported dependency areas include: `agent`, `flask`, `helpers.api`.
26 +
27 +## Key Concepts
28 +
29 +- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.output_all`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
35 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
36 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
37 +
38 +## Verification
39 +
40 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
41 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
api/notifications_mark_read.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# notifications_mark_read.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `notifications_mark_read.py` API endpoint.
6 +- This module handles notification notifications mark read requests.
7 +- Keep this file-level DOX profile synchronized with `notifications_mark_read.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `notifications_mark_read.py` owns the runtime implementation.
12 +- `notifications_mark_read.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `NotificationsMarkRead` (`ApiHandler`)
15 + - `requires_auth(cls) -> bool`
16 + - `async process(self, input: dict, request: Request) -> dict | Response`
17 +
18 +## Runtime Contracts
19 +
20 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
21 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
22 +- `NotificationsMarkRead` is an `ApiHandler`.
23 +- `NotificationsMarkRead` defines `process(...)`.
24 +- `NotificationsMarkRead` defines `requires_auth(...)`.
25 +- Imported dependency areas include: `agent`, `flask`, `helpers.api`.
26 +
27 +## Key Concepts
28 +
29 +- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.mark_read_by_ids`, `notification_manager.mark_all_read`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
35 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
36 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
37 +
38 +## Verification
39 +
40 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
41 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
api/nudge.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# nudge.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `nudge.py` API endpoint.
6 +- This module handles nudge API requests.
7 +- Keep this file-level DOX profile synchronized with `nudge.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `nudge.py` owns the runtime implementation.
12 +- `nudge.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Nudge` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `Nudge` is an `ApiHandler`.
22 +- `Nudge` defines `process(...)`.
23 +- Imported dependency areas include: `helpers.api`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `self.use_context`, `context.nudge`, `context.log.log`, `Exception`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- Related tests observed by source search:
40 + - `tests/test_browser_agent_regressions.py`
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/pause.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# pause.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `pause.py` API endpoint.
6 +- This module handles pause API requests.
7 +- Keep this file-level DOX profile synchronized with `pause.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `pause.py` owns the runtime implementation.
12 +- `pause.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Pause` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `Pause` is an `ApiHandler`.
22 +- `Pause` defines `process(...)`.
23 +- Imported dependency areas include: `helpers.api`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `self.use_context`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- Related tests observed by source search:
40 + - `tests/test_multi_tab_isolation.py`
41 + - `tests/test_snapshot_schema_v1.py`
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
api/plugins.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# plugins.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `plugins.py` API endpoint.
6 +- This module manages plugin actions and plugin settings through the core API.
7 +- Keep this file-level DOX profile synchronized with `plugins.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `plugins.py` owns the runtime implementation.
12 +- `plugins.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Plugins` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `Plugins` is an `ApiHandler`.
22 +- `Plugins` defines `process(...)`.
23 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, plugin state, settings/state persistence.
24 +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.localization`, `json`, `os`, `subprocess`, `sys`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- Related tests observed by source search:
41 + - `tests/test_a0_connector_computer_use_metadata.py`
42 + - `tests/test_a0_connector_prompt_gating.py`
43 + - `tests/test_browser_agent_regressions.py`
44 + - `tests/test_chat_compaction.py`
45 + - `tests/test_default_prompt_budget.py`
46 + - `tests/test_document_query_plugin.py`
47 + - `tests/test_error_retry_plugin.py`
48 + - `tests/test_host_browser_connector.py`
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
api/plugins_list.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# plugins_list.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `plugins_list.py` API endpoint.
6 +- This module returns plugin inventory and activation metadata for plugin UI surfaces.
7 +- Keep this file-level DOX profile synchronized with `plugins_list.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `plugins_list.py` owns the runtime implementation.
12 +- `plugins_list.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `PluginsList` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `PluginsList` is an `ApiHandler`.
22 +- `PluginsList` defines `process(...)`.
23 +- Observed side-effect areas: plugin state, settings/state persistence.
24 +- Imported dependency areas include: `helpers`, `helpers.api`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `plugins.get_enhanced_plugins_list`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- Related tests observed by source search:
41 + - `tests/test_plugin_activation_ui.py`
42 + - `tests/test_speech_plugin_split.py`
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
api/poll.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# poll.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `poll.py` API endpoint.
6 +- This module returns chat/log/status changes for polling clients.
7 +- Keep this file-level DOX profile synchronized with `poll.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `poll.py` owns the runtime implementation.
12 +- `poll.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Poll` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `Poll` is an `ApiHandler`.
22 +- `Poll` defines `process(...)`.
23 +- Observed side-effect areas: settings/state persistence.
24 +- Imported dependency areas include: `helpers.api`, `helpers.state_snapshot`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `build_snapshot`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- Related tests observed by source search:
41 + - `tests/test_multi_tab_isolation.py`
42 + - `tests/test_oauth_github_copilot.py`
43 + - `tests/test_oauth_providers.py`
44 + - `tests/test_office_document_store.py`
45 + - `tests/test_snapshot_parity.py`
46 + - `tests/test_snapshot_schema_v1.py`
47 + - `tests/test_timezone_regressions.py`
48 + - `tests/test_tunnel_remote_link.py`
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
api/projects.py.dox.md new
+59
@@ -0,0 +1,59 @@
1 +# projects.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `projects.py` API endpoint.
6 +- This module manages project create, update, delete, clone, and metadata flows.
7 +- Keep this file-level DOX profile synchronized with `projects.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `projects.py` owns the runtime implementation.
12 +- `projects.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Projects` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 + - `get_active_projects_list(self)`
17 + - `get_active_projects_options(self)`
18 + - `create_project(self, project: dict | None)`
19 + - `clone_project(self, project: dict | None)`
20 + - `load_project(self, name: str | None)`
21 + - `update_project(self, project: dict | None)`
22 + - `delete_project(self, name: str | None)`
23 +
24 +## Runtime Contracts
25 +
26 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
27 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
28 +- `Projects` is an `ApiHandler`.
29 +- `Projects` defines `process(...)`.
30 +- Observed side-effect areas: filesystem deletion, settings/state persistence.
31 +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.notification`.
32 +
33 +## Key Concepts
34 +
35 +- 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`.
36 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
37 +
38 +## Work Guidance
39 +
40 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
41 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
42 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
43 +
44 +## Verification
45 +
46 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
47 +- Related tests observed by source search:
48 + - `tests/test_model_config_project_presets.py`
49 + - `tests/test_office_document_store.py`
50 + - `tests/test_plugin_activation_ui.py`
51 + - `tests/test_projects.py`
52 + - `tests/test_skills_runtime.py`
53 + - `tests/test_task_scheduler_timezone.py`
54 + - `tests/test_time_travel.py`
55 + - `tests/test_tool_action_contracts.py`
56 +
57 +## Child DOX Index
58 +
59 +No child DOX files.
api/rename_work_dir_file.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# rename_work_dir_file.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `rename_work_dir_file.py` API endpoint.
6 +- This module handles workdir file operations for rename work dir file.
7 +- Keep this file-level DOX profile synchronized with `rename_work_dir_file.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `rename_work_dir_file.py` owns the runtime implementation.
12 +- `rename_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `RenameWorkDirFile` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +- Top-level functions:
17 +- `async rename_item(file_path: str, new_name: str) -> bool`
18 +- `async create_folder(parent_path: str, folder_name: str) -> bool`
19 +
20 +## Runtime Contracts
21 +
22 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
23 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
24 +- `RenameWorkDirFile` is an `ApiHandler`.
25 +- `RenameWorkDirFile` defines `process(...)`.
26 +- Observed side-effect areas: filesystem writes.
27 +- Imported dependency areas include: `api`, `helpers`, `helpers.api`, `helpers.file_browser`, `posixpath`.
28 +
29 +## Key Concepts
30 +
31 +- 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`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/restart.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# restart.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `restart.py` API endpoint.
6 +- This module requests server restart or reload behavior.
7 +- Keep this file-level DOX profile synchronized with `restart.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `restart.py` owns the runtime implementation.
12 +- `restart.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Restart` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `Restart` is an `ApiHandler`.
22 +- `Restart` defines `process(...)`.
23 +- Imported dependency areas include: `helpers`, `helpers.api`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `process.reload`, `Response`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- Related tests observed by source search:
40 + - `tests/test_browser_agent_regressions.py`
41 + - `tests/test_download_toast_regressions.py`
42 + - `tests/test_self_update_tag_filter.py`
43 + - `tests/test_timezone_regressions.py`
44 + - `tests/test_ws_manager.py`
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
api/rfc.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# rfc.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `rfc.py` API endpoint.
6 +- This module dispatches remote function calls through the RFC helper layer.
7 +- Keep this file-level DOX profile synchronized with `rfc.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `rfc.py` owns the runtime implementation.
12 +- `rfc.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `RFC` (`ApiHandler`)
15 + - `requires_csrf(cls) -> bool`
16 + - `requires_auth(cls) -> bool`
17 + - `async process(self, input: dict, request: Request) -> dict | Response`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `RFC` is an `ApiHandler`.
24 +- `RFC` defines `process(...)`.
25 +- `RFC` defines `requires_auth(...)`.
26 +- `RFC` defines `requires_csrf(...)`.
27 +- Imported dependency areas include: `helpers`, `helpers.api`.
28 +
29 +## Key Concepts
30 +
31 +- Important called helpers/classes observed in the source: `runtime.handle_rfc`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/scheduler_task_create.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# scheduler_task_create.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `scheduler_task_create.py` API endpoint.
6 +- This module handles scheduler task create requests.
7 +- Keep this file-level DOX profile synchronized with `scheduler_task_create.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `scheduler_task_create.py` owns the runtime implementation.
12 +- `scheduler_task_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SchedulerTaskCreate` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SchedulerTaskCreate` is an `ApiHandler`.
22 +- `SchedulerTaskCreate` defines `process(...)`.
23 +- Observed side-effect areas: filesystem writes, secret handling, scheduler state.
24 +- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.projects`, `helpers.task_scheduler`, `random`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/scheduler_task_delete.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# scheduler_task_delete.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `scheduler_task_delete.py` API endpoint.
6 +- This module handles scheduler task delete requests.
7 +- Keep this file-level DOX profile synchronized with `scheduler_task_delete.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `scheduler_task_delete.py` owns the runtime implementation.
12 +- `scheduler_task_delete.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SchedulerTaskDelete` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SchedulerTaskDelete` is an `ApiHandler`.
22 +- `SchedulerTaskDelete` defines `process(...)`.
23 +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state.
24 +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.localization`, `helpers.task_scheduler`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/scheduler_task_run.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# scheduler_task_run.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `scheduler_task_run.py` API endpoint.
6 +- This module handles scheduler task run requests.
7 +- Keep this file-level DOX profile synchronized with `scheduler_task_run.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `scheduler_task_run.py` owns the runtime implementation.
12 +- `scheduler_task_run.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SchedulerTaskRun` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SchedulerTaskRun` is an `ApiHandler`.
22 +- `SchedulerTaskRun` defines `process(...)`.
23 +- Observed side-effect areas: settings/state persistence, scheduler state.
24 +- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/scheduler_task_update.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# scheduler_task_update.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `scheduler_task_update.py` API endpoint.
6 +- This module handles scheduler task update requests.
7 +- Keep this file-level DOX profile synchronized with `scheduler_task_update.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `scheduler_task_update.py` owns the runtime implementation.
12 +- `scheduler_task_update.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SchedulerTaskUpdate` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SchedulerTaskUpdate` is an `ApiHandler`.
22 +- `SchedulerTaskUpdate` defines `process(...)`.
23 +- Observed side-effect areas: settings/state persistence, secret handling, scheduler state.
24 +- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.task_scheduler`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/scheduler_tasks_list.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# scheduler_tasks_list.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `scheduler_tasks_list.py` API endpoint.
6 +- This module handles scheduler tasks list requests.
7 +- Keep this file-level DOX profile synchronized with `scheduler_tasks_list.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `scheduler_tasks_list.py` owns the runtime implementation.
12 +- `scheduler_tasks_list.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SchedulerTasksList` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SchedulerTasksList` is an `ApiHandler`.
22 +- `SchedulerTasksList` defines `process(...)`.
23 +- Observed side-effect areas: scheduler state.
24 +- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`, `traceback`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `scheduler.serialize_all_tasks`, `Localization.get.set_timezone`, `scheduler.reload`, `PrintStyle.error`, `traceback.format_exc`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/scheduler_tick.py.dox.md new
+50
@@ -0,0 +1,50 @@
1 +# scheduler_tick.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `scheduler_tick.py` API endpoint.
6 +- This module handles scheduler tick requests.
7 +- Keep this file-level DOX profile synchronized with `scheduler_tick.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `scheduler_tick.py` owns the runtime implementation.
12 +- `scheduler_tick.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SchedulerTick` (`ApiHandler`)
15 + - `requires_loopback(cls) -> bool`
16 + - `requires_auth(cls) -> bool`
17 + - `requires_csrf(cls) -> bool`
18 + - `async process(self, input: Input, request: Request) -> Output`
19 +
20 +## Runtime Contracts
21 +
22 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
23 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
24 +- `SchedulerTick` is an `ApiHandler`.
25 +- `SchedulerTick` defines `process(...)`.
26 +- `SchedulerTick` defines `requires_auth(...)`.
27 +- `SchedulerTick` defines `requires_csrf(...)`.
28 +- `SchedulerTick` defines `requires_loopback(...)`.
29 +- Observed side-effect areas: settings/state persistence, scheduler state.
30 +- Imported dependency areas include: `datetime`, `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`.
31 +
32 +## Key Concepts
33 +
34 +- 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`.
35 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
36 +
37 +## Work Guidance
38 +
39 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
40 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
41 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
42 +
43 +## Verification
44 +
45 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
46 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
47 +
48 +## Child DOX Index
49 +
50 +No child DOX files.
api/self_update_get.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# self_update_get.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `self_update_get.py` API endpoint.
6 +- This module handles self update get API requests.
7 +- Keep this file-level DOX profile synchronized with `self_update_get.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `self_update_get.py` owns the runtime implementation.
12 +- `self_update_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SelfUpdateGet` (`ApiHandler`)
15 + - `get_methods(cls) -> list[str]`
16 + - `async process(self, input: dict, request: Request) -> dict | Response`
17 +
18 +## Runtime Contracts
19 +
20 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
21 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
22 +- `SelfUpdateGet` is an `ApiHandler`.
23 +- `SelfUpdateGet` defines `process(...)`.
24 +- `SelfUpdateGet` defines `get_methods(...)`.
25 +- Imported dependency areas include: `helpers`, `helpers.api`.
26 +
27 +## Key Concepts
28 +
29 +- 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`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
35 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
36 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
37 +
38 +## Verification
39 +
40 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
41 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
api/self_update_schedule.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# self_update_schedule.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `self_update_schedule.py` API endpoint.
6 +- This module handles self update schedule API requests.
7 +- Keep this file-level DOX profile synchronized with `self_update_schedule.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `self_update_schedule.py` owns the runtime implementation.
12 +- `self_update_schedule.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SelfUpdateSchedule` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SelfUpdateSchedule` is an `ApiHandler`.
22 +- `SelfUpdateSchedule` defines `process(...)`.
23 +- Observed side-effect areas: filesystem writes, subprocess/runtime control.
24 +- Imported dependency areas include: `helpers`, `helpers.api`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `runtime.is_dockerized`, `self_update.schedule_update`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- Related tests observed by source search:
41 + - `tests/test_self_update_tag_filter.py`
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
api/self_update_tags.py.dox.md new
+43
@@ -0,0 +1,43 @@
1 +# self_update_tags.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `self_update_tags.py` API endpoint.
6 +- This module handles self update tags API requests.
7 +- Keep this file-level DOX profile synchronized with `self_update_tags.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `self_update_tags.py` owns the runtime implementation.
12 +- `self_update_tags.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SelfUpdateTags` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SelfUpdateTags` is an `ApiHandler`.
22 +- `SelfUpdateTags` defines `process(...)`.
23 +- Imported dependency areas include: `helpers`, `helpers.api`.
24 +
25 +## Key Concepts
26 +
27 +- 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`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
33 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
34 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
35 +
36 +## Verification
37 +
38 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
39 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
40 +
41 +## Child DOX Index
42 +
43 +No child DOX files.
api/settings_get.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# settings_get.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `settings_get.py` API endpoint.
6 +- This module returns current application settings.
7 +- Keep this file-level DOX profile synchronized with `settings_get.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `settings_get.py` owns the runtime implementation.
12 +- `settings_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `GetSettings` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 + - `get_methods(cls) -> list[str]`
17 +
18 +## Runtime Contracts
19 +
20 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
21 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
22 +- `GetSettings` is an `ApiHandler`.
23 +- `GetSettings` defines `process(...)`.
24 +- `GetSettings` defines `get_methods(...)`.
25 +- Observed side-effect areas: settings/state persistence.
26 +- Imported dependency areas include: `helpers`, `helpers.api`.
27 +
28 +## Key Concepts
29 +
30 +- Important called helpers/classes observed in the source: `settings.get_settings`, `settings.convert_out`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
36 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
37 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
38 +
39 +## Verification
40 +
41 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
42 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
api/settings_set.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# settings_set.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `settings_set.py` API endpoint.
6 +- This module persists application settings updates.
7 +- Keep this file-level DOX profile synchronized with `settings_set.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `settings_set.py` owns the runtime implementation.
12 +- `settings_set.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SetSettings` (`ApiHandler`)
15 + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SetSettings` is an `ApiHandler`.
22 +- `SetSettings` defines `process(...)`.
23 +- Observed side-effect areas: settings/state persistence.
24 +- Imported dependency areas include: `helpers`, `helpers.api`, `typing`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `settings.convert_in`, `settings.set_settings`, `settings.convert_out`, `settings.Settings`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/settings_workdir_file_structure.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# settings_workdir_file_structure.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `settings_workdir_file_structure.py` API endpoint.
6 +- This module handles settings workdir file structure API requests.
7 +- Keep this file-level DOX profile synchronized with `settings_workdir_file_structure.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `settings_workdir_file_structure.py` owns the runtime implementation.
12 +- `settings_workdir_file_structure.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SettingsWorkdirFileStructure` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 + - `get_methods(cls) -> list[str]`
17 +
18 +## Runtime Contracts
19 +
20 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
21 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
22 +- `SettingsWorkdirFileStructure` is an `ApiHandler`.
23 +- `SettingsWorkdirFileStructure` defines `process(...)`.
24 +- `SettingsWorkdirFileStructure` defines `get_methods(...)`.
25 +- Observed side-effect areas: filesystem reads, settings/state persistence.
26 +- Imported dependency areas include: `helpers`, `helpers.api`.
27 +
28 +## Key Concepts
29 +
30 +- Important called helpers/classes observed in the source: `files.get_abs_path_development`, `Exception`, `file_tree.file_tree`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
36 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
37 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
38 +
39 +## Verification
40 +
41 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
42 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
api/skills.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# skills.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `skills.py` API endpoint.
6 +- This module lists and manages available skills for settings and agent-facing skill flows.
7 +- Keep this file-level DOX profile synchronized with `skills.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `skills.py` owns the runtime implementation.
12 +- `skills.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Skills` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 + - `list_skills(self, input: Input)`
17 + - `delete_skill(self, input: Input)`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `Skills` is an `ApiHandler`.
24 +- `Skills` defines `process(...)`.
25 +- Observed side-effect areas: filesystem reads, filesystem deletion.
26 +- Imported dependency areas include: `helpers`, `helpers.api`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
36 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
37 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
38 +
39 +## Verification
40 +
41 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
42 +- Related tests observed by source search:
43 + - `tests/test_a0_connector_prompt_gating.py`
44 + - `tests/test_browser_agent_regressions.py`
45 + - `tests/test_document_query_plugin.py`
46 + - `tests/test_fasta2a_client.py`
47 + - `tests/test_office_canvas_setup.py`
48 + - `tests/test_office_document_store.py`
49 + - `tests/test_skills_runtime.py`
50 + - `tests/test_time_travel.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
api/skills_import.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# skills_import.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `skills_import.py` API endpoint.
6 +- This module handles skills import API requests.
7 +- Keep this file-level DOX profile synchronized with `skills_import.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `skills_import.py` owns the runtime implementation.
12 +- `skills_import.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SkillsImport` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SkillsImport` is an `ApiHandler`.
22 +- `SkillsImport` defines `process(...)`.
23 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
24 +- Imported dependency areas include: `__future__`, `helpers`, `helpers.api`, `helpers.skills_import`, `os`, `pathlib`, `time`, `uuid`, `werkzeug.datastructures`, `werkzeug.utils`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/skills_import_preview.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# skills_import_preview.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `skills_import_preview.py` API endpoint.
6 +- This module handles skills import preview API requests.
7 +- Keep this file-level DOX profile synchronized with `skills_import_preview.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `skills_import_preview.py` owns the runtime implementation.
12 +- `skills_import_preview.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SkillsImportPreview` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `SkillsImportPreview` is an `ApiHandler`.
22 +- `SkillsImportPreview` defines `process(...)`.
23 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
24 +- Imported dependency areas include: `__future__`, `helpers`, `helpers.api`, `helpers.skills_import`, `os`, `pathlib`, `time`, `uuid`, `werkzeug.datastructures`, `werkzeug.utils`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/subagents.py.dox.md new
+49
@@ -0,0 +1,49 @@
1 +# subagents.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `subagents.py` API endpoint.
6 +- This module returns subordinate agent profile data for UI and delegation flows.
7 +- Keep this file-level DOX profile synchronized with `subagents.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `subagents.py` owns the runtime implementation.
12 +- `subagents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Subagents` (`ApiHandler`)
15 + - `async process(self, input: Input, request: Request) -> Output`
16 + - `get_subagents_list(self)`
17 + - `load_agent(self, name: str | None)`
18 + - `save_agent(self, name: str | None, data: dict | None)`
19 + - `delete_agent(self, name: str | None)`
20 +
21 +## Runtime Contracts
22 +
23 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
24 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
25 +- `Subagents` is an `ApiHandler`.
26 +- `Subagents` defines `process(...)`.
27 +- Observed side-effect areas: filesystem writes, filesystem deletion.
28 +- Imported dependency areas include: `helpers`, `helpers.api`, `typing`.
29 +
30 +## Key Concepts
31 +
32 +- 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`.
33 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
34 +
35 +## Work Guidance
36 +
37 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
38 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
39 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
40 +
41 +## Verification
42 +
43 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
44 +- Related tests observed by source search:
45 + - `tests/test_skills_runtime.py`
46 +
47 +## Child DOX Index
48 +
49 +No child DOX files.
api/tunnel.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# tunnel.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `tunnel.py` API endpoint.
6 +- This module manages tunnel provider status, start, and stop actions.
7 +- Keep this file-level DOX profile synchronized with `tunnel.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `tunnel.py` owns the runtime implementation.
12 +- `tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Tunnel` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +- Top-level functions:
17 +- `async process(input: dict) -> dict | Response`
18 +- `stop()`
19 +
20 +## Runtime Contracts
21 +
22 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
23 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
24 +- `Tunnel` is an `ApiHandler`.
25 +- `Tunnel` defines `process(...)`.
26 +- Observed side-effect areas: tunnel state.
27 +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.tunnel_manager`.
28 +
29 +## Key Concepts
30 +
31 +- 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`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- Related tests observed by source search:
44 + - `tests/test_tunnel_remote_link.py`
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
api/tunnel_proxy.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# tunnel_proxy.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `tunnel_proxy.py` API endpoint.
6 +- This module proxies tunnel-related HTTP traffic through the configured tunnel provider.
7 +- Keep this file-level DOX profile synchronized with `tunnel_proxy.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `tunnel_proxy.py` owns the runtime implementation.
12 +- `tunnel_proxy.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `TunnelProxy` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +- Top-level functions:
17 +- `async process(input: dict) -> dict | Response`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `TunnelProxy` is an `ApiHandler`.
24 +- `TunnelProxy` defines `process(...)`.
25 +- Observed side-effect areas: network calls, settings/state persistence, tunnel state.
26 +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.tunnel_manager`, `requests`.
27 +
28 +## Key Concepts
29 +
30 +- Important called helpers/classes observed in the source: `runtime.get_arg`, `requests.post`, `process`, `dotenv.get_dotenv_value`, `response.json`, `local_process`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
36 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
37 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
38 +
39 +## Verification
40 +
41 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
42 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
api/upload.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# upload.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `upload.py` API endpoint.
6 +- This module accepts general uploads into runtime upload storage.
7 +- Keep this file-level DOX profile synchronized with `upload.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `upload.py` owns the runtime implementation.
12 +- `upload.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `UploadFile` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 + - `allowed_file(self, filename)`
17 +
18 +## Runtime Contracts
19 +
20 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
21 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
22 +- `UploadFile` is an `ApiHandler`.
23 +- `UploadFile` defines `process(...)`.
24 +- Observed side-effect areas: filesystem reads, settings/state persistence.
25 +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.security`.
26 +
27 +## Key Concepts
28 +
29 +- Important called helpers/classes observed in the source: `request.files.getlist`, `Exception`, `self.allowed_file`, `safe_filename`, `file.save`, `files.get_abs_path`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
35 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
36 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
37 +
38 +## Verification
39 +
40 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
41 +- Related tests observed by source search:
42 + - `tests/test_browser_agent_regressions.py`
43 + - `tests/test_image_get_security.py`
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/upload_work_dir_files.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# upload_work_dir_files.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `upload_work_dir_files.py` API endpoint.
6 +- This module handles workdir file operations for upload work dir files.
7 +- Keep this file-level DOX profile synchronized with `upload_work_dir_files.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `upload_work_dir_files.py` owns the runtime implementation.
12 +- `upload_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `UploadWorkDirFiles` (`ApiHandler`)
15 + - `async process(self, input: dict, request: Request) -> dict | Response`
16 +- Top-level functions:
17 +- `async upload_files(uploaded_files: list[FileStorage], current_path: str)`
18 +- `async upload_file(current_path: str, filename: str, base64_content: str)`
19 +
20 +## Runtime Contracts
21 +
22 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
23 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
24 +- `UploadWorkDirFiles` is an `ApiHandler`.
25 +- `UploadWorkDirFiles` defines `process(...)`.
26 +- Observed side-effect areas: filesystem writes.
27 +- Imported dependency areas include: `api`, `base64`, `helpers`, `helpers.api`, `helpers.file_browser`, `os`, `posixpath`, `werkzeug.datastructures`.
28 +
29 +## Key Concepts
30 +
31 +- 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`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
37 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
38 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
39 +
40 +## Verification
41 +
42 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
api/ws_dev_test.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# ws_dev_test.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `ws_dev_test.py` API endpoint.
6 +- This module provides a development WebSocket test namespace.
7 +- Keep this file-level DOX profile synchronized with `ws_dev_test.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `ws_dev_test.py` owns the runtime implementation.
12 +- `ws_dev_test.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `WsDevTest` (`WsHandler`)
15 + - `async process(self, event: str, data: dict, sid: str) -> dict[str, Any] | WsResult | None`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `WsDevTest` is a `WsHandler`.
22 +- `WsDevTest` defines `process(...)`.
23 +- Observed side-effect areas: filesystem writes, network calls, WebSocket state.
24 +- Imported dependency areas include: `asyncio`, `helpers`, `helpers.print_style`, `helpers.ws`, `helpers.ws_manager`, `typing`.
25 +
26 +## Key Concepts
27 +
28 +- 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`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/ws_hello.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# ws_hello.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `ws_hello.py` API endpoint.
6 +- This module provides a small WebSocket hello/test namespace.
7 +- Keep this file-level DOX profile synchronized with `ws_hello.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `ws_hello.py` owns the runtime implementation.
12 +- `ws_hello.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `WsHello` (`WsHandler`)
15 + - `async process(self, event: str, data: dict, sid: str) -> dict | None`
16 +
17 +## Runtime Contracts
18 +
19 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
20 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
21 +- `WsHello` is a `WsHandler`.
22 +- `WsHello` defines `process(...)`.
23 +- Observed side-effect areas: WebSocket state.
24 +- Imported dependency areas include: `helpers.print_style`, `helpers.ws`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `PrintStyle.info`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
34 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
35 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
36 +
37 +## Verification
38 +
39 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
40 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
api/ws_webui.py.dox.md new
+49
@@ -0,0 +1,49 @@
1 +# ws_webui.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `ws_webui.py` API endpoint.
6 +- This module owns the primary WebUI WebSocket namespace and event bridge.
7 +- Keep this file-level DOX profile synchronized with `ws_webui.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `ws_webui.py` owns the runtime implementation.
12 +- `ws_webui.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `WsWebui` (`WsHandler`)
15 + - `async on_connect(self, sid: str) -> None`
16 + - `async on_disconnect(self, sid: str) -> None`
17 + - `async process(self, event: str, data: dict, sid: str) -> dict | None`
18 +
19 +## Runtime Contracts
20 +
21 +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
22 +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
23 +- `WsWebui` is a `WsHandler`.
24 +- `WsWebui` defines `process(...)`.
25 +- Observed side-effect areas: network calls, WebSocket state, settings/state persistence.
26 +- Imported dependency areas include: `helpers`, `helpers.ws`.
27 +
28 +## Key Concepts
29 +
30 +- Important called helpers/classes observed in the source: `extension.call_extensions_async`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
36 +- Update frontend callers, plugin callers, and tests together when payload shape changes.
37 +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
38 +
39 +## Verification
40 +
41 +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
42 +- Related tests observed by source search:
43 + - `tests/test_state_sync_handler.py`
44 + - `tests/test_state_sync_welcome_screen.py`
45 + - `tests/test_ws_handlers.py`
46 +
47 +## Child DOX Index
48 +
49 +No child DOX files.
docker/AGENTS.md
+6 -1
@@ -31,4 +31,9 @@
31
32 ## Child DOX Index
33
34 -No child DOX files.
34 +Direct child DOX files:
35 +
36 +| Child | Scope |
37 +| --- | --- |
38 +| [base/AGENTS.md](base/AGENTS.md) | Base image Dockerfile, copied filesystem, and installation scripts. |
39 +| [run/AGENTS.md](run/AGENTS.md) | Runnable image Dockerfile, compose example, entrypoints, and install scripts. |
docker/base/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# Docker Base Image DOX
2 +
3 +## Purpose
4 +
5 +- Own the Agent Zero base image build context.
6 +- Build the operating system, package, Python, SearXNG, SSH, and bootstrap layers reused by runnable images.
7 +
8 +## Ownership
9 +
10 +- `Dockerfile` owns base image layering and installation order.
11 +- `build.txt` owns maintainer build and push command notes.
12 +- `fs/ins/` owns installation scripts copied into the image.
13 +- Files under `fs/` are copied to container root during the base build.
14 +
15 +## Local Contracts
16 +
17 +- Preserve cache-friendly package and runtime installation stages.
18 +- Keep locale and timezone defaults compatible with the root Docker contract.
19 +- Do not add secrets, user data, or local environment files to the image context.
20 +- Installation scripts must be noninteractive and suitable for multi-architecture buildx runs.
21 +
22 +## Work Guidance
23 +
24 +- Keep base dependencies here only when they are common to runnable Agent Zero images.
25 +- Coordinate Python runtime changes with root Docker documentation and runnable image setup.
26 +
27 +## Verification
28 +
29 +- Build `docker/base` when changing Dockerfile or install scripts.
30 +- Run a runnable image smoke check when base runtime behavior changes.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
docker/run/AGENTS.md new
+36
@@ -0,0 +1,36 @@
1 +# Docker Runtime Image DOX
2 +
3 +## Purpose
4 +
5 +- Own the runnable Agent Zero image context and local compose example.
6 +- Install Agent Zero from a selected branch onto the base image and prepare runtime entrypoints.
7 +
8 +## Ownership
9 +
10 +- `Dockerfile` owns branch-based image assembly, exposed ports, and container startup command.
11 +- `docker-compose.yml` owns the local compose service example.
12 +- `build.txt` owns maintainer build and push command notes.
13 +- `fs/exe/` owns runtime entrypoint, supervisor, self-update, Node eval, and service scripts.
14 +- `fs/ins/` owns preinstall, installation, virtualenv, Playwright, SSH, and postinstall scripts.
15 +- Files under `fs/` are copied to container root during the runtime build.
16 +
17 +## Local Contracts
18 +
19 +- `BRANCH` is required for branch-based Docker builds.
20 +- Preserve exposed ports for SSH, HTTP, and tunneled services unless docs and workflows are updated together.
21 +- Keep the two-runtime Python model aligned with the root contract.
22 +- Do not bake secrets, local `.env` values, or user data into the image.
23 +
24 +## Work Guidance
25 +
26 +- Keep startup scripts explicit about framework runtime versus execution runtime.
27 +- Coordinate tag, branch, and publishing changes with GitHub workflow automation.
28 +
29 +## Verification
30 +
31 +- Build `docker/run` when changing Dockerfile or install scripts.
32 +- Smoke-test container startup after entrypoint, supervisor, port, or compose changes.
33 +
34 +## Child DOX Index
35 +
36 +No child DOX files.
extensions/python/AGENTS.md
+34 -1
@@ -31,4 +31,37 @@
31
32 ## Child DOX Index
33
34 -No child DOX files.
34 +Direct child DOX files:
35 +
36 +| Child | Scope |
37 +| --- | --- |
38 +| [_functions/AGENTS.md](_functions/AGENTS.md) | Implicit `@extensible` backend hook implementations. |
39 +| [agent_init/AGENTS.md](agent_init/AGENTS.md) | Agent context initialization hooks. |
40 +| [banners/AGENTS.md](banners/AGENTS.md) | Backend banner and discovery-card contributions. |
41 +| [before_main_llm_call/AGENTS.md](before_main_llm_call/AGENTS.md) | Pre-main-model-call behavior. |
42 +| [error_format/AGENTS.md](error_format/AGENTS.md) | Error formatting and masking behavior. |
43 +| [hist_add_before/AGENTS.md](hist_add_before/AGENTS.md) | Pre-history-insertion masking behavior. |
44 +| [hist_add_tool_result/AGENTS.md](hist_add_tool_result/AGENTS.md) | Tool-result history side effects. |
45 +| [job_loop/AGENTS.md](job_loop/AGENTS.md) | Periodic backend maintenance jobs. |
46 +| [message_loop_end/AGENTS.md](message_loop_end/AGENTS.md) | End-of-message-loop history and persistence behavior. |
47 +| [message_loop_prompts_after/AGENTS.md](message_loop_prompts_after/AGENTS.md) | Prompt extras appended after message-loop prompt construction. |
48 +| [message_loop_prompts_before/AGENTS.md](message_loop_prompts_before/AGENTS.md) | Pre-prompt-construction message-loop gates. |
49 +| [message_loop_start/AGENTS.md](message_loop_start/AGENTS.md) | Start-of-message-loop iteration state. |
50 +| [monologue_end/AGENTS.md](monologue_end/AGENTS.md) | End-of-monologue UI and cleanup behavior. |
51 +| [monologue_start/AGENTS.md](monologue_start/AGENTS.md) | Start-of-monologue behavior such as chat renaming. |
52 +| [process_chain_end/AGENTS.md](process_chain_end/AGENTS.md) | Process-chain completion and queued-message handling. |
53 +| [reasoning_stream/AGENTS.md](reasoning_stream/AGENTS.md) | Full reasoning stream handling. |
54 +| [reasoning_stream_chunk/AGENTS.md](reasoning_stream_chunk/AGENTS.md) | Reasoning stream chunk masking. |
55 +| [reasoning_stream_end/AGENTS.md](reasoning_stream_end/AGENTS.md) | Reasoning stream finalization. |
56 +| [response_stream/AGENTS.md](response_stream/AGENTS.md) | Full assistant response stream handling. |
57 +| [response_stream_chunk/AGENTS.md](response_stream_chunk/AGENTS.md) | Assistant response chunk masking. |
58 +| [response_stream_end/AGENTS.md](response_stream_end/AGENTS.md) | Assistant response stream finalization. |
59 +| [startup_migration/AGENTS.md](startup_migration/AGENTS.md) | Startup migrations. |
60 +| [system_prompt/AGENTS.md](system_prompt/AGENTS.md) | Core system prompt section construction. |
61 +| [tool_execute_after/AGENTS.md](tool_execute_after/AGENTS.md) | Post-tool-execution processing. |
62 +| [tool_execute_before/AGENTS.md](tool_execute_before/AGENTS.md) | Pre-tool-execution processing. |
63 +| [user_message_ui/AGENTS.md](user_message_ui/AGENTS.md) | User-visible UI message hooks. |
64 +| [util_model_call_before/AGENTS.md](util_model_call_before/AGENTS.md) | Pre-utility-model-call masking. |
65 +| [webui_ws_connect/AGENTS.md](webui_ws_connect/AGENTS.md) | WebUI WebSocket connect behavior. |
66 +| [webui_ws_disconnect/AGENTS.md](webui_ws_disconnect/AGENTS.md) | WebUI WebSocket disconnect behavior. |
67 +| [webui_ws_event/AGENTS.md](webui_ws_event/AGENTS.md) | Incoming WebUI WebSocket event behavior. |
extensions/python/_functions/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Python Function Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own implicit `@extensible` backend hook implementations.
6 +- Preserve nested module, class/function, method, and `start`/`end` extension layout.
7 +
8 +## Ownership
9 +
10 +- Each nested path mirrors a Python module and qualname segment.
11 +- Leaf `start/` and `end/` directories own ordered extension files for that extensible function point.
12 +
13 +## Local Contracts
14 +
15 +- Do not flatten nested qualname paths into retired legacy folder names.
16 +- Extension functions must match the implicit hook's supplied arguments.
17 +- Preserve ordering prefixes where exception handling, watchdog registration, or cleanup depends on them.
18 +
19 +## Work Guidance
20 +
21 +- Keep implicit hook extensions narrow and colocated with the exact function point they extend.
22 +
23 +## Verification
24 +
25 +- Run targeted tests for the affected function point after changes.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
extensions/python/agent_init/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Agent Init Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend extensions that run when an agent context initializes.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own initial UI message setup and profile settings load behavior.
10 +
11 +## Local Contracts
12 +
13 +- Keep initialization idempotent for contexts that may be restored or reloaded.
14 +- Preserve ordering between initial message creation and profile settings loading.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate changes with profile loading, settings resolution, and startup smoke checks.
19 +
20 +## Verification
21 +
22 +- Smoke-test new chat/context initialization after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/banners/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Banner Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend banner and discovery-card contributions.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files append alert banners or discovery cards to the mutable `banners` list.
10 +
11 +## Local Contracts
12 +
13 +- Banner IDs must be unique and stable.
14 +- Use supported banner/card fields and types only.
15 +- Do not expose secrets, local paths, or raw system diagnostics in banner text.
16 +
17 +## Work Guidance
18 +
19 +- Gate setup or warning banners on current configuration/status where possible.
20 +
21 +## Verification
22 +
23 +- Smoke-test welcome-screen banner rendering, ordering, dismissal, and CTA behavior after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
extensions/python/before_main_llm_call/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Before Main LLM Call Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior that runs immediately before the main LLM call.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own pre-call logging or context preparation for streaming/model execution.
10 +
11 +## Local Contracts
12 +
13 +- Do not mutate prompt or history data unless the hook contract explicitly passes mutable state for that purpose.
14 +- Avoid logging secrets, hidden prompt sections, or private user data.
15 +
16 +## Work Guidance
17 +
18 +- Keep this hook light because it sits on the main model hot path.
19 +
20 +## Verification
21 +
22 +- Run targeted model-call or streaming tests after behavior changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/error_format/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Error Format Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend error formatting and masking before errors are shown or logged.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own mutation of error-format data passed by the hook.
10 +
11 +## Local Contracts
12 +
13 +- Preserve secret masking and safe user-facing error messages.
14 +- Do not expose raw tokens, credentials, hidden prompts, or private payloads.
15 +
16 +## Work Guidance
17 +
18 +- Keep masking rules conservative and synchronized with tool/model error surfaces.
19 +
20 +## Verification
21 +
22 +- Test or inspect representative masked and unmasked error paths after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/hist_add_before/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# History Add Before Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own preprocessing before messages are added to agent history.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own history content masking before persistence or model reuse.
10 +
11 +## Local Contracts
12 +
13 +- Preserve secret and sensitive-content masking before history storage.
14 +- Do not remove fields required by downstream history organization or replay.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate history mutation changes with message persistence and memory behavior.
19 +
20 +## Verification
21 +
22 +- Test message history insertion for masked content after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/hist_add_tool_result/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# History Tool Result Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own processing after tool results are added to history.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own tool-call file persistence and related history side effects.
10 +
11 +## Local Contracts
12 +
13 +- Preserve tool result traceability without leaking secrets.
14 +- Keep file artifacts inside expected runtime/user-owned paths.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate changes with tool output storage and chat persistence behavior.
19 +
20 +## Verification
21 +
22 +- Smoke-test a tool call that produces persisted output after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/job_loop/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Job Loop Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own periodic backend maintenance jobs.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own cleanup of expired API chats, cache trimming, and future job-loop tasks.
10 +
11 +## Local Contracts
12 +
13 +- Jobs must be idempotent and safe to run repeatedly.
14 +- Keep cleanup scoped to owned caches, temporary contexts, or documented runtime state.
15 +
16 +## Work Guidance
17 +
18 +- Avoid expensive work on every loop; use timestamps or thresholds when practical.
19 +
20 +## Verification
21 +
22 +- Run targeted cleanup/cache tests or smoke-test job-loop startup after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/message_loop_end/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Message Loop End Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior that runs after a message loop completes.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own history organization and chat persistence at loop end.
10 +
11 +## Local Contracts
12 +
13 +- Preserve history consistency before saving chats.
14 +- Do not skip persistence for successful loops unless the hook contract explicitly permits it.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate changes with chat serialization, history organization, and WebUI refresh behavior.
19 +
20 +## Verification
21 +
22 +- Smoke-test sending a message, reloading the chat, and checking persisted history after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/message_loop_prompts_after/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Message Loop Prompts After Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own prompt extras appended after primary message-loop prompt construction.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own current datetime, skill recall/load context, agent info, and workdir extras injection.
10 +
11 +## Local Contracts
12 +
13 +- Keep injected content bounded and clearly attributed.
14 +- Preserve ordering where later prompt extras depend on earlier recall or load results.
15 +- Do not expose secrets or private files from workdir extras.
16 +
17 +## Work Guidance
18 +
19 +- Coordinate prompt-extra changes with skill, workdir, and profile contracts.
20 +
21 +## Verification
22 +
23 +- Inspect rendered prompt extras or run prompt-construction tests after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
extensions/python/message_loop_prompts_before/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Message Loop Prompts Before Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own preprocessing before message-loop prompt construction.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own history organization waits and related prompt-preparation gates.
10 +
11 +## Local Contracts
12 +
13 +- Preserve history consistency before prompts are assembled.
14 +- Avoid blocking indefinitely on background organization tasks.
15 +
16 +## Work Guidance
17 +
18 +- Keep waiting behavior observable and bounded.
19 +
20 +## Verification
21 +
22 +- Smoke-test prompt construction after chats with pending history organization.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/message_loop_start/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Message Loop Start Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior that runs at the start of each message loop iteration.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own iteration counters and future loop-start state setup.
10 +
11 +## Local Contracts
12 +
13 +- Keep per-loop counters deterministic and scoped to the active context.
14 +- Do not reset state owned by monologue-level hooks.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate loop-start state changes with logging, streaming, and process-chain behavior.
19 +
20 +## Verification
21 +
22 +- Smoke-test multi-turn conversations after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/monologue_end/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Monologue End Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior that runs when a monologue ends.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own waiting-for-input UI message behavior and future monologue-end cleanup.
10 +
11 +## Local Contracts
12 +
13 +- Preserve clear UI state when the agent stops for user input.
14 +- Do not leave loading/processing indicators stale.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate changes with WebUI loading state and message-loop persistence.
19 +
20 +## Verification
21 +
22 +- Smoke-test an agent response that returns to waiting-for-input state.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/monologue_start/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Monologue Start Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior that runs when a monologue starts.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own automatic chat renaming and future monologue-start setup.
10 +
11 +## Local Contracts
12 +
13 +- Keep automatic rename behavior bounded and non-destructive.
14 +- Do not override explicit user chat names without the intended guard conditions.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate rename behavior with chat persistence and WebUI refresh.
19 +
20 +## Verification
21 +
22 +- Smoke-test new chat naming and existing named chat behavior after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/process_chain_end/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Process Chain End Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior after process-chain execution completes.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own queued-message processing and future process-chain completion behavior.
10 +
11 +## Local Contracts
12 +
13 +- Preserve queue ordering and avoid duplicate message processing.
14 +- Keep queue side effects synchronized with chat persistence and WebUI state.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate changes with message queue components and external integration plugins.
19 +
20 +## Verification
21 +
22 +- Smoke-test queued messages and final response handling after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/reasoning_stream/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Reasoning Stream Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own handling of full reasoning stream updates.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own logging reasoning content from stream state.
10 +
11 +## Local Contracts
12 +
13 +- Preserve masking and privacy rules for reasoning content.
14 +- Keep stream logging compatible with chunk and end hooks.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate reasoning stream changes with UI log rendering and hidden-content policy.
19 +
20 +## Verification
21 +
22 +- Smoke-test reasoning stream display/logging when the active model provides reasoning.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/reasoning_stream_chunk/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Reasoning Stream Chunk Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own handling of incremental reasoning stream chunks.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own chunk-level masking before reasoning is displayed or stored.
10 +
11 +## Local Contracts
12 +
13 +- Mask secrets and sensitive content before chunk data reaches logs or UI.
14 +- Keep chunk mutation compatible with final stream-end masking.
15 +
16 +## Work Guidance
17 +
18 +- Keep chunk processing lightweight for streaming performance.
19 +
20 +## Verification
21 +
22 +- Smoke-test streamed reasoning with representative sensitive patterns after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/reasoning_stream_end/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Reasoning Stream End Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own finalization of reasoning stream content.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own final reasoning masking and end-of-stream cleanup.
10 +
11 +## Local Contracts
12 +
13 +- Preserve final masking even if earlier chunk masking missed content.
14 +- Keep end-state consistent with reasoning stream log entries.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate final masking changes with chunk masking and UI rendering.
19 +
20 +## Verification
21 +
22 +- Smoke-test reasoning stream completion with sensitive-content cases.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/response_stream/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Response Stream Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own handling of full assistant response stream updates.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own response logging, include-alias replacement, and live response updates.
10 +
11 +## Local Contracts
12 +
13 +- Keep streaming output synchronized with UI log items.
14 +- Preserve include-alias replacement semantics where prompts/tools rely on them.
15 +- Do not expose unmasked secrets in live responses.
16 +
17 +## Work Guidance
18 +
19 +- Coordinate stream changes with chunk/end hooks and message rendering.
20 +
21 +## Verification
22 +
23 +- Smoke-test streamed responses, live updates, and include alias replacement after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
extensions/python/response_stream_chunk/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Response Stream Chunk Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own handling of incremental assistant response chunks.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own chunk-level response masking.
10 +
11 +## Local Contracts
12 +
13 +- Mask secrets before response chunks reach UI or persisted logs.
14 +- Keep chunk processing compatible with final response stream masking.
15 +
16 +## Work Guidance
17 +
18 +- Keep per-chunk work lightweight for streaming responsiveness.
19 +
20 +## Verification
21 +
22 +- Smoke-test streaming responses with sensitive patterns after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/response_stream_end/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Response Stream End Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own finalization of assistant response stream content.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own final masking and stream-end log updates.
10 +
11 +## Local Contracts
12 +
13 +- Preserve final masking before response content is considered complete.
14 +- Keep log state consistent with streamed chunks and final response text.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate finalization changes with live response and message rendering behavior.
19 +
20 +## Verification
21 +
22 +- Smoke-test response completion and persisted message display after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/startup_migration/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Startup Migration Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend startup migrations.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files in this folder own idempotent migration steps that run during startup.
10 +
11 +## Local Contracts
12 +
13 +- Migrations must be safe to run repeatedly.
14 +- Preserve user data and create backups or reversible paths when changing durable state.
15 +- Keep long-running work bounded and observable.
16 +
17 +## Work Guidance
18 +
19 +- Add migrations only for durable state changes that cannot be handled lazily elsewhere.
20 +
21 +## Verification
22 +
23 +- Smoke-test startup on a clean checkout and on representative existing user state when practical.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
extensions/python/system_prompt/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# System Prompt Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own construction of core system prompt sections.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own main, tools, MCP, secrets, skills, and project prompt sections.
10 +
11 +## Local Contracts
12 +
13 +- Preserve ordering where sections depend on earlier context.
14 +- Keep secret-related prompt sections masked and scoped.
15 +- Prompt additions must be bounded and compatible with tool-call contracts.
16 +
17 +## Work Guidance
18 +
19 +- Coordinate broad system prompt changes with profiles, skills, tools, plugins, and prompt tests.
20 +
21 +## Verification
22 +
23 +- Inspect rendered system prompts or run prompt-construction tests after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
extensions/python/tool_execute_after/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Tool Execute After Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend processing immediately after tool execution.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own post-tool secret masking and future tool-result postprocessing.
10 +
11 +## Local Contracts
12 +
13 +- Mask secrets before tool results reach history, UI, or model-visible context.
14 +- Do not alter tool `break_loop` or response semantics unless the hook contract owns that behavior.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate with tool implementations and history hooks when changing tool result data.
19 +
20 +## Verification
21 +
22 +- Smoke-test tool execution with sensitive output after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/tool_execute_before/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Tool Execute Before Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend processing immediately before tool execution.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own prior tool-output replacement and secret unmasking before execution.
10 +
11 +## Local Contracts
12 +
13 +- Unmask only values required by the target tool.
14 +- Preserve safety checks and do not expose secrets to logs or unrelated tools.
15 +- Keep ordering stable where replacement must occur before unmasking or execution.
16 +
17 +## Work Guidance
18 +
19 +- Coordinate with secret handling, tool argument preparation, and plugin tool gates.
20 +
21 +## Verification
22 +
23 +- Smoke-test tool execution with masked secret arguments and prior-output references after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
extensions/python/user_message_ui/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# User Message UI Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior triggered around user-visible UI messages.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own update-check messaging and future user-message UI hooks.
10 +
11 +## Local Contracts
12 +
13 +- Keep proactive UI messages relevant, non-spammy, and safe for display.
14 +- Do not expose local diagnostics or update data that should stay internal.
15 +
16 +## Work Guidance
17 +
18 +- Gate recurring messages so they do not repeat unnecessarily across chats or tabs.
19 +
20 +## Verification
21 +
22 +- Smoke-test UI message rendering after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/util_model_call_before/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Utility Model Call Before Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own preprocessing before utility model calls.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own secret masking and future utility-call preparation.
10 +
11 +## Local Contracts
12 +
13 +- Mask secrets before utility prompts leave the framework.
14 +- Keep utility model inputs compatible with callers expecting structured outputs.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate masking changes with main model call and error-format masking behavior.
19 +
20 +## Verification
21 +
22 +- Test utility model calls that include masked secret patterns after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/webui_ws_connect/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# WebUI WebSocket Connect Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior when a WebUI WebSocket client connects.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own state-sync behavior for new WebSocket connections.
10 +
11 +## Local Contracts
12 +
13 +- Preserve WebSocket auth/session assumptions.
14 +- Send only state the connected client is allowed to receive.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate connect behavior with frontend WebSocket client and sync store.
19 +
20 +## Verification
21 +
22 +- Smoke-test WebUI connection and initial state sync after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/webui_ws_disconnect/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# WebUI WebSocket Disconnect Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior when a WebUI WebSocket client disconnects.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own state-sync cleanup for disconnect events.
10 +
11 +## Local Contracts
12 +
13 +- Cleanup must be idempotent and safe for repeated disconnect events.
14 +- Do not remove shared state still needed by other active clients.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate disconnect behavior with frontend reconnect and sync indicators.
19 +
20 +## Verification
21 +
22 +- Smoke-test disconnect and reconnect behavior after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/python/webui_ws_event/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# WebUI WebSocket Event Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own backend behavior for incoming WebUI WebSocket events.
6 +
7 +## Ownership
8 +
9 +- Ordered Python files own state-sync event handling and future WebSocket event extensions.
10 +
11 +## Local Contracts
12 +
13 +- Validate event names and payloads before acting on them.
14 +- Preserve auth/session boundaries for all WebSocket events.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate event changes with frontend WebSocket client and sync store.
19 +
20 +## Verification
21 +
22 +- Smoke-test relevant WebSocket events after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/webui/AGENTS.md
+14 -1
@@ -31,4 +31,17 @@
31
32 ## Child DOX Index
33
34 -No child DOX files.
34 +Direct child DOX files:
35 +
36 +| Child | Scope |
37 +| --- | --- |
38 +| [fetch_api_call_after/AGENTS.md](fetch_api_call_after/AGENTS.md) | Frontend hooks after raw `fetchApi()` calls. |
39 +| [fetch_api_call_before/AGENTS.md](fetch_api_call_before/AGENTS.md) | Frontend hooks before raw `fetchApi()` calls. |
40 +| [get_message_handler/AGENTS.md](get_message_handler/AGENTS.md) | Message rendering handler extensions. |
41 +| [initFw_end/AGENTS.md](initFw_end/AGENTS.md) | Post-WebUI-framework-initialization extensions. |
42 +| [json_api_call_after/AGENTS.md](json_api_call_after/AGENTS.md) | Frontend hooks after `callJsonApi()` calls. |
43 +| [json_api_call_before/AGENTS.md](json_api_call_before/AGENTS.md) | Frontend hooks before `callJsonApi()` calls. |
44 +| [right_canvas_register_surfaces/AGENTS.md](right_canvas_register_surfaces/AGENTS.md) | Built-in right-canvas surface registrations. |
45 +| [set_messages_after_loop/AGENTS.md](set_messages_after_loop/AGENTS.md) | Frontend hooks after message DOM updates. |
46 +| [set_messages_before_loop/AGENTS.md](set_messages_before_loop/AGENTS.md) | Frontend hooks before message DOM updates. |
47 +| [webui_ws_push/AGENTS.md](webui_ws_push/AGENTS.md) | WebUI WebSocket push-event behavior. |
extensions/webui/fetch_api_call_after/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Fetch API Call After Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend extension hooks that run after raw `fetchApi()` calls.
6 +
7 +## Ownership
8 +
9 +- Files in this folder own after-call behavior for CSRF-aware raw fetch flows.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function when present.
14 +- Do not consume response bodies unless the hook contract explicitly passes a clone or mutable context for that purpose.
15 +
16 +## Work Guidance
17 +
18 +- Keep after-call extensions lightweight and safe for all fetch callers.
19 +
20 +## Verification
21 +
22 +- Smoke-test frontend API calls after adding behavior here.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/webui/fetch_api_call_before/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Fetch API Call Before Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend extension hooks that run before raw `fetchApi()` calls.
6 +
7 +## Ownership
8 +
9 +- Files in this folder own before-call behavior for CSRF-aware raw fetch flows.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function when present.
14 +- Preserve CSRF, auth, and redirect behavior owned by `/js/api.js`.
15 +
16 +## Work Guidance
17 +
18 +- Avoid broad request mutation that surprises unrelated API callers.
19 +
20 +## Verification
21 +
22 +- Smoke-test affected frontend API calls after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/webui/get_message_handler/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Get Message Handler Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend extensions that provide or modify message rendering handlers.
6 +
7 +## Ownership
8 +
9 +- Files in this folder own handler registration behavior for rendered chat messages.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function when present.
14 +- Preserve mutable context contracts used by `/js/messages.js`.
15 +- Do not render unsanitized model or user content.
16 +
17 +## Work Guidance
18 +
19 +- Coordinate handler changes with message components and plugin message extensions.
20 +
21 +## Verification
22 +
23 +- Smoke-test message rendering for affected message types after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
extensions/webui/initFw_end/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Init Framework End Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend extensions that run after WebUI framework initialization.
6 +
7 +## Ownership
8 +
9 +- JavaScript files own post-bootstrap global setup such as self-update helpers.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function.
14 +- Setup must be idempotent across reloads and cache resets.
15 +- Do not register duplicate global listeners.
16 +
17 +## Work Guidance
18 +
19 +- Coordinate initialization changes with `/js/initFw.js` and component lifecycle directives.
20 +
21 +## Verification
22 +
23 +- Smoke-test WebUI startup and browser console after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
extensions/webui/json_api_call_after/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# JSON API Call After Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend extension hooks that run after `callJsonApi()` calls.
6 +
7 +## Ownership
8 +
9 +- JavaScript files own after-call behavior such as cache reset handling.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function.
14 +- Preserve JSON API response contracts and avoid hiding errors from callers.
15 +
16 +## Work Guidance
17 +
18 +- Keep global side effects narrow and tied to explicit API results or mutable contexts.
19 +
20 +## Verification
21 +
22 +- Smoke-test JSON API callers affected by extension changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/webui/json_api_call_before/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# JSON API Call Before Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend extension hooks that run before `callJsonApi()` calls.
6 +
7 +## Ownership
8 +
9 +- Files in this folder own before-call behavior for JSON API requests.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function when present.
14 +- Preserve CSRF/auth behavior and JSON payload shape expected by `/js/api.js`.
15 +
16 +## Work Guidance
17 +
18 +- Avoid broad request mutation that affects unrelated plugin or core API calls.
19 +
20 +## Verification
21 +
22 +- Smoke-test affected JSON API calls after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/webui/right_canvas_register_surfaces/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Right Canvas Surface Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend registration of built-in right-canvas surfaces.
6 +
7 +## Ownership
8 +
9 +- JavaScript files own registration of remote link, space agent, and future core canvas surfaces.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function.
14 +- Surface IDs must be unique and stable.
15 +- Registered surfaces must point to valid components or handlers.
16 +
17 +## Work Guidance
18 +
19 +- Coordinate surface registration changes with `webui/components/canvas/` and related plugin panels.
20 +
21 +## Verification
22 +
23 +- Smoke-test opening each registered right-canvas surface after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
extensions/webui/set_messages_after_loop/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Set Messages After Loop Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend extensions that run after message DOM updates complete.
6 +
7 +## Ownership
8 +
9 +- Files in this folder own after-render message behavior.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function when present.
14 +- Preserve message DOM stability and avoid duplicate controls on repeated renders.
15 +
16 +## Work Guidance
17 +
18 +- Use stable markers when injecting controls into message elements.
19 +
20 +## Verification
21 +
22 +- Smoke-test message rerendering and extension-injected controls after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/webui/set_messages_before_loop/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Set Messages Before Loop Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend extensions that run before message DOM updates.
6 +
7 +## Ownership
8 +
9 +- Files in this folder own pre-render message behavior.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function when present.
14 +- Do not remove DOM state needed by message rendering unless the mutable context owns it.
15 +
16 +## Work Guidance
17 +
18 +- Coordinate pre-render behavior with `/js/messages.js` and message components.
19 +
20 +## Verification
21 +
22 +- Smoke-test message updates after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
extensions/webui/webui_ws_push/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# WebUI WebSocket Push Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own frontend behavior for WebUI WebSocket push events.
6 +
7 +## Ownership
8 +
9 +- JavaScript files own push-event side effects such as cache clearing.
10 +
11 +## Local Contracts
12 +
13 +- JavaScript modules must export a default function.
14 +- Validate event payload shape before acting.
15 +- Keep cache or state resets scoped to the event type.
16 +
17 +## Work Guidance
18 +
19 +- Coordinate push behavior with backend WebSocket event extensions and frontend stores.
20 +
21 +## Verification
22 +
23 +- Smoke-test relevant WebSocket push events after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
helpers/AGENTS.md
+6
@@ -18,17 +18,23 @@
18 - 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.
19 - Do not hardcode secrets, provider keys, local absolute paths, or environment-specific values.
20 - Use `RepairableException` for errors an agent may be able to fix.
21 +- 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.
22 +- 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.
23 +- When a helper module is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change.
24 +- Do not leave stale file-level DOX after helper deletion or rename.
25
26 ## Work Guidance
27
28 - Prefer cohesive helper modules over adding unrelated utilities to large files.
29 - Keep imports acyclic where possible; defer imports inside functions only when needed to avoid startup cycles.
30 - For changes touching auth, CSRF, files, plugins, tunnels, WebSockets, or model calls, read the caller and tests before editing.
31 +- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed helper behavior is described there.
32
33 ## Verification
34
35 - Run targeted tests for changed helper modules.
36 - Run security regression tests for auth, CSRF, filesystem, WebSocket, tunnel, upload, or image-serving changes.
37 +- Check file-level documentation coverage with a script or shell loop that verifies each `helpers/*.py` has a matching `helpers/*.py.dox.md`.
38
39 ## Child DOX Index
40
helpers/api.py.dox.md new
+71
@@ -0,0 +1,71 @@
1 +# api.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `api.py` helper module.
6 +- This module defines API handler registration, request security gates, CSRF checks, and watchdog registration.
7 +- Keep this file-level DOX profile synchronized with `api.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `api.py` owns the runtime implementation.
12 +- `api.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ApiHandler` (no explicit base class)
15 + - `requires_loopback(cls) -> bool`
16 + - `requires_api_key(cls) -> bool`
17 + - `requires_auth(cls) -> bool`
18 + - `get_methods(cls) -> list[str]`
19 + - `requires_csrf(cls) -> bool`
20 + - `async process(self, input: Input, request: Request) -> Output`
21 + - `async handle_request(self, request: Request) -> Response`
22 + - `use_context(self, ctxid: str, create_if_not_exists: bool=...)`
23 +- Top-level functions:
24 +- `requires_api_key(f)`
25 +- `requires_loopback(f)`
26 +- `requires_auth(f)`
27 +- `csrf_protect(f)`
28 +- `register_api_route(app: Flask, lock: ThreadLockType) -> None`
29 +- `register_watchdogs()`
30 +- Notable constants/configuration names: `CACHE_AREA`.
31 +
32 +## Runtime Contracts
33 +
34 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
35 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
36 +- `ApiHandler` defines `process(...)`.
37 +- `ApiHandler` defines `get_methods(...)`.
38 +- `ApiHandler` defines `requires_auth(...)`.
39 +- `ApiHandler` defines `requires_csrf(...)`.
40 +- `ApiHandler` defines `requires_api_key(...)`.
41 +- `ApiHandler` defines `requires_loopback(...)`.
42 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, plugin state, settings/state persistence, secret handling.
43 +- Imported dependency areas include: `abc`, `flask`, `functools`, `helpers`, `helpers.errors`, `helpers.network`, `helpers.print_style`, `json`, `pathlib`, `threading`, `typing`, `werkzeug.wrappers.response`.
44 +
45 +## Key Concepts
46 +
47 +- 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`.
48 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
49 +
50 +## Work Guidance
51 +
52 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
53 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
54 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
55 +
56 +## Verification
57 +
58 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
59 +- Related tests observed by source search:
60 + - `tests/test_api_chat_lifetime.py`
61 + - `tests/test_browser_agent_regressions.py`
62 + - `tests/test_download_toast_regressions.py`
63 + - `tests/test_fasta2a_client.py`
64 + - `tests/test_fastmcp_openapi_security.py`
65 + - `tests/test_host_browser_connector.py`
66 + - `tests/test_image_get_security.py`
67 + - `tests/test_model_config_api_keys.py`
68 +
69 +## Child DOX Index
70 +
71 +No child DOX files.
helpers/attachment_manager.py.dox.md new
+47
@@ -0,0 +1,47 @@
1 +# attachment_manager.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `attachment_manager.py` helper module.
6 +- This module tracks uploaded or generated attachments associated with chat contexts.
7 +- Keep this file-level DOX profile synchronized with `attachment_manager.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `attachment_manager.py` owns the runtime implementation.
12 +- `attachment_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `AttachmentManager` (no explicit base class)
15 + - `is_allowed_file(self, filename: str) -> bool`
16 + - `get_file_type(self, filename: str) -> str`
17 + - `get_file_extension(filename: str) -> str`
18 + - `validate_mime_type(self, file) -> bool`
19 + - `save_file(self, file: FileStorage, name: str) -> Tuple[str, Dict]`
20 + - `generate_image_preview(self, image_path: str, max_size: int=...) -> Optional[str]`
21 +
22 +## Runtime Contracts
23 +
24 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
25 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
26 +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence.
27 +- Imported dependency areas include: `PIL`, `base64`, `helpers.print_style`, `helpers.security`, `io`, `os`, `typing`, `werkzeug.datastructures`.
28 +
29 +## Key Concepts
30 +
31 +- 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`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
37 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
38 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
39 +
40 +## Verification
41 +
42 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
43 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
44 +
45 +## Child DOX Index
46 +
47 +No child DOX files.
helpers/backup.py.dox.md new
+50
@@ -0,0 +1,50 @@
1 +# backup.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `backup.py` helper module.
6 +- This module builds, inspects, previews, tests, and restores Agent Zero backup archives.
7 +- Keep this file-level DOX profile synchronized with `backup.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `backup.py` owns the runtime implementation.
12 +- `backup.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `BackupService` (no explicit base class)
15 + - `get_default_backup_metadata(self) -> Dict[str, Any]`
16 + - `async test_patterns(self, metadata: Dict[str, Any], max_files: int=...) -> List[Dict[str, Any]]`
17 + - `async create_backup(self, include_patterns: List[str], exclude_patterns: List[str], include_hidden: bool=..., backup_name: str=...) -> str`
18 + - `async inspect_backup(self, backup_file) -> Dict[str, Any]`
19 + - `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]`
20 + - `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]`
21 +
22 +## Runtime Contracts
23 +
24 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
25 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
26 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, secret handling.
27 +- Imported dependency areas include: `datetime`, `helpers`, `helpers.localization`, `helpers.print_style`, `json`, `os`, `pathspec`, `platform`, `tempfile`, `typing`, `zipfile`.
28 +
29 +## Key Concepts
30 +
31 +- 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`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
37 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
38 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
39 +
40 +## Verification
41 +
42 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
43 +- Related tests observed by source search:
44 + - `tests/test_download_toast_regressions.py`
45 + - `tests/test_office_document_store.py`
46 + - `tests/test_self_update_tag_filter.py`
47 +
48 +## Child DOX Index
49 +
50 +No child DOX files.
helpers/browser.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# browser.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `browser.py` helper module.
6 +- This module holds shared browser helper state used by browser-facing integrations.
7 +- Keep this file-level DOX profile synchronized with `browser.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `browser.py` owns the runtime implementation.
12 +- `browser.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +
14 +## Runtime Contracts
15 +
16 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
17 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
18 +- Observed side-effect areas: filesystem reads, filesystem deletion.
19 +
20 +## Key Concepts
21 +
22 +- This module is primarily declarative or delegates behavior through classes/imported objects.
23 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
24 +
25 +## Work Guidance
26 +
27 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
28 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
29 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
30 +
31 +## Verification
32 +
33 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
34 +- Related tests observed by source search:
35 + - `tests/test_a0_connector_prompt_gating.py`
36 + - `tests/test_browser_agent_regressions.py`
37 + - `tests/test_download_toast_regressions.py`
38 + - `tests/test_host_browser_connector.py`
39 + - `tests/test_oauth_gemini_api.py`
40 + - `tests/test_oauth_providers.py`
41 + - `tests/test_oauth_static.py`
42 + - `tests/test_oauth_xai_grok.py`
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
helpers/cache.py.dox.md new
+64
@@ -0,0 +1,64 @@
1 +# cache.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `cache.py` helper module.
6 +- This module provides in-process cache areas with optional global and area toggles.
7 +- Keep this file-level DOX profile synchronized with `cache.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `cache.py` owns the runtime implementation.
12 +- `cache.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `CacheEntry` (no explicit base class)
15 +- Top-level functions:
16 +- `toggle_global(enabled: bool) -> None`
17 +- `toggle_area(area: str, enabled: bool) -> None`
18 +- `has(area: str, key: Any) -> bool`
19 +- `add(area: str, key: Any, data: Any) -> None`
20 +- `get(area: str, key: Any, default: Any=...) -> Any`
21 +- `remove(area: str, key: Any) -> None`
22 +- `clear(area: str) -> None`
23 +- `trim_cache(area: str, seconds: float=...) -> None`
24 +- `clear_all() -> None`
25 +- `_is_enabled(area: str) -> bool`
26 +- `_create_entry(value: Any) -> CacheEntry`
27 +- `_touch_entry(entry: CacheEntry) -> None`
28 +- `_get_matching_areas(area: str) -> list[str]`
29 +- `determine_cache_key(agent, *additional)`
30 +
31 +## Runtime Contracts
32 +
33 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
34 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
35 +- Observed side-effect areas: filesystem deletion, plugin state, settings/state persistence.
36 +- Imported dependency areas include: `dataclasses`, `fnmatch`, `threading`, `time`, `typing`.
37 +
38 +## Key Concepts
39 +
40 +- 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`.
41 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
42 +
43 +## Work Guidance
44 +
45 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
46 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
47 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
48 +
49 +## Verification
50 +
51 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
52 +- Related tests observed by source search:
53 + - `tests/test_browser_agent_regressions.py`
54 + - `tests/test_file_tree_visualize.py`
55 + - `tests/test_office_canvas_setup.py`
56 + - `tests/test_office_document_store.py`
57 + - `tests/test_self_update_tag_filter.py`
58 + - `tests/test_time_travel.py`
59 + - `tests/test_webui_extension_surfaces.py`
60 + - `tests/test_whatsapp_bridge_manager.py`
61 +
62 +## Child DOX Index
63 +
64 +No child DOX files.
helpers/call_llm.py.dox.md new
+43
@@ -0,0 +1,43 @@
1 +# call_llm.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `call_llm.py` helper module.
6 +- This module wraps LiteLLM/model calls with examples, streaming, and extension hooks.
7 +- Keep this file-level DOX profile synchronized with `call_llm.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `call_llm.py` owns the runtime implementation.
12 +- `call_llm.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Example` (`TypedDict`)
15 +- Top-level functions:
16 +- `async call_llm(system: str, model: BaseChatModel | BaseLLM, message: str, examples: list[Example]=..., callback: Callable[[str], None] | None=...)`
17 +
18 +## Runtime Contracts
19 +
20 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
21 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
22 +- Observed side-effect areas: model calls.
23 +- Imported dependency areas include: `langchain.prompts`, `langchain.schema`, `langchain_core.language_models.chat_models`, `langchain_core.language_models.llms`, `langchain_core.messages`, `typing`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `ChatPromptTemplate.from_messages`, `FewShotChatMessagePromptTemplate`, `few_shot_prompt.format`, `chain.astream`, `HumanMessage`, `AIMessage`, `SystemMessage`, `callback`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
33 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
34 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
35 +
36 +## Verification
37 +
38 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
39 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
40 +
41 +## Child DOX Index
42 +
43 +No child DOX files.
helpers/chat_media.py.dox.md new
+60
@@ -0,0 +1,60 @@
1 +# chat_media.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `chat_media.py` helper module.
6 +- This module materializes, stores, and resolves chat-scoped image/media artifacts.
7 +- Keep this file-level DOX profile synchronized with `chat_media.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `chat_media.py` owns the runtime implementation.
12 +- `chat_media.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ChatImage` (no explicit base class)
15 +- Top-level functions:
16 +- `screenshot_dir(context_id: str, source: str) -> Path`
17 +- `artifact_dir(context_id: str, category: ImageCategory=..., source: str=...) -> Path`
18 +- `save_image_bytes(context_id: str, payload: bytes, mime_type: str=..., category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
19 +- `save_image_base64(context_id: str, data: str, mime_type: str=..., category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
20 +- `save_image_file(context_id: str, path: str | Path, category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
21 +- `save_image_data_url(context_id: str, data_url: str, category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
22 +- `materialize_image_ref(context_id: str, url: str, source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> str`
23 +- `is_chat_scoped_path(context_id: str, path: str | Path) -> bool`
24 +- `infer_source(value: str=..., preferred_name: str=...) -> str`
25 +- `category_for_source(source: str) -> ImageCategory`
26 +- `_guess_image_mime(path: Path) -> str`
27 +- `_is_data_image_url(value: str) -> bool`
28 +- `_split_image_data_url(data_url: str) -> tuple[str, str]`
29 +- Notable constants/configuration names: `DEFAULT_MAX_IMAGE_BYTES`.
30 +
31 +## Runtime Contracts
32 +
33 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
34 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
35 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
36 +- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `pathlib`, `time`, `typing`, `uuid`.
37 +
38 +## Key Concepts
39 +
40 +- 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`.
41 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
42 +
43 +## Work Guidance
44 +
45 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
46 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
47 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
48 +
49 +## Verification
50 +
51 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
52 +- Related tests observed by source search:
53 + - `tests/test_browser_agent_regressions.py`
54 + - `tests/test_host_browser_connector.py`
55 + - `tests/test_tool_action_contracts.py`
56 + - `tests/test_vision_load_image_refs.py`
57 +
58 +## Child DOX Index
59 +
60 +No child DOX files.
helpers/cli_tunnel.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# cli_tunnel.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `cli_tunnel.py` helper module.
6 +- This module provides shared download and install mechanics for CLI-based tunnel providers.
7 +- Keep this file-level DOX profile synchronized with `cli_tunnel.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `cli_tunnel.py` owns the runtime implementation.
12 +- `cli_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `CliTunnelHelper` (`TunnelHelper`)
15 + - `start(self)`
16 + - `stop(self)`
17 +- Top-level functions:
18 +- `executable_name(name)`
19 +- `chmod_executable(path)`
20 +- `notify_download(notify, message, data=...)`
21 +- `notify_download_complete(notify, message, data=...)`
22 +- `download_file(url, destination, notify=...)`
23 +- `platform_parts()`
24 +- `extract_named_members_from_tar(archive_path, destination_dir, member_names)`
25 +- `extract_named_members_from_zip(archive_path, destination_dir, member_names)`
26 +- Notable constants/configuration names: `RUNTIME_BIN_DIR`.
27 +
28 +## Runtime Contracts
29 +
30 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
31 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
32 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, tunnel state.
33 +- Imported dependency areas include: `collections`, `flaredantic`, `helpers`, `helpers.tunnel_common`, `os`, `pathlib`, `platform`, `queue`, `shutil`, `subprocess`, `tarfile`, `tempfile`, `threading`, `time`, `urllib.request`, `zipfile`.
34 +
35 +## Key Concepts
36 +
37 +- 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`.
38 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
39 +
40 +## Work Guidance
41 +
42 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
43 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
44 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
45 +
46 +## Verification
47 +
48 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
49 +- Related tests observed by source search:
50 + - `tests/test_tunnel_remote_link.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
helpers/cloudflare_tunnel.py.dox.md new
+43
@@ -0,0 +1,43 @@
1 +# cloudflare_tunnel.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `cloudflare_tunnel.py` helper module.
6 +- This module implements Cloudflare tunnel provider lifecycle behavior.
7 +- Keep this file-level DOX profile synchronized with `cloudflare_tunnel.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `cloudflare_tunnel.py` owns the runtime implementation.
12 +- `cloudflare_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `CloudflareTunnel` (`FlaredanticTunnelHelper`)
15 + - `build_tunnel(self)`
16 +
17 +## Runtime Contracts
18 +
19 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
20 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
21 +- Observed side-effect areas: settings/state persistence, tunnel state.
22 +- Imported dependency areas include: `flaredantic`, `helpers.tunnel_common`.
23 +
24 +## Key Concepts
25 +
26 +- Important called helpers/classes observed in the source: `FlareConfig`, `FlareTunnel`.
27 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
28 +
29 +## Work Guidance
30 +
31 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
32 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
33 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
34 +
35 +## Verification
36 +
37 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
38 +- Related tests observed by source search:
39 + - `tests/test_tunnel_remote_link.py`
40 +
41 +## Child DOX Index
42 +
43 +No child DOX files.
helpers/context.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# context.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `context.py` helper module.
6 +- This module provides compatibility helpers for reading and writing `AgentContext` data.
7 +- Keep this file-level DOX profile synchronized with `context.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `context.py` owns the runtime implementation.
12 +- `context.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `_ensure_context() -> Dict[str, Any]`: Make sure a context dict exists, and return it.
15 +- `set_context_data(key: str, value: Any)`: Set context data for the current async/task context.
16 +- `delete_context_data(key: str)`: Delete a key from the current async/task context.
17 +- `get_context_data(key: Optional[str]=..., default: T=...) -> T`: Get a key from the current context, or the full dict if key is None.
18 +- `clear_context_data()`: Completely clear the context dict.
19 +- Notable constants/configuration names: `T`.
20 +
21 +## Runtime Contracts
22 +
23 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
24 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
25 +- Observed side-effect areas: filesystem deletion, scheduler state.
26 +- Imported dependency areas include: `contextvars`, `typing`.
27 +
28 +## Key Concepts
29 +
30 +- Important called helpers/classes observed in the source: `TypeVar`, `ContextVar`, `_ensure_context`, `cast`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
36 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
37 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
38 +
39 +## Verification
40 +
41 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
42 +- Related tests observed by source search:
43 + - `tests/test_a0_connector_prompt_gating.py`
44 + - `tests/test_api_chat_lifetime.py`
45 + - `tests/test_browser_agent_regressions.py`
46 + - `tests/test_document_query_plugin.py`
47 + - `tests/test_error_retry_plugin.py`
48 + - `tests/test_extensions_stress.py`
49 + - `tests/test_file_tree_visualize.py`
50 + - `tests/test_history_compression_wait.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
helpers/context_utils.py.dox.md new
+41
@@ -0,0 +1,41 @@
1 +# context_utils.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `context_utils.py` helper module.
6 +- This module provides context managers/utilities for current context binding.
7 +- Keep this file-level DOX profile synchronized with `context_utils.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `context_utils.py` owns the runtime implementation.
12 +- `context_utils.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `use_context(lock: ThreadLockType, ctxid: str, create_if_not_exists: bool=...)`
15 +
16 +## Runtime Contracts
17 +
18 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
19 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
20 +- Observed side-effect areas: WebSocket state, settings/state persistence.
21 +- Imported dependency areas include: `threading`, `typing`.
22 +
23 +## Key Concepts
24 +
25 +- Important called helpers/classes observed in the source: `AgentContext.use`, `AgentContext.first`, `AgentContext`, `Exception`, `initialize_agent`.
26 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
27 +
28 +## Work Guidance
29 +
30 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
31 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
32 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
33 +
34 +## Verification
35 +
36 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
37 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
38 +
39 +## Child DOX Index
40 +
41 +No child DOX files.
helpers/crypto.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# crypto.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `crypto.py` helper module.
6 +- This module hashes, verifies, encrypts, and decrypts data for signed or protected payloads.
7 +- Keep this file-level DOX profile synchronized with `crypto.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `crypto.py` owns the runtime implementation.
12 +- `crypto.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `hash_data(data: str, password: str)`
15 +- `verify_data(data: str, hash: str, password: str)`
16 +- `_generate_private_key()`
17 +- `_generate_public_key(private_key: rsa.RSAPrivateKey)`
18 +- `_decode_public_key(public_key: str) -> rsa.RSAPublicKey`
19 +- `encrypt_data(data: str, public_key_pem: str)`
20 +- `_encrypt_data(data: bytes, public_key: rsa.RSAPublicKey)`
21 +- `decrypt_data(data: str, private_key: rsa.RSAPrivateKey)`
22 +
23 +## Runtime Contracts
24 +
25 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
26 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
27 +- Observed side-effect areas: secret handling.
28 +- Imported dependency areas include: `cryptography.hazmat.primitives`, `cryptography.hazmat.primitives.asymmetric`, `hashlib`, `hmac`, `os`.
29 +
30 +## Key Concepts
31 +
32 +- 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`.
33 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
34 +
35 +## Work Guidance
36 +
37 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
38 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
39 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
40 +
41 +## Verification
42 +
43 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
44 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
helpers/defer.py.dox.md new
+55
@@ -0,0 +1,55 @@
1 +# defer.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `defer.py` helper module.
6 +- This module runs deferred or child async tasks on managed event-loop threads.
7 +- Keep this file-level DOX profile synchronized with `defer.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `defer.py` owns the runtime implementation.
12 +- `defer.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `EventLoopThread` (no explicit base class)
15 + - `terminate(self)`
16 + - `run_coroutine(self, coro)`
17 +- `ChildTask` (no explicit base class)
18 +- `DeferredTask` (no explicit base class)
19 + - `start_task(self, func: Callable[..., Coroutine[Any, Any, Any]], *args, **kwargs)`
20 + - `is_ready(self) -> bool`
21 + - `result_sync(self, timeout: Optional[float]=...) -> Any`
22 + - `async result(self, timeout: Optional[float]=...) -> Any`
23 + - `kill(self, terminate_thread: bool=...) -> None`
24 + - `kill_children(self) -> None`
25 + - `is_alive(self) -> bool`
26 + - `restart(self, terminate_thread: bool=...) -> None`
27 +- Notable constants/configuration names: `T`, `THREAD_BACKGROUND`.
28 +
29 +## Runtime Contracts
30 +
31 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
32 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
33 +- Observed side-effect areas: scheduler state.
34 +- Imported dependency areas include: `asyncio`, `concurrent.futures`, `dataclasses`, `threading`, `typing`.
35 +
36 +## Key Concepts
37 +
38 +- 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`.
39 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
40 +
41 +## Work Guidance
42 +
43 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
44 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
45 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
46 +
47 +## Verification
48 +
49 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
50 +- Related tests observed by source search:
51 + - `tests/test_office_document_store.py`
52 +
53 +## Child DOX Index
54 +
55 +No child DOX files.
helpers/dirty_json.py
+71 -3
@@ -214,7 +214,7 @@ class DirtyJson:
214 def _parse_key(self):
215 self._skip_whitespace()
216 if self.current_char in ['"', "'"]:
217 - return self._parse_string()
217 + return self._parse_string(is_key=True)
218 else:
219 return self._parse_unquoted_key()
220
@@ -260,11 +260,18 @@ class DirtyJson:
260 self._pop_stack()
261 return
262
263 - def _parse_string(self):
263 + def _parse_string(self, is_key: bool = False):
264 result = ""
265 quote_char = self.current_char
266 self._advance() # Skip opening quote
267 - while self.current_char is not None and self.current_char != quote_char:
267 + while self.current_char is not None:
268 + if self.current_char == quote_char:
269 + if self._is_closing_quote(is_key):
270 + break
271 + result += self.current_char
272 + self._advance()
273 + continue
274 +
275 if self.current_char == "\\":
276 self._advance()
277 if self.current_char in ['"', "'", "\\", "/", "b", "f", "n", "r", "t"]:
@@ -298,6 +305,67 @@ class DirtyJson:
305 self._advance() # Skip closing quote
306 return result
307
308 + def _is_closing_quote(self, is_key: bool) -> bool:
309 + next_index = self._skip_padding_from(self.index + 1)
310 + if next_index >= len(self.json_string):
311 + return True
312 +
313 + next_char = self.json_string[next_index]
314 + if is_key:
315 + return next_char in [":", ",", "}", "]"]
316 +
317 + if next_char in [",", "}", "]"]:
318 + return True
319 +
320 + return self._looks_like_missing_comma_before_key(next_index)
321 +
322 + def _looks_like_missing_comma_before_key(self, index: int) -> bool:
323 + if not self.stack or not isinstance(self.stack[-1], dict):
324 + return False
325 + if index >= len(self.json_string) or self.json_string[index] not in ['"', "'"]:
326 + return False
327 +
328 + quote_char = self.json_string[index]
329 + index += 1
330 + while index < len(self.json_string):
331 + char = self.json_string[index]
332 + if char == "\\":
333 + index += 2
334 + continue
335 + if char == quote_char:
336 + next_index = self._skip_padding_from(index + 1)
337 + return (
338 + next_index < len(self.json_string)
339 + and self.json_string[next_index] == ":"
340 + )
341 + if char in ["\n", "\r", "{", "}", "[", "]", ","]:
342 + return False
343 + index += 1
344 +
345 + return False
346 +
347 + def _skip_padding_from(self, index: int) -> int:
348 + while index < len(self.json_string):
349 + char = self.json_string[index]
350 + if char.isspace():
351 + index += 1
352 + elif char == "/" and index + 1 < len(self.json_string):
353 + next_char = self.json_string[index + 1]
354 + if next_char == "/":
355 + index += 2
356 + while index < len(self.json_string) and self.json_string[index] != "\n":
357 + index += 1
358 + elif next_char == "*":
359 + end = self.json_string.find("*/", index + 2)
360 + if end == -1:
361 + return len(self.json_string)
362 + index = end + 2
363 + else:
364 + break
365 + else:
366 + break
367 + return index
368 +
369 def _parse_multiline_string(self):
370 result = ""
371 quote_char = self.current_char
helpers/dirty_json.py.dox.md new
+51
@@ -0,0 +1,51 @@
1 +# dirty_json.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `dirty_json.py` helper module.
6 +- This module parses and serializes relaxed JSON-like model output.
7 +- Keep this file-level DOX profile synchronized with `dirty_json.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `dirty_json.py` owns the runtime implementation.
12 +- `dirty_json.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `DirtyJson` (no explicit base class)
15 + - `parse_string(json_string)`
16 + - `parse(self, json_string)`
17 + - `feed(self, chunk)`
18 + - `get_start_pos(self, input_str: str) -> int`
19 +- Top-level functions:
20 +- `try_parse(json_string: str)`
21 +- `parse(json_string: str)`
22 +- `stringify(obj, **kwargs)`
23 +
24 +## Runtime Contracts
25 +
26 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
27 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
28 +- Observed side-effect areas: filesystem writes, settings/state persistence.
29 +- Imported dependency areas include: `json`.
30 +
31 +## Key Concepts
32 +
33 +- 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`.
34 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
35 +
36 +## Work Guidance
37 +
38 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
39 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
40 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
41 +
42 +## Verification
43 +
44 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
45 +- Related tests observed by source search:
46 + - `tests/test_dirty_json.py`
47 + - `tests/test_projects.py`
48 +
49 +## Child DOX Index
50 +
51 +No child DOX files.
helpers/docker.py.dox.md new
+53
@@ -0,0 +1,53 @@
1 +# docker.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `docker.py` helper module.
6 +- This module manages Docker container operations used by runtime helpers.
7 +- Keep this file-level DOX profile synchronized with `docker.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `docker.py` owns the runtime implementation.
12 +- `docker.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `DockerContainerManager` (no explicit base class)
15 + - `init_docker(self)`
16 + - `cleanup_container(self) -> None`
17 + - `get_image_containers(self)`
18 + - `start_container(self) -> None`
19 +
20 +## Runtime Contracts
21 +
22 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
23 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
24 +- Observed side-effect areas: filesystem reads, filesystem deletion, subprocess/runtime control, WebSocket state.
25 +- Imported dependency areas include: `atexit`, `docker`, `helpers.errors`, `helpers.files`, `helpers.log`, `helpers.print_style`, `time`, `typing`.
26 +
27 +## Key Concepts
28 +
29 +- 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`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
35 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
36 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
37 +
38 +## Verification
39 +
40 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
41 +- Related tests observed by source search:
42 + - `tests/test_browser_agent_regressions.py`
43 + - `tests/test_default_prompt_budget.py`
44 + - `tests/test_docker_release_plan.py`
45 + - `tests/test_document_query_plugin.py`
46 + - `tests/test_host_browser_connector.py`
47 + - `tests/test_model_search.py`
48 + - `tests/test_office_canvas_setup.py`
49 + - `tests/test_office_document_store.py`
50 +
51 +## Child DOX Index
52 +
53 +No child DOX files.
helpers/document_query.py.dox.md new
+41
@@ -0,0 +1,41 @@
1 +# document_query.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `document_query.py` helper module.
6 +- This module provides compatibility exports for document query behavior.
7 +- Keep this file-level DOX profile synchronized with `document_query.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `document_query.py` owns the runtime implementation.
12 +- `document_query.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +
14 +## Runtime Contracts
15 +
16 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
17 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
18 +- Observed side-effect areas: plugin state.
19 +- Imported dependency areas include: `plugins._document_query.helpers.document_query`.
20 +
21 +## Key Concepts
22 +
23 +- This module is primarily declarative or delegates behavior through classes/imported objects.
24 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
25 +
26 +## Work Guidance
27 +
28 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
29 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
30 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
31 +
32 +## Verification
33 +
34 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
35 +- Related tests observed by source search:
36 + - `tests/test_document_query_fallback.py`
37 + - `tests/test_document_query_plugin.py`
38 +
39 +## Child DOX Index
40 +
41 +No child DOX files.
helpers/dotenv.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# dotenv.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `dotenv.py` helper module.
6 +- This module loads and updates `.env` configuration values.
7 +- Keep this file-level DOX profile synchronized with `dotenv.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `dotenv.py` owns the runtime implementation.
12 +- `dotenv.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `load_dotenv()`
15 +- `get_dotenv_file_path()`
16 +- `get_dotenv_value(key: str, default: Any=...)`
17 +- `save_dotenv_value(key: str, value: str)`
18 +- Notable constants/configuration names: `KEY_AUTH_LOGIN`, `KEY_AUTH_PASSWORD`, `KEY_RFC_PASSWORD`, `KEY_ROOT_PASSWORD`.
19 +
20 +## Runtime Contracts
21 +
22 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
23 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
24 +- Observed side-effect areas: filesystem reads, filesystem writes, secret handling.
25 +- Imported dependency areas include: `dotenv`, `files`, `os`, `re`, `typing`.
26 +
27 +## Key Concepts
28 +
29 +- 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`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
35 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
36 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
37 +
38 +## Verification
39 +
40 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
41 +- Related tests observed by source search:
42 + - `tests/email_parser_test.py`
43 + - `tests/test_model_config_api_keys.py`
44 + - `tests/test_timezone_regressions.py`
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
helpers/duckduckgo_search.py.dox.md new
+40
@@ -0,0 +1,40 @@
1 +# duckduckgo_search.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `duckduckgo_search.py` helper module.
6 +- This module queries DuckDuckGo search through the configured helper path.
7 +- Keep this file-level DOX profile synchronized with `duckduckgo_search.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `duckduckgo_search.py` owns the runtime implementation.
12 +- `duckduckgo_search.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `search(query: str, results=..., region=..., time=...) -> list[str]`
15 +
16 +## Runtime Contracts
17 +
18 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
19 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
20 +- Imported dependency areas include: `duckduckgo_search`.
21 +
22 +## Key Concepts
23 +
24 +- Important called helpers/classes observed in the source: `DDGS`, `ddgs.text`.
25 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
26 +
27 +## Work Guidance
28 +
29 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
30 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
31 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
32 +
33 +## Verification
34 +
35 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
36 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
37 +
38 +## Child DOX Index
39 +
40 +No child DOX files.
helpers/email_client.py.dox.md new
+39
@@ -0,0 +1,39 @@
1 +# email_client.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `email_client.py` helper module.
6 +- This module provides shared email client plumbing for mail integrations.
7 +- Keep this file-level DOX profile synchronized with `email_client.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `email_client.py` owns the runtime implementation.
12 +- `email_client.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +
14 +## Runtime Contracts
15 +
16 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
17 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
18 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, settings/state persistence, secret handling.
19 +
20 +## Key Concepts
21 +
22 +- This module is primarily declarative or delegates behavior through classes/imported objects.
23 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
24 +
25 +## Work Guidance
26 +
27 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
28 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
29 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
30 +
31 +## Verification
32 +
33 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
34 +- Related tests observed by source search:
35 + - `tests/email_parser_test.py`
36 +
37 +## Child DOX Index
38 +
39 +No child DOX files.
helpers/ephemeral_images.py.dox.md new
+58
@@ -0,0 +1,58 @@
1 +# ephemeral_images.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `ephemeral_images.py` helper module.
6 +- This module stores temporary image payloads by reference for safe short-lived access.
7 +- Keep this file-level DOX profile synchronized with `ephemeral_images.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `ephemeral_images.py` owns the runtime implementation.
12 +- `ephemeral_images.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `EphemeralImage` (no explicit base class)
15 + - `data_url(self) -> str`
16 + - `display_name(self) -> str`
17 +- Top-level functions:
18 +- `put_image_bytes(context_id: str, mime: str, payload: bytes, name: str=..., ttl_seconds: float=...) -> str`
19 +- `put_image(context_id: str, mime: str, data: str, name: str=..., ttl_seconds: float=...) -> str`
20 +- `is_ref(value: object) -> bool`
21 +- `display_ref(ref: str) -> str`
22 +- `get_image(ref: str, context_id: str=...) -> EphemeralImage | None`
23 +- `consume_image(ref: str, context_id: str=...) -> EphemeralImage | None`
24 +- `delete_image(ref: str) -> None`
25 +- `clear_context(context_id: str) -> None`
26 +- `_resolve_image(ref: str, context_id: str=..., consume: bool) -> EphemeralImage | None`
27 +- `_compact_base64(data: str) -> str`
28 +- `_normalize_mime(mime: str) -> str`
29 +- `_prune_expired_locked(now: float | None=...) -> None`
30 +- Notable constants/configuration names: `REF_PREFIX`, `DEFAULT_TTL_SECONDS`.
31 +
32 +## Runtime Contracts
33 +
34 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
35 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
36 +- Observed side-effect areas: filesystem deletion.
37 +- Imported dependency areas include: `__future__`, `base64`, `dataclasses`, `threading`, `time`, `uuid`.
38 +
39 +## Key Concepts
40 +
41 +- 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`.
42 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
43 +
44 +## Work Guidance
45 +
46 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
47 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
48 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
49 +
50 +## Verification
51 +
52 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
53 +- Related tests observed by source search:
54 + - `tests/test_browser_agent_regressions.py`
55 +
56 +## Child DOX Index
57 +
58 +No child DOX files.
helpers/errors.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# errors.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `errors.py` helper module.
6 +- This module defines framework exceptions and safe error formatting.
7 +- Keep this file-level DOX profile synchronized with `errors.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `errors.py` owns the runtime implementation.
12 +- `errors.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `RepairableException` (`Exception`)
15 +- `InterventionException` (`Exception`)
16 +- `HandledException` (`Exception`)
17 +- Top-level functions:
18 +- `handle_error(e: Exception)`
19 +- `error_text(e: Exception)`
20 +- `format_error(e: Exception, start_entries=..., end_entries=..., error_message_position: Literal['top', 'bottom', 'none']=...)`
21 +
22 +## Runtime Contracts
23 +
24 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
25 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
26 +- Imported dependency areas include: `asyncio`, `re`, `traceback`, `typing`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
36 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
37 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
38 +
39 +## Verification
40 +
41 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
42 +- Related tests observed by source search:
43 + - `tests/test_browser_agent_regressions.py`
44 + - `tests/test_fasta2a_client.py`
45 + - `tests/test_host_browser_connector.py`
46 + - `tests/test_office_desktop_state.py`
47 + - `tests/test_office_document_store.py`
48 + - `tests/test_skills_runtime.py`
49 + - `tests/test_speech_plugin_split.py`
50 + - `tests/test_time_travel.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
helpers/extension.py.dox.md new
+63
@@ -0,0 +1,63 @@
1 +# extension.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `extension.py` helper module.
6 +- This module discovers and dispatches Python and WebUI extension hooks.
7 +- Keep this file-level DOX profile synchronized with `extension.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `extension.py` owns the runtime implementation.
12 +- `extension.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `_Unset` (no explicit base class)
15 +- `Extension` (no explicit base class)
16 + - `execute(self, **kwargs) -> None | Awaitable[None]`
17 +- Top-level functions:
18 +- `_log_extension_call(name: str)`
19 +- `extensible(func)`: Make a function emit two implicit extension points around its execution.
20 +- `async call_extensions_async(extension_point: str, agent: 'Agent|None'=..., **kwargs)`
21 +- `call_extensions_sync(extension_point: str, agent: 'Agent|None'=..., **kwargs)`
22 +- `get_webui_extensions(agent: 'Agent | None', extension_point: str, filters: list[str] | None=...)`
23 +- `_get_extension_classes(extension_point: str, agent: 'Agent|None'=..., **kwargs) -> list[Type[Extension]]`
24 +- `_get_file_from_module(module_name: str) -> str`
25 +- `_get_extensions(folder: str)`
26 +- `register_extensions_watchdogs()`
27 +- Notable constants/configuration names: `DEFAULT_EXTENSIONS_FOLDER`, `USER_EXTENSIONS_FOLDER`, `_EXTENSIONS_CACHE_AREA`, `_CLASSES_CACHE_AREA`, `_UNSET`, `_EXTENSIONS_LOG_COUNTS`.
28 +
29 +## Runtime Contracts
30 +
31 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
32 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
33 +- `Extension` defines `execute(...)`.
34 +- Observed side-effect areas: filesystem reads, WebSocket state, plugin state.
35 +- Imported dependency areas include: `abc`, `functools`, `helpers`, `helpers.print_style`, `inspect`, `os`, `typing`.
36 +
37 +## Key Concepts
38 +
39 +- 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`.
40 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
41 +
42 +## Work Guidance
43 +
44 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
45 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
46 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
47 +
48 +## Verification
49 +
50 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
51 +- Related tests observed by source search:
52 + - `tests/test_a0_connector_prompt_gating.py`
53 + - `tests/test_api_chat_lifetime.py`
54 + - `tests/test_browser_agent_regressions.py`
55 + - `tests/test_error_retry_plugin.py`
56 + - `tests/test_extensions_stress.py`
57 + - `tests/test_history_compression_wait.py`
58 + - `tests/test_model_config_api_keys.py`
59 + - `tests/test_oauth_codex.py`
60 +
61 +## Child DOX Index
62 +
63 +No child DOX files.
helpers/extract_tools.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# extract_tools.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `extract_tools.py` helper module.
6 +- This module normalizes and repairs model-emitted tool-call JSON.
7 +- Keep this file-level DOX profile synchronized with `extract_tools.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `extract_tools.py` owns the runtime implementation.
12 +- `extract_tools.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `json_parse_dirty(json: str) -> dict[str, Any] | None`
15 +- `normalize_tool_request(tool_request: Any) -> tuple[str, dict]`
16 +- `extract_json_root_string(content: str) -> str | None`
17 +- `extract_json_object_string(content)`
18 +- `extract_json_string(content)`
19 +- `fix_json_string(json_string)`
20 +
21 +## Runtime Contracts
22 +
23 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
24 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
25 +- Observed side-effect areas: settings/state persistence.
26 +- Imported dependency areas include: `dirty_json`, `helpers.modules`, `re`, `regex`, `typing`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
36 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
37 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
38 +
39 +## Verification
40 +
41 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
42 +- Related tests observed by source search:
43 + - `tests/test_stream_tool_early_stop.py`
44 + - `tests/test_tool_request_normalization.py`
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
helpers/faiss_monkey_patch.py.dox.md new
+38
@@ -0,0 +1,38 @@
1 +# faiss_monkey_patch.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `faiss_monkey_patch.py` helper module.
6 +- This module applies compatibility patches for FAISS behavior.
7 +- Keep this file-level DOX profile synchronized with `faiss_monkey_patch.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `faiss_monkey_patch.py` owns the runtime implementation.
12 +- `faiss_monkey_patch.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +
14 +## Runtime Contracts
15 +
16 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
17 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
18 +- Imported dependency areas include: `numpy`, `sys`, `types`, `warnings`.
19 +
20 +## Key Concepts
21 +
22 +- Important called helpers/classes observed in the source: `types.ModuleType`, `SimpleNamespace`, `warnings.catch_warnings`, `warnings.simplefilter`.
23 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
24 +
25 +## Work Guidance
26 +
27 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
28 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
29 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
30 +
31 +## Verification
32 +
33 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
34 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
35 +
36 +## Child DOX Index
37 +
38 +No child DOX files.
helpers/fasta2a_client.py.dox.md new
+50
@@ -0,0 +1,50 @@
1 +# fasta2a_client.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `fasta2a_client.py` helper module.
6 +- This module connects Agent Zero to external A2A agents.
7 +- Keep this file-level DOX profile synchronized with `fasta2a_client.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `fasta2a_client.py` owns the runtime implementation.
12 +- `fasta2a_client.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `AgentConnection` (no explicit base class)
15 + - `async get_agent_card(self) -> Dict[str, Any]`
16 + - `async send_message(self, message: str, attachments: Optional[List[str]]=..., context_id: Optional[str]=..., metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]`
17 + - `async get_task(self, task_id: str) -> Dict[str, Any]`
18 + - `async wait_for_completion(self, task_id: str, poll_interval: int=..., max_wait: int=...) -> Dict[str, Any]`
19 + - `async close(self)`
20 +- Top-level functions:
21 +- `async connect_to_agent(agent_url: str, timeout: int=...) -> AgentConnection`: Create a connection to a remote agent.
22 +- `is_client_available() -> bool`: Check if FastA2A client is available.
23 +- Notable constants/configuration names: `_PRINTER`.
24 +
25 +## Runtime Contracts
26 +
27 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
28 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
29 +- Observed side-effect areas: filesystem writes, network calls, WebSocket state, settings/state persistence, secret handling, scheduler state.
30 +- Imported dependency areas include: `helpers.print_style`, `typing`, `uuid`.
31 +
32 +## Key Concepts
33 +
34 +- 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`.
35 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
36 +
37 +## Work Guidance
38 +
39 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
40 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
41 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
42 +
43 +## Verification
44 +
45 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
46 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
47 +
48 +## Child DOX Index
49 +
50 +No child DOX files.
helpers/fasta2a_server.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# fasta2a_server.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `fasta2a_server.py` helper module.
6 +- This module serves Agent Zero through a dynamic A2A proxy.
7 +- Keep this file-level DOX profile synchronized with `fasta2a_server.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `fasta2a_server.py` owns the runtime implementation.
12 +- `fasta2a_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `AgentZeroWorker` (`Worker`)
15 + - `async run_task(self, params: Any) -> None`
16 + - `async cancel_task(self, params: Any) -> None`
17 + - `build_message_history(self, history: List[Any]) -> List[Message]`
18 + - `build_artifacts(self, result: Any) -> List[Artifact]`
19 +- `DynamicA2AProxy` (no explicit base class)
20 + - `get_instance()`
21 + - `reconfigure(self, token: str)`
22 +- Top-level functions:
23 +- `is_available()`: Check if FastA2A is available and properly configured.
24 +- `get_proxy()`: Get the FastA2A proxy instance.
25 +- Notable constants/configuration names: `_PRINTER`.
26 +
27 +## Runtime Contracts
28 +
29 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
30 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
31 +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
32 +- Imported dependency areas include: `agent`, `asyncio`, `atexit`, `contextlib`, `helpers`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `starlette.requests`, `threading`, `typing`, `uuid`.
33 +
34 +## Key Concepts
35 +
36 +- 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`.
37 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
38 +
39 +## Work Guidance
40 +
41 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
42 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
43 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
44 +
45 +## Verification
46 +
47 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
48 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
helpers/file_browser.py.dox.md new
+51
@@ -0,0 +1,51 @@
1 +# file_browser.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `file_browser.py` helper module.
6 +- This module builds safe file-browser views over allowed filesystem roots.
7 +- Keep this file-level DOX profile synchronized with `file_browser.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `file_browser.py` owns the runtime implementation.
12 +- `file_browser.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `FileBrowser` (no explicit base class)
15 + - `save_file_b64(self, current_path: str, filename: str, base64_content: str)`
16 + - `save_files(self, files: List, current_path: str=...) -> Tuple[List[str], List[str]]`
17 + - `delete_file(self, file_path: str) -> bool`
18 + - `rename_item(self, file_path: str, new_name: str) -> bool`
19 + - `create_folder(self, parent_path: str, folder_name: str) -> bool`
20 + - `save_text_file(self, file_path: str, content: str) -> bool`
21 + - `get_files(self, current_path: str=...) -> Dict`
22 + - `get_full_path(self, file_path: str, allow_dir: bool=...) -> str`
23 +
24 +## Runtime Contracts
25 +
26 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
27 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
28 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, settings/state persistence.
29 +- Imported dependency areas include: `base64`, `datetime`, `helpers`, `helpers.localization`, `helpers.print_style`, `helpers.security`, `os`, `pathlib`, `shutil`, `subprocess`, `typing`.
30 +
31 +## Key Concepts
32 +
33 +- 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`.
34 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
35 +
36 +## Work Guidance
37 +
38 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
39 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
40 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
41 +
42 +## Verification
43 +
44 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
45 +- Related tests observed by source search:
46 + - `tests/test_download_toast_regressions.py`
47 + - `tests/test_office_document_store.py`
48 +
49 +## Child DOX Index
50 +
51 +No child DOX files.
helpers/file_tree.py.dox.md new
+63
@@ -0,0 +1,63 @@
1 +# file_tree.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `file_tree.py` helper module.
6 +- This module renders bounded file-tree summaries for prompts and UI surfaces.
7 +- Keep this file-level DOX profile synchronized with `file_tree.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `file_tree.py` owns the runtime implementation.
12 +- `file_tree.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `_TreeEntry` (no explicit base class)
15 + - `as_dict(self) -> dict[str, Any]`
16 +- Top-level functions:
17 +- `_from_timestamp(timestamp: float) -> datetime`
18 +- `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.
19 +- `_normalize_relative_path(path: str) -> str`
20 +- `_directory_has_visible_entries(directory: str, root_abs_path: str, ignore_spec: PathSpec, cache: dict[str, bool], max_depth_remaining: int) -> bool`
21 +- `_create_summary_comment(parent: _TreeEntry, noun: str, count: int) -> _TreeEntry`
22 +- `_create_global_limit_comment(parent: _TreeEntry, hidden_children: Sequence[_TreeEntry]) -> _TreeEntry`
23 +- `_create_folder_unprocessed_comment(folder_node: _TreeEntry, folder_path: str, abs_root: str, ignore_spec: Optional[PathSpec]) -> Optional[_TreeEntry]`
24 +- `_prune_to_visible(node: _TreeEntry, visible_ids: set[int]) -> None`
25 +- `_mark_last_flags(node: _TreeEntry) -> None`
26 +- `_refresh_render_metadata(node: _TreeEntry) -> None`
27 +- `_resolve_ignore_patterns(ignore: str | None, root_abs_path: str) -> Optional[PathSpec]`
28 +- `_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]]`
29 +- `_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]`
30 +- `_format_line(node: _TreeEntry) -> str`
31 +- `_build_tree_items_flat(items: Sequence[_TreeEntry]) -> list[dict]`
32 +- `_to_nested_structure(items: Sequence[_TreeEntry]) -> list[dict]`
33 +- `_iter_depth_first(items: Sequence[_TreeEntry]) -> Iterable[_TreeEntry]`
34 +- 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`.
35 +
36 +## Runtime Contracts
37 +
38 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
39 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
40 +- Observed side-effect areas: filesystem reads, subprocess/runtime control, WebSocket state.
41 +- Imported dependency areas include: `__future__`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.localization`, `os`, `pathspec`, `typing`.
42 +
43 +## Key Concepts
44 +
45 +- 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`.
46 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
47 +
48 +## Work Guidance
49 +
50 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
51 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
52 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
53 +
54 +## Verification
55 +
56 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
57 +- Related tests observed by source search:
58 + - `tests/test_file_tree_visualize.py`
59 + - `tests/test_skills_runtime.py`
60 +
61 +## Child DOX Index
62 +
63 +No child DOX files.
helpers/files.py.dox.md new
+82
@@ -0,0 +1,82 @@
1 +# files.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `files.py` helper module.
6 +- This module owns repository/user path helpers and file read/write/parsing primitives.
7 +- Keep this file-level DOX profile synchronized with `files.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `files.py` owns the runtime implementation.
12 +- `files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `VariablesPlugin` (`ABC`)
15 + - `get_variables(self, file: str, backup_dirs: list[str] | None=..., **kwargs) -> dict[str, Any]`
16 +- Top-level functions:
17 +- `load_plugin_variables(file: str, backup_dirs: list[str] | None=..., **kwargs) -> dict[str, Any]`
18 +- `parse_file(_filename: str, _directories: list[str] | None=..., _encoding=..., **kwargs)`
19 +- `read_prompt_file(_file: str, _directories: list[str] | None=..., _encoding=..., **kwargs)`
20 +- `evaluate_text_conditions(_content: str, **kwargs)`
21 +- `read_file(relative_path: str, encoding=...)`
22 +- `read_file_json(relative_path: str, encoding=...)`
23 +- `read_file_yaml(relative_path: str, encoding=...)`
24 +- `read_file_bin(relative_path: str)`
25 +- `read_file_base64(relative_path)`
26 +- `is_probably_binary_bytes(data: bytes, threshold: float=...) -> bool`: Binary detection.
27 +- `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.
28 +- `replace_placeholders_text(_content: str, **kwargs)`
29 +- `replace_placeholders_json(_content: str, **kwargs)`
30 +- `replace_placeholders_dict(_content: dict, **kwargs)`
31 +- `process_includes(_content: str, _directories: list[str], _source_file: str=..., _source_dir: str=..., **kwargs)`
32 +- `_get_dirs_after(_directories: list[str], _source_dir: str) -> list[str]`: Return directories after _source_dir in the priority list.
33 +- `find_file_in_dirs(_filename: str, _directories: list[str])`: This function searches for a filename in a list of directories in order.
34 +- `get_unique_filenames_in_dirs(dir_paths: list[str], pattern: str=..., type: Literal['file', 'dir', 'any']=...)`
35 +- `find_existing_paths_by_pattern(pattern: str)`
36 +- `remove_code_fences(text)`
37 +- `is_full_json_template(text)`
38 +- `write_file(relative_path: str, content: str, encoding: str=...)`
39 +- `delete_file(relative_path: str)`
40 +- `write_file_bin(relative_path: str, content: bytes)`
41 +- `write_file_base64(relative_path: str, content: str)`
42 +- `delete_dir(relative_path: str)`
43 +- `move_dir(old_path: str, new_path: str)`
44 +- `move_dir_safe(src, dst, rename_format=...)`
45 +- `create_dir_safe(dst, rename_format=...)`
46 +- `create_dir(relative_path: str)`
47 +- Notable constants/configuration names: `AGENTS_DIR`, `PLUGINS_DIR`, `PROJECTS_DIR`, `EXTENSIONS_DIR`, `USER_DIR`, `TEMP_DIR`, `API_DIR`.
48 +
49 +## Runtime Contracts
50 +
51 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
52 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
53 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, plugin state, settings/state persistence, secret handling.
54 +- Imported dependency areas include: `abc`, `base64`, `fnmatch`, `glob`, `helpers`, `helpers.strings`, `json`, `mimetypes`, `os`, `re`, `shutil`, `simpleeval`, `tempfile`, `typing`, `zipfile`.
55 +
56 +## Key Concepts
57 +
58 +- 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`.
59 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
60 +
61 +## Work Guidance
62 +
63 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
64 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
65 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
66 +
67 +## Verification
68 +
69 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
70 +- Related tests observed by source search:
71 + - `tests/test_a0_connector_prompt_gating.py`
72 + - `tests/test_browser_agent_regressions.py`
73 + - `tests/test_default_prompt_budget.py`
74 + - `tests/test_document_query_plugin.py`
75 + - `tests/test_download_toast_regressions.py`
76 + - `tests/test_file_tree_visualize.py`
77 + - `tests/test_host_browser_connector.py`
78 + - `tests/test_image_get_security.py`
79 +
80 +## Child DOX Index
81 +
82 +No child DOX files.
helpers/functions.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# functions.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `functions.py` helper module.
6 +- This module provides safe generic callable execution helpers.
7 +- Keep this file-level DOX profile synchronized with `functions.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `functions.py` owns the runtime implementation.
12 +- `functions.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `safe_call(func, *args, **kwargs)`
15 +
16 +## Runtime Contracts
17 +
18 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
19 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
20 +- Imported dependency areas include: `inspect`.
21 +
22 +## Key Concepts
23 +
24 +- Important called helpers/classes observed in the source: `inspect.signature`, `func`.
25 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
26 +
27 +## Work Guidance
28 +
29 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
30 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
31 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
32 +
33 +## Verification
34 +
35 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
36 +- Related tests observed by source search:
37 + - `tests/test_a0_connector_prompt_gating.py`
38 + - `tests/test_browser_agent_regressions.py`
39 + - `tests/test_error_retry_plugin.py`
40 + - `tests/test_oauth_codex.py`
41 + - `tests/test_oauth_providers.py`
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
helpers/git.py.dox.md new
+70
@@ -0,0 +1,70 @@
1 +# git.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `git.py` helper module.
6 +- This module reads local and remote Git release/commit metadata safely.
7 +- Keep this file-level DOX profile synchronized with `git.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `git.py` owns the runtime implementation.
12 +- `git.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `GitHeadInfo` (no explicit base class)
15 +- `GitReleaseInfo` (no explicit base class)
16 +- `GitRemoteReleaseInfo` (no explicit base class)
17 +- `GitRemoteReleasesResult` (no explicit base class)
18 +- `GitRemoteCommitsInfo` (no explicit base class)
19 +- `GitRepoReleaseInfo` (no explicit base class)
20 +- Top-level functions:
21 +- `strip_auth_from_url(url: str) -> str`: Remove any authentication info from URL.
22 +- `extract_author_repo(url: str) -> tuple[str, str]`
23 +- `_format_git_timestamp(timestamp: int) -> str`
24 +- `_split_describe_version(describe: str) -> tuple[str, int]`
25 +- `_format_release_version(branch: str, short_tag: str, commits_since_tag: int, commit_hash: str) -> str`
26 +- `get_remote_releases(author: str, repo: str) -> GitRemoteReleasesResult`
27 +- `get_remote_commits_since_local(repo_path: str) -> GitRemoteCommitsInfo`
28 +- `get_repo_release_info(repo_path: str) -> GitRepoReleaseInfo`
29 +- `get_git_info()`
30 +- `get_version()`
31 +- `is_official_agent_zero_repo() -> bool`: Return True when origin points to agent0ai/agent-zero.
32 +- `clone_repo(url: str, dest: str, token: str | None=...)`: Clone a git repository. Uses http.extraHeader for token auth (never stored in URL/config).
33 +- `update_repo(repo_path: str) -> Repo`
34 +- `get_repo_status(repo_path: str) -> dict`: Get Git repository status, ignoring A0 project metadata files.
35 +- Notable constants/configuration names: `A0_IGNORE_PATTERNS`.
36 +
37 +## Runtime Contracts
38 +
39 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
40 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
41 +- Observed side-effect areas: filesystem writes, filesystem deletion, network calls, subprocess/runtime control, plugin state, settings/state persistence, secret handling.
42 +- Imported dependency areas include: `base64`, `dataclasses`, `datetime`, `git`, `giturlparse`, `helpers`, `helpers.localization`, `os`, `re`, `subprocess`, `urllib.parse`.
43 +
44 +## Key Concepts
45 +
46 +- 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`.
47 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
48 +
49 +## Work Guidance
50 +
51 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
52 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
53 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
54 +
55 +## Verification
56 +
57 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
58 +- Related tests observed by source search:
59 + - `tests/test_docker_release_plan.py`
60 + - `tests/test_git_version_label.py`
61 + - `tests/test_model_config_api_keys.py`
62 + - `tests/test_model_config_project_presets.py`
63 + - `tests/test_model_search.py`
64 + - `tests/test_oauth_github_copilot.py`
65 + - `tests/test_oauth_providers.py`
66 + - `tests/test_onboarding_static.py`
67 +
68 +## Child DOX Index
69 +
70 +No child DOX files.
helpers/guids.py.dox.md new
+40
@@ -0,0 +1,40 @@
1 +# guids.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `guids.py` helper module.
6 +- This module generates framework IDs.
7 +- Keep this file-level DOX profile synchronized with `guids.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `guids.py` owns the runtime implementation.
12 +- `guids.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `generate_id(length: int=...) -> str`
15 +
16 +## Runtime Contracts
17 +
18 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
19 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
20 +- Imported dependency areas include: `random`, `string`.
21 +
22 +## Key Concepts
23 +
24 +- Important called helpers/classes observed in the source: `join`, `random.choices`.
25 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
26 +
27 +## Work Guidance
28 +
29 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
30 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
31 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
32 +
33 +## Verification
34 +
35 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
36 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
37 +
38 +## Child DOX Index
39 +
40 +No child DOX files.
helpers/history.py.dox.md new
+109
@@ -0,0 +1,109 @@
1 +# history.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `history.py` helper module.
6 +- This module owns chat history message records and model-output conversion.
7 +- Keep this file-level DOX profile synchronized with `history.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `history.py` owns the runtime implementation.
12 +- `history.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `RawMessage` (`TypedDict`)
15 +- `OutputMessage` (`TypedDict`)
16 +- `Record` (no explicit base class)
17 + - `get_tokens(self) -> int`
18 + - `async compress(self) -> bool`
19 + - `output(self) -> list[OutputMessage]`
20 + - `async summarize(self) -> str`
21 + - `to_dict(self) -> dict`
22 + - `from_dict(data: dict, history: 'History')`
23 + - `output_langchain(self)`
24 + - `output_text(self, human_label=..., ai_label=...)`
25 +- `Message` (`Record`)
26 + - `get_tokens(self) -> int`
27 + - `calculate_tokens(self)`
28 + - `set_summary(self, summary: str)`
29 + - `async compress(self)`
30 + - `output(self)`
31 + - `output_langchain(self)`
32 + - `output_text(self, human_label=..., ai_label=...)`
33 + - `to_dict(self)`
34 +- `Topic` (`Record`)
35 + - `get_tokens(self)`
36 + - `add_message(self, ai: bool, content: MessageContent, tokens: int=..., id: str=...) -> Message`
37 + - `output(self) -> list[OutputMessage]`
38 + - `async summarize(self)`
39 + - `compress_large_messages(self, message_ratio: float=...) -> bool`
40 + - `async compress(self) -> bool`
41 + - `async compress_attention(self, ratio: float=...) -> bool`
42 + - `async summarize_messages(self, messages: list[Message])`
43 +- `Bulk` (`Record`)
44 + - `get_tokens(self)`
45 + - `output(self, human_label: str=..., ai_label: str=...) -> list[OutputMessage]`
46 + - `async compress(self)`
47 + - `async summarize(self)`
48 + - `to_dict(self)`
49 + - `from_dict(data: dict, history: 'History')`
50 +- `History` (`Record`)
51 + - `get_tokens(self) -> int`
52 + - `is_over_limit(self)`
53 + - `get_bulks_tokens(self) -> int`
54 + - `get_topics_tokens(self) -> int`
55 + - `get_current_topic_tokens(self) -> int`
56 + - `add_message(self, ai: bool, content: MessageContent, tokens: int=..., id: str=...) -> Message`
57 + - `new_topic(self)`
58 + - `output(self) -> list[OutputMessage]`
59 +- Top-level functions:
60 +- `deserialize_history(json_data: str, agent) -> History`
61 +- `_stringify_output(output: OutputMessage, ai_label=..., human_label=...)`
62 +- `_stringify_content(content: MessageContent) -> str`
63 +- `_output_content_langchain(content: MessageContent)`
64 +- `group_outputs_abab(outputs: list[OutputMessage]) -> list[OutputMessage]`
65 +- `group_messages_abab(messages: list[BaseMessage]) -> list[BaseMessage]`
66 +- `output_langchain(messages: list[OutputMessage])`
67 +- `output_text(messages: list[OutputMessage], ai_label=..., human_label=...)`
68 +- `_merge_outputs(a: MessageContent, b: MessageContent) -> MessageContent`
69 +- `_merge_properties(a: Dict[str, MessageContent], b: Dict[str, MessageContent]) -> Dict[str, MessageContent]`
70 +- `_is_raw_message(obj: object) -> bool`
71 +- `_is_embedded_data(obj: object) -> bool`
72 +- `_json_dumps(obj)`
73 +- `_json_loads(obj)`
74 +- 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`.
75 +
76 +## Runtime Contracts
77 +
78 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
79 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
80 +- Observed side-effect areas: filesystem writes, filesystem deletion, model calls, plugin state, settings/state persistence, secret handling.
81 +- Imported dependency areas include: `abc`, `asyncio`, `collections`, `collections.abc`, `enum`, `helpers`, `json`, `langchain_core.messages`, `math`, `plugins._model_config.helpers.model_config`, `typing`, `uuid`.
82 +
83 +## Key Concepts
84 +
85 +- 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`.
86 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
87 +
88 +## Work Guidance
89 +
90 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
91 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
92 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
93 +
94 +## Verification
95 +
96 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
97 +- Related tests observed by source search:
98 + - `tests/test_browser_agent_regressions.py`
99 + - `tests/test_chat_compaction.py`
100 + - `tests/test_error_retry_plugin.py`
101 + - `tests/test_history_compression_wait.py`
102 + - `tests/test_mcp_handler_multimodal.py`
103 + - `tests/test_memory_quality.py`
104 + - `tests/test_model_config_project_presets.py`
105 + - `tests/test_office_document_store.py`
106 +
107 +## Child DOX Index
108 +
109 +No child DOX files.
helpers/images.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# images.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `images.py` helper module.
6 +- This module resolves, compresses, and serializes image references for model inputs.
7 +- Keep this file-level DOX profile synchronized with `images.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `images.py` owns the runtime implementation.
12 +- `images.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `prepare_content(content: Any) -> Any`
15 +- `is_local_ref(url: str) -> bool`
16 +- `to_data_url(url: str) -> str`
17 +- `resolve_ref(url: str) -> Path`
18 +- `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.
19 +
20 +## Runtime Contracts
21 +
22 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
23 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
24 +- Observed side-effect areas: filesystem reads, network calls, settings/state persistence.
25 +- Imported dependency areas include: `PIL`, `base64`, `io`, `math`, `mimetypes`, `pathlib`, `typing`, `urllib.parse`.
26 +
27 +## Key Concepts
28 +
29 +- 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`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
35 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
36 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
37 +
38 +## Verification
39 +
40 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
41 +- Related tests observed by source search:
42 + - `tests/test_browser_agent_regressions.py`
43 + - `tests/test_image_get_security.py`
44 + - `tests/test_vision_load_image_refs.py`
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
helpers/integration_commands.py.dox.md new
+53
@@ -0,0 +1,53 @@
1 +# integration_commands.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `integration_commands.py` helper module.
6 +- This module parses external integration slash commands such as project/config/send controls.
7 +- Keep this file-level DOX profile synchronized with `integration_commands.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `integration_commands.py` owns the runtime implementation.
12 +- `integration_commands.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `extract_command_line(text: str) -> str`
15 +- `parse_command(text: str) -> tuple[str, str] | None`
16 +- `try_handle_command(context: 'AgentContext', text: str) -> str | None`
17 +- `_handle_queue(context: 'AgentContext', args: str) -> str`
18 +- `_handle_project(context: 'AgentContext', args: str) -> str`
19 +- `_handle_config(context: 'AgentContext', args: str) -> str`
20 +- `_format_project_entry(item: dict) -> str`
21 +- `_describe_project(items: list[dict], current_name: str) -> str`
22 +- `_describe_override(override: dict | None) -> str`
23 +- `_strip_quotes(value: str) -> str`
24 +- `_normalize_lookup(value: str) -> str`
25 +- `_match_named_item(items: list[dict], desired: str, keys: tuple[str, ...]) -> tuple[dict | None, list[dict]]`
26 +- Notable constants/configuration names: `_CLEAR_VALUES`, `_SUPPORTED_COMMANDS`.
27 +
28 +## Runtime Contracts
29 +
30 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
31 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
32 +- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence.
33 +- Imported dependency areas include: `__future__`, `helpers`, `helpers.persist_chat`, `helpers.state_monitor_integration`, `plugins._model_config.helpers`, `re`, `typing`.
34 +
35 +## Key Concepts
36 +
37 +- 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`.
38 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
39 +
40 +## Work Guidance
41 +
42 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
43 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
44 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
45 +
46 +## Verification
47 +
48 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
49 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
50 +
51 +## Child DOX Index
52 +
53 +No child DOX files.
helpers/job_loop.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# job_loop.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `job_loop.py` helper module.
6 +- This module runs periodic scheduler and maintenance loops.
7 +- Keep this file-level DOX profile synchronized with `job_loop.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `job_loop.py` owns the runtime implementation.
12 +- `job_loop.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `async run_loop()`
15 +- `async scheduler_tick()`
16 +- `pause_loop()`
17 +- `resume_loop()`
18 +- Notable constants/configuration names: `SLEEP_TIME`.
19 +
20 +## Runtime Contracts
21 +
22 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
23 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
24 +- Observed side-effect areas: scheduler state.
25 +- Imported dependency areas include: `asyncio`, `datetime`, `helpers`, `helpers.print_style`, `helpers.task_scheduler`, `time`.
26 +
27 +## Key Concepts
28 +
29 +- 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`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
35 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
36 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
37 +
38 +## Verification
39 +
40 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
41 +- Related tests observed by source search:
42 + - `tests/test_api_chat_lifetime.py`
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
helpers/kvp.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# kvp.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `kvp.py` helper module.
6 +- This module provides runtime and persistent key-value storage helpers.
7 +- Keep this file-level DOX profile synchronized with `kvp.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `kvp.py` owns the runtime implementation.
12 +- `kvp.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `_persistent_dir() -> str`
15 +- `_validate_key(key: str) -> None`
16 +- `_key_to_path(key: str) -> str`
17 +- `get_runtime(key: str, default: Any=...) -> Any`
18 +- `set_runtime(key: str, value: Any) -> None`
19 +- `remove_runtime(key: str) -> None`
20 +- `find_runtime(pattern: str) -> list[str]`
21 +- `get_persistent(key: str, default: Any=...) -> Any`
22 +- `set_persistent(key: str, value: Any) -> None`
23 +- `remove_persistent(key: str) -> None`
24 +- `find_persistent(pattern: str) -> list[str]`
25 +
26 +## Runtime Contracts
27 +
28 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
29 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
30 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence.
31 +- Imported dependency areas include: `fnmatch`, `glob`, `helpers.files`, `json`, `os`, `tempfile`, `threading`, `typing`.
32 +
33 +## Key Concepts
34 +
35 +- 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`.
36 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
37 +
38 +## Work Guidance
39 +
40 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
41 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
42 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
43 +
44 +## Verification
45 +
46 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
47 +- Related tests observed by source search:
48 + - `tests/test_browser_agent_regressions.py`
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
helpers/localization.py.dox.md new
+50
@@ -0,0 +1,50 @@
1 +# localization.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `localization.py` helper module.
6 +- This module loads and resolves localized UI/application text.
7 +- Keep this file-level DOX profile synchronized with `localization.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `localization.py` owns the runtime implementation.
12 +- `localization.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Localization` (no explicit base class)
15 + - `get(cls, *args, **kwargs)`
16 + - `get_timezone(self) -> str`
17 + - `get_tzinfo(self)`
18 + - `get_offset_minutes(self) -> int`
19 + - `apply_process_timezone(self) -> None`
20 + - `now(self) -> datetime`
21 + - `now_iso(self, sep: str=..., timespec: str=...) -> str`
22 + - `localize_naive_datetime(self, dt: datetime) -> datetime`
23 +
24 +## Runtime Contracts
25 +
26 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
27 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
28 +- Observed side-effect areas: filesystem writes, settings/state persistence.
29 +- Imported dependency areas include: `datetime`, `helpers.dotenv`, `helpers.print_style`, `os`, `pytz`, `time`.
30 +
31 +## Key Concepts
32 +
33 +- 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`.
34 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
35 +
36 +## Work Guidance
37 +
38 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
39 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
40 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
41 +
42 +## Verification
43 +
44 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
45 +- Related tests observed by source search:
46 + - `tests/test_timezone_regressions.py`
47 +
48 +## Child DOX Index
49 +
50 +No child DOX files.
helpers/log.py.dox.md new
+68
@@ -0,0 +1,68 @@
1 +# log.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `log.py` helper module.
6 +- This module owns chat log items, outputs, truncation, and dirty-state integration.
7 +- Keep this file-level DOX profile synchronized with `log.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `log.py` owns the runtime implementation.
12 +- `log.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `LogItem` (no explicit base class)
15 + - `update(self, type: Type | None=..., heading: str | None=..., content: str | None=..., kvps: dict | None=..., update_progress: ProgressUpdate | None=..., **kwargs)`
16 + - `stream(self, heading: str | None=..., content: str | None=..., **kwargs)`
17 + - `output(self)`
18 +- `LogOutput` (no explicit base class)
19 +- `Log` (no explicit base class)
20 + - `log(self, type: Type, heading: str | None=..., content: str | None=..., kvps: dict | None=..., update_progress: ProgressUpdate | None=..., id: Optional[str]=..., **kwargs) -> LogItem`
21 + - `set_progress(self, progress: str, no: int=..., active: bool=...)`
22 + - `set_initial_progress(self)`
23 + - `output(self, start=..., end=...)`
24 + - `reset(self)`
25 +- Top-level functions:
26 +- `_lazy_mark_dirty_all(reason: str | None=...) -> None`
27 +- `_lazy_mark_dirty_for_context(context_id: str, reason: str | None=...) -> None`
28 +- `_truncate_heading(text: str | None) -> str`
29 +- `_truncate_progress(text: str | None) -> str`
30 +- `_truncate_key(text: str) -> str`
31 +- `_truncate_value(val: T) -> T`
32 +- `_truncate_content(text: str | None, type: Type) -> str`
33 +- 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`.
34 +
35 +## Runtime Contracts
36 +
37 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
38 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
39 +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
40 +- Imported dependency areas include: `collections`, `copy`, `dataclasses`, `helpers.secrets`, `helpers.strings`, `json`, `threading`, `time`, `typing`, `uuid`.
41 +
42 +## Key Concepts
43 +
44 +- 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`.
45 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
46 +
47 +## Work Guidance
48 +
49 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
50 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
51 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
52 +
53 +## Verification
54 +
55 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
56 +- Related tests observed by source search:
57 + - `tests/test_browser_agent_regressions.py`
58 + - `tests/test_chat_compaction.py`
59 + - `tests/test_error_retry_plugin.py`
60 + - `tests/test_fasta2a_client.py`
61 + - `tests/test_file_tree_visualize.py`
62 + - `tests/test_history_compression_wait.py`
63 + - `tests/test_http_auth_csrf.py`
64 + - `tests/test_mcp_handler_multimodal.py`
65 +
66 +## Child DOX Index
67 +
68 +No child DOX files.
helpers/login.py.dox.md new
+49
@@ -0,0 +1,49 @@
1 +# login.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `login.py` helper module.
6 +- This module checks login requirements and credential hashes.
7 +- Keep this file-level DOX profile synchronized with `login.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `login.py` owns the runtime implementation.
12 +- `login.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `get_credentials_hash()`
15 +- `is_login_required()`
16 +
17 +## Runtime Contracts
18 +
19 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
20 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
21 +- Observed side-effect areas: secret handling.
22 +- Imported dependency areas include: `hashlib`, `helpers`.
23 +
24 +## Key Concepts
25 +
26 +- Important called helpers/classes observed in the source: `dotenv.get_dotenv_value`, `hashlib.sha256.hexdigest`, `hashlib.sha256`, `encode`.
27 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
28 +
29 +## Work Guidance
30 +
31 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
32 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
33 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
34 +
35 +## Verification
36 +
37 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
38 +- Related tests observed by source search:
39 + - `tests/test_http_auth_csrf.py`
40 + - `tests/test_oauth_gemini_api.py`
41 + - `tests/test_oauth_github_copilot.py`
42 + - `tests/test_oauth_providers.py`
43 + - `tests/test_oauth_xai_grok.py`
44 + - `tests/test_tunnel_remote_link.py`
45 + - `tests/test_ws_security.py`
46 +
47 +## Child DOX Index
48 +
49 +No child DOX files.
helpers/mcp_handler.py.dox.md new
+90
@@ -0,0 +1,90 @@
1 +# mcp_handler.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `mcp_handler.py` helper module.
6 +- This module loads MCP server configuration and exposes MCP tools to agents.
7 +- Keep this file-level DOX profile synchronized with `mcp_handler.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `mcp_handler.py` owns the runtime implementation.
12 +- `mcp_handler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `MCPTool` (`Tool`)
15 + - `get_log_object(self) -> LogItem`
16 + - `async execute(self, **kwargs)`
17 + - `async before_execution(self, **kwargs)`
18 + - `async after_execution(self, response: Response, **kwargs)`
19 +- `MCPServerRemote` (`BaseModel`)
20 + - `get_error(self) -> str`
21 + - `get_log(self) -> str`
22 + - `get_tools(self) -> List[dict[str, Any]]`
23 + - `has_tool(self, tool_name: str) -> bool`
24 + - `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult`
25 + - `update(self, config: dict[str, Any]) -> 'MCPServerRemote'`
26 + - `async initialize(self) -> 'MCPServerRemote'`
27 +- `MCPServerLocal` (`BaseModel`)
28 + - `get_error(self) -> str`
29 + - `get_log(self) -> str`
30 + - `get_tools(self) -> List[dict[str, Any]]`
31 + - `has_tool(self, tool_name: str) -> bool`
32 + - `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult`
33 + - `update(self, config: dict[str, Any]) -> 'MCPServerLocal'`
34 + - `async initialize(self) -> 'MCPServerLocal'`
35 +- `MCPConfig` (`BaseModel`)
36 + - `get_instance(cls) -> 'MCPConfig'`
37 + - `wait_for_lock(cls)`
38 + - `update(cls, config_str: str) -> Any`
39 + - `normalize_config(cls, servers: Any)`
40 + - `get_server_log(self, server_name: str) -> str`
41 + - `get_servers_status(self) -> list[dict[str, Any]]`
42 + - `get_server_detail(self, server_name: str) -> dict[str, Any]`
43 + - `is_initialized(self) -> bool`
44 +- `MCPClientBase` (`ABC`)
45 + - `async update_tools(self) -> 'MCPClientBase'`
46 + - `has_tool(self, tool_name: str) -> bool`
47 + - `get_tools(self) -> List[dict[str, Any]]`
48 + - `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult`
49 + - `get_log(self)`
50 +- `MCPClientLocal` (`MCPClientBase`)
51 +- `CustomHTTPClientFactory` (`ABC`)
52 +- `MCPClientRemote` (`MCPClientBase`)
53 + - `get_session_id(self) -> Optional[str]`
54 +- Top-level functions:
55 +- `_mcp_get(item: Any, key: str, default: Any=...) -> Any`
56 +- `normalize_name(name: str) -> str`
57 +- `_determine_server_type(config_dict: dict) -> str`: Determine the server type based on configuration, with backward compatibility.
58 +- `_is_streaming_http_type(server_type: str) -> bool`: Check if the server type is a streaming HTTP variant.
59 +- `initialize_mcp(mcp_servers_config: str)`
60 +- Notable constants/configuration names: `MCP_MEDIA_TOKENS_ESTIMATE`, `MAX_MCP_RESOURCE_TEXT_CHARS`, `T`.
61 +
62 +## Runtime Contracts
63 +
64 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
65 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
66 +- `MCPTool` is a `Tool`.
67 +- `MCPTool` defines `execute(...)`.
68 +- Observed side-effect areas: filesystem writes, network calls, WebSocket state, settings/state persistence, secret handling.
69 +- 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`.
70 +
71 +## Key Concepts
72 +
73 +- 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`.
74 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
75 +
76 +## Work Guidance
77 +
78 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
79 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
80 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
81 +
82 +## Verification
83 +
84 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
85 +- Related tests observed by source search:
86 + - `tests/test_mcp_handler_multimodal.py`
87 +
88 +## Child DOX Index
89 +
90 +No child DOX files.
helpers/mcp_server.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# mcp_server.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `mcp_server.py` helper module.
6 +- This module serves Agent Zero chats through a dynamic MCP proxy.
7 +- Keep this file-level DOX profile synchronized with `mcp_server.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `mcp_server.py` owns the runtime implementation.
12 +- `mcp_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ToolResponse` (`BaseModel`)
15 +- `ToolError` (`BaseModel`)
16 +- `DynamicMcpProxy` (no explicit base class)
17 + - `get_instance()`
18 + - `reconfigure(self, token: str)`
19 +- Top-level functions:
20 +- `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')]`
21 +- `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')]`
22 +- `async _run_chat(context: AgentContext, message: str, attachments: list[str] | None=...)`
23 +- `async mcp_middleware(request: Request, call_next)`: Middleware to check if MCP server is enabled.
24 +- Notable constants/configuration names: `_PRINTER`, `SEND_MESSAGE_DESCRIPTION`, `FINISH_CHAT_DESCRIPTION`.
25 +
26 +## Runtime Contracts
27 +
28 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
29 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
30 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, settings/state persistence, secret handling, scheduler state.
31 +- 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`.
32 +
33 +## Key Concepts
34 +
35 +- 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`.
36 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
37 +
38 +## Work Guidance
39 +
40 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
41 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
42 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
43 +
44 +## Verification
45 +
46 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
47 +- Related tests observed by source search:
48 + - `tests/test_default_prompt_budget.py`
49 + - `tests/test_fasta2a_client.py`
50 + - `tests/test_ws_security.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
helpers/media_artifacts.py.dox.md new
+60
@@ -0,0 +1,60 @@
1 +# media_artifacts.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `media_artifacts.py` helper module.
6 +- This module validates, decodes, names, and normalizes media artifact payloads.
7 +- Keep this file-level DOX profile synchronized with `media_artifacts.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `media_artifacts.py` owns the runtime implementation.
12 +- `media_artifacts.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `MediaArtifactError` (`ValueError`)
15 +- `EmptyBase64Data` (`MediaArtifactError`)
16 +- `InvalidBase64Data` (`MediaArtifactError`)
17 +- `ArtifactTooLarge` (`MediaArtifactError`)
18 +- `Base64Payload` (no explicit base class)
19 +- `ImageDataUrl` (no explicit base class)
20 +- `SavedArtifact` (no explicit base class)
21 +- Top-level functions:
22 +- `compact_base64(data: str) -> str`
23 +- `estimated_base64_decoded_size(data: str) -> int`
24 +- `decode_base64_payload(data: str, max_bytes: int | None=...) -> Base64Payload`
25 +- `normalize_mime(mime_type: str, default: str=..., required_prefix: str=...) -> str`
26 +- `guess_extension(mime_type: str, fallback: str=...) -> str`
27 +- `filename_from_uri(uri: str) -> str`
28 +- `safe_filename(value: str, default: str=..., default_extension: str=...) -> str`
29 +- `image_data_url_from_base64(data: str, mime_type: str=..., max_bytes: int | None=...) -> ImageDataUrl`
30 +- `save_base64_artifact(data: str, mime_type: str=..., directory_parts: tuple[str, ...], preferred_name: str=..., default_filename: str=..., max_bytes: int | None=...) -> SavedArtifact`
31 +- Notable constants/configuration names: `DEFAULT_MAX_ARTIFACT_SIZE_BYTES`.
32 +
33 +## Runtime Contracts
34 +
35 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
36 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
37 +- Observed side-effect areas: filesystem reads, filesystem writes, network calls.
38 +- Imported dependency areas include: `__future__`, `base64`, `binascii`, `dataclasses`, `helpers`, `mimetypes`, `pathlib`, `urllib.parse`, `uuid`.
39 +
40 +## Key Concepts
41 +
42 +- 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`.
43 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
44 +
45 +## Work Guidance
46 +
47 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
48 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
49 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
50 +
51 +## Verification
52 +
53 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
54 +- Related tests observed by source search:
55 + - `tests/test_mcp_handler_multimodal.py`
56 + - `tests/test_media_artifacts.py`
57 +
58 +## Child DOX Index
59 +
60 +No child DOX files.
helpers/message_queue.py.dox.md new
+53
@@ -0,0 +1,53 @@
1 +# message_queue.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `message_queue.py` helper module.
6 +- This module stores and drains queued user messages for a context.
7 +- Keep this file-level DOX profile synchronized with `message_queue.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `message_queue.py` owns the runtime implementation.
12 +- `message_queue.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `get_queue(context: 'AgentContext') -> list`: Get current queue from context.data.
15 +- `_get_next_seq(context: 'AgentContext') -> int`: Get next sequence number.
16 +- `_sync_output(context: 'AgentContext')`: Sync queue to output_data for frontend polling.
17 +- `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.
18 +- `remove(context: 'AgentContext', item_id: str | None=...) -> int`: Remove item(s). If item_id is None, clears all. Returns remaining count.
19 +- `pop_first(context: 'AgentContext') -> dict | None`: Remove and return first item.
20 +- `pop_item(context: 'AgentContext', item_id: str) -> dict | None`: Remove and return specific item.
21 +- `has_queue(context: 'AgentContext') -> bool`: Check if queue has items.
22 +- `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.
23 +- `send_message(context: 'AgentContext', item: dict, source: str=...)`: Send a single queued message (log + communicate).
24 +- `send_next(context: 'AgentContext') -> bool`: Send next queued message. Returns True if sent, False if queue empty.
25 +- `send_all_aggregated(context: 'AgentContext') -> int`: Aggregate and send all queued messages as one. Returns count of items sent.
26 +- Notable constants/configuration names: `QUEUE_KEY`, `QUEUE_SEQ_KEY`, `UPLOAD_FOLDER`.
27 +
28 +## Runtime Contracts
29 +
30 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
31 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
32 +- Observed side-effect areas: filesystem reads, filesystem deletion, settings/state persistence.
33 +- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `typing`, `uuid`.
34 +
35 +## Key Concepts
36 +
37 +- 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`.
38 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
39 +
40 +## Work Guidance
41 +
42 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
43 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
44 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
45 +
46 +## Verification
47 +
48 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
49 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
50 +
51 +## Child DOX Index
52 +
53 +No child DOX files.
helpers/messages.py.dox.md new
+50
@@ -0,0 +1,50 @@
1 +# messages.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `messages.py` helper module.
6 +- This module truncates message payloads for display and storage safety.
7 +- Keep this file-level DOX profile synchronized with `messages.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `messages.py` owns the runtime implementation.
12 +- `messages.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `truncate_text(agent, output, threshold=...)`
15 +- `truncate_dict_by_ratio(agent, data: dict | list | str, threshold_chars: int, truncate_to: int)`
16 +
17 +## Runtime Contracts
18 +
19 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
20 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
21 +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence.
22 +- Imported dependency areas include: `json`.
23 +
24 +## Key Concepts
25 +
26 +- Important called helpers/classes observed in the source: `agent.read_prompt`, `process_item`, `json.dumps`, `truncate_text`.
27 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
28 +
29 +## Work Guidance
30 +
31 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
32 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
33 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
34 +
35 +## Verification
36 +
37 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
38 +- Related tests observed by source search:
39 + - `tests/email_parser_test.py`
40 + - `tests/test_browser_agent_regressions.py`
41 + - `tests/test_chat_compaction.py`
42 + - `tests/test_document_query_fallback.py`
43 + - `tests/test_download_toast_regressions.py`
44 + - `tests/test_fasta2a_client.py`
45 + - `tests/test_mcp_handler_multimodal.py`
46 + - `tests/test_oauth_codex.py`
47 +
48 +## Child DOX Index
49 +
50 +No child DOX files.
helpers/microsoft_tunnel.py.dox.md new
+50
@@ -0,0 +1,50 @@
1 +# microsoft_tunnel.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `microsoft_tunnel.py` helper module.
6 +- This module implements Microsoft Dev Tunnel provider behavior.
7 +- Keep this file-level DOX profile synchronized with `microsoft_tunnel.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `microsoft_tunnel.py` owns the runtime implementation.
12 +- `microsoft_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `AgentZeroMicrosoftTunnel` (`MicrosoftTunnel`)
15 + - `notify(self, event, message, data=...)`
16 + - `agent_zero_notifications(self)`
17 +- `MicrosoftDevTunnel` (`FlaredanticTunnelHelper`)
18 + - `build_tunnel(self)`
19 + - `start(self)`
20 +- Top-level functions:
21 +- `default_microsoft_tunnel_id()`
22 +- Notable constants/configuration names: `MICROSOFT_TUNNEL_ID_ENV_KEYS`, `MICROSOFT_TUNNEL_TIMEOUT`.
23 +
24 +## Runtime Contracts
25 +
26 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
27 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
28 +- Observed side-effect areas: filesystem reads, network calls, settings/state persistence, tunnel state.
29 +- Imported dependency areas include: `flaredantic`, `getpass`, `hashlib`, `helpers`, `helpers.tunnel_common`, `os`, `socket`.
30 +
31 +## Key Concepts
32 +
33 +- 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`.
34 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
35 +
36 +## Work Guidance
37 +
38 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
39 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
40 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
41 +
42 +## Verification
43 +
44 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
45 +- Related tests observed by source search:
46 + - `tests/test_tunnel_remote_link.py`
47 +
48 +## Child DOX Index
49 +
50 +No child DOX files.
helpers/migration.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# migration.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `migration.py` helper module.
6 +- This module migrates legacy user data and runtime layout at startup.
7 +- Keep this file-level DOX profile synchronized with `migration.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `migration.py` owns the runtime implementation.
12 +- `migration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `startup_migration() -> None`
15 +- `migrate_user_data() -> None`: Migrate user data from /tmp and other locations to /usr.
16 +- `convert_agents_json_yaml() -> None`
17 +- `_move_dir(src: str, dst: str, overwrite: bool=...) -> None`: Move a directory from src to dst if src exists and dst does not.
18 +- `_move_file(src: str, dst: str, overwrite: bool=...) -> None`: Move a file from src to dst if src exists and dst does not.
19 +- `_migrate_memory(base_path: str=...) -> None`: Migrate memory subdirectories.
20 +- `_merge_dir_contents(src_parent: str, dst_parent: str) -> None`: Moves all items from src_parent to dst_parent.
21 +- `_cleanup_obsolete() -> None`: Remove directories that are no longer needed.
22 +
23 +## Runtime Contracts
24 +
25 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
26 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
27 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
28 +- Imported dependency areas include: `helpers`, `helpers.print_style`, `json`, `os`.
29 +
30 +## Key Concepts
31 +
32 +- 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`.
33 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
34 +
35 +## Work Guidance
36 +
37 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
38 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
39 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
40 +
41 +## Verification
42 +
43 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
44 +- Related tests observed by source search:
45 + - `tests/test_browser_agent_regressions.py`
46 + - `tests/test_office_canvas_setup.py`
47 + - `tests/test_office_document_store.py`
48 + - `tests/test_speech_plugin_split.py`
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
helpers/modules.py.dox.md new
+53
@@ -0,0 +1,53 @@
1 +# modules.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `modules.py` helper module.
6 +- This module imports modules and classes dynamically with namespace cache control.
7 +- Keep this file-level DOX profile synchronized with `modules.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `modules.py` owns the runtime implementation.
12 +- `modules.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `import_module(file_path: str) -> ModuleType`
15 +- `load_classes_from_folder(folder: str, name_pattern: str, base_class: Type[T], one_per_file: bool=...) -> list[Type[T]]`
16 +- `load_classes_from_file(file: str, base_class: type[T], one_per_file: bool=...) -> list[type[T]]`
17 +- `purge_namespace(namespace: str)`
18 +- Notable constants/configuration names: `T`.
19 +
20 +## Runtime Contracts
21 +
22 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
23 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
24 +- Observed side-effect areas: filesystem reads, filesystem deletion.
25 +- Imported dependency areas include: `fnmatch`, `helpers.files`, `importlib`, `importlib.util`, `inspect`, `os`, `re`, `sys`, `types`, `typing`.
26 +
27 +## Key Concepts
28 +
29 +- 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`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
35 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
36 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
37 +
38 +## Verification
39 +
40 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
41 +- Related tests observed by source search:
42 + - `tests/test_a0_connector_prompt_gating.py`
43 + - `tests/test_browser_agent_regressions.py`
44 + - `tests/test_docker_release_plan.py`
45 + - `tests/test_error_retry_plugin.py`
46 + - `tests/test_file_tree_visualize.py`
47 + - `tests/test_git_version_label.py`
48 + - `tests/test_mcp_handler_multimodal.py`
49 + - `tests/test_memory_quality.py`
50 +
51 +## Child DOX Index
52 +
53 +No child DOX files.
helpers/network.py.dox.md new
+55
@@ -0,0 +1,55 @@
1 +# network.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `network.py` helper module.
6 +- This module validates public URLs and fetches remote resources safely.
7 +- Keep this file-level DOX profile synchronized with `network.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `network.py` owns the runtime implementation.
12 +- `network.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `HttpFetchResult` (no explicit base class)
15 +- `UnsafeUrlError` (`ValueError`)
16 +- Top-level functions:
17 +- `_build_request_headers() -> dict[str, str]`
18 +- `_normalize_content_type(content_type: str | None) -> str | None`
19 +- `resolve_host_ips(hostname: str) -> tuple[ipaddress._BaseAddress, ...]`
20 +- `validate_public_http_url(url: str) -> tuple[ipaddress._BaseAddress, ...]`
21 +- `fetch_public_http_resource(url: str, max_bytes: int, max_redirects: int=..., timeout: tuple[float, float]=...) -> HttpFetchResult`
22 +- `is_loopback_address(address: str) -> bool`: Check whether *address* resolves to a loopback interface.
23 +- Notable constants/configuration names: `SAFE_HTTP_SCHEMES`, `DEFAULT_FETCH_TIMEOUT`, `DEFAULT_HTTP_USER_AGENT`.
24 +
25 +## Runtime Contracts
26 +
27 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
28 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
29 +- Observed side-effect areas: network calls, secret handling.
30 +- Imported dependency areas include: `__future__`, `dataclasses`, `ipaddress`, `os`, `requests`, `socket`, `struct`, `urllib.parse`.
31 +
32 +## Key Concepts
33 +
34 +- 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`.
35 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
36 +
37 +## Work Guidance
38 +
39 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
40 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
41 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
42 +
43 +## Verification
44 +
45 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
46 +- Related tests observed by source search:
47 + - `tests/test_oauth_gemini_api.py`
48 + - `tests/test_oauth_github_copilot.py`
49 + - `tests/test_oauth_xai_grok.py`
50 + - `tests/test_plugin_scan_prompt.py`
51 + - `tests/test_tunnel_remote_link.py`
52 +
53 +## Child DOX Index
54 +
55 +No child DOX files.
helpers/notification.py.dox.md new
+62
@@ -0,0 +1,62 @@
1 +# notification.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `notification.py` helper module.
6 +- This module owns notification data models and notification manager state.
7 +- Keep this file-level DOX profile synchronized with `notification.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `notification.py` owns the runtime implementation.
12 +- `notification.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `NotificationType` (`Enum`)
15 +- `NotificationPriority` (`Enum`)
16 +- `NotificationItem` (no explicit base class)
17 + - `mark_read(self)`
18 + - `output(self)`
19 +- `NotificationManager` (no explicit base class)
20 + - `send_notification(type: NotificationType, priority: NotificationPriority, message: str, title: str=..., detail: str=..., display_time: int=..., group: str=..., id: str=...) -> NotificationItem`
21 + - `add_notification(self, type: NotificationType, priority: NotificationPriority, message: str, title: str=..., detail: str=..., display_time: int=..., group: str=..., id: str=...) -> NotificationItem`
22 + - `get_recent_notifications(self, seconds: int=...) -> list[NotificationItem]`
23 + - `output(self, start: int | None=..., end: int | None=...) -> list[dict]`
24 + - `output_all(self) -> list[dict]`
25 + - `mark_read_by_ids(self, notification_ids: list[str]) -> int`
26 + - `update_item(self, no: int, **kwargs) -> None`
27 + - `mark_all_read(self)`
28 +
29 +## Runtime Contracts
30 +
31 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
32 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
33 +- Observed side-effect areas: filesystem deletion, settings/state persistence.
34 +- Imported dependency areas include: `dataclasses`, `datetime`, `enum`, `helpers.localization`, `threading`, `uuid`.
35 +
36 +## Key Concepts
37 +
38 +- 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`.
39 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
40 +
41 +## Work Guidance
42 +
43 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
44 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
45 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
46 +
47 +## Verification
48 +
49 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
50 +- Related tests observed by source search:
51 + - `tests/test_download_toast_regressions.py`
52 + - `tests/test_multi_tab_isolation.py`
53 + - `tests/test_self_update_tag_filter.py`
54 + - `tests/test_snapshot_parity.py`
55 + - `tests/test_snapshot_schema_v1.py`
56 + - `tests/test_state_monitor.py`
57 + - `tests/test_state_sync_handler.py`
58 + - `tests/test_state_sync_welcome_screen.py`
59 +
60 +## Child DOX Index
61 +
62 +No child DOX files.
helpers/performance.py.dox.md new
+42
@@ -0,0 +1,42 @@
1 +# performance.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `performance.py` helper module.
6 +- This module provides lightweight performance tracing helpers.
7 +- Keep this file-level DOX profile synchronized with `performance.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `performance.py` owns the runtime implementation.
12 +- `performance.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `trace_performance(show_all=..., color=..., unicode=...)`: Decorator that profiles a function and prints a call tree when it finishes.
15 +
16 +## Runtime Contracts
17 +
18 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
19 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
20 +- Imported dependency areas include: `functools`, `inspect`, `pyinstrument`.
21 +
22 +## Key Concepts
23 +
24 +- Important called helpers/classes observed in the source: `inspect.iscoroutinefunction`, `functools.wraps`, `Profiler`, `profiler.start`, `profiler.stop`, `func`, `profiler.output_text`.
25 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
26 +
27 +## Work Guidance
28 +
29 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
30 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
31 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
32 +
33 +## Verification
34 +
35 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
36 +- Related tests observed by source search:
37 + - `tests/test_extensions_stress.py`
38 + - `tests/test_ws_manager.py`
39 +
40 +## Child DOX Index
41 +
42 +No child DOX files.
helpers/perplexity_search.py.dox.md new
+41
@@ -0,0 +1,41 @@
1 +# perplexity_search.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `perplexity_search.py` helper module.
6 +- This module queries Perplexity search using configured model/provider credentials.
7 +- Keep this file-level DOX profile synchronized with `perplexity_search.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `perplexity_search.py` owns the runtime implementation.
12 +- `perplexity_search.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `perplexity_search(query: str, model_name=..., api_key=..., base_url=...)`
15 +
16 +## Runtime Contracts
17 +
18 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
19 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
20 +- Observed side-effect areas: secret handling.
21 +- Imported dependency areas include: `models`, `openai`.
22 +
23 +## Key Concepts
24 +
25 +- Important called helpers/classes observed in the source: `OpenAI`, `client.chat.completions.create`, `models.get_api_key`.
26 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
27 +
28 +## Work Guidance
29 +
30 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
31 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
32 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
33 +
34 +## Verification
35 +
36 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
37 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
38 +
39 +## Child DOX Index
40 +
41 +No child DOX files.
helpers/persist_chat.py.dox.md new
+65
@@ -0,0 +1,65 @@
1 +# persist_chat.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `persist_chat.py` helper module.
6 +- This module persists and reloads chat contexts and message artifacts.
7 +- Keep this file-level DOX profile synchronized with `persist_chat.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `persist_chat.py` owns the runtime implementation.
12 +- `persist_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `_fallback_datetime_iso() -> str`
15 +- `_parse_persisted_datetime(value: str | None) -> datetime`
16 +- `get_chat_folder_path(ctxid: str)`: Get the folder path for any context (chat or task).
17 +- `get_chat_msg_files_folder(ctxid: str)`
18 +- `save_tmp_chat(context: AgentContext)`: Save context to the chats folder
19 +- `save_tmp_chats()`: Save all contexts to the chats folder
20 +- `load_tmp_chats()`: Load all contexts from the chats folder
21 +- `_get_chat_file_path(ctxid: str)`
22 +- `_convert_v080_chats()`
23 +- `load_json_chats(jsons: list[str])`: Load contexts from JSON strings
24 +- `export_json_chat(context: AgentContext)`: Export context as JSON string
25 +- `remove_chat(ctxid)`: Remove a chat or task context
26 +- `remove_msg_files(ctxid)`: Remove all message files for a chat or task context
27 +- `_serialize_context(context: AgentContext)`
28 +- `_serialize_agent(agent: Agent)`
29 +- `_serialize_log(log: Log)`
30 +- `_deserialize_context(data)`
31 +- `_deserialize_agents(agents: list[dict[str, Any]], config: AgentConfig, context: AgentContext) -> Agent`
32 +- `_deserialize_log(data: dict[str, Any]) -> 'Log'`
33 +- `_safe_json_serialize(obj, **kwargs)`
34 +- Notable constants/configuration names: `CHATS_FOLDER`, `LOG_SIZE`, `CHAT_FILE_NAME`.
35 +
36 +## Runtime Contracts
37 +
38 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
39 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
40 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, scheduler state.
41 +- Imported dependency areas include: `agent`, `collections`, `datetime`, `helpers`, `helpers.localization`, `helpers.log`, `initialize`, `json`, `typing`, `uuid`.
42 +
43 +## Key Concepts
44 +
45 +- 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`.
46 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
47 +
48 +## Work Guidance
49 +
50 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
51 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
52 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
53 +
54 +## Verification
55 +
56 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
57 +- Related tests observed by source search:
58 + - `tests/test_api_chat_lifetime.py`
59 + - `tests/test_browser_agent_regressions.py`
60 + - `tests/test_persist_chat_log_ids.py`
61 + - `tests/test_tool_action_contracts.py`
62 +
63 +## Child DOX Index
64 +
65 +No child DOX files.
helpers/plugins.py.dox.md new
+81
@@ -0,0 +1,81 @@
1 +# plugins.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `plugins.py` helper module.
6 +- This module discovers plugins, resolves plugin config/toggles, runs hooks, and tracks plugin updates.
7 +- Keep this file-level DOX profile synchronized with `plugins.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `plugins.py` owns the runtime implementation.
12 +- `plugins.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `PluginAssetFile` (`TypedDict`)
15 +- `PluginMetadata` (`BaseModel`)
16 +- `PluginListItem` (`BaseModel`)
17 +- `PluginUpdateInfo` (`BaseModel`)
18 +- Top-level functions:
19 +- `register_watchdogs()`
20 +- `after_plugin_change(plugin_names: list[str] | None=..., python_change: bool=...)`
21 +- `refresh_plugin_modules(plugin_names: list[str] | None=...)`
22 +- `clear_plugin_cache(plugin_names: list[str] | None=...)`
23 +- `get_plugin_roots(plugin_name: str=...) -> List[str]`: Plugin root directories, ordered by priority (user first).
24 +- `get_plugins_list()`
25 +- `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.
26 +- `get_custom_plugins_updates(plugin_names: list[str] | None=...) -> List[PluginUpdateInfo]`
27 +- `get_plugin_meta(plugin_name: str)`
28 +- `find_plugin_dir(plugin_name: str)`
29 +- `uninstall_plugin(plugin_name)`
30 +- `delete_plugin(plugin_name: str)`
31 +- `get_plugin_paths(*subpaths) -> List[str]`
32 +- `get_enabled_plugin_paths(agent: Agent | None, *subpaths) -> List[str]`
33 +- `get_enabled_plugins(agent: Agent | None)`
34 +- `determined_toggle_from_paths(default: bool, paths: Iterator[str])`
35 +- `get_toggle_state(plugin_name: str) -> ToggleState`
36 +- `toggle_plugin(plugin_name: str, enabled: bool, project_name: str=..., agent_profile: str=..., clear_overrides: bool=...)`
37 +- `get_plugin_config(plugin_name: str, agent: Agent | None=..., project_name: str | None=..., agent_profile: str | None=...)`
38 +- `get_default_plugin_config(plugin_name: str)`
39 +- `save_plugin_config(plugin_name: str, project_name: str, agent_profile: str, settings: dict)`
40 +- `find_plugin_asset(plugin_name: str, *subpaths, project_name=..., agent_profile=...)`
41 +- `find_plugin_assets(*subpaths, plugin_name: str=..., project_name: str=..., agent_profile: str=..., only_first: bool=...) -> list[PluginAssetFile]`
42 +- `determine_plugin_asset_path(plugin_name: str, project_name: str, agent_profile: str, *subpaths)`
43 +- `send_frontend_reload_notification(plugin_names: list[str] | None=...)`: If the plugin changed has webui extensions, notify frontend to reload the page
44 +- `call_plugin_hook(plugin_name: str, hook_name: str, default: Any=..., *args, **kwargs)`
45 +- `_apply_defaults_from_env(plugin_name: str, config: dict[str, Any])`
46 +- 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`.
47 +
48 +## Runtime Contracts
49 +
50 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
51 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
52 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, plugin state, settings/state persistence, secret handling.
53 +- Imported dependency areas include: `__future__`, `asyncio`, `glob`, `helpers`, `helpers.defer`, `helpers.watchdog`, `json`, `pathlib`, `pydantic`, `re`, `regex`, `time`, `typing`.
54 +
55 +## Key Concepts
56 +
57 +- 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`.
58 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
59 +
60 +## Work Guidance
61 +
62 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
63 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
64 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
65 +
66 +## Verification
67 +
68 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
69 +- Related tests observed by source search:
70 + - `tests/test_a0_connector_computer_use_metadata.py`
71 + - `tests/test_a0_connector_prompt_gating.py`
72 + - `tests/test_browser_agent_regressions.py`
73 + - `tests/test_chat_compaction.py`
74 + - `tests/test_default_prompt_budget.py`
75 + - `tests/test_document_query_plugin.py`
76 + - `tests/test_error_retry_plugin.py`
77 + - `tests/test_host_browser_connector.py`
78 +
79 +## Child DOX Index
80 +
81 +No child DOX files.
helpers/print_catch.py.dox.md new
+40
@@ -0,0 +1,40 @@
1 +# print_catch.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `print_catch.py` helper module.
6 +- This module captures printed output from async callables.
7 +- Keep this file-level DOX profile synchronized with `print_catch.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `print_catch.py` owns the runtime implementation.
12 +- `print_catch.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `capture_prints_async(func: Callable[..., Awaitable[Any]], *args, **kwargs) -> Tuple[Awaitable[Any], Callable[[], str]]`
15 +
16 +## Runtime Contracts
17 +
18 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
19 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
20 +- Imported dependency areas include: `asyncio`, `io`, `sys`, `typing`.
21 +
22 +## Key Concepts
23 +
24 +- Important called helpers/classes observed in the source: `io.StringIO`, `captured_output.getvalue`, `wrapped_func`, `func`.
25 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
26 +
27 +## Work Guidance
28 +
29 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
30 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
31 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
32 +
33 +## Verification
34 +
35 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
36 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
37 +
38 +## Child DOX Index
39 +
40 +No child DOX files.
helpers/print_style.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# print_style.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `print_style.py` helper module.
6 +- This module formats console/debug output consistently.
7 +- Keep this file-level DOX profile synchronized with `print_style.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `print_style.py` owns the runtime implementation.
12 +- `print_style.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `PrintStyle` (no explicit base class)
15 + - `get(self, *args, sep=..., **kwargs)`
16 + - `print(self, *args, sep=..., end=..., flush=...)`
17 + - `stream(self, *args, sep=..., flush=...)`
18 + - `is_last_line_empty(self)`
19 + - `standard(*args, sep=..., end=..., flush=...)`
20 + - `hint(*args, sep=..., end=..., flush=...)`
21 + - `info(*args, sep=..., end=..., flush=...)`
22 + - `success(*args, sep=..., end=..., flush=...)`
23 +- Top-level functions:
24 +- `_get_runtime()`
25 +
26 +## Runtime Contracts
27 +
28 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
29 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
30 +- Observed side-effect areas: filesystem reads, WebSocket state, secret handling.
31 +- Imported dependency areas include: `atexit`, `collections.abc`, `datetime`, `html`, `os`, `strings`, `sys`, `webcolors`.
32 +
33 +## Key Concepts
34 +
35 +- 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`.
36 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
37 +
38 +## Work Guidance
39 +
40 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
41 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
42 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
43 +
44 +## Verification
45 +
46 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
47 +- Related tests observed by source search:
48 + - `tests/test_print_style.py`
49 + - `tests/test_tool_action_contracts.py`
50 + - `tests/test_ws_manager.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
helpers/process.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# process.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `process.py` helper module.
6 +- This module manages process reload, restart, exit, and server references.
7 +- Keep this file-level DOX profile synchronized with `process.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `process.py` owns the runtime implementation.
12 +- `process.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `set_server(server)`
15 +- `get_server(server)`
16 +- `stop_server()`
17 +- `reload()`
18 +- `restart_process()`
19 +- `exit_process()`
20 +
21 +## Runtime Contracts
22 +
23 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
24 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
25 +- Observed side-effect areas: subprocess/runtime control.
26 +- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `sys`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
36 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
37 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
38 +
39 +## Verification
40 +
41 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
42 +- Related tests observed by source search:
43 + - `tests/test_api_chat_lifetime.py`
44 + - `tests/test_browser_agent_regressions.py`
45 + - `tests/test_docker_release_plan.py`
46 + - `tests/test_document_query_plugin.py`
47 + - `tests/test_download_toast_regressions.py`
48 + - `tests/test_git_version_label.py`
49 + - `tests/test_image_get_security.py`
50 + - `tests/test_model_config_project_presets.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
helpers/projects.py.dox.md new
+85
@@ -0,0 +1,85 @@
1 +# projects.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `projects.py` helper module.
6 +- This module owns project metadata, workspace creation, Git status, and project-scoped settings.
7 +- Keep this file-level DOX profile synchronized with `projects.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `projects.py` owns the runtime implementation.
12 +- `projects.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `FileStructureInjectionSettings` (`TypedDict`)
15 +- `SubAgentSettings` (`TypedDict`)
16 +- `BasicProjectData` (`TypedDict`)
17 +- `GitStatusData` (`TypedDict`)
18 +- `EditProjectData` (`BasicProjectData`)
19 +- Top-level functions:
20 +- `get_projects_parent_folder()`
21 +- `get_project_folder(name: str)`
22 +- `get_project_meta(name: str, *sub_dirs)`
23 +- `delete_project(name: str)`
24 +- `create_project(name: str, data: BasicProjectData)`
25 +- `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.
26 +- `load_project_header(name: str)`
27 +- `_default_file_structure_settings()`
28 +- `_normalizeBasicData(data: BasicProjectData) -> BasicProjectData`
29 +- `_normalizeEditData(data: EditProjectData) -> EditProjectData`
30 +- `_edit_data_to_basic_data(data: EditProjectData)`
31 +- `_basic_data_to_edit_data(data: BasicProjectData) -> EditProjectData`
32 +- `update_project(name: str, data: EditProjectData)`
33 +- `load_basic_project_data(name: str) -> BasicProjectData`
34 +- `load_edit_project_data(name: str) -> EditProjectData`
35 +- `save_project_header(name: str, data: BasicProjectData)`
36 +- `load_project_llm_data(name: str) -> dict`
37 +- `save_project_llm_settings(name: str, llm_data: object)`
38 +- `get_active_projects_list()`
39 +- `_get_projects_list(parent_dir)`
40 +- `activate_project(context_id: str, name: str, mark_dirty: bool=...)`
41 +- `deactivate_project(context_id: str, mark_dirty: bool=...)`
42 +- `reactivate_project_in_chats(name: str)`
43 +- `deactivate_project_in_chats(name: str)`
44 +- `build_system_prompt_vars(name: str)`
45 +- `get_additional_instructions_files(name: str)`
46 +- `get_project_instruction_files(name: str, include_agents_md: bool=...) -> list[tuple[str, str]]`
47 +- `get_project_agents_md_instruction_file(name: str) -> tuple[str, str] | None`
48 +- `_format_project_instruction_files(instruction_files: list[tuple[str, str]]) -> str`
49 +- `_normalize_include_agents_md(value: object) -> bool`
50 +- 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`.
51 +
52 +## Runtime Contracts
53 +
54 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
55 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
56 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence, secret handling.
57 +- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `typing`.
58 +
59 +## Key Concepts
60 +
61 +- 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`.
62 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
63 +
64 +## Work Guidance
65 +
66 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
67 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
68 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
69 +
70 +## Verification
71 +
72 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
73 +- Related tests observed by source search:
74 + - `tests/test_model_config_project_presets.py`
75 + - `tests/test_office_document_store.py`
76 + - `tests/test_plugin_activation_ui.py`
77 + - `tests/test_projects.py`
78 + - `tests/test_skills_runtime.py`
79 + - `tests/test_task_scheduler_timezone.py`
80 + - `tests/test_time_travel.py`
81 + - `tests/test_tool_action_contracts.py`
82 +
83 +## Child DOX Index
84 +
85 +No child DOX files.
helpers/providers.py.dox.md new
+61
@@ -0,0 +1,61 @@
1 +# providers.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `providers.py` helper module.
6 +- This module loads model provider configuration and provider metadata.
7 +- Keep this file-level DOX profile synchronized with `providers.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `providers.py` owns the runtime implementation.
12 +- `providers.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `FieldOption` (`TypedDict`)
15 +- `ProviderManager` (no explicit base class)
16 + - `get_instance(cls)`
17 + - `reload(cls)`
18 + - `get_providers(self, provider_type: ModelType) -> List[FieldOption]`
19 + - `get_raw_providers(self, provider_type: ModelType) -> List[Dict[str, str]]`
20 + - `get_provider_config(self, provider_type: ModelType, provider_id: str) -> Optional[Dict[str, str]]`
21 +- Top-level functions:
22 +- `get_providers(provider_type: ModelType) -> List[FieldOption]`: Convenience function to get providers of a specific type.
23 +- `get_raw_providers(provider_type: ModelType) -> List[Dict[str, str]]`: Return full metadata for providers of a given type.
24 +- `get_provider_config(provider_type: ModelType, provider_id: str) -> Optional[Dict[str, str]]`: Return metadata for a single provider (None if not found).
25 +- `reload_providers()`: Re-merge base + plugin provider configs. Call after plugin changes.
26 +- Notable constants/configuration names: `PROVIDER_MANAGER_CACHE_AREA`, `PROVIDER_MANAGER_CACHE_KEY`.
27 +
28 +## Runtime Contracts
29 +
30 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
31 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
32 +- Observed side-effect areas: filesystem reads, filesystem deletion, plugin state, settings/state persistence.
33 +- Imported dependency areas include: `helpers`, `typing`, `yaml`.
34 +
35 +## Key Concepts
36 +
37 +- 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`.
38 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
39 +
40 +## Work Guidance
41 +
42 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
43 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
44 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
45 +
46 +## Verification
47 +
48 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
49 +- Related tests observed by source search:
50 + - `tests/test_fastmcp_openapi_security.py`
51 + - `tests/test_model_config_api_keys.py`
52 + - `tests/test_oauth_codex.py`
53 + - `tests/test_oauth_gemini_api.py`
54 + - `tests/test_oauth_github_copilot.py`
55 + - `tests/test_oauth_providers.py`
56 + - `tests/test_oauth_xai_grok.py`
57 + - `tests/test_onboarding_static.py`
58 +
59 +## Child DOX Index
60 +
61 +No child DOX files.
helpers/rate_limiter.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# rate_limiter.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `rate_limiter.py` helper module.
6 +- This module provides simple rate-limiting primitives.
7 +- Keep this file-level DOX profile synchronized with `rate_limiter.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `rate_limiter.py` owns the runtime implementation.
12 +- `rate_limiter.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `RateLimiter` (no explicit base class)
15 + - `add(self, **kwargs)`
16 + - `async cleanup(self)`
17 + - `async get_total(self, key: str) -> int`
18 + - `async wait(self, callback: Callable[[str, str, int, int], Awaitable[bool]] | None=...)`
19 +
20 +## Runtime Contracts
21 +
22 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
23 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
24 +- Imported dependency areas include: `asyncio`, `time`, `typing`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `asyncio.Lock`, `time.time`, `self.cleanup`, `asyncio.sleep`, `self.get_total`, `callback`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
34 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
35 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
36 +
37 +## Verification
38 +
39 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
40 +- Related tests observed by source search:
41 + - `tests/test_stream_tool_early_stop.py`
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
helpers/rfc.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# rfc.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `rfc.py` helper module.
6 +- This module implements remote function call dispatch and serialization.
7 +- Keep this file-level DOX profile synchronized with `rfc.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `rfc.py` owns the runtime implementation.
12 +- `rfc.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `RFCInput` (`TypedDict`)
15 +- `RFCCall` (`TypedDict`)
16 +- Top-level functions:
17 +- `async call_rfc(url: str, password: str, module: str, function_name: str, args: list, kwargs: dict)`
18 +- `async handle_rfc(rfc_call: RFCCall, password: str)`
19 +- `async _call_function(module: str, function_name: str, *args, **kwargs)`
20 +- `_get_function(module: str, function_name: str)`
21 +- `async _send_json_data(url: str, data)`
22 +
23 +## Runtime Contracts
24 +
25 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
26 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
27 +- Observed side-effect areas: filesystem writes, network calls, settings/state persistence, secret handling.
28 +- Imported dependency areas include: `aiohttp`, `helpers`, `importlib`, `inspect`, `json`, `typing`.
29 +
30 +## Key Concepts
31 +
32 +- 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`.
33 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
34 +
35 +## Work Guidance
36 +
37 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
38 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
39 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
40 +
41 +## Verification
42 +
43 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
44 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
helpers/rfc_exchange.py.dox.md new
+42
@@ -0,0 +1,42 @@
1 +# rfc_exchange.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `rfc_exchange.py` helper module.
6 +- This module handles privileged RFC exchange data such as root password provisioning.
7 +- Keep this file-level DOX profile synchronized with `rfc_exchange.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `rfc_exchange.py` owns the runtime implementation.
12 +- `rfc_exchange.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `async get_root_password()`
15 +- `_provide_root_password(public_key_pem: str)`
16 +- `_get_root_password()`
17 +
18 +## Runtime Contracts
19 +
20 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
21 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
22 +- Imported dependency areas include: `helpers`.
23 +
24 +## Key Concepts
25 +
26 +- 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`.
27 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
28 +
29 +## Work Guidance
30 +
31 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
32 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
33 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
34 +
35 +## Verification
36 +
37 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
38 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
39 +
40 +## Child DOX Index
41 +
42 +No child DOX files.
helpers/rfc_files.py.dox.md new
+70
@@ -0,0 +1,70 @@
1 +# rfc_files.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `rfc_files.py` helper module.
6 +- This module exposes RFC-safe filesystem operations.
7 +- Keep this file-level DOX profile synchronized with `rfc_files.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `rfc_files.py` owns the runtime implementation.
12 +- `rfc_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `get_abs_path(*relative_paths)`: Convert relative paths to absolute paths based on the base directory.
15 +- `read_file_bin(relative_path: str, backup_dirs=...) -> bytes`: Read binary file content.
16 +- `read_file_base64(relative_path: str, backup_dirs=...) -> str`: Read file content and return as base64 string.
17 +- `write_file_binary(relative_path: str, content: bytes) -> bool`: Write binary content to a file.
18 +- `write_file_base64(relative_path: str, content: str) -> bool`: Write base64 content to a file.
19 +- `delete_file(relative_path: str) -> bool`: Delete a file.
20 +- `delete_directory(relative_path: str) -> bool`: Delete a directory recursively.
21 +- `list_directory(relative_path: str, include_hidden: bool=...) -> list`: List directory contents.
22 +- `make_directories(relative_path: str) -> bool`: Create directories recursively.
23 +- `path_exists(relative_path: str) -> bool`: Check if a path exists.
24 +- `file_exists(relative_path: str) -> bool`: Check if a file exists.
25 +- `folder_exists(relative_path: str) -> bool`: Check if a folder exists.
26 +- `get_subdirectories(relative_path: str, include: str | list[str]=..., exclude: str | list[str] | None=...) -> list[str]`: Get subdirectories in a directory.
27 +- `zip_directory(relative_path: str) -> str`: Create a zip archive of a directory.
28 +- `move_file(source_path: str, destination_path: str) -> bool`: Move a file from source to destination.
29 +- `read_directory_as_zip(relative_path: str) -> bytes`: Read entire directory contents as a zip file.
30 +- `find_file_in_dirs(file_path: str, backup_dirs: list[str]) -> str`: Find a file in the main directory or backup directories.
31 +- `_read_file_binary_impl(file_path: str) -> str`: Implementation function to read a file in binary mode.
32 +- `_write_file_binary_impl(file_path: str, b64_content: str) -> bool`: Implementation function to write binary content to a file.
33 +- `_delete_file_impl(file_path: str) -> bool`: Implementation function to delete a file.
34 +- `_delete_folder_impl(folder_path: str) -> bool`: Implementation function to delete a folder recursively.
35 +- `_list_folder_impl(folder_path: str, include_hidden: bool=...) -> list`: Implementation function to list folder contents.
36 +- `_make_dirs_impl(folder_path: str) -> bool`: Implementation function to create directories.
37 +- `_path_exists_impl(file_path: str) -> bool`: Implementation function to check if path exists.
38 +- `_file_exists_impl(file_path: str) -> bool`: Implementation function to check if file exists.
39 +- `_folder_exists_impl(folder_path: str) -> bool`: Implementation function to check if folder exists.
40 +- `_get_subdirectories_impl(folder_path: str, include: str | list[str], exclude: str | list[str] | None) -> list[str]`: Implementation function to get subdirectories.
41 +- `_zip_dir_impl(folder_path: str) -> str`: Implementation function to create a zip archive of a directory.
42 +- `_move_file_impl(source_path: str, destination_path: str) -> bool`: Implementation function to move a file.
43 +- `_read_directory_impl(dir_path: str) -> str`: Implementation function to zip a directory and return base64 encoded zip.
44 +
45 +## Runtime Contracts
46 +
47 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
48 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
49 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
50 +- Imported dependency areas include: `base64`, `fnmatch`, `helpers`, `os`, `shutil`, `tempfile`, `zipfile`.
51 +
52 +## Key Concepts
53 +
54 +- 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`.
55 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
56 +
57 +## Work Guidance
58 +
59 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
60 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
61 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
62 +
63 +## Verification
64 +
65 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
66 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
67 +
68 +## Child DOX Index
69 +
70 +No child DOX files.
helpers/runtime.py.dox.md new
+69
@@ -0,0 +1,69 @@
1 +# runtime.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `runtime.py` helper module.
6 +- This module owns runtime identity, environment flags, and startup arguments.
7 +- Keep this file-level DOX profile synchronized with `runtime.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `runtime.py` owns the runtime implementation.
12 +- `runtime.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `initialize()`
15 +- `get_arg(name: str)`
16 +- `has_arg(name: str)`
17 +- `is_dockerized() -> bool`
18 +- `is_development() -> bool`
19 +- `get_local_url()`
20 +- `get_runtime_id() -> str`
21 +- `get_persistent_id() -> str`
22 +- `async call_development_function(func: Callable[..., Awaitable[T]], *args, **kwargs) -> T`
23 +- `async call_development_function(func: Callable[..., T], *args, **kwargs) -> T`
24 +- `async call_development_function(func: Union[Callable[..., T], Callable[..., Awaitable[T]]], *args, **kwargs) -> T`
25 +- `async handle_rfc(rfc_call: rfc.RFCCall)`
26 +- `_get_rfc_password() -> str`
27 +- `_get_rfc_url() -> str`
28 +- `call_development_function_sync(func: Union[Callable[..., T], Callable[..., Awaitable[T]]], *args, **kwargs) -> T`
29 +- `get_web_ui_port()`
30 +- `get_tunnel_api_port()`
31 +- `get_platform()`
32 +- `is_windows()`
33 +- `get_terminal_executable()`
34 +- Notable constants/configuration names: `T`, `R`.
35 +
36 +## Runtime Contracts
37 +
38 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
39 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
40 +- Observed side-effect areas: filesystem reads, filesystem writes, subprocess/runtime control, settings/state persistence, secret handling, tunnel state.
41 +- Imported dependency areas include: `argparse`, `asyncio`, `helpers`, `inspect`, `nest_asyncio`, `pathlib`, `queue`, `secrets`, `sys`, `threading`, `typing`.
42 +
43 +## Key Concepts
44 +
45 +- 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`.
46 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
47 +
48 +## Work Guidance
49 +
50 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
51 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
52 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
53 +
54 +## Verification
55 +
56 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
57 +- Related tests observed by source search:
58 + - `tests/test_a0_connector_computer_use_metadata.py`
59 + - `tests/test_a0_connector_prompt_gating.py`
60 + - `tests/test_browser_agent_regressions.py`
61 + - `tests/test_default_prompt_budget.py`
62 + - `tests/test_document_query_plugin.py`
63 + - `tests/test_host_browser_connector.py`
64 + - `tests/test_http_auth_csrf.py`
65 + - `tests/test_image_get_security.py`
66 +
67 +## Child DOX Index
68 +
69 +No child DOX files.
helpers/searxng.py.dox.md new
+43
@@ -0,0 +1,43 @@
1 +# searxng.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `searxng.py` helper module.
6 +- This module queries SearXNG search.
7 +- Keep this file-level DOX profile synchronized with `searxng.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `searxng.py` owns the runtime implementation.
12 +- `searxng.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `async search(query: str)`
15 +- `async _search(query: str)`
16 +- Notable constants/configuration names: `URL`.
17 +
18 +## Runtime Contracts
19 +
20 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
21 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
22 +- Observed side-effect areas: network calls, settings/state persistence.
23 +- Imported dependency areas include: `aiohttp`, `helpers`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `runtime.call_development_function`, `aiohttp.ClientSession`, `session.post`, `response.json`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
33 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
34 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
35 +
36 +## Verification
37 +
38 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
39 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
40 +
41 +## Child DOX Index
42 +
43 +No child DOX files.
helpers/secrets.py.dox.md new
+62
@@ -0,0 +1,62 @@
1 +# secrets.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `secrets.py` helper module.
6 +- This module loads, aliases, masks, and streams secret values safely.
7 +- Keep this file-level DOX profile synchronized with `secrets.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `secrets.py` owns the runtime implementation.
12 +- `secrets.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `EnvLine` (no explicit base class)
15 +- `StreamingSecretsFilter` (no explicit base class)
16 + - `process_chunk(self, chunk: str) -> str`
17 + - `finalize(self) -> str`
18 +- `SecretsManager` (no explicit base class)
19 + - `get_instance(cls, *secrets_files) -> 'SecretsManager'`
20 + - `read_secrets_raw(self) -> str`
21 + - `load_secrets(self) -> Dict[str, str]`
22 + - `save_secrets(self, secrets_content: str)`
23 + - `save_secrets_with_merge(self, submitted_content: str)`
24 + - `get_keys(self) -> List[str]`
25 + - `get_secrets_for_prompt(self) -> str`
26 + - `create_streaming_filter(self) -> 'StreamingSecretsFilter'`
27 +- Top-level functions:
28 +- `alias_for_key(key: str, placeholder: str=...) -> str`
29 +- `get_secrets_manager(context: 'AgentContext|None'=...) -> SecretsManager`
30 +- `get_project_secrets_manager(project_name: str, merge_with_global: bool=...) -> SecretsManager`
31 +- `get_default_secrets_manager() -> SecretsManager`
32 +- Notable constants/configuration names: `ALIAS_PATTERN`, `DEFAULT_SECRETS_FILE`.
33 +
34 +## Runtime Contracts
35 +
36 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
37 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
38 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, settings/state persistence, secret handling.
39 +- Imported dependency areas include: `dataclasses`, `dotenv.parser`, `helpers`, `helpers.errors`, `helpers.extension`, `io`, `os`, `re`, `threading`, `time`, `typing`.
40 +
41 +## Key Concepts
42 +
43 +- 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`.
44 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
45 +
46 +## Work Guidance
47 +
48 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
49 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
50 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
51 +
52 +## Verification
53 +
54 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
55 +- Related tests observed by source search:
56 + - `tests/test_plugin_scan_prompt.py`
57 + - `tests/test_print_style.py`
58 + - `tests/test_time_travel.py`
59 +
60 +## Child DOX Index
61 +
62 +No child DOX files.
helpers/security.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# security.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `security.py` helper module.
6 +- This module contains small security helpers such as filename sanitization.
7 +- Keep this file-level DOX profile synchronized with `security.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `security.py` owns the runtime implementation.
12 +- `security.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `safe_filename(filename: str) -> Optional[str]`
15 +- Notable constants/configuration names: `FORBIDDEN_CHARS_RE`, `WINDOWS_RESERVED`, `FILENAME_MAX_LENGTH`.
16 +
17 +## Runtime Contracts
18 +
19 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
20 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
21 +- Observed side-effect areas: filesystem reads, filesystem deletion.
22 +- Imported dependency areas include: `pathlib`, `re`, `typing`, `unicodedata`.
23 +
24 +## Key Concepts
25 +
26 +- 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`.
27 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
28 +
29 +## Work Guidance
30 +
31 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
32 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
33 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
34 +
35 +## Verification
36 +
37 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
38 +- Related tests observed by source search:
39 + - `tests/test_fastmcp_openapi_security.py`
40 + - `tests/test_image_get_security.py`
41 + - `tests/test_ws_security.py`
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
helpers/self_update.py.dox.md new
+77
@@ -0,0 +1,77 @@
1 +# self_update.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `self_update.py` helper module.
6 +- This module manages self-update status, scheduling, tag selection, and durable scripts.
7 +- Keep this file-level DOX profile synchronized with `self_update.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `self_update.py` owns the runtime implementation.
12 +- `self_update.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `PendingUpdateConfig` (`TypedDict`)
15 +- `UpdateStatus` (`TypedDict`)
16 +- `SelectorTagOption` (`TypedDict`)
17 +- Top-level functions:
18 +- `_now_iso() -> str`
19 +- `get_update_file_path() -> Path`
20 +- `get_status_file_path() -> Path`
21 +- `get_log_file_path() -> Path`
22 +- `get_durable_exe_dir() -> Path`
23 +- `get_durable_self_update_manager_path() -> Path`
24 +- `_load_yaml(path: Path) -> dict[str, Any] | None`
25 +- `_write_yaml(path: Path, payload: dict[str, Any]) -> None`
26 +- `load_pending_update() -> PendingUpdateConfig | None`
27 +- `load_last_status() -> UpdateStatus | None`
28 +- `get_log_text() -> str`
29 +- `get_default_backup_dir(repo_dir: str | Path | None=...) -> Path`
30 +- `get_repo_dir(repo_dir: str | Path | None=...) -> Path`
31 +- `get_repo_self_update_manager_path(repo_dir: str | Path | None=...) -> Path`
32 +- `_get_official_remote_url() -> str`
33 +- `_run_git_raw(*args) -> str`
34 +- `_run_git(repo_dir: str | Path, *args) -> str`
35 +- `_normalize_describe_to_version(describe: str) -> str`
36 +- `_split_describe_version(describe: str) -> tuple[str, int]`
37 +- `_is_latest_selector_tag(tag: str) -> bool`
38 +- `_get_tag_release_time_in_repo(repo_dir: str | Path, tag: str) -> str`
39 +- `get_repo_version_info(repo_dir: str | Path | None=...) -> dict[str, str]`
40 +- `_sanitize_filename(name: str, default_name: str) -> str`
41 +- `_slugify_version(text: str) -> str`
42 +- `build_default_backup_name(current_version: str, target_tag: str | None=...) -> str`
43 +- `_resolve_backup_path(backup_path: str, repo_dir: str | Path | None=...) -> Path`
44 +- `_is_excluded_self_update_branch(branch: str) -> bool`
45 +- `_sort_branch_names(branches: list[str]) -> list[str]`
46 +- `_get_remote_branch_names() -> list[str]`
47 +- `_get_local_origin_branch_names(repo_dir: str | Path | None=...) -> list[str]`
48 +- 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`.
49 +
50 +## Runtime Contracts
51 +
52 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
53 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
54 +- Observed side-effect areas: filesystem reads, filesystem writes, subprocess/runtime control, settings/state persistence.
55 +- Imported dependency areas include: `__future__`, `datetime`, `helpers`, `helpers.localization`, `os`, `pathlib`, `re`, `subprocess`, `tempfile`, `time`, `typing`.
56 +
57 +## Key Concepts
58 +
59 +- 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`.
60 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
61 +
62 +## Work Guidance
63 +
64 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
65 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
66 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
67 +
68 +## Verification
69 +
70 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
71 +- Related tests observed by source search:
72 + - `tests/test_office_document_store.py`
73 + - `tests/test_self_update_tag_filter.py`
74 +
75 +## Child DOX Index
76 +
77 +No child DOX files.
helpers/serveo_tunnel.py.dox.md new
+43
@@ -0,0 +1,43 @@
1 +# serveo_tunnel.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `serveo_tunnel.py` helper module.
6 +- This module implements Serveo tunnel provider behavior.
7 +- Keep this file-level DOX profile synchronized with `serveo_tunnel.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `serveo_tunnel.py` owns the runtime implementation.
12 +- `serveo_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ServeoTunnelHelper` (`FlaredanticTunnelHelper`)
15 + - `build_tunnel(self)`
16 +
17 +## Runtime Contracts
18 +
19 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
20 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
21 +- Observed side-effect areas: settings/state persistence, tunnel state.
22 +- Imported dependency areas include: `flaredantic`, `helpers.tunnel_common`.
23 +
24 +## Key Concepts
25 +
26 +- Important called helpers/classes observed in the source: `ServeoConfig`, `ServeoTunnel`.
27 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
28 +
29 +## Work Guidance
30 +
31 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
32 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
33 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
34 +
35 +## Verification
36 +
37 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
38 +- Related tests observed by source search:
39 + - `tests/test_tunnel_remote_link.py`
40 +
41 +## Child DOX Index
42 +
43 +No child DOX files.
helpers/server_startup.py.dox.md new
+62
@@ -0,0 +1,62 @@
1 +# server_startup.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `server_startup.py` helper module.
6 +- This module runs Uvicorn startup with health checks and retry tracking.
7 +- Keep this file-level DOX profile synchronized with `server_startup.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `server_startup.py` owns the runtime implementation.
12 +- `server_startup.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `StartupConfig` (no explicit base class)
15 + - `from_env(cls) -> 'StartupConfig'`
16 +- `StartupStageRecord` (no explicit base class)
17 +- `StartupMonitor` (no explicit base class)
18 + - `mark(self, stage: str, detail: str | None=...) -> None`
19 + - `stage(self, stage: str, detail: str | None=...) -> Iterator[None]`
20 + - `lifespan(self)`
21 + - `attach_server(self, server: uvicorn.Server) -> None`
22 + - `start_watchdog(self) -> None`
23 + - `mark_ready(self, source: str=...) -> None`
24 + - `is_ready(self) -> bool`
25 + - `close(self) -> None`
26 +- `_UvicornServerWrapper` (no explicit base class)
27 + - `shutdown(self) -> None`
28 +- Top-level functions:
29 +- `_env_int(name: str, default: int, minimum: int=...) -> int`
30 +- `_env_float(name: str, default: float, minimum: float=...) -> float`
31 +- `get_health_probe_host(bind_host: str) -> str`
32 +- `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`
33 +- `_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`
34 +- `wait_for_health(host: str, port: int, startup_monitor: StartupMonitor) -> None`
35 +- `_serve_uvicorn(server: uvicorn.Server) -> None`
36 +
37 +## Runtime Contracts
38 +
39 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
40 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
41 +- Observed side-effect areas: filesystem writes, network calls, subprocess/runtime control, settings/state persistence.
42 +- Imported dependency areas include: `asyncio`, `collections`, `contextlib`, `dataclasses`, `faulthandler`, `helpers`, `helpers.print_style`, `os`, `sys`, `threading`, `time`, `typing`, `urllib.request`, `uvicorn`.
43 +
44 +## Key Concepts
45 +
46 +- 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`.
47 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
48 +
49 +## Work Guidance
50 +
51 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
52 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
53 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
54 +
55 +## Verification
56 +
57 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
58 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
59 +
60 +## Child DOX Index
61 +
62 +No child DOX files.
helpers/settings.py.dox.md new
+88
@@ -0,0 +1,88 @@
1 +# settings.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `settings.py` helper module.
6 +- This module defines settings models, defaults, validation, and serialization.
7 +- Keep this file-level DOX profile synchronized with `settings.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `settings.py` owns the runtime implementation.
12 +- `settings.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Settings` (`TypedDict`)
15 +- `PartialSettings` (`Settings`)
16 +- `FieldOption` (`TypedDict`)
17 +- `SettingsField` (`TypedDict`)
18 +- `SettingsSection` (`TypedDict`)
19 +- `ModelProvider` (`ProvidersFO`)
20 +- `SettingsOutputAdditional` (`TypedDict`)
21 +- `SettingsOutput` (`TypedDict`)
22 +- Top-level functions:
23 +- `get_default_value(name: str, value: T) -> T`: Load setting value from .env with A0_SET_ prefix, falling back to default.
24 +- `_ensure_option_present(options: list[OptionT] | None, current_value: str | None) -> list[OptionT]`: Ensure the currently selected value exists in a dropdown options list.
25 +- `_is_valid_timezone(value: str) -> bool`
26 +- `_normalize_timezone_setting(value: Any, default: str=...) -> str`
27 +- `_normalize_time_format(value: Any, default: str=...) -> str`
28 +- `_resolve_runtime_timezone(setting_value: str, browser_timezone: str | None=...) -> str`
29 +- `_timezone_options() -> list[FieldOption]`
30 +- `convert_out(settings: Settings) -> SettingsOutput`
31 +- `_get_api_key_field(settings: Settings, provider: str, title: str) -> SettingsField`
32 +- `convert_in(settings: Settings) -> Settings`
33 +- `get_settings() -> Settings`
34 +- `reload_settings() -> Settings`
35 +- `set_runtime_settings_snapshot(settings: Settings) -> None`
36 +- `set_settings(settings: Settings, apply: bool=..., browser_timezone: str | None=...)`
37 +- `set_settings_delta(delta: dict, apply: bool=...)`
38 +- `merge_settings(original: Settings, delta: dict) -> Settings`
39 +- `normalize_settings(settings: Settings) -> Settings`
40 +- `_adjust_to_version(settings: Settings, default: Settings)`
41 +- `_load_sensitive_settings(settings: Settings)`
42 +- `_read_settings_file() -> Settings | None`
43 +- `_write_settings_file(settings: Settings)`
44 +- `_remove_sensitive_settings(settings: Settings)`
45 +- `_write_sensitive_settings(settings: Settings)`
46 +- `get_default_settings() -> Settings`
47 +- `_apply_timezone_setting(previous: Settings | None, browser_timezone: str | None=...) -> None`
48 +- `_apply_settings(previous: Settings | None, browser_timezone: str | None=...)`
49 +- `_env_to_dict(data: str)`
50 +- `_dict_to_env(data_dict)`
51 +- `set_root_password(password: str)`
52 +- `get_runtime_config(set: Settings)`
53 +- Notable constants/configuration names: `T`, `PASSWORD_PLACEHOLDER`, `API_KEY_PLACEHOLDER`, `TIMEZONE_AUTO`, `TIME_FORMAT_12H`, `TIME_FORMAT_24H`, `SETTINGS_FILE`.
54 +
55 +## Runtime Contracts
56 +
57 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
58 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
59 +- 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.
60 +- Imported dependency areas include: `base64`, `hashlib`, `helpers`, `helpers.notification`, `helpers.print_style`, `helpers.providers`, `helpers.secrets`, `json`, `models`, `os`, `pytz`, `re`, `subprocess`, `typing`.
61 +
62 +## Key Concepts
63 +
64 +- 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`.
65 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
66 +
67 +## Work Guidance
68 +
69 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
70 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
71 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
72 +
73 +## Verification
74 +
75 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
76 +- Related tests observed by source search:
77 + - `tests/test_browser_agent_regressions.py`
78 + - `tests/test_document_query_plugin.py`
79 + - `tests/test_download_toast_regressions.py`
80 + - `tests/test_fasta2a_client.py`
81 + - `tests/test_mcp_handler_multimodal.py`
82 + - `tests/test_model_config_api_keys.py`
83 + - `tests/test_model_config_project_presets.py`
84 + - `tests/test_oauth_static.py`
85 +
86 +## Child DOX Index
87 +
88 +No child DOX files.
helpers/skills.py.dox.md new
+83
@@ -0,0 +1,83 @@
1 +# skills.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `skills.py` helper module.
6 +- This module discovers, parses, filters, and resolves Agent Zero skills.
7 +- Keep this file-level DOX profile synchronized with `skills.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `skills.py` owns the runtime implementation.
12 +- `skills.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ActiveSkillEntry` (`TypedDict`)
15 +- `CatalogSkill` (`TypedDict`)
16 +- `Skill` (no explicit base class)
17 +- Top-level functions:
18 +- `get_skills_base_dir() -> Path`
19 +- `get_skill_roots(agent: Agent | None=...) -> List[str]`
20 +- `_is_hidden_path(path: Path) -> bool`
21 +- `discover_skill_md_files(root: Path) -> List[Path]`: Recursively discover SKILL.md files under a root directory.
22 +- `_coerce_list(value: Any) -> List[str]`
23 +- `_normalize_name(name: str) -> str`
24 +- `_read_text(path: Path) -> str`
25 +- `split_frontmatter(markdown: str) -> Tuple[Dict[str, Any], str, List[str]]`: Splits a SKILL.md into (frontmatter_dict, body_text, errors).
26 +- `_parse_frontmatter_fallback(frontmatter_text: str) -> Dict[str, Any]`
27 +- `parse_frontmatter(frontmatter_text: str) -> Tuple[Dict[str, Any], List[str]]`: Parse YAML frontmatter with PyYAML when available,
28 +- `skill_from_markdown(skill_md_path: Path, include_content: bool=..., validate: bool=...) -> Optional[Skill]`
29 +- `list_skills(agent: Agent | None=..., include_content: bool=..., include_hidden: bool=...) -> List[Skill]`: List skills, optionally filtered by agent scope.
30 +- `delete_skill(skill_path: str) -> None`: Delete a skill directory.
31 +- `find_skill(skill_name: str, agent: Agent | None=..., include_content: bool=..., include_hidden: bool=...) -> Optional[Skill]`
32 +- `load_skill_for_agent(skill_name: str, agent: Agent | None=...) -> str`: Load skill and format it as a complete string for agent context.
33 +- `_get_skill_files(skill_dir: Path) -> str`: Get file tree for skill directory.
34 +- `search_skills(query: str, limit: int=..., agent: Agent | None=..., include_hidden: bool=...) -> List[Skill]`
35 +- `validate_skill(skill: Skill) -> List[str]`
36 +- `validate_skill_md(skill_md_path: Path) -> List[str]`
37 +- `_normalize_max_active_skills(value: Any) -> int`
38 +- `get_max_active_skills(agent: Agent | None=..., project_name: str | None=...) -> int`
39 +- `normalize_skills_config(config: dict[str, Any] | None) -> dict[str, Any]`
40 +- `normalize_active_skills(raw: Any, limit: int | None=...) -> list[ActiveSkillEntry]`
41 +- `normalize_hidden_skills(raw: Any) -> list[ActiveSkillEntry]`
42 +- `normalize_skill_entries(raw: Any, limit: int | None=...) -> list[ActiveSkillEntry]`
43 +- `list_skill_catalog(project_name: str=..., agent: Agent | None=...) -> list[CatalogSkill]`
44 +- `get_scope_active_skills(agent: Agent | None) -> list[ActiveSkillEntry]`
45 +- `get_scope_hidden_skills(agent: Agent | None) -> list[ActiveSkillEntry]`
46 +- `get_chat_active_skills(context: Any | None) -> list[ActiveSkillEntry]`
47 +- `get_chat_disabled_skills(context: Any | None) -> list[ActiveSkillEntry]`
48 +- 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`.
49 +
50 +## Runtime Contracts
51 +
52 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
53 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
54 +- Observed side-effect areas: filesystem reads, filesystem deletion, plugin state, settings/state persistence, secret handling.
55 +- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `os`, `pathlib`, `re`, `typing`.
56 +
57 +## Key Concepts
58 +
59 +- 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`.
60 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
61 +
62 +## Work Guidance
63 +
64 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
65 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
66 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
67 +
68 +## Verification
69 +
70 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
71 +- Related tests observed by source search:
72 + - `tests/test_a0_connector_prompt_gating.py`
73 + - `tests/test_browser_agent_regressions.py`
74 + - `tests/test_document_query_plugin.py`
75 + - `tests/test_fasta2a_client.py`
76 + - `tests/test_office_canvas_setup.py`
77 + - `tests/test_office_document_store.py`
78 + - `tests/test_skills_runtime.py`
79 + - `tests/test_time_travel.py`
80 +
81 +## Child DOX Index
82 +
83 +No child DOX files.
helpers/skills_cli.py.dox.md new
+51
@@ -0,0 +1,51 @@
1 +# skills_cli.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `skills_cli.py` helper module.
6 +- This module provides command-line skill listing, search, validation, and creation helpers.
7 +- Keep this file-level DOX profile synchronized with `skills_cli.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `skills_cli.py` owns the runtime implementation.
12 +- `skills_cli.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Skill` (no explicit base class)
15 +- Top-level functions:
16 +- `get_skills_dirs() -> List[Path]`: Get all skill directories
17 +- `parse_skill_file(skill_path: Path) -> Optional[Skill]`: Parse a SKILL.md file and return a Skill object
18 +- `list_skills() -> List[Skill]`: List all available skills
19 +- `find_skill(name: str) -> Optional[Skill]`: Find a skill by name
20 +- `search_skills(query: str) -> List[Skill]`: Search skills by name, description, or tags
21 +- `validate_skill(skill: Skill) -> List[str]`: Validate a skill and return list of issues
22 +- `create_skill(name: str, description: str=..., author: str=...) -> Path`: Create a new skill from template
23 +- `print_skill_table(skills: List[Skill])`: Print skills in a formatted table
24 +- `main()`
25 +
26 +## Runtime Contracts
27 +
28 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
29 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
30 +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, secret handling.
31 +- Imported dependency areas include: `argparse`, `dataclasses`, `datetime`, `helpers`, `os`, `pathlib`, `re`, `sys`, `typing`, `yaml`.
32 +
33 +## Key Concepts
34 +
35 +- 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`.
36 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
37 +
38 +## Work Guidance
39 +
40 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
41 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
42 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
43 +
44 +## Verification
45 +
46 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
47 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
48 +
49 +## Child DOX Index
50 +
51 +No child DOX files.
helpers/skills_import.py.dox.md new
+55
@@ -0,0 +1,55 @@
1 +# skills_import.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `skills_import.py` helper module.
6 +- This module plans and imports skill bundles into user, project, or profile scopes.
7 +- Keep this file-level DOX profile synchronized with `skills_import.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `skills_import.py` owns the runtime implementation.
12 +- `skills_import.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ImportPlanItem` (no explicit base class)
15 +- `ImportResult` (no explicit base class)
16 +- Top-level functions:
17 +- `_is_within(child: Path, parent: Path) -> bool`
18 +- `_derive_namespace(source: Path) -> str`
19 +- `_candidate_skill_roots(source_dir: Path) -> List[Path]`: Heuristics to find likely skill roots inside a repo/pack:
20 +- `_unzip_to_temp_dir(zip_path: Path) -> Path`: Extract a zip into a temp folder under tmp/skill_imports (inside Agent Zero base dir).
21 +- `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.
22 +- `_resolve_conflict(dest: Path, policy: ConflictPolicy) -> Tuple[Path, bool]`: Returns (final_dest_path, should_copy).
23 +- `get_project_skills_folder(project_name: str) -> Path`: Get the skills folder path for a project.
24 +- `get_agent_profile_skills_folder(profile_name: str) -> Path`
25 +- `get_project_agent_profile_skills_folder(project_name: str, profile_name: str) -> Path`
26 +- `resolve_skills_destination_root(project_name: Optional[str], agent_profile: Optional[str]) -> Path`
27 +- `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>/...
28 +- Notable constants/configuration names: `PROJECT_SKILLS_DIR`.
29 +
30 +## Runtime Contracts
31 +
32 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
33 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
34 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state.
35 +- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `helpers.skills`, `os`, `pathlib`, `shutil`, `tempfile`, `time`, `typing`, `zipfile`.
36 +
37 +## Key Concepts
38 +
39 +- 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`.
40 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
41 +
42 +## Work Guidance
43 +
44 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
45 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
46 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
47 +
48 +## Verification
49 +
50 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
51 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
52 +
53 +## Child DOX Index
54 +
55 +No child DOX files.
helpers/state_migration.py.dox.md new
+45
@@ -0,0 +1,45 @@
1 +# state_migration.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `state_migration.py` helper module.
6 +- This module moves retired state tree paths to current runtime locations.
7 +- Keep this file-level DOX profile synchronized with `state_migration.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `state_migration.py` owns the runtime implementation.
12 +- `state_migration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `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.
15 +- `_move_path(source: Path, target: Path, migrated: list[str]) -> None`
16 +- `_next_conflict_path(path: Path) -> Path`
17 +- `_remove_empty_dir(path: Path, owner: str, warnings: list[str]) -> None`
18 +- `_same_path(left: Path, right: Path) -> bool`
19 +
20 +## Runtime Contracts
21 +
22 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
23 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
24 +- Observed side-effect areas: filesystem reads, filesystem writes, plugin state, settings/state persistence.
25 +- Imported dependency areas include: `__future__`, `pathlib`, `shutil`.
26 +
27 +## Key Concepts
28 +
29 +- 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`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
35 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
36 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
37 +
38 +## Verification
39 +
40 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
41 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
helpers/state_monitor.py.dox.md new
+59
@@ -0,0 +1,59 @@
1 +# state_monitor.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `state_monitor.py` helper module.
6 +- This module tracks dirty state and connection projections for WebUI sync.
7 +- Keep this file-level DOX profile synchronized with `state_monitor.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `state_monitor.py` owns the runtime implementation.
12 +- `state_monitor.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ConnectionProjection` (no explicit base class)
15 +- `StateMonitor` (no explicit base class)
16 + - `bind_manager(self, manager: 'WsManager', handler_id: str | None=...) -> None`
17 + - `register_sid(self, namespace: str, sid: str) -> None`
18 + - `unregister_sid(self, namespace: str, sid: str) -> None`
19 + - `mark_dirty_all(self, reason: str | None=...) -> None`
20 + - `mark_dirty_for_context(self, context_id: str, reason: str | None=...) -> None`
21 + - `update_projection(self, namespace: str, sid: str, request: StateRequestV1, seq_base: int) -> None`
22 + - `mark_dirty(self, namespace: str, sid: str, reason: str | None=..., wave_id: str | None=...) -> None`
23 +- Top-level functions:
24 +- `get_state_monitor() -> StateMonitor`
25 +- `_reset_state_monitor_for_testing() -> None`
26 +- Notable constants/configuration names: `_STATE_MONITOR_HOLDER`, `_STATE_MONITOR_LOCK`.
27 +
28 +## Runtime Contracts
29 +
30 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
31 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
32 +- Observed side-effect areas: filesystem deletion, WebSocket state, settings/state persistence, scheduler state.
33 +- Imported dependency areas include: `__future__`, `asyncio`, `dataclasses`, `helpers`, `helpers.print_style`, `helpers.state_snapshot`, `helpers.ws`, `helpers.ws_manager`, `os`, `threading`, `time`, `typing`.
34 +
35 +## Key Concepts
36 +
37 +- 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`.
38 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
39 +
40 +## Work Guidance
41 +
42 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
43 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
44 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
45 +
46 +## Verification
47 +
48 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
49 +- Related tests observed by source search:
50 + - `tests/test_model_config_api_keys.py`
51 + - `tests/test_multi_tab_isolation.py`
52 + - `tests/test_state_monitor.py`
53 + - `tests/test_state_sync_handler.py`
54 + - `tests/test_state_sync_welcome_screen.py`
55 + - `tests/test_ws_handlers.py`
56 +
57 +## Child DOX Index
58 +
59 +No child DOX files.
helpers/state_monitor_integration.py.dox.md new
+43
@@ -0,0 +1,43 @@
1 +# state_monitor_integration.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `state_monitor_integration.py` helper module.
6 +- This module bridges dirty-state calls into the shared state monitor.
7 +- Keep this file-level DOX profile synchronized with `state_monitor_integration.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `state_monitor_integration.py` owns the runtime implementation.
12 +- `state_monitor_integration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `mark_dirty_all(reason: str | None=...) -> None`
15 +- `mark_dirty_for_context(context_id: str, reason: str | None=...) -> None`
16 +
17 +## Runtime Contracts
18 +
19 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
20 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
21 +- Observed side-effect areas: settings/state persistence.
22 +- Imported dependency areas include: `__future__`.
23 +
24 +## Key Concepts
25 +
26 +- Important called helpers/classes observed in the source: `get_state_monitor.mark_dirty_all`, `get_state_monitor.mark_dirty_for_context`, `get_state_monitor`.
27 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
28 +
29 +## Work Guidance
30 +
31 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
32 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
33 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
34 +
35 +## Verification
36 +
37 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
38 +- Related tests observed by source search:
39 + - `tests/test_model_config_api_keys.py`
40 +
41 +## Child DOX Index
42 +
43 +No child DOX files.
helpers/state_snapshot.py.dox.md new
+63
@@ -0,0 +1,63 @@
1 +# state_snapshot.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `state_snapshot.py` helper module.
6 +- This module builds and validates typed WebUI state snapshots.
7 +- Keep this file-level DOX profile synchronized with `state_snapshot.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `state_snapshot.py` owns the runtime implementation.
12 +- `state_snapshot.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SnapshotV1` (`TypedDict`)
15 +- `StateRequestV1` (no explicit base class)
16 +- `StateRequestValidationError` (`ValueError`)
17 +- Top-level functions:
18 +- `_annotation_to_isinstance_types(annotation: Any) -> tuple[type, ...]`: Convert type annotation to tuple suitable for isinstance().
19 +- `_build_schema_from_typeddict(td: type) -> dict[str, tuple[type, ...]]`: Extract field names and isinstance-compatible types from TypedDict.
20 +- `validate_snapshot_schema_v1(snapshot: Mapping[str, Any]) -> None`
21 +- `_coerce_non_negative_int(value: Any, default: int=...) -> int`
22 +- `_get_agent_profile_labels() -> dict[str, str]`
23 +- `_apply_agent_profile_metadata(context_data: dict[str, Any], ctx: AgentContext, labels: dict[str, str]) -> None`
24 +- `parse_state_request_payload(payload: Mapping[str, Any]) -> StateRequestV1`
25 +- `_coerce_state_request_inputs(context: Any, log_from: Any, notifications_from: Any, timezone: Any) -> StateRequestV1`
26 +- `advance_state_request_after_snapshot(request: StateRequestV1, snapshot: Mapping[str, Any]) -> StateRequestV1`
27 +- `async build_snapshot_from_request(request: StateRequestV1) -> SnapshotV1`: Build a poll-shaped snapshot for both /poll and state_push.
28 +- `_notify_timezone_changed(previous_timezone: str, current_timezone: str) -> None`
29 +- `async build_snapshot(context: str | None, log_from: int, notifications_from: int, timezone: str | None) -> SnapshotV1`
30 +- Notable constants/configuration names: `_SNAPSHOT_V1_SCHEMA`, `SNAPSHOT_SCHEMA_V1_KEYS`.
31 +
32 +## Runtime Contracts
33 +
34 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
35 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
36 +- Observed side-effect areas: plugin state, settings/state persistence, secret handling, scheduler state.
37 +- Imported dependency areas include: `__future__`, `agent`, `dataclasses`, `helpers.dotenv`, `helpers.localization`, `helpers.task_scheduler`, `pytz`, `types`, `typing`.
38 +
39 +## Key Concepts
40 +
41 +- 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`.
42 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
43 +
44 +## Work Guidance
45 +
46 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
47 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
48 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
49 +
50 +## Verification
51 +
52 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
53 +- Related tests observed by source search:
54 + - `tests/test_multi_tab_isolation.py`
55 + - `tests/test_snapshot_parity.py`
56 + - `tests/test_snapshot_schema_v1.py`
57 + - `tests/test_state_monitor.py`
58 + - `tests/test_state_sync_handler.py`
59 + - `tests/test_state_sync_welcome_screen.py`
60 +
61 +## Child DOX Index
62 +
63 +No child DOX files.
helpers/strings.py.dox.md new
+49
@@ -0,0 +1,49 @@
1 +# strings.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `strings.py` helper module.
6 +- This module sanitizes, formats, truncates, and expands framework string content.
7 +- Keep this file-level DOX profile synchronized with `strings.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `strings.py` owns the runtime implementation.
12 +- `strings.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `sanitize_string(s: str, encoding: str=...) -> str`
15 +- `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]`
16 +- `format_key(key: str) -> str`: Format a key string to be more readable.
17 +- `dict_to_text(d: dict) -> str`
18 +- `truncate_text(text: str, length: int, at_end: bool=..., replacement: str=...) -> str`
19 +- `truncate_text_by_ratio(text: str, threshold: int, replacement: str=..., ratio: float=...) -> str`: Truncate text with replacement at a specified ratio position.
20 +- `replace_file_includes(text: str, placeholder_pattern: str=...) -> str`
21 +
22 +## Runtime Contracts
23 +
24 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
25 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
26 +- Observed side-effect areas: filesystem reads, filesystem deletion.
27 +- Imported dependency areas include: `helpers`, `re`, `sys`, `time`.
28 +
29 +## Key Concepts
30 +
31 +- 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`.
32 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
33 +
34 +## Work Guidance
35 +
36 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
37 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
38 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
39 +
40 +## Verification
41 +
42 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
43 +- Related tests observed by source search:
44 + - `tests/test_model_search.py`
45 + - `tests/test_whatsapp_number_utils.py`
46 +
47 +## Child DOX Index
48 +
49 +No child DOX files.
helpers/subagents.py.dox.md new
+61
@@ -0,0 +1,61 @@
1 +# subagents.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `subagents.py` helper module.
6 +- This module discovers, merges, loads, and saves agent profile definitions.
7 +- Keep this file-level DOX profile synchronized with `subagents.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `subagents.py` owns the runtime implementation.
12 +- `subagents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SubAgentListItem` (`BaseModel`)
15 + - `post_validator(self)`
16 +- `SubAgent` (`SubAgentListItem`)
17 +- Top-level functions:
18 +- `get_agents_list(project_name: str | None=...) -> list[SubAgentListItem]`
19 +- `get_agents_dict(project_name: str | None=...) -> dict[str, SubAgentListItem]`
20 +- `_get_agents_list_from_dir(dir: str, origin: Origin) -> dict[str, SubAgentListItem]`
21 +- `load_agent_data(name: str, project_name: str | None=...) -> SubAgent`
22 +- `save_agent_data(name: str, subagent: SubAgent) -> None`
23 +- `delete_agent_data(name: str) -> None`
24 +- `_load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent | None`
25 +- `_merge_agents(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None`
26 +- `_merge_agent_list_items(base: SubAgentListItem, override: SubAgentListItem) -> SubAgentListItem`
27 +- `get_agents_roots() -> list[str]`
28 +- `get_all_agents_list() -> list[dict[str, str]]`
29 +- `_merge_origins(base: list[Origin], override: list[Origin]) -> list[Origin]`
30 +- `get_default_promp_file_names() -> list[str]`
31 +- `get_available_agents_dict(project_name: str | None) -> dict[str, SubAgentListItem]`
32 +- `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:
33 +- Notable constants/configuration names: `GLOBAL_DIR`, `USER_DIR`, `DEFAULT_AGENTS_DIR`, `USER_AGENTS_DIR`, `PATHS_CACHE_AREA`.
34 +
35 +## Runtime Contracts
36 +
37 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
38 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
39 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence.
40 +- Imported dependency areas include: `helpers`, `json`, `os`, `pydantic`, `typing`.
41 +
42 +## Key Concepts
43 +
44 +- 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`.
45 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
46 +
47 +## Work Guidance
48 +
49 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
50 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
51 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
52 +
53 +## Verification
54 +
55 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
56 +- Related tests observed by source search:
57 + - `tests/test_skills_runtime.py`
58 +
59 +## Child DOX Index
60 +
61 +No child DOX files.
helpers/system_packages.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# system_packages.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `system_packages.py` helper module.
6 +- This module runs apt operations with retry behavior.
7 +- Keep this file-level DOX profile synchronized with `system_packages.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `system_packages.py` owns the runtime implementation.
12 +- `system_packages.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `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.
15 +- `is_apt_lock_error(result: subprocess.CompletedProcess[str]) -> bool`
16 +- Notable constants/configuration names: `APT_LOCK_TIMEOUT_SECONDS`, `APT_LOCK_RETRY_SECONDS`.
17 +
18 +## Runtime Contracts
19 +
20 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
21 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
22 +- Observed side-effect areas: subprocess/runtime control.
23 +- Imported dependency areas include: `__future__`, `subprocess`, `threading`, `time`, `typing`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `threading.RLock`, `lower`, `time.monotonic`, `runner`, `time.sleep`, `is_apt_lock_error`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
33 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
34 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
35 +
36 +## Verification
37 +
38 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
39 +- Related tests observed by source search:
40 + - `tests/test_office_document_store.py`
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
helpers/tailscale_tunnel.py.dox.md new
+64
@@ -0,0 +1,64 @@
1 +# tailscale_tunnel.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `tailscale_tunnel.py` helper module.
6 +- This module implements Tailscale tunnel install and provider lifecycle behavior.
7 +- Keep this file-level DOX profile synchronized with `tailscale_tunnel.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `tailscale_tunnel.py` owns the runtime implementation.
12 +- `tailscale_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `TailscaleTunnel` (`CliTunnelHelper`)
15 + - `stop(self)`
16 +- Top-level functions:
17 +- `tailscale_arch()`
18 +- `tailscale_archive_url()`
19 +- `install_tailscale(notify=...)`
20 +- `resolve_tailscaled_binary(binary_path)`
21 +- `notify_info(notify, message, data=...)`
22 +- `tailscale_socket_args(socket_path=...)`
23 +- `tailscale_command(binary_path, args, socket_path=...)`
24 +- `tailscale_status(binary_path, socket_path=...)`
25 +- `tailscale_funnel_help(binary_path, socket_path=...)`
26 +- `compact_output(lines)`
27 +- `tailscale_daemon_hint(output)`
28 +- `tailscale_daemon_ready(binary_path, socket_path)`
29 +- `read_recent_tailscaled_log()`
30 +- `start_tailscaled(binary_path, notify=...)`
31 +- `stop_managed_tailscaled()`
32 +- `tailscale_up_failure_message(output, timed_out=...)`
33 +- `run_tailscale_up(binary_path, notify=..., timeout=..., socket_path=...)`
34 +- `ensure_tailscale_funnel_command(binary_path, socket_path=...)`
35 +- `ensure_tailscale_ready(binary_path, notify=...)`
36 +- 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`.
37 +
38 +## Runtime Contracts
39 +
40 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
41 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
42 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, WebSocket state, settings/state persistence, tunnel state.
43 +- Imported dependency areas include: `collections`, `flaredantic`, `helpers`, `helpers.cli_tunnel`, `json`, `os`, `pathlib`, `queue`, `re`, `shutil`, `subprocess`, `threading`, `time`, `urllib.parse`, `urllib.request`.
44 +
45 +## Key Concepts
46 +
47 +- 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`.
48 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
49 +
50 +## Work Guidance
51 +
52 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
53 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
54 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
55 +
56 +## Verification
57 +
58 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
59 +- Related tests observed by source search:
60 + - `tests/test_tunnel_remote_link.py`
61 +
62 +## Child DOX Index
63 +
64 +No child DOX files.
helpers/task_scheduler.py.dox.md new
+112
@@ -0,0 +1,112 @@
1 +# task_scheduler.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `task_scheduler.py` helper module.
6 +- This module models, serializes, schedules, runs, and persists scheduled tasks.
7 +- Keep this file-level DOX profile synchronized with `task_scheduler.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `task_scheduler.py` owns the runtime implementation.
12 +- `task_scheduler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `TaskState` (`str`, `Enum`)
15 +- `TaskType` (`str`, `Enum`)
16 +- `TaskSchedule` (`BaseModel`)
17 + - `to_crontab(self) -> str`
18 +- `TaskPlan` (`BaseModel`)
19 + - `create(cls, todo: list[datetime] | None=..., in_progress: datetime | None=..., done: list[datetime] | None=...)`
20 + - `add_todo(self, launch_time: datetime)`
21 + - `set_in_progress(self, launch_time: datetime)`
22 + - `set_done(self, launch_time: datetime)`
23 + - `get_next_launch_time(self) -> datetime | None`
24 + - `should_launch(self) -> datetime | None`
25 +- `BaseTask` (`BaseModel`)
26 + - `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)`
27 + - `check_schedule(self, frequency_seconds: float=...) -> bool`
28 + - `get_next_run(self) -> datetime | None`
29 + - `is_dedicated(self) -> bool`
30 + - `get_next_run_minutes(self) -> int | None`
31 + - `async on_run(self)`
32 + - `async on_finish(self)`
33 + - `async on_error(self, error: str)`
34 +- `AdHocTask` (`BaseTask`)
35 + - `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=...)`
36 + - `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)`
37 +- `ScheduledTask` (`BaseTask`)
38 + - `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=...)`
39 + - `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)`
40 + - `check_schedule(self, frequency_seconds: float=...) -> bool`
41 + - `get_next_run(self) -> datetime | None`
42 +- `PlannedTask` (`BaseTask`)
43 + - `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=...)`
44 + - `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)`
45 + - `check_schedule(self, frequency_seconds: float=...) -> bool`
46 + - `get_next_run(self) -> datetime | None`
47 + - `async on_run(self)`
48 + - `async on_finish(self)`
49 + - `async on_success(self, result: str)`
50 + - `async on_error(self, error: str)`
51 +- `SchedulerTaskList` (`BaseModel`)
52 + - `get(cls) -> 'SchedulerTaskList'`
53 + - `async reload(self) -> 'SchedulerTaskList'`
54 + - `async add_task(self, task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> 'SchedulerTaskList'`
55 + - `async save(self) -> 'SchedulerTaskList'`
56 + - `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`
57 + - `get_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
58 + - `get_tasks_by_context_id(self, context_id: str, only_running: bool=...) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
59 + - `async get_due_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
60 +- `TaskScheduler` (no explicit base class)
61 + - `get(cls) -> 'TaskScheduler'`
62 + - `cancel_running_task(self, task_uuid: str, terminate_thread: bool=...) -> bool`
63 + - `cancel_tasks_by_context(self, context_id: str, terminate_thread: bool=...) -> bool`
64 + - `async reload(self)`
65 + - `get_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
66 + - `get_tasks_by_context_id(self, context_id: str, only_running: bool=...) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
67 + - `async add_task(self, task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> 'TaskScheduler'`
68 + - `async remove_task_by_uuid(self, task_uuid: str) -> 'TaskScheduler'`
69 +- Top-level functions:
70 +- `normalize_schedule_timezone(timezone_name: str | None) -> str`
71 +- `_now() -> datetime`
72 +- `_localize_task_datetime(dt: datetime) -> datetime`
73 +- `serialize_datetime(dt: Optional[datetime]) -> Optional[str]`: Serialize a datetime object to ISO format string in the user's timezone.
74 +- `parse_datetime(dt_str: Optional[str]) -> Optional[datetime]`: Parse ISO format datetime string with timezone awareness.
75 +- `serialize_task_schedule(schedule: TaskSchedule) -> Dict[str, str]`: Convert TaskSchedule to a standardized dictionary format.
76 +- `parse_task_schedule(schedule_data: Dict[str, str]) -> TaskSchedule`: Parse dictionary into TaskSchedule with validation.
77 +- `serialize_task_plan(plan: TaskPlan) -> Dict[str, Any]`: Convert TaskPlan to a standardized dictionary format.
78 +- `parse_task_plan(plan_data: Dict[str, Any]) -> TaskPlan`: Parse dictionary into TaskPlan with validation.
79 +- `serialize_task(task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> Dict[str, Any]`: Standardized serialization for task objects with proper handling of all complex types.
80 +- `serialize_tasks(tasks: list[Union[ScheduledTask, AdHocTask, PlannedTask]]) -> list[Dict[str, Any]]`: Serialize a list of tasks to a list of dictionaries.
81 +- `deserialize_task(task_data: Dict[str, Any], task_class: Optional[Type[T]]=...) -> T`: Deserialize dictionary into appropriate task object with validation.
82 +- Notable constants/configuration names: `SCHEDULER_FOLDER`, `LOCAL_TIMEZONE_ALIASES`, `T`.
83 +
84 +## Runtime Contracts
85 +
86 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
87 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
88 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, settings/state persistence, secret handling, scheduler state.
89 +- 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`.
90 +
91 +## Key Concepts
92 +
93 +- 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`.
94 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
95 +
96 +## Work Guidance
97 +
98 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
99 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
100 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
101 +
102 +## Verification
103 +
104 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
105 +- Related tests observed by source search:
106 + - `tests/test_task_scheduler_timezone.py`
107 + - `tests/test_timezone_regressions.py`
108 + - `tests/test_tool_action_contracts.py`
109 +
110 +## Child DOX Index
111 +
112 +No child DOX files.
helpers/timed_input.py.dox.md new
+40
@@ -0,0 +1,40 @@
1 +# timed_input.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `timed_input.py` helper module.
6 +- This module reads terminal input with timeout handling.
7 +- Keep this file-level DOX profile synchronized with `timed_input.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `timed_input.py` owns the runtime implementation.
12 +- `timed_input.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `timeout_input(prompt, timeout=...)`
15 +
16 +## Runtime Contracts
17 +
18 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
19 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
20 +- Imported dependency areas include: `inputimeout`, `sys`.
21 +
22 +## Key Concepts
23 +
24 +- Important called helpers/classes observed in the source: `inputimeout`.
25 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
26 +
27 +## Work Guidance
28 +
29 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
30 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
31 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
32 +
33 +## Verification
34 +
35 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
36 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
37 +
38 +## Child DOX Index
39 +
40 +No child DOX files.
helpers/tokens.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# tokens.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `tokens.py` helper module.
6 +- This module counts and approximates tokens and trims text to budgets.
7 +- Keep this file-level DOX profile synchronized with `tokens.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `tokens.py` owns the runtime implementation.
12 +- `tokens.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `count_tokens(text: str, encoding_name=...) -> int`
15 +- `approximate_tokens(text: str) -> int`
16 +- `sanitize_embedded_image_data_urls(text: str) -> str`
17 +- `approximate_prompt_tokens(text: str) -> int`
18 +- `trim_to_tokens(text: str, max_tokens: int, direction: Literal['start', 'end'], ellipsis: str=...) -> str`
19 +- Notable constants/configuration names: `APPROX_BUFFER`, `TRIM_BUFFER`, `EMBEDDED_IMAGE_DATA_PLACEHOLDER`, `_EMBEDDED_IMAGE_DATA_URL_PATTERN`.
20 +
21 +## Runtime Contracts
22 +
23 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
24 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
25 +- Observed side-effect areas: secret handling.
26 +- Imported dependency areas include: `re`, `tiktoken`, `typing`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
36 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
37 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
38 +
39 +## Verification
40 +
41 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
42 +- Related tests observed by source search:
43 + - `tests/test_chat_compaction.py`
44 + - `tests/test_default_prompt_budget.py`
45 + - `tests/test_history_compression_wait.py`
46 + - `tests/test_mcp_handler_multimodal.py`
47 + - `tests/test_oauth_codex.py`
48 + - `tests/test_oauth_gemini_api.py`
49 + - `tests/test_oauth_xai_grok.py`
50 + - `tests/test_ws_security.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
helpers/tool.py.dox.md new
+58
@@ -0,0 +1,58 @@
1 +# tool.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `tool.py` helper module.
6 +- This module defines the base agent tool class and response contract.
7 +- Keep this file-level DOX profile synchronized with `tool.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `tool.py` owns the runtime implementation.
12 +- `tool.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Response` (no explicit base class)
15 +- `Tool` (no explicit base class)
16 + - `async execute(self, **kwargs) -> Response`
17 + - `async set_progress(self, content: str | None)`
18 + - `add_progress(self, content: str | None)`
19 + - `async before_execution(self, **kwargs)`
20 + - `async after_execution(self, response: Response, **kwargs)`
21 + - `get_log_object(self)`
22 + - `nice_key(self, key: str)`
23 +
24 +## Runtime Contracts
25 +
26 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
27 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
28 +- `Tool` defines `execute(...)`.
29 +- Observed side-effect areas: settings/state persistence.
30 +- Imported dependency areas include: `abc`, `agent`, `dataclasses`, `helpers.extension`, `helpers.print_style`, `helpers.strings`, `typing`.
31 +
32 +## Key Concepts
33 +
34 +- 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`.
35 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
36 +
37 +## Work Guidance
38 +
39 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
40 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
41 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
42 +
43 +## Verification
44 +
45 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
46 +- Related tests observed by source search:
47 + - `tests/test_a0_connector_prompt_gating.py`
48 + - `tests/test_browser_agent_regressions.py`
49 + - `tests/test_default_prompt_budget.py`
50 + - `tests/test_dirty_json.py`
51 + - `tests/test_document_query_plugin.py`
52 + - `tests/test_fastmcp_openapi_security.py`
53 + - `tests/test_host_browser_connector.py`
54 + - `tests/test_mcp_handler_multimodal.py`
55 +
56 +## Child DOX Index
57 +
58 +No child DOX files.
helpers/tunnel_common.py.dox.md new
+51
@@ -0,0 +1,51 @@
1 +# tunnel_common.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `tunnel_common.py` helper module.
6 +- This module contains shared tunnel provider helper classes and event parsing.
7 +- Keep this file-level DOX profile synchronized with `tunnel_common.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `tunnel_common.py` owns the runtime implementation.
12 +- `tunnel_common.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `TunnelHelper` (no explicit base class)
15 + - `notify_starting(self, label)`
16 + - `notify_url_ready(self, label, url)`
17 + - `notify_stopped(self, label)`
18 +- `FlaredanticTunnelHelper` (`TunnelHelper`)
19 + - `build_tunnel(self)`
20 + - `start(self)`
21 + - `stop(self)`
22 +- Top-level functions:
23 +- `event_value(event)`
24 +
25 +## Runtime Contracts
26 +
27 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
28 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
29 +- Observed side-effect areas: tunnel state.
30 +- Imported dependency areas include: `flaredantic`.
31 +
32 +## Key Concepts
33 +
34 +- 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`.
35 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
36 +
37 +## Work Guidance
38 +
39 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
40 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
41 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
42 +
43 +## Verification
44 +
45 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
46 +- Related tests observed by source search:
47 + - `tests/test_tunnel_remote_link.py`
48 +
49 +## Child DOX Index
50 +
51 +No child DOX files.
helpers/tunnel_manager.py.dox.md new
+51
@@ -0,0 +1,51 @@
1 +# tunnel_manager.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `tunnel_manager.py` helper module.
6 +- This module selects and coordinates configured tunnel providers.
7 +- Keep this file-level DOX profile synchronized with `tunnel_manager.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `tunnel_manager.py` owns the runtime implementation.
12 +- `tunnel_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `TunnelManager` (no explicit base class)
15 + - `get_instance(cls)`
16 + - `get_notifications(self)`
17 + - `get_last_error(self)`
18 + - `start_tunnel(self, port=..., provider=...)`
19 + - `stop_tunnel(self)`
20 + - `get_tunnel_url(self)`
21 +- Top-level functions:
22 +- `normalize_provider(provider)`
23 +- Notable constants/configuration names: `SUPPORTED_TUNNEL_PROVIDERS`, `TUNNEL_PROVIDER_ALIASES`.
24 +
25 +## Runtime Contracts
26 +
27 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
28 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
29 +- Observed side-effect areas: tunnel state.
30 +- 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`.
31 +
32 +## Key Concepts
33 +
34 +- 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`.
35 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
36 +
37 +## Work Guidance
38 +
39 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
40 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
41 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
42 +
43 +## Verification
44 +
45 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
46 +- Related tests observed by source search:
47 + - `tests/test_tunnel_remote_link.py`
48 +
49 +## Child DOX Index
50 +
51 +No child DOX files.
helpers/ui_server.py.dox.md new
+57
@@ -0,0 +1,57 @@
1 +# ui_server.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `ui_server.py` helper module.
6 +- This module configures and owns Flask/WebUI runtime route handlers.
7 +- Keep this file-level DOX profile synchronized with `ui_server.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `ui_server.py` owns the runtime implementation.
12 +- `ui_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `UiServerRuntime` (no explicit base class)
15 + - `create(cls) -> 'UiServerRuntime'`
16 + - `refresh_runtime_settings(self) -> None`
17 + - `register_http_routes(self) -> None`
18 + - `register_transport_handlers(self) -> None`
19 + - `build_asgi_app(self, startup_monitor: StartupMonitor)`
20 + - `access_log_enabled(self) -> bool`
21 +- `UiRouteHandlers` (no explicit base class)
22 + - `async login_handler(self)`
23 + - `async logout_handler(self)`
24 + - `async serve_index(self)`
25 + - `async serve_builtin_plugin_asset(self, plugin_name, asset_path)`
26 + - `async serve_plugin_asset(self, plugin_name, asset_path)`
27 + - `async serve_extension_asset(self, asset_path)`
28 +- Top-level functions:
29 +- `configure_process_environment() -> None`
30 +- Notable constants/configuration names: `UPLOAD_LIMIT_BYTES`.
31 +
32 +## Runtime Contracts
33 +
34 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
35 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
36 +- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, WebSocket state, plugin state, settings/state persistence, secret handling.
37 +- 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`.
38 +
39 +## Key Concepts
40 +
41 +- 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`.
42 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
43 +
44 +## Work Guidance
45 +
46 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
47 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
48 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
49 +
50 +## Verification
51 +
52 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
53 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
54 +
55 +## Child DOX Index
56 +
57 +No child DOX files.
helpers/update_check.py.dox.md new
+41
@@ -0,0 +1,41 @@
1 +# update_check.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `update_check.py` helper module.
6 +- This module checks available Agent Zero updates.
7 +- Keep this file-level DOX profile synchronized with `update_check.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `update_check.py` owns the runtime implementation.
12 +- `update_check.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `async check_version()`
15 +
16 +## Runtime Contracts
17 +
18 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
19 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
20 +- Observed side-effect areas: network calls, settings/state persistence.
21 +- Imported dependency areas include: `hashlib`, `helpers`.
22 +
23 +## Key Concepts
24 +
25 +- 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`.
26 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
27 +
28 +## Work Guidance
29 +
30 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
31 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
32 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
33 +
34 +## Verification
35 +
36 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
37 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
38 +
39 +## Child DOX Index
40 +
41 +No child DOX files.
helpers/vector_db.py.dox.md new
+53
@@ -0,0 +1,53 @@
1 +# vector_db.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `vector_db.py` helper module.
6 +- This module wraps FAISS vector storage, retrieval, and comparator behavior.
7 +- Keep this file-level DOX profile synchronized with `vector_db.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `vector_db.py` owns the runtime implementation.
12 +- `vector_db.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `MyFaiss` (`FAISS`)
15 + - `get_by_ids(self, ids: Sequence[str]) -> List[Document]`
16 + - `async aget_by_ids(self, ids: Sequence[str]) -> List[Document]`
17 + - `get_all_docs(self) -> dict[str, Document]`
18 +- `VectorDB` (no explicit base class)
19 + - `async search_by_similarity_threshold(self, query: str, limit: int, threshold: float, filter: str=...)`
20 + - `async search_by_metadata(self, filter: str, limit: int=...) -> list[Document]`
21 + - `async insert_documents(self, docs: list[Document])`
22 + - `async delete_documents_by_ids(self, ids: list[str])`
23 +- Top-level functions:
24 +- `format_docs_plain(docs: list[Document]) -> list[str]`
25 +- `cosine_normalizer(val: float) -> float`
26 +- `get_comparator(condition: str)`
27 +
28 +## Runtime Contracts
29 +
30 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
31 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
32 +- Observed side-effect areas: filesystem deletion.
33 +- 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`.
34 +
35 +## Key Concepts
36 +
37 +- 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`.
38 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
39 +
40 +## Work Guidance
41 +
42 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
43 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
44 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
45 +
46 +## Verification
47 +
48 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
49 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
50 +
51 +## Child DOX Index
52 +
53 +No child DOX files.
helpers/virtual_desktop.py.dox.md new
+74
@@ -0,0 +1,74 @@
1 +# virtual_desktop.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `virtual_desktop.py` helper module.
6 +- This module registers and proxies virtual desktop sessions.
7 +- Keep this file-level DOX profile synchronized with `virtual_desktop.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `virtual_desktop.py` owns the runtime implementation.
12 +- `virtual_desktop.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `VirtualDesktopEndpoint` (no explicit base class)
15 +- `VirtualDesktopRegistry` (no explicit base class)
16 + - `register(self, endpoint: VirtualDesktopEndpoint) -> None`
17 + - `unregister(self, token: str) -> None`
18 + - `proxy_for_token(self, token: str) -> VirtualDesktopEndpoint | None`
19 + - `resize(self, token: str, width: int, height: int) -> dict[str, Any]`
20 +- Top-level functions:
21 +- `register_session(token: str, host: str, port: int, owner: str=..., title: str=..., resize: ResizeCallback | None=...) -> None`
22 +- `unregister_session(token: str) -> None`
23 +- `proxy_for_token(token: str) -> VirtualDesktopEndpoint | None`
24 +- `resize_session(token: str, width: int, height: int) -> dict[str, Any]`
25 +- `get_registry() -> VirtualDesktopRegistry`
26 +- `session_url(token: str, title: str=...) -> str`
27 +- `collect_status() -> dict[str, Any]`
28 +- `find_xpra_html_root() -> Path | None`
29 +- `_package_installed(package: str) -> bool`
30 +- `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]`
31 +- `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]`
32 +- `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]`
33 +- `_ensure_xrandr_mode(env: dict[str, str], width: int, height: int) -> None`
34 +- `_select_xrandr_mode(env: dict[str, str], width: int, height: int) -> subprocess.CompletedProcess[str]`
35 +- `_xrandr_output_modes(env: dict[str, str]) -> tuple[str, set[str]]`
36 +- `current_display_size(display: int, xauthority: str=..., home: str=...) -> tuple[int, int] | None`
37 +- `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`
38 +- `fit_window(display: int, width: int, height: int, window_class: str=..., keys: tuple[str, ...]=..., xauthority: str=..., home: str=...) -> bool`
39 +- `has_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> bool`
40 +- `find_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> str`
41 +- `close_windows(display: int, names: tuple[str, ...]=..., window_class: str=..., xauthority: str=..., home: str=...) -> int`
42 +- `_find_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> str`
43 +- `_display_env(display: int, xauthority: str=..., home: str=...) -> dict[str, str]`
44 +- 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`.
45 +
46 +## Runtime Contracts
47 +
48 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
49 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
50 +- Observed side-effect areas: filesystem reads, filesystem writes, network calls, subprocess/runtime control, plugin state, settings/state persistence, secret handling.
51 +- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `helpers.localization`, `math`, `os`, `pathlib`, `re`, `shutil`, `subprocess`, `threading`, `time`, `typing`, `urllib.parse`.
52 +
53 +## Key Concepts
54 +
55 +- 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`.
56 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
57 +
58 +## Work Guidance
59 +
60 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
61 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
62 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
63 +
64 +## Verification
65 +
66 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
67 +- Related tests observed by source search:
68 + - `tests/test_office_canvas_setup.py`
69 + - `tests/test_office_desktop_state.py`
70 + - `tests/test_office_document_store.py`
71 +
72 +## Child DOX Index
73 +
74 +No child DOX files.
helpers/virtual_desktop_routes.py.dox.md new
+55
@@ -0,0 +1,55 @@
1 +# virtual_desktop_routes.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `virtual_desktop_routes.py` helper module.
6 +- This module installs virtual desktop gateway route hooks.
7 +- Keep this file-level DOX profile synchronized with `virtual_desktop_routes.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `virtual_desktop_routes.py` owns the runtime implementation.
12 +- `virtual_desktop_routes.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `VirtualDesktopGateway` (no explicit base class)
15 + - `async http(self, scope: Scope, receive: Receive, send: Send) -> None`
16 + - `async resize(self, scope: Scope, receive: Receive, send: Send) -> None`
17 + - `async proxy_http(self, scope: Scope, receive: Receive, send: Send, token: str, upstream_path: str) -> None`
18 + - `async websocket(self, scope: Scope, receive: Receive, send: Send) -> None`
19 + - `async open_websocket(self, endpoint: virtual_desktop.VirtualDesktopEndpoint, target: str, subprotocols: tuple[str, ...]) -> tuple[asyncio.StreamReader, asyncio.StreamWriter, WSConnection, str | None]`
20 + - `async browser_to_xpra(self, websocket: WebSocket, upstream: WSConnection, writer: asyncio.StreamWriter) -> None`
21 + - `async xpra_to_browser(self, websocket: WebSocket, upstream: WSConnection, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None`
22 + - `session_request(self, path: str) -> tuple[str, str] | None`
23 +- Top-level functions:
24 +- `install_route_hooks() -> None`
25 +- `is_installed() -> bool`
26 +- 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`.
27 +
28 +## Runtime Contracts
29 +
30 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
31 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
32 +- Observed side-effect areas: filesystem deletion, network calls, subprocess/runtime control, WebSocket state, settings/state persistence, secret handling.
33 +- 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`.
34 +
35 +## Key Concepts
36 +
37 +- 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`.
38 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
39 +
40 +## Work Guidance
41 +
42 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
43 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
44 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
45 +
46 +## Verification
47 +
48 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
49 +- Related tests observed by source search:
50 + - `tests/test_office_canvas_setup.py`
51 + - `tests/test_office_document_store.py`
52 +
53 +## Child DOX Index
54 +
55 +No child DOX files.
helpers/wait.py.dox.md new
+49
@@ -0,0 +1,49 @@
1 +# wait.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `wait.py` helper module.
6 +- This module formats and runs managed waits with progress updates.
7 +- Keep this file-level DOX profile synchronized with `wait.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `wait.py` owns the runtime implementation.
12 +- `wait.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `format_remaining_time(total_seconds: float) -> str`
15 +- `async managed_wait(agent, target_time, is_duration_wait, log, get_heading_callback)`
16 +
17 +## Runtime Contracts
18 +
19 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
20 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
21 +- Imported dependency areas include: `asyncio`, `helpers.localization`, `helpers.print_style`.
22 +
23 +## Key Concepts
24 +
25 +- 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`.
26 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
27 +
28 +## Work Guidance
29 +
30 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
31 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
32 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
33 +
34 +## Verification
35 +
36 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
37 +- Related tests observed by source search:
38 + - `tests/email_parser_test.py`
39 + - `tests/rate_limiter_test.py`
40 + - `tests/test_api_chat_lifetime.py`
41 + - `tests/test_browser_agent_regressions.py`
42 + - `tests/test_chat_compaction.py`
43 + - `tests/test_default_prompt_budget.py`
44 + - `tests/test_document_query_plugin.py`
45 + - `tests/test_download_toast_regressions.py`
46 +
47 +## Child DOX Index
48 +
49 +No child DOX files.
helpers/watchdog.py.dox.md new
+72
@@ -0,0 +1,72 @@
1 +# watchdog.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `watchdog.py` helper module.
6 +- This module registers filesystem watchdogs with debouncing and path filtering.
7 +- Keep this file-level DOX profile synchronized with `watchdog.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `watchdog.py` owns the runtime implementation.
12 +- `watchdog.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `_DispatchHandler` (no explicit base class)
15 + - `dispatch(self, event: Any)`
16 +- `_Watch` (no explicit base class)
17 +- `_PendingBatch` (no explicit base class)
18 +- `_WatchRegistry` (no explicit base class)
19 + - `add(self, id: str, roots: list[str], patterns: list[str] | None, ignore_patterns: list[str] | None, events: WatchEvents, debounce: float, handler: WatchHandler) -> None`
20 + - `remove(self, id: str) -> bool`
21 + - `clear(self) -> None`
22 + - `start(self) -> None`
23 + - `stop(self) -> None`
24 + - `dispatch(self, scheduled_root: str, event: Any) -> None`
25 +- Top-level functions:
26 +- `_normalize_root(root: str) -> str`
27 +- `_normalize_roots(roots: list[str]) -> list[str]`
28 +- `_normalize_patterns(patterns: list[str] | None, default: list[str] | None=...) -> list[str]`
29 +- `_normalize_events(events: WatchEvents) -> frozenset[WatchEvent]`
30 +- `_map_event_type(event_type: str) -> WatchEvent | None`
31 +- `_normalize_debounce(debounce: float) -> float`
32 +- `_covering_roots(roots: Iterable[str]) -> set[str]`
33 +- `_is_same_or_nested(path: str, root: str) -> bool`
34 +- `_is_under_watch(path: str, watch: _Watch) -> bool`
35 +- `_compile_matcher(root: str, patterns: list[str], ignore_patterns: list[str]) -> PatternMatcher`
36 +- `_compile_single_matcher(root: str, patterns: list[str]) -> PatternMatcher`
37 +- `add_watchdog(id: str, roots: list[str], patterns: list[str] | None=..., ignore_patterns: list[str] | None=..., events: WatchEvents=..., debounce: float=..., handler: WatchHandler | None=...) -> None`
38 +- `remove_watchdog(id: str) -> bool`
39 +- `clear_watchdogs() -> None`
40 +- `start_watchdog_daemon() -> None`
41 +- `stop_watchdog_daemon() -> None`
42 +- Notable constants/configuration names: `_DEFAULT_PATTERNS`, `_DEFAULT_IGNORE_PATTERNS`, `_VALID_EVENTS`, `_EVENT_ALIASES`.
43 +
44 +## Runtime Contracts
45 +
46 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
47 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
48 +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
49 +- Imported dependency areas include: `__future__`, `dataclasses`, `os`, `pathlib`, `threading`, `typing`, `watchdog.observers`.
50 +
51 +## Key Concepts
52 +
53 +- 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`.
54 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
55 +
56 +## Work Guidance
57 +
58 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
59 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
60 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
61 +
62 +## Verification
63 +
64 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
65 +- Related tests observed by source search:
66 + - `tests/test_model_config_api_keys.py`
67 + - `tests/test_model_config_project_presets.py`
68 + - `tests/test_time_travel.py`
69 +
70 +## Child DOX Index
71 +
72 +No child DOX files.
helpers/ws.py.dox.md new
+75
@@ -0,0 +1,75 @@
1 +# ws.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `ws.py` helper module.
6 +- This module defines WebSocket handler registration, origin validation, and security checks.
7 +- Keep this file-level DOX profile synchronized with `ws.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `ws.py` owns the runtime implementation.
12 +- `ws.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ConnectionNotFoundError` (`RuntimeError`)
15 +- `_SecurityContext` (no explicit base class)
16 +- `WsHandler` (no explicit base class)
17 + - `namespace(self) -> str`
18 + - `manager(self) -> 'WsManager'`
19 + - `identifier(self) -> str`
20 + - `bind_manager(self, manager: 'WsManager', namespace: str | None=...) -> None`
21 + - `requires_loopback(cls) -> bool`
22 + - `requires_api_key(cls) -> bool`
23 + - `requires_auth(cls) -> bool`
24 + - `requires_csrf(cls) -> bool`
25 +- Top-level functions:
26 +- `_ws_debug_enabled() -> bool`: Check A0_WS_DEBUG env var - lightweight, no heavy imports.
27 +- `ws_debug(message: str) -> None`: Log *message* via :class:`PrintStyle` when ``A0_WS_DEBUG`` is active.
28 +- `_default_port_for_scheme(scheme: str) -> int | None`
29 +- `normalize_origin(value: Any) -> str | None`: Normalize an Origin/Referer header value to scheme://host[:port].
30 +- `_parse_host_header(value: Any) -> tuple[str | None, int | None]`
31 +- `validate_ws_origin(environ: dict[str, Any]) -> tuple[bool, str | None]`: Validate the browser Origin during the Socket.IO handshake.
32 +- `_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.
33 +- `register_ws_namespace(socketio_server: socketio.AsyncServer, webapp: Flask, lock: ThreadLockType, manager: 'WsManager | None'=...) -> None`
34 +- `_error_response(code: str, message: str, correlation_id: str) -> dict[str, Any]`
35 +- Notable constants/configuration names: `NAMESPACE`, `CACHE_AREA`.
36 +
37 +## Runtime Contracts
38 +
39 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
40 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
41 +- `WsHandler` defines `process(...)`.
42 +- `WsHandler` defines `requires_auth(...)`.
43 +- `WsHandler` defines `requires_csrf(...)`.
44 +- `WsHandler` defines `requires_api_key(...)`.
45 +- `WsHandler` defines `requires_loopback(...)`.
46 +- Observed side-effect areas: filesystem reads, filesystem deletion, network calls, WebSocket state, plugin state, settings/state persistence, secret handling.
47 +- Imported dependency areas include: `abc`, `dataclasses`, `flask`, `helpers`, `helpers.errors`, `helpers.network`, `helpers.print_style`, `os`, `pathlib`, `socketio`, `threading`, `typing`, `urllib.parse`, `uuid`.
48 +
49 +## Key Concepts
50 +
51 +- 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`.
52 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
53 +
54 +## Work Guidance
55 +
56 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
57 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
58 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
59 +
60 +## Verification
61 +
62 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
63 +- Related tests observed by source search:
64 + - `tests/test_a0_connector_computer_use_metadata.py`
65 + - `tests/test_a0_connector_prompt_gating.py`
66 + - `tests/test_browser_agent_regressions.py`
67 + - `tests/test_docker_release_plan.py`
68 + - `tests/test_download_toast_regressions.py`
69 + - `tests/test_git_version_label.py`
70 + - `tests/test_host_browser_connector.py`
71 + - `tests/test_multi_tab_isolation.py`
72 +
73 +## Child DOX Index
74 +
75 +No child DOX files.
helpers/ws_manager.py.dox.md new
+70
@@ -0,0 +1,70 @@
1 +# ws_manager.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `ws_manager.py` helper module.
6 +- This module manages WebSocket connections, event validation, buffering, and dispatch.
7 +- Keep this file-level DOX profile synchronized with `ws_manager.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `ws_manager.py` owns the runtime implementation.
12 +- `ws_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `WsResult` (no explicit base class)
15 + - `ok(cls, data: dict[str, Any] | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'`
16 + - `error(cls, code: str, message: str, details: Any | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'`
17 + - `as_result(self, handler_id: str, fallback_correlation_id: str | None, duration_ms: float | None=...) -> dict[str, Any]`
18 +- `BufferedEvent` (no explicit base class)
19 +- `ConnectionInfo` (no explicit base class)
20 +- `_HandlerExecution` (no explicit base class)
21 +- `WsManager` (no explicit base class)
22 + - `register_diagnostic_watcher(self, namespace: str, sid: str) -> bool`
23 + - `unregister_diagnostic_watcher(self, namespace: str, sid: str) -> None`
24 + - `register_handlers(self, handlers_by_namespace: dict[str, Iterable[WsHandler]]) -> None`
25 + - `iter_namespaces(self) -> list[str]`
26 + - `async process_client_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, handlers: list[WsHandler]) -> dict[str, Any]`
27 + - `async handle_connect(self, namespace: str, sid: str, user_id: str | None=...) -> None`
28 + - `async handle_disconnect(self, namespace: str, sid: str) -> None`
29 + - `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]`
30 +- Top-level functions:
31 +- `validate_event_type(event_type: str) -> str`: Validate an event name: must be lowercase_snake_case and not reserved.
32 +- `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`.
33 +- `_utcnow() -> datetime`
34 +- `set_shared_ws_manager(manager: 'WsManager') -> None`
35 +- `get_shared_ws_manager() -> 'WsManager'`
36 +- 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`.
37 +
38 +## Runtime Contracts
39 +
40 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
41 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
42 +- Observed side-effect areas: filesystem deletion, network calls, WebSocket state, settings/state persistence, scheduler state.
43 +- Imported dependency areas include: `__future__`, `asyncio`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.defer`, `helpers.print_style`, `helpers.ws`, `os`, `re`, `socketio`, `threading`, `time`, `typing`, `uuid`.
44 +
45 +## Key Concepts
46 +
47 +- 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`.
48 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
49 +
50 +## Work Guidance
51 +
52 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
53 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
54 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
55 +
56 +## Verification
57 +
58 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
59 +- Related tests observed by source search:
60 + - `tests/test_browser_agent_regressions.py`
61 + - `tests/test_host_browser_connector.py`
62 + - `tests/test_state_sync_handler.py`
63 + - `tests/test_state_sync_welcome_screen.py`
64 + - `tests/test_tool_action_contracts.py`
65 + - `tests/test_ws_handlers.py`
66 + - `tests/test_ws_manager.py`
67 +
68 +## Child DOX Index
69 +
70 +No child DOX files.
helpers/yaml.py.dox.md new
+52
@@ -0,0 +1,52 @@
1 +# yaml.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `yaml.py` helper module.
6 +- This module wraps YAML loading/dumping and JSON conversion helpers.
7 +- Keep this file-level DOX profile synchronized with `yaml.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `yaml.py` owns the runtime implementation.
12 +- `yaml.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Top-level functions:
14 +- `loads(text: str)`
15 +- `dumps(obj, **kwargs) -> str`
16 +- `from_json(text: str, **yaml_dump_kwargs) -> str`
17 +- `to_json(text: str, **json_dump_kwargs) -> str`
18 +
19 +## Runtime Contracts
20 +
21 +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
22 +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
23 +- Observed side-effect areas: filesystem writes, settings/state persistence.
24 +- Imported dependency areas include: `json`, `yaml`.
25 +
26 +## Key Concepts
27 +
28 +- Important called helpers/classes observed in the source: `yaml.safe_load`, `yaml.safe_dump`, `dumps`, `loads`, `json.dumps`, `json.loads`.
29 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
30 +
31 +## Work Guidance
32 +
33 +- Preserve public helper APIs used by core code and plugins unless every caller is updated.
34 +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
35 +- Prefer adding cohesive helper functions here only when behavior is reused across modules.
36 +
37 +## Verification
38 +
39 +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
40 +- Related tests observed by source search:
41 + - `tests/test_a0_connector_prompt_gating.py`
42 + - `tests/test_browser_agent_regressions.py`
43 + - `tests/test_document_query_plugin.py`
44 + - `tests/test_model_config_api_keys.py`
45 + - `tests/test_model_config_project_presets.py`
46 + - `tests/test_oauth_codex.py`
47 + - `tests/test_oauth_providers.py`
48 + - `tests/test_office_canvas_setup.py`
49 +
50 +## Child DOX Index
51 +
52 +No child DOX files.
plugins/AGENTS.md
+32 -1
@@ -60,4 +60,35 @@
60
61 ## Child DOX Index
62
63 -No child DOX files.
63 +Direct child DOX files:
64 +
65 +| Child | Scope |
66 +| --- | --- |
67 +| [_a0_connector/AGENTS.md](_a0_connector/AGENTS.md) | HTTP and WebSocket connector integration with remote tools and runtime bridges. |
68 +| [_browser/AGENTS.md](_browser/AGENTS.md) | Playwright browser tool, helpers, viewer, and browser panel UI. |
69 +| [_chat_branching/AGENTS.md](_chat_branching/AGENTS.md) | Chat branching from an existing message. |
70 +| [_chat_compaction/AGENTS.md](_chat_compaction/AGENTS.md) | Full-chat compaction into a summary message. |
71 +| [_code_execution/AGENTS.md](_code_execution/AGENTS.md) | Terminal, Python, and Node.js execution tools and shell runtimes. |
72 +| [_desktop/AGENTS.md](_desktop/AGENTS.md) | Linux desktop runtime, sessions, and desktop surface. |
73 +| [_discovery/AGENTS.md](_discovery/AGENTS.md) | Welcome-screen plugin discovery cards and promotions. |
74 +| [_document_query/AGENTS.md](_document_query/AGENTS.md) | Document parsing, indexing, and Q&A tools. |
75 +| [_editor/AGENTS.md](_editor/AGENTS.md) | Native Markdown editor surface and sessions. |
76 +| [_email_integration/AGENTS.md](_email_integration/AGENTS.md) | IMAP/Exchange polling and SMTP reply integration. |
77 +| [_error_retry/AGENTS.md](_error_retry/AGENTS.md) | Critical exception retry lifecycle hooks. |
78 +| [_infection_check/AGENTS.md](_infection_check/AGENTS.md) | Prompt-injection safety analysis before tool execution. |
79 +| [_kokoro_tts/AGENTS.md](_kokoro_tts/AGENTS.md) | Kokoro text-to-speech integration. |
80 +| [_memory/AGENTS.md](_memory/AGENTS.md) | Persistent vector memory, knowledge import, tools, and dashboard. |
81 +| [_model_config/AGENTS.md](_model_config/AGENTS.md) | Model selection, presets, API-key checks, and scoped overrides. |
82 +| [_oauth/AGENTS.md](_oauth/AGENTS.md) | OAuth-backed model-provider connections and local proxy routes. |
83 +| [_office/AGENTS.md](_office/AGENTS.md) | LibreOffice office artifacts and office canvas sessions. |
84 +| [_onboarding/AGENTS.md](_onboarding/AGENTS.md) | First-time model onboarding wizard. |
85 +| [_plugin_installer/AGENTS.md](_plugin_installer/AGENTS.md) | Plugin install and update flows from ZIP, Git, and Plugin Index. |
86 +| [_plugin_scan/AGENTS.md](_plugin_scan/AGENTS.md) | LLM-guided security scanner for third-party plugins. |
87 +| [_plugin_validator/AGENTS.md](_plugin_validator/AGENTS.md) | Plugin manifest, structure, convention, and security validator. |
88 +| [_promptinclude/AGENTS.md](_promptinclude/AGENTS.md) | Promptinclude scanning and prompt injection. |
89 +| [_skills/AGENTS.md](_skills/AGENTS.md) | Active and hidden skill configuration and prompt injection. |
90 +| [_telegram_integration/AGENTS.md](_telegram_integration/AGENTS.md) | Telegram bot integration and per-user chat sessions. |
91 +| [_text_editor/AGENTS.md](_text_editor/AGENTS.md) | Native text read, write, and patch tool. |
92 +| [_time_travel/AGENTS.md](_time_travel/AGENTS.md) | Workspace history, diff, travel, snapshot, and revert flows. |
93 +| [_whatsapp_integration/AGENTS.md](_whatsapp_integration/AGENTS.md) | WhatsApp Baileys bridge integration. |
94 +| [_whisper_stt/AGENTS.md](_whisper_stt/AGENTS.md) | Whisper speech-to-text integration. |
plugins/_a0_connector/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# A0 Connector Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own the current Agent Zero connector plugin for HTTP and WebSocket integration.
6 +- Provide remote execution, text-editing freshness, and connector runtime bridges.
7 +
8 +## Ownership
9 +
10 +- `plugin.yaml` owns plugin metadata and settings scope.
11 +- `api/` owns connector WebSocket and API entry points.
12 +- `helpers/` owns chat context, event bridge, execution config, freshness, version, and WebSocket runtime helpers.
13 +- `tools/`, `prompts/`, `skills/`, `extensions/`, and `webui/` own connector-facing agent and UI contributions.
14 +
15 +## Local Contracts
16 +
17 +- Preserve session-auth and `auth.handlers` activation assumptions.
18 +- Keep remote tool prompts synchronized with remote tool behavior.
19 +- Do not bypass WebSocket authentication or leak connector session data.
20 +
21 +## Work Guidance
22 +
23 +- Coordinate connector runtime changes with API, tools, prompts, and WebUI viewer behavior together.
24 +
25 +## Verification
26 +
27 +- Run connector-specific tests or smoke-test HTTP and `/ws` integration when changing runtime behavior.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
plugins/_browser/AGENTS.md new
+32
@@ -0,0 +1,32 @@
1 +# Browser Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own the built-in Playwright browser tool and WebUI browser viewer.
6 +- Bridge browser automation, page inspection helpers, and browser panel UI.
7 +
8 +## Ownership
9 +
10 +- `plugin.yaml` and `default_config.yaml` own metadata and browser settings defaults.
11 +- `tools/browser.py` owns the agent-facing browser tool.
12 +- `helpers/` owns Playwright runtime, selectors, URL helpers, extension management, and connector runtime logic.
13 +- `api/` owns status, extension, and browser WebSocket handlers.
14 +- `assets/`, `prompts/`, `skills/`, `extensions/`, and `webui/` own browser scripts, prompts, skill guidance, hook contributions, and UI.
15 +
16 +## Local Contracts
17 +
18 +- Keep browser actions safe around external pages, credentials, and user data.
19 +- Preserve Playwright lifecycle cleanup and WebSocket viewer compatibility.
20 +- Do not hardcode user-specific browser paths or secrets.
21 +
22 +## Work Guidance
23 +
24 +- Coordinate tool, helper, and panel changes so browser state shown in the UI matches tool behavior.
25 +
26 +## Verification
27 +
28 +- Smoke-test browser launch, navigation, DOM capture, and WebUI viewer after runtime changes.
29 +
30 +## Child DOX Index
31 +
32 +No child DOX files.
plugins/_chat_branching/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# Chat Branching Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own branching a chat from any existing message.
6 +- Keep log and history trimming behavior consistent when creating a branched conversation.
7 +
8 +## Ownership
9 +
10 +- `plugin.yaml` and `README.md` own metadata and user-facing behavior notes.
11 +- `api/branch_chat.py` owns branch creation, clone, trim, persist, and refresh behavior.
12 +- `extensions/` owns WebUI button injection.
13 +- `webui/` owns plugin thumbnail assets.
14 +
15 +## Local Contracts
16 +
17 +- Preserve UUID-based linking between log entries and history messages.
18 +- Branched chats must include history only up to the selected message.
19 +- Do not mutate the source chat while creating a branch.
20 +
21 +## Work Guidance
22 +
23 +- Coordinate UI button injection with message rendering extension points.
24 +
25 +## Verification
26 +
27 +- Smoke-test branching from several message positions and confirm source chat remains unchanged.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
plugins/_chat_compaction/AGENTS.md new
+32
@@ -0,0 +1,32 @@
1 +# Chat Compaction Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own compacting an entire chat history into a single optimized summary message.
6 +- Keep compaction prompt, helper, API, and modal behavior aligned.
7 +
8 +## Ownership
9 +
10 +- `plugin.yaml` and `default_config.yaml` own metadata and compaction defaults.
11 +- `api/compact_chat.py` owns the compaction endpoint.
12 +- `helpers/compactor.py` owns summary generation and history rewrite logic.
13 +- `prompts/` owns compaction system and message prompts.
14 +- `webui/` owns the compaction modal and store.
15 +
16 +## Local Contracts
17 +
18 +- Preserve chat history integrity and persistence after compaction.
19 +- Keep generated summaries bounded by configured model and token limits.
20 +- Do not discard original context data unless the compaction flow explicitly owns that behavior.
21 +
22 +## Work Guidance
23 +
24 +- Coordinate prompt changes with helper behavior and UI confirmation text.
25 +
26 +## Verification
27 +
28 +- Smoke-test compacting a chat and reloading it after persistence.
29 +
30 +## Child DOX Index
31 +
32 +No child DOX files.
plugins/_code_execution/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Code Execution Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own terminal, Python, and Node.js code execution through persistent local or SSH-backed sessions.
6 +
7 +## Ownership
8 +
9 +- `tools/` owns the code execution and input tools.
10 +- `helpers/` owns local shell, SSH shell, and TTY session management.
11 +- `prompts/` owns execution prompt and runtime response fragments.
12 +- `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own settings, metadata, hooks, and UI config.
13 +
14 +## Local Contracts
15 +
16 +- Keep session concurrency, timeout, streaming, and reset behavior predictable.
17 +- Explicitly target local versus SSH execution runtimes.
18 +- Do not hardcode secrets, SSH credentials, or local user paths.
19 +
20 +## Work Guidance
21 +
22 +- Preserve long-running command output retrieval and busy-session guards when changing execution flow.
23 +
24 +## Verification
25 +
26 +- Smoke-test terminal, Python, Node.js, output polling, and reset paths after tool changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_desktop/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Desktop Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own the Agent Zero Linux desktop runtime, Xpra/Xfce session integration, and live desktop surface.
6 +
7 +## Ownership
8 +
9 +- `helpers/` owns desktop routes, session lifecycle, state, and prompt context.
10 +- `api/desktop_session.py` owns desktop session API behavior.
11 +- `hooks.py` owns route registration and plugin lifecycle hooks.
12 +- `prompts/`, `assets/`, `skills/`, `extensions/`, and `webui/` own desktop context, assets, skill guidance, hooks, and panel UI.
13 +
14 +## Local Contracts
15 +
16 +- Preserve session startup, cleanup, and route protection for desktop access.
17 +- Keep desktop state injected into prompts accurate and bounded.
18 +- Do not expose desktop routes without the expected auth protections.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate runtime and panel changes so live UI reflects actual desktop session state.
23 +
24 +## Verification
25 +
26 +- Smoke-test desktop startup, panel connection, route access, and session cleanup after changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_discovery/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Plugin Discovery DOX
2 +
3 +## Purpose
4 +
5 +- Own contextual plugin discovery cards and welcome-screen promotions.
6 +
7 +## Ownership
8 +
9 +- `plugin.yaml` owns metadata and always-enabled status.
10 +- `extensions/` owns backend or WebUI discovery contributions.
11 +- `webui/discovery-store.js` owns discovery UI state and actions.
12 +
13 +## Local Contracts
14 +
15 +- Discovery cards must be accurate, dismissible where appropriate, and avoid advertising already-complete setup.
16 +- CTA actions must match supported welcome-screen action contracts.
17 +- Keep card IDs unique and plugin-prefixed.
18 +
19 +## Work Guidance
20 +
21 +- Prefer backend status checks before surfacing setup or integration prompts.
22 +
23 +## Verification
24 +
25 +- Smoke-test welcome-screen discovery cards, ordering, dismissal, and CTA behavior after changes.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
plugins/_document_query/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Document Query Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own document loading, parsing, indexing, and Q&A over local and remote documents.
6 +
7 +## Ownership
8 +
9 +- `tools/document_query.py` owns the agent-facing query tool.
10 +- `helpers/` owns fetching, parser routing, indexing, and query orchestration.
11 +- `prompts/` owns document-query tool and optimization prompts.
12 +- `hooks.py`, `default_config.yaml`, `plugin.yaml`, `skills/`, `extensions/`, and `webui/` own dependency bootstrap, settings, metadata, skill guidance, hooks, and UI.
13 +
14 +## Local Contracts
15 +
16 +- Respect configured size, timeout, retry, parser concurrency, and OCR limits.
17 +- Fetch local and remote resources safely and avoid leaking document contents beyond intended prompt/tool use.
18 +- Keep optional dependency installation targeted to the framework runtime.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate parser changes with timeout handling and fallback behavior.
23 +
24 +## Verification
25 +
26 +- Smoke-test representative PDF, text/HTML, image/OCR, and remote-document queries after parser changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_editor/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Editor Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own the native Markdown editor surface for canvas and floating modal workflows.
6 +
7 +## Ownership
8 +
9 +- `api/` owns editor session and WebSocket handlers.
10 +- `helpers/` owns markdown session and open-file context helpers.
11 +- `prompts/` owns agent-visible open-file context.
12 +- `webui/` owns editor panel, preview, store, and main surface.
13 +- `extensions/` owns editor hook contributions.
14 +
15 +## Local Contracts
16 +
17 +- Keep editor session state synchronized across API, WebSocket, and WebUI panel behavior.
18 +- Do not expose unsaved content or local paths beyond intended chat/context surfaces.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate editor preview and session changes with canvas surface registration.
23 +
24 +## Verification
25 +
26 +- Smoke-test opening, editing, previewing, and reconnecting editor sessions after changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_email_integration/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Email Integration Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own communicating with Agent Zero through email inboxes and SMTP replies.
6 +
7 +## Ownership
8 +
9 +- `helpers/handler.py` owns mailbox polling, state, dispatch, routing, and reply flow.
10 +- `helpers/imap_client.py` and `helpers/smtp_client.py` own inbound and outbound mail transports.
11 +- `helpers/dispatcher.py`, `prompts/`, and attachment helpers own routing decisions and message formatting.
12 +- `api/`, `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own tests, settings, metadata, hooks, and config UI.
13 +
14 +## Local Contracts
15 +
16 +- Treat mailbox credentials and downloaded attachments as sensitive.
17 +- Preserve UID/state tracking so restarts do not duplicate old mail.
18 +- Keep SMTP replies threaded and safe around user-visible errors.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate polling, dispatch prompts, and WebUI settings when adding account or routing behavior.
23 +
24 +## Verification
25 +
26 +- Smoke-test connection checks, polling, attachment handling, dispatch routing, and SMTP replies when practical.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_error_retry/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Error Retry Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own retry behavior for unexpected critical exceptions in agent loops.
6 +
7 +## Ownership
8 +
9 +- `extensions/` owns retry counter reset and critical-exception retry hooks.
10 +- `default_config.yaml` owns retry count defaults.
11 +- `webui/config.html` owns settings UI.
12 +- `plugin.yaml` and `README.md` own metadata and behavior notes.
13 +
14 +## Local Contracts
15 +
16 +- Do not retry controlled flow exceptions such as `HandledException` and `RepairableException`.
17 +- Keep retry counts scoped per monologue.
18 +- Preserve clear agent-facing history injection when retrying a critical exception.
19 +
20 +## Work Guidance
21 +
22 +- Keep retry behavior conservative and observable through logs/UI.
23 +
24 +## Verification
25 +
26 +- Test or simulate critical, handled, and repairable exception paths after hook changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_infection_check/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Infection Check Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own prompt-injection safety checks over streamed reasoning/response content before tool execution.
6 +
7 +## Ownership
8 +
9 +- `helpers/checker.py` owns safety analysis orchestration and gate behavior.
10 +- `extensions/` owns stream collection and tool-execution blocking hooks.
11 +- `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own settings, metadata, behavior notes, and config UI.
12 +
13 +## Local Contracts
14 +
15 +- Preserve configured `thoughts` and `complete` analysis modes.
16 +- Tool execution must wait for required safety verdicts.
17 +- Do not log or expose chain-of-thought or sensitive prompt content beyond intended warning flows.
18 +
19 +## Work Guidance
20 +
21 +- Keep termination and clarification loops bounded and explicit.
22 +
23 +## Verification
24 +
25 +- Smoke-test ok, clarify, and terminate verdicts around tool execution after changes.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
plugins/_kokoro_tts/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# Kokoro TTS Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own built-in Kokoro text-to-speech integration and browser TTS fallback coordination.
6 +
7 +## Ownership
8 +
9 +- `api/` owns synthesize and status endpoints.
10 +- `helpers/` owns runtime and migration behavior.
11 +- `hooks.py` owns provider registration/lifecycle behavior.
12 +- `webui/` owns settings and speech UI integration.
13 +- `default_config.yaml`, `plugin.yaml`, and `README.md` own defaults, metadata, and behavior notes.
14 +
15 +## Local Contracts
16 +
17 +- Keep Kokoro dependencies on Docker/bootstrap paths, not opportunistic runtime installs.
18 +- Preserve browser-native fallback when the plugin is disabled or unavailable.
19 +- Do not expose generated speech artifacts outside intended response paths.
20 +
21 +## Work Guidance
22 +
23 +- Coordinate status endpoint behavior with frontend fallback decisions.
24 +
25 +## Verification
26 +
27 +- Smoke-test status, synthesis, configured voice/speed, and disabled fallback behavior after changes.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
plugins/_memory/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# Memory Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own persistent memory, knowledge import, vector indexing, and memory management UI.
6 +
7 +## Ownership
8 +
9 +- `helpers/memory.py` owns FAISS store loading, embedding metadata, and knowledge preload.
10 +- `helpers/knowledge_import.py` and `helpers/memory_consolidation.py` own import and consolidation behavior.
11 +- `tools/` owns memory save/load/delete/forget and behavior adjustment tools.
12 +- `api/` and `webui/` own memory dashboard and knowledge reindex/import flows.
13 +- `prompts/`, `default_config.yaml`, and `plugin.yaml` own memory prompts, defaults, and metadata.
14 +
15 +## Local Contracts
16 +
17 +- Keep memory scoped by configured subdirectory/context.
18 +- Preserve embedding metadata needed to rebuild indexes safely.
19 +- Avoid storing transient action-history noise as durable memory.
20 +
21 +## Work Guidance
22 +
23 +- Coordinate tool, prompt, and consolidation changes so saved memories remain useful and bounded.
24 +
25 +## Verification
26 +
27 +- Smoke-test save, recall, delete, dashboard search/update, and knowledge import/reindex after changes.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
plugins/_model_config/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Model Configuration Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own LLM model selection, presets, API-key checks, scoped overrides, and model settings UI.
6 +
7 +## Ownership
8 +
9 +- `helpers/model_config.py` owns config resolution, presets, overrides, and runtime model object construction.
10 +- `api/` owns model config, override, preset, search, and API-key endpoints.
11 +- `webui/` owns model settings, summaries, switcher, and API-key UI.
12 +- `default_config.yaml`, `default_presets.yaml`, `provider_metadata.yaml`, `hooks.py`, and `plugin.yaml` own defaults, metadata, hooks, and manifest.
13 +
14 +## Local Contracts
15 +
16 +- Preserve global, project, agent, and chat override resolution order.
17 +- Keep provider metadata and API-key checks safe around secrets.
18 +- Coordinate OAuth-backed providers with `_oauth` instead of hardcoding provider-specific auth here.
19 +
20 +## Work Guidance
21 +
22 +- Keep backend model config shape and frontend settings fields synchronized.
23 +
24 +## Verification
25 +
26 +- Run model-config and onboarding-related tests when model provider, preset, or API-key behavior changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_office/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# LibreOffice Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own ODF-first LibreOffice office artifact workflows for Writer, Calc, and Impress files.
6 +
7 +## Ownership
8 +
9 +- `tools/office_artifact.py` owns the agent-facing office artifact tool.
10 +- `helpers/` owns artifact editing, canvas context, document storage, LibreOffice runtime, and presentation writing.
11 +- `api/` owns office session and WebSocket handlers.
12 +- `hooks.py`, `prompts/`, `skills/`, `extensions/`, and `webui/` own lifecycle behavior, prompts, skill guidance, hooks, and office panel UI.
13 +
14 +## Local Contracts
15 +
16 +- Preserve document storage integrity and live session synchronization.
17 +- Keep LibreOffice operations bounded to intended workspaces and artifact paths.
18 +- Do not expose document contents or temporary files beyond intended UI/tool flows.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate tool, session, and panel changes so canvas state reflects document state.
23 +
24 +## Verification
25 +
26 +- Smoke-test creating, editing, previewing, and reconnecting office artifact sessions after changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_onboarding/AGENTS.md new
+28
@@ -0,0 +1,28 @@
1 +# Onboarding Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own the built-in first-time onboarding wizard for model configuration.
6 +
7 +## Ownership
8 +
9 +- `plugin.yaml` owns metadata and always-enabled status.
10 +- `webui/` owns onboarding providers, wizard store, modal/page markup, and thumbnail.
11 +
12 +## Local Contracts
13 +
14 +- Keep onboarding provider choices synchronized with model configuration and provider metadata.
15 +- Do not ask for or expose API keys outside approved settings/API flows.
16 +- Avoid blocking already-configured users with unnecessary onboarding prompts.
17 +
18 +## Work Guidance
19 +
20 +- Coordinate provider changes with `_model_config` and `_oauth` when account-backed providers are involved.
21 +
22 +## Verification
23 +
24 +- Smoke-test first-run onboarding, provider selection, completion, and skip/close behavior after changes.
25 +
26 +## Child DOX Index
27 +
28 +No child DOX files.
plugins/_plugin_installer/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Plugin Installer DOX
2 +
3 +## Purpose
4 +
5 +- Own installing and updating plugins from ZIP uploads, Git repositories, and the community Plugin Index.
6 +
7 +## Ownership
8 +
9 +- `helpers/install.py` owns archive extraction, Git install/update, validation, hook execution, and install finalization.
10 +- `api/plugin_install.py` owns install/update/index API dispatch.
11 +- `webui/` owns Plugin Hub, ZIP, Git, detail, and shared install UI.
12 +- `plugin.yaml` and `README.md` own metadata and behavior notes.
13 +
14 +## Local Contracts
15 +
16 +- Install third-party plugins into `usr/plugins/`, not bundled `plugins/`.
17 +- Reject unsafe archive paths, missing manifests, invalid manifests, and plugin name conflicts.
18 +- Run plugin install hooks and refresh plugin state after successful changes.
19 +
20 +## Work Guidance
21 +
22 +- Keep installer validation aligned with plugin contracts and Plugin Index expectations.
23 +
24 +## Verification
25 +
26 +- Smoke-test ZIP install, Git install, Plugin Hub install, and Git update paths after changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_plugin_scan/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Plugin Scanner DOX
2 +
3 +## Purpose
4 +
5 +- Own LLM-guided security scanning for third-party Agent Zero plugins.
6 +
7 +## Ownership
8 +
9 +- `helpers/prompt.py` owns scan prompt construction from selectable checks.
10 +- `api/` owns scan queue, start, and synchronous run endpoints.
11 +- `webui/` owns scan checks, prompt template, store, UI, and thumbnail.
12 +- `plugin.yaml` and `README.md` own metadata and behavior notes.
13 +
14 +## Local Contracts
15 +
16 +- Keep scan prompts explicit about source handling, security categories, and report expectations.
17 +- Temporary scan contexts must be isolated and cleaned up as intended.
18 +- Do not install or execute scanned plugin code as part of scanning unless explicitly designed and documented.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate check schema changes with prompt builder and frontend selection UI.
23 +
24 +## Verification
25 +
26 +- Smoke-test a synchronous scan and selected-check scan after prompt or API changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_plugin_validator/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Plugin Validator DOX
2 +
3 +## Purpose
4 +
5 +- Own structured validation of Agent Zero plugins against manifest, structure, code-pattern, and security conventions.
6 +
7 +## Ownership
8 +
9 +- `helpers/prompt.py` owns validation prompt construction.
10 +- `api/` owns ZIP preparation, queue, start, and synchronous run endpoints.
11 +- `webui/` owns validation checks, guidance, prompt template, store, UI, and thumbnail.
12 +- `plugin.yaml` and `README.md` own metadata and behavior notes.
13 +
14 +## Local Contracts
15 +
16 +- Keep validation criteria aligned with `plugins/AGENTS.md`, WebUI contracts, and Plugin Index requirements.
17 +- Temporary validation source directories and contexts must be cleaned up as intended.
18 +- Do not confuse runtime `plugin.yaml` with Plugin Index `index.yaml`.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate checklist changes with prompt builder and frontend check selection.
23 +
24 +## Verification
25 +
26 +- Smoke-test local, Git, and ZIP validation paths when API or prompt behavior changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_promptinclude/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Prompt Include Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own automatic prompt injection of persistent behavioral rules and preferences from `*.promptinclude.md` files.
6 +
7 +## Ownership
8 +
9 +- `helpers/scanner.py` owns workspace scanning, ignore handling, token budgeting, and trimming.
10 +- `prompts/` owns prompt-inclusion fragments.
11 +- `extensions/` owns prompt injection hooks.
12 +- `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own defaults, metadata, behavior notes, and settings UI.
13 +
14 +## Local Contracts
15 +
16 +- Respect gitignore-style filtering, per-file budgets, and total token budgets.
17 +- Include only intended promptinclude files from configured workspaces.
18 +- Keep scan result status fields accurate for skipped, cropped, and included files.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate scanner changes with prompt fragments so included content is clearly attributed.
23 +
24 +## Verification
25 +
26 +- Smoke-test include, ignore, crop, and over-budget cases after scanner changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_skills/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# Skills Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own active and hidden skill configuration injected into prompt extras on each turn.
6 +
7 +## Ownership
8 +
9 +- `hooks.py` owns skill prompt injection and plugin lifecycle behavior.
10 +- `api/skills_catalog.py` owns skill catalog access.
11 +- `prompts/agent.system.active_skills.md` owns injected active-skill prompt content.
12 +- `webui/` owns skill settings UI and store.
13 +- `default_config.yaml`, `plugin.yaml`, `README.md`, and `LICENSE` own defaults, metadata, docs, and license.
14 +
15 +## Local Contracts
16 +
17 +- Keep active skill lists bounded by configured caps.
18 +- Store configured skills in normalized portable paths.
19 +- Hidden skills affect catalog/search/load visibility but must not be injected as active prompt content.
20 +
21 +## Work Guidance
22 +
23 +- Coordinate active-skill resolution changes with core skill loading and settings UI.
24 +
25 +## Verification
26 +
27 +- Run skill runtime/catalog tests or smoke-test active, hidden, global, project, and chat-scope behavior after changes.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
plugins/_telegram_integration/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Telegram Integration Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own Telegram bot integration for Agent Zero with polling, webhook, per-user sessions, and file exchange.
6 +
7 +## Ownership
8 +
9 +- `helpers/bot_manager.py` owns bot lifecycle.
10 +- `helpers/handler.py` and `helpers/telegram_client.py` own message routing, replies, and Telegram API interaction.
11 +- `helpers/dependencies.py` and `requirements.txt` own framework-runtime dependency bootstrap.
12 +- `api/`, `prompts/`, `extensions/`, `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own tests/webhook endpoints, prompt fragments, hooks, settings, metadata, docs, and UI.
13 +
14 +## Local Contracts
15 +
16 +- Treat bot tokens, chat IDs, attachments, and user data as sensitive.
17 +- Keep allowed-user, group-mode, project, model, and `/send` controls enforced.
18 +- Install Telegram dependencies into the framework runtime only when required.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate bot lifecycle changes with job-loop hooks and settings reload behavior.
23 +
24 +## Verification
25 +
26 +- Smoke-test connection checks, polling or webhook delivery, per-user context reuse, attachments, and replies when practical.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_text_editor/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Text Editor Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own the native LLM-friendly text editing tool for reading, writing, and patching text files.
6 +
7 +## Ownership
8 +
9 +- `tools/text_editor.py` owns method dispatch and agent-facing tool behavior.
10 +- `helpers/` owns file operations, patch requests, context patching, stale-read tracking, and patch state.
11 +- `prompts/` owns read/write/patch success and error messages.
12 +- `default_config.yaml`, `plugin.yaml`, `README.md`, `extensions/`, and `webui/` own defaults, metadata, docs, hooks, and config UI.
13 +
14 +## Local Contracts
15 +
16 +- Preserve stale-read protection before patch operations.
17 +- Validate patch structures before applying edits.
18 +- Read back changed regions after writes or patches where the tool contract requires confirmation.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate helper changes with prompt responses so the agent receives actionable edit feedback.
23 +
24 +## Verification
25 +
26 +- Smoke-test read, write, patch, stale-read rejection, and error handling after tool changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_time_travel/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Time Travel Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own Agent Zero workspace history, diff inspection, travel, snapshots, and revert for active `/a0/usr` workspaces.
6 +
7 +## Ownership
8 +
9 +- `helpers/time_travel.py` owns history storage, diff, travel, snapshot, preview, and revert mechanics.
10 +- `api/` owns history list, diff, preview, revert, snapshot, and travel endpoints.
11 +- `webui/` owns the time-travel panel, store, main surface, and thumbnail.
12 +- `plugin.yaml` and `extensions/` own metadata and hook contributions.
13 +
14 +## Local Contracts
15 +
16 +- Keep history operations scoped to Agent Zero-owned workspaces.
17 +- Revert and travel operations must avoid unintended writes outside managed workspace paths.
18 +- Preserve enough metadata for clear preview and diff inspection before destructive actions.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate API and UI changes so users can inspect effects before applying travel or revert operations.
23 +
24 +## Verification
25 +
26 +- Smoke-test snapshot, list, diff, preview, travel, and revert flows after changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
plugins/_whatsapp_integration/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# WhatsApp Integration Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own WhatsApp communication through a Baileys-based Node.js bridge.
6 +
7 +## Ownership
8 +
9 +- `helpers/bridge_manager.py` owns bridge lifecycle.
10 +- `helpers/handler.py` and `helpers/wa_client.py` own message routing and bridge API interaction.
11 +- `helpers/storage_paths.py`, attachment helpers, and number utilities own storage, attachment, and phone-number handling.
12 +- `whatsapp-bridge/` owns the Node.js bridge package.
13 +- `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.
14 +
15 +## Local Contracts
16 +
17 +- Treat WhatsApp sessions, QR data, phone numbers, attachments, and bridge state as sensitive.
18 +- Keep allowed-number and group-response controls enforced.
19 +- Do not leave unmanaged bridge services outside plugin-owned runtime paths.
20 +
21 +## Work Guidance
22 +
23 +- Coordinate Node bridge changes with Python bridge client and settings UI.
24 +
25 +## Verification
26 +
27 +- Smoke-test dependency install, bridge start, QR pairing, allowed-number filtering, message routing, and replies when practical.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
plugins/_whisper_stt/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# Whisper STT Plugin DOX
2 +
3 +## Purpose
4 +
5 +- Own built-in Whisper speech-to-text integration, microphone runtime settings, and transcription delivery behavior.
6 +
7 +## Ownership
8 +
9 +- `api/` owns transcribe and status endpoints.
10 +- `helpers/` owns runtime and migration behavior.
11 +- `hooks.py` owns provider registration/lifecycle behavior.
12 +- `webui/` owns settings, main speech UI, store, and styling.
13 +- `default_config.yaml`, `plugin.yaml`, and `README.md` own defaults, metadata, and behavior notes.
14 +
15 +## Local Contracts
16 +
17 +- Keep dependency installation and model bootstrap on Docker/bootstrap paths.
18 +- Preserve configured message mode, language, silence threshold, silence duration, and waiting timeout behavior.
19 +- Do not expose raw audio or transcriptions beyond intended UI/API paths.
20 +
21 +## Work Guidance
22 +
23 +- Coordinate status endpoint behavior with frontend microphone and transcription state.
24 +
25 +## Verification
26 +
27 +- Smoke-test status, transcription, model/language settings, send/draft modes, and silence handling after changes.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
skills/AGENTS.md
+14 -1
@@ -31,4 +31,17 @@
31
32 ## Child DOX Index
33
34 -No child DOX files.
34 +Direct child DOX files:
35 +
36 +| Child | Scope |
37 +| --- | --- |
38 +| [a0-contribute-plugin/AGENTS.md](a0-contribute-plugin/AGENTS.md) | Publishing plugins to the community Plugin Index. |
39 +| [a0-create-agent/AGENTS.md](a0-create-agent/AGENTS.md) | Creating Agent Zero agent profiles. |
40 +| [a0-create-plugin/AGENTS.md](a0-create-plugin/AGENTS.md) | Creating or extending Agent Zero plugins. |
41 +| [a0-debug-plugin/AGENTS.md](a0-debug-plugin/AGENTS.md) | Diagnosing plugin loading, API, frontend, and extension issues. |
42 +| [a0-development/AGENTS.md](a0-development/AGENTS.md) | Broad Agent Zero framework development guidance. |
43 +| [a0-manage-plugin/AGENTS.md](a0-manage-plugin/AGENTS.md) | Plugin install, update, scan, enable, disable, and removal workflows. |
44 +| [a0-plugin-router/AGENTS.md](a0-plugin-router/AGENTS.md) | Routing plugin-related user requests to specialist skills. |
45 +| [a0-review-plugin/AGENTS.md](a0-review-plugin/AGENTS.md) | Full plugin audit workflow and checklists. |
46 +| [build-skill/AGENTS.md](build-skill/AGENTS.md) | Building and improving Agent Zero skills. |
47 +| [scheduled-tasks/AGENTS.md](scheduled-tasks/AGENTS.md) | Managing scheduled, planned, and adhoc tasks. |
skills/a0-contribute-plugin/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Plugin Contribution Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own the workflow for publishing an Agent Zero plugin to the community Plugin Index.
6 +- Keep contribution guidance aligned with current Plugin Hub and `a0-plugins` repository requirements.
7 +
8 +## Ownership
9 +
10 +- `SKILL.md` owns trigger metadata and the contribution procedure.
11 +
12 +## Local Contracts
13 +
14 +- Keep repository, `index.yaml`, manifest, license, validation, and PR guidance current.
15 +- Do not hardcode user credentials, personal repository names, or private URLs.
16 +- Keep handoffs to plugin review and management skills accurate.
17 +
18 +## Work Guidance
19 +
20 +- Update this skill when Plugin Index CI rules, manifest expectations, or submission flow changes.
21 +- Prefer concise command examples that a user can adapt.
22 +
23 +## Verification
24 +
25 +- Manually read `SKILL.md` for broken links, stale paths, and invalid relative references.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
skills/a0-create-agent/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Agent Creation Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own the workflow for creating Agent Zero agent profiles.
6 +- Keep guidance for user, plugin-distributed, and project-scoped profiles accurate.
7 +
8 +## Ownership
9 +
10 +- `SKILL.md` owns trigger metadata, intake flow, profile blueprint schema, and file creation guidance.
11 +
12 +## Local Contracts
13 +
14 +- Default new user profiles to `usr/agents/`, not bundled `agents/`.
15 +- Keep `agent.yaml`, prompt inheritance, tools, and extension guidance synchronized with profile loader behavior.
16 +- Do not encourage storing secrets or provider credentials in profiles.
17 +
18 +## Work Guidance
19 +
20 +- Keep intake lightweight and progressive for user-facing profile creation.
21 +- Update examples when the bundled `_example/` or profile schema changes.
22 +
23 +## Verification
24 +
25 +- Manually read `SKILL.md` for stale paths and blueprint/schema drift.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
skills/a0-create-plugin/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Plugin Creation Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own the workflow for creating, extending, or modifying Agent Zero plugins.
6 +- Keep full-stack plugin conventions accurate for API, tools, extensions, settings UI, and WebUI integration.
7 +
8 +## Ownership
9 +
10 +- `SKILL.md` owns trigger metadata, plugin scaffold guidance, manifest rules, and frontend/backend patterns.
11 +
12 +## Local Contracts
13 +
14 +- New custom plugins must default to `usr/plugins/`.
15 +- Keep plugin manifest, settings, extension layout, Store Gating, and notification guidance synchronized with `plugins/AGENTS.md` and WebUI contracts.
16 +- Do not recommend hardcoding secrets, bypassing auth, or persistent unmanaged side effects.
17 +
18 +## Work Guidance
19 +
20 +- Update this skill when plugin loader, Plugin Hub, settings modal, extension, or WebUI patterns change.
21 +- Keep code examples short and aligned with current helper APIs.
22 +
23 +## Verification
24 +
25 +- Manually read `SKILL.md` for stale paths and broken handoffs to related plugin skills.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
skills/a0-debug-plugin/AGENTS.md new
+28
@@ -0,0 +1,28 @@
1 +# Plugin Debug Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own the troubleshooting workflow for Agent Zero plugin loading, activation, API, frontend, extension, settings, and hook problems.
6 +
7 +## Ownership
8 +
9 +- `SKILL.md` owns diagnostic order, commands, and common failure cases.
10 +
11 +## Local Contracts
12 +
13 +- Keep route formats, import guidance, extension layouts, toggle files, and settings resolution aligned with runtime behavior.
14 +- Do not recommend destructive cleanup unless the user explicitly asks and the target is clear.
15 +- Keep diagnostics safe around secrets and local user data.
16 +
17 +## Work Guidance
18 +
19 +- Add checks when new plugin surfaces or loader failure modes are introduced.
20 +- Prefer targeted commands that identify the first failing layer.
21 +
22 +## Verification
23 +
24 +- Manually read `SKILL.md` for stale commands and plugin path assumptions.
25 +
26 +## Child DOX Index
27 +
28 +No child DOX files.
skills/a0-development/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Development Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own the broad Agent Zero development guide used by agents extending the framework.
6 +- Keep architecture, tools, extensions, API, agents, prompts, projects, and skills guidance in sync with the repository.
7 +
8 +## Ownership
9 +
10 +- `SKILL.md` owns the development overview, path conventions, and implementation references.
11 +
12 +## Local Contracts
13 +
14 +- Keep paths and examples current with source files and DOX contracts.
15 +- Route plugin-specific tasks to the plugin router or specialist plugin skills.
16 +- Do not duplicate long contracts that belong in narrower AGENTS.md files when a reference is enough.
17 +
18 +## Work Guidance
19 +
20 +- Update this skill after durable framework workflow, extension, tool, API, prompt, or profile changes.
21 +- Keep examples operational and compatible with the current helper classes.
22 +
23 +## Verification
24 +
25 +- Manually read `SKILL.md` for stale architecture references and broken related-skill links.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
skills/a0-manage-plugin/AGENTS.md new
+28
@@ -0,0 +1,28 @@
1 +# Plugin Management Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own the workflow for browsing, scanning, installing, updating, enabling, disabling, and uninstalling Agent Zero plugins.
6 +
7 +## Ownership
8 +
9 +- `SKILL.md` owns management routing, Plugin Hub usage, security scan guidance, and lifecycle commands.
10 +
11 +## Local Contracts
12 +
13 +- Keep Plugin Hub URLs, install API behavior, scan expectations, and activation semantics current.
14 +- Warn about third-party plugin execution risk before install workflows.
15 +- Do not recommend unmanaged deletion outside plugin-owned paths.
16 +
17 +## Work Guidance
18 +
19 +- Update this skill when installer, scanner, validator, Plugin Index, or toggle behavior changes.
20 +- Keep diagnostics and install examples consistent with plugin helper APIs.
21 +
22 +## Verification
23 +
24 +- Manually read `SKILL.md` for stale endpoints, paths, and security guidance.
25 +
26 +## Child DOX Index
27 +
28 +No child DOX files.
skills/a0-plugin-router/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Plugin Router Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own routing for Agent Zero plugin-related user requests.
6 +- Keep handoffs to plugin creation, review, contribution, management, and debugging skills accurate.
7 +
8 +## Ownership
9 +
10 +- `SKILL.md` owns intent classification, routing table, and concise plugin system overview.
11 +
12 +## Local Contracts
13 +
14 +- Keep related skill names and responsibilities synchronized with the actual skill directories.
15 +- Keep plugin root, discovery, manifest, and extension layout summaries aligned with `plugins/AGENTS.md`.
16 +- Ask only when plugin intent is ambiguous.
17 +
18 +## Work Guidance
19 +
20 +- Update this skill when plugin lifecycle skills are renamed, added, or reorganized.
21 +- Keep the overview brief enough to serve routing, not replace specialist skills.
22 +
23 +## Verification
24 +
25 +- Manually read `SKILL.md` for stale skill paths and routing gaps.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
skills/a0-review-plugin/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Plugin Review Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own the full audit workflow for Agent Zero plugins.
6 +- Keep manifest, structure, code-pattern, security, and duplicate-detection checks current.
7 +
8 +## Ownership
9 +
10 +- `SKILL.md` owns the review workflow and phase order.
11 +- `checklists.md` owns detailed review criteria loaded when needed.
12 +
13 +## Local Contracts
14 +
15 +- Keep review checks aligned with current plugin contracts, WebUI patterns, and Plugin Index expectations.
16 +- Treat user plugins as `usr/plugins/` artifacts unless explicitly reviewing bundled core plugins.
17 +- Do not expose secrets or private plugin data in review output.
18 +
19 +## Work Guidance
20 +
21 +- Update both `SKILL.md` and `checklists.md` when plugin conventions or security expectations change.
22 +- Keep findings actionable and grouped by review phase.
23 +
24 +## Verification
25 +
26 +- Manually read changed skill files for stale paths, duplicated checks, and broken references.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
skills/build-skill/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Build Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own the workflow for creating, improving, auditing, and refactoring Agent Zero skills.
6 +- Keep skill format guidance aligned with runtime discovery and loading.
7 +
8 +## Ownership
9 +
10 +- `SKILL.md` owns standard skill shape, writing rules, placement rules, and validation guidance.
11 +
12 +## Local Contracts
13 +
14 +- Every skill folder must contain `SKILL.md`.
15 +- Keep frontmatter and directory-shape guidance synchronized with skill loader behavior.
16 +- Prefer plugin-scoped skills when the workflow is owned by a plugin.
17 +
18 +## Work Guidance
19 +
20 +- Update this skill when skill metadata, discovery, or validation behavior changes.
21 +- Keep examples concise and avoid duplicating long reference material in the skill body.
22 +
23 +## Verification
24 +
25 +- Manually read `SKILL.md` for stale test commands and format assumptions.
26 +- Run skill runtime tests when changing skill loader contracts.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
skills/scheduled-tasks/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Scheduled Tasks Skill DOX
2 +
3 +## Purpose
4 +
5 +- Own the workflow for managing Agent Zero scheduled, planned, and adhoc tasks.
6 +- Keep scheduler tool usage and date/time guidance accurate.
7 +
8 +## Ownership
9 +
10 +- `SKILL.md` owns scheduler action descriptions, schedule field guidance, safety rules, and examples.
11 +
12 +## Local Contracts
13 +
14 +- Inspect existing tasks before create, update, delete, or run operations.
15 +- Use cron-like `schedule` fields for recurring tasks and ISO datetimes in `plan` for planned tasks.
16 +- Do not create recursive scheduling prompts or run scheduled tasks unless the user asks.
17 +
18 +## Work Guidance
19 +
20 +- Update this skill when scheduler tool actions, field names, or timezone behavior changes.
21 +- Keep examples valid JSON tool arguments.
22 +
23 +## Verification
24 +
25 +- Manually read `SKILL.md` for stale scheduler action names and date guidance.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
tests/test_dirty_json.py
+39
@@ -54,3 +54,42 @@ def test_completed_remains_true_after_trailing_content() -> None:
54 }
55
56 assert parser.completed is True
57 +
58 +
59 +def test_value_keeps_unescaped_markdown_quotes_until_structural_delimiter() -> None:
60 + payload = (
61 + "{\n"
62 + ' "tool_name": "response",\n'
63 + ' "tool_args": {\n'
64 + ' "text": "The rule:\\n\\n> *"'
65 + 'Create a child AGENTS.md when a folder becomes a boundary."'
66 + '*\\n\\nAdding `css/AGENTS.md` that says *"'
67 + 'this folder contains CSS"'
68 + '* is duplication."\n'
69 + " }\n"
70 + "}"
71 + )
72 +
73 + parsed = DirtyJson.parse_string(payload)
74 +
75 + assert parsed["tool_args"] == {
76 + "text": (
77 + "The rule:\n\n"
78 + '> *"Create a child AGENTS.md when a folder becomes a boundary."*\n\n'
79 + 'Adding `css/AGENTS.md` that says *"this folder contains CSS"* is duplication.'
80 + )
81 + }
82 +
83 +
84 +def test_value_keeps_unescaped_quotes_on_single_line() -> None:
85 + parsed = DirtyJson.parse_string(
86 + '{"text":"He said "hello" before closing","ok":true}'
87 + )
88 +
89 + assert parsed == {"text": 'He said "hello" before closing', "ok": True}
90 +
91 +
92 +def test_value_can_still_end_before_quoted_key_when_comma_is_missing() -> None:
93 + parsed = DirtyJson.parse_string('{"first":"one" "second":"two"}')
94 +
95 + assert parsed == {"first": "one", "second": "two"}
tools/AGENTS.md
+6
@@ -18,17 +18,23 @@
18 - Use `await self.agent.handle_intervention(...)` when a long-running or external result should respect pause/intervention flow.
19 - Sanitize or mask secrets before logging, returning, or storing tool outputs.
20 - Do not perform destructive filesystem or network actions without the tool contract making that behavior explicit.
21 +- 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.
22 +- 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.
23 +- When a tool module is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change.
24 +- Do not leave stale file-level DOX after tool deletion or rename.
25
26 ## Work Guidance
27
28 - Keep tool output concise enough for message history while preserving actionable detail.
29 - Put reusable parsing, provider, filesystem, or network logic in `helpers/`.
30 - Update prompt tool instructions when changing tool names, arguments, or behavior.
31 +- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed tool behavior is described there.
32
33 ## Verification
34
35 - Run targeted tool tests after changing a tool or its prompt contract.
36 - Run prompt/snapshot tests when tool instructions or output shape changes.
37 +- Check file-level documentation coverage with a script or shell loop that verifies each `tools/*.py` has a matching `tools/*.py.dox.md`.
38
39 ## Child DOX Index
40
tools/a2a_chat.py.dox.md new
+51
@@ -0,0 +1,51 @@
1 +# a2a_chat.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `a2a_chat.py` agent tool.
6 +- This module lets the agent message an external A2A agent and extract the assistant reply.
7 +- Keep this file-level DOX profile synchronized with `a2a_chat.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `a2a_chat.py` owns the runtime implementation.
12 +- `a2a_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `A2AChatTool` (`Tool`)
15 + - `async execute(self, **kwargs)`
16 +- Top-level functions:
17 +- `_session_key(agent_url: str) -> str`: Keep root and explicit /a2a URLs in the same conversation cache.
18 +- `_text_from_part(part: Any) -> str`
19 +- `_text_from_message(message: Any) -> str`
20 +- `_extract_latest_assistant_text(task_response: Any) -> str`
21 +- Notable constants/configuration names: `A2A_EMPTY_RESPONSE_ERROR`.
22 +
23 +## Runtime Contracts
24 +
25 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
26 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
27 +- `A2AChatTool` is a `Tool`.
28 +- `A2AChatTool` defines `execute(...)`.
29 +- Observed side-effect areas: filesystem writes, scheduler state.
30 +- Imported dependency areas include: `helpers.fasta2a_client`, `helpers.print_style`, `helpers.tool`, `typing`.
31 +
32 +## Key Concepts
33 +
34 +- 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`.
35 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
36 +
37 +## Work Guidance
38 +
39 +- Keep tool output concise, model-readable, and safe for history persistence.
40 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
41 +- Respect intervention flow for long-running, external, or user-visible operations.
42 +
43 +## Verification
44 +
45 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
46 +- Related tests observed by source search:
47 + - `tests/test_tool_action_contracts.py`
48 +
49 +## Child DOX Index
50 +
51 +No child DOX files.
tools/call_subordinate.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# call_subordinate.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `call_subordinate.py` agent tool.
6 +- This module delegates work to a subordinate Agent Zero profile and returns its result.
7 +- Keep this file-level DOX profile synchronized with `call_subordinate.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `call_subordinate.py` owns the runtime implementation.
12 +- `call_subordinate.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Delegation` (`Tool`)
15 + - `async execute(self, message=..., reset=..., **kwargs)`
16 + - `get_log_object(self)`
17 +
18 +## Runtime Contracts
19 +
20 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
21 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
22 +- `Delegation` is a `Tool`.
23 +- `Delegation` defines `execute(...)`.
24 +- Observed side-effect areas: filesystem writes, settings/state persistence.
25 +- Imported dependency areas include: `agent`, `extensions.python.hist_add_tool_result`, `helpers.tool`, `initialize`.
26 +
27 +## Key Concepts
28 +
29 +- 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`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Keep tool output concise, model-readable, and safe for history persistence.
35 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
36 +- Respect intervention flow for long-running, external, or user-visible operations.
37 +
38 +## Verification
39 +
40 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
41 +- Related tests observed by source search:
42 + - `tests/test_default_prompt_budget.py`
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
tools/document_query.py.dox.md new
+41
@@ -0,0 +1,41 @@
1 +# document_query.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `document_query.py` agent tool.
6 +- This module loads and queries documents through the document query plugin compatibility path.
7 +- Keep this file-level DOX profile synchronized with `document_query.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `document_query.py` owns the runtime implementation.
12 +- `document_query.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +
14 +## Runtime Contracts
15 +
16 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
17 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
18 +- Observed side-effect areas: plugin state.
19 +- Imported dependency areas include: `plugins._document_query.tools.document_query`.
20 +
21 +## Key Concepts
22 +
23 +- This module is primarily declarative or delegates behavior through classes/imported objects.
24 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
25 +
26 +## Work Guidance
27 +
28 +- Keep tool output concise, model-readable, and safe for history persistence.
29 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
30 +- Respect intervention flow for long-running, external, or user-visible operations.
31 +
32 +## Verification
33 +
34 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
35 +- Related tests observed by source search:
36 + - `tests/test_document_query_fallback.py`
37 + - `tests/test_document_query_plugin.py`
38 +
39 +## Child DOX Index
40 +
41 +No child DOX files.
tools/notify_user.py.dox.md new
+44
@@ -0,0 +1,44 @@
1 +# notify_user.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `notify_user.py` agent tool.
6 +- This module sends a user-facing notification from the agent.
7 +- Keep this file-level DOX profile synchronized with `notify_user.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `notify_user.py` owns the runtime implementation.
12 +- `notify_user.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `NotifyUserTool` (`Tool`)
15 + - `async execute(self, **kwargs)`
16 +
17 +## Runtime Contracts
18 +
19 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
20 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
21 +- `NotifyUserTool` is a `Tool`.
22 +- `NotifyUserTool` defines `execute(...)`.
23 +- Imported dependency areas include: `agent`, `helpers.notification`, `helpers.tool`.
24 +
25 +## Key Concepts
26 +
27 +- 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`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Keep tool output concise, model-readable, and safe for history persistence.
33 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
34 +- Respect intervention flow for long-running, external, or user-visible operations.
35 +
36 +## Verification
37 +
38 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
39 +- Related tests observed by source search:
40 + - `tests/test_tool_action_contracts.py`
41 +
42 +## Child DOX Index
43 +
44 +No child DOX files.
tools/response.py.dox.md new
+53
@@ -0,0 +1,53 @@
1 +# response.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `response.py` agent tool.
6 +- This module emits the final or intermediate agent response to the user.
7 +- Keep this file-level DOX profile synchronized with `response.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `response.py` owns the runtime implementation.
12 +- `response.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `ResponseTool` (`Tool`)
15 + - `async execute(self, **kwargs)`
16 + - `async before_execution(self, **kwargs)`
17 + - `async after_execution(self, response, **kwargs)`
18 +
19 +## Runtime Contracts
20 +
21 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
22 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
23 +- `ResponseTool` is a `Tool`.
24 +- `ResponseTool` defines `execute(...)`.
25 +- Imported dependency areas include: `helpers.tool`.
26 +
27 +## Key Concepts
28 +
29 +- Important called helpers/classes observed in the source: `Response`.
30 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
31 +
32 +## Work Guidance
33 +
34 +- Keep tool output concise, model-readable, and safe for history persistence.
35 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
36 +- Respect intervention flow for long-running, external, or user-visible operations.
37 +
38 +## Verification
39 +
40 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
41 +- Related tests observed by source search:
42 + - `tests/chunk_parser_test.py`
43 + - `tests/rate_limiter_test.py`
44 + - `tests/test_browser_agent_regressions.py`
45 + - `tests/test_chat_compaction.py`
46 + - `tests/test_dirty_json.py`
47 + - `tests/test_download_toast_regressions.py`
48 + - `tests/test_fasta2a_client.py`
49 + - `tests/test_fastmcp_openapi_security.py`
50 +
51 +## Child DOX Index
52 +
53 +No child DOX files.
tools/scheduler.py.dox.md new
+63
@@ -0,0 +1,63 @@
1 +# scheduler.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `scheduler.py` agent tool.
6 +- This module creates, updates, lists, runs, waits for, and deletes scheduled/planned/adhoc tasks.
7 +- Keep this file-level DOX profile synchronized with `scheduler.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `scheduler.py` owns the runtime implementation.
12 +- `scheduler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SchedulerTool` (`Tool`)
15 + - `async execute(self, **kwargs)`
16 + - `async list_tasks(self, **kwargs) -> Response`
17 + - `async find_task_by_name(self, **kwargs) -> Response`
18 + - `async show_task(self, **kwargs) -> Response`
19 + - `async run_task(self, **kwargs) -> Response`
20 + - `async delete_task(self, **kwargs) -> Response`
21 + - `async update_task(self, **kwargs) -> Response`
22 + - `async create_scheduled_task(self, **kwargs) -> Response`
23 +- Top-level functions:
24 +- `_current_action(tool: Tool, kwargs: dict) -> str`
25 +- `_normalize_timezone(value: Any) -> str | None`
26 +- `_schedule_timezone(kwargs: dict) -> str | None`
27 +- `_task_schedule_from_input(schedule: Any, timezone: str | None=...) -> TaskSchedule`
28 +- `_validate_task_schedule(task_schedule: TaskSchedule) -> str`
29 +- `_task_plan_from_input(plan: Any) -> tuple[TaskPlan | None, str]`
30 +- Notable constants/configuration names: `DEFAULT_WAIT_TIMEOUT`, `LOCAL_TIMEZONE_ALIASES`.
31 +
32 +## Runtime Contracts
33 +
34 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
35 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
36 +- `SchedulerTool` is a `Tool`.
37 +- `SchedulerTool` defines `execute(...)`.
38 +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
39 +- Imported dependency areas include: `agent`, `asyncio`, `datetime`, `helpers`, `helpers.localization`, `helpers.projects`, `helpers.task_scheduler`, `helpers.tool`, `json`, `pytz`, `random`, `re`, `typing`.
40 +
41 +## Key Concepts
42 +
43 +- 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`.
44 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
45 +
46 +## Work Guidance
47 +
48 +- Keep tool output concise, model-readable, and safe for history persistence.
49 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
50 +- Respect intervention flow for long-running, external, or user-visible operations.
51 +
52 +## Verification
53 +
54 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
55 +- Related tests observed by source search:
56 + - `tests/test_task_scheduler_timezone.py`
57 + - `tests/test_timezone_regressions.py`
58 + - `tests/test_tool_action_contracts.py`
59 + - `tests/test_tool_request_normalization.py`
60 +
61 +## Child DOX Index
62 +
63 +No child DOX files.
tools/search_engine.py.dox.md new
+46
@@ -0,0 +1,46 @@
1 +# search_engine.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `search_engine.py` agent tool.
6 +- This module runs web search through the configured search helper.
7 +- Keep this file-level DOX profile synchronized with `search_engine.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `search_engine.py` owns the runtime implementation.
12 +- `search_engine.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SearchEngine` (`Tool`)
15 + - `async execute(self, query=..., **kwargs)`
16 + - `async searxng_search(self, question)`
17 + - `format_result_searxng(self, result, source)`
18 +- Notable constants/configuration names: `SEARCH_ENGINE_RESULTS`.
19 +
20 +## Runtime Contracts
21 +
22 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
23 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
24 +- `SearchEngine` is a `Tool`.
25 +- `SearchEngine` defines `execute(...)`.
26 +- Imported dependency areas include: `asyncio`, `helpers`, `helpers.errors`, `helpers.print_style`, `helpers.searxng`, `helpers.tool`, `os`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Keep tool output concise, model-readable, and safe for history persistence.
36 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
37 +- Respect intervention flow for long-running, external, or user-visible operations.
38 +
39 +## Verification
40 +
41 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
42 +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
43 +
44 +## Child DOX Index
45 +
46 +No child DOX files.
tools/skills_tool.py.dox.md new
+51
@@ -0,0 +1,51 @@
1 +# skills_tool.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `skills_tool.py` agent tool.
6 +- This module searches, loads, and lists Agent Zero skills for the agent.
7 +- Keep this file-level DOX profile synchronized with `skills_tool.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `skills_tool.py` owns the runtime implementation.
12 +- `skills_tool.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `SkillsTool` (`Tool`)
15 + - `get_log_object(self)`
16 + - `async before_execution(self, **kwargs)`
17 + - `async execute(self, **kwargs) -> Response`
18 +- Top-level functions:
19 +- `max_loaded_skills() -> int`
20 +- Notable constants/configuration names: `DATA_NAME_LOADED_SKILLS`.
21 +
22 +## Runtime Contracts
23 +
24 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
25 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
26 +- `SkillsTool` is a `Tool`.
27 +- `SkillsTool` defines `execute(...)`.
28 +- Observed side-effect areas: filesystem reads, filesystem deletion, settings/state persistence.
29 +- Imported dependency areas include: `__future__`, `helpers`, `helpers.print_style`, `helpers.tool`, `pathlib`, `typing`.
30 +
31 +## Key Concepts
32 +
33 +- 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`.
34 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
35 +
36 +## Work Guidance
37 +
38 +- Keep tool output concise, model-readable, and safe for history persistence.
39 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
40 +- Respect intervention flow for long-running, external, or user-visible operations.
41 +
42 +## Verification
43 +
44 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
45 +- Related tests observed by source search:
46 + - `tests/test_document_query_plugin.py`
47 + - `tests/test_tool_action_contracts.py`
48 +
49 +## Child DOX Index
50 +
51 +No child DOX files.
tools/unknown.py.dox.md new
+48
@@ -0,0 +1,48 @@
1 +# unknown.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `unknown.py` agent tool.
6 +- This module handles unknown or malformed tool-call requests.
7 +- Keep this file-level DOX profile synchronized with `unknown.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `unknown.py` owns the runtime implementation.
12 +- `unknown.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `Unknown` (`Tool`)
15 + - `async execute(self, **kwargs)`
16 +
17 +## Runtime Contracts
18 +
19 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
20 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
21 +- `Unknown` is a `Tool`.
22 +- `Unknown` defines `execute(...)`.
23 +- Imported dependency areas include: `extensions.python.system_prompt._11_tools_prompt`, `helpers.tool`.
24 +
25 +## Key Concepts
26 +
27 +- Important called helpers/classes observed in the source: `Response`, `build_tools_prompt`, `self.agent.read_prompt`.
28 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
29 +
30 +## Work Guidance
31 +
32 +- Keep tool output concise, model-readable, and safe for history persistence.
33 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
34 +- Respect intervention flow for long-running, external, or user-visible operations.
35 +
36 +## Verification
37 +
38 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
39 +- Related tests observed by source search:
40 + - `tests/test_file_tree_visualize.py`
41 + - `tests/test_oauth_providers.py`
42 + - `tests/test_socketio_unknown_namespace.py`
43 + - `tests/test_tunnel_remote_link.py`
44 + - `tests/test_ws_manager.py`
45 +
46 +## Child DOX Index
47 +
48 +No child DOX files.
tools/vision_load.py.dox.md new
+50
@@ -0,0 +1,50 @@
1 +# vision_load.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `vision_load.py` agent tool.
6 +- This module loads images into model-visible content for vision-capable models.
7 +- Keep this file-level DOX profile synchronized with `vision_load.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `vision_load.py` owns the runtime implementation.
12 +- `vision_load.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `VisionLoad` (`Tool`)
15 + - `async execute(self, paths: list[str]=..., **kwargs) -> Response`
16 + - `async after_execution(self, response: Response, **kwargs)`
17 +- Notable constants/configuration names: `TOKENS_ESTIMATE`.
18 +
19 +## Runtime Contracts
20 +
21 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
22 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
23 +- `VisionLoad` is a `Tool`.
24 +- `VisionLoad` defines `execute(...)`.
25 +- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence, secret handling.
26 +- Imported dependency areas include: `helpers`, `helpers.print_style`, `helpers.tool`, `mimetypes`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Keep tool output concise, model-readable, and safe for history persistence.
36 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
37 +- Respect intervention flow for long-running, external, or user-visible operations.
38 +
39 +## Verification
40 +
41 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
42 +- Related tests observed by source search:
43 + - `tests/test_browser_agent_regressions.py`
44 + - `tests/test_host_browser_connector.py`
45 + - `tests/test_office_desktop_state.py`
46 + - `tests/test_vision_load_image_refs.py`
47 +
48 +## Child DOX Index
49 +
50 +No child DOX files.
tools/wait.py.dox.md new
+54
@@ -0,0 +1,54 @@
1 +# wait.py DOX
2 +
3 +## Purpose
4 +
5 +- Own the `wait.py` agent tool.
6 +- This module lets the agent wait for a managed duration while respecting intervention flow.
7 +- Keep this file-level DOX profile synchronized with `wait.py` because this directory is intentionally flat.
8 +
9 +## Ownership
10 +
11 +- `wait.py` owns the runtime implementation.
12 +- `wait.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
13 +- Classes:
14 +- `WaitTool` (`Tool`)
15 + - `async execute(self, **kwargs) -> Response`
16 + - `get_log_object(self)`
17 + - `get_heading(self, text: str=..., done: bool=...)`
18 +
19 +## Runtime Contracts
20 +
21 +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
22 +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
23 +- `WaitTool` is a `Tool`.
24 +- `WaitTool` defines `execute(...)`.
25 +- Observed side-effect areas: settings/state persistence.
26 +- Imported dependency areas include: `asyncio`, `datetime`, `helpers.localization`, `helpers.print_style`, `helpers.tool`, `helpers.wait`.
27 +
28 +## Key Concepts
29 +
30 +- 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`.
31 +- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
32 +
33 +## Work Guidance
34 +
35 +- Keep tool output concise, model-readable, and safe for history persistence.
36 +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
37 +- Respect intervention flow for long-running, external, or user-visible operations.
38 +
39 +## Verification
40 +
41 +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
42 +- Related tests observed by source search:
43 + - `tests/email_parser_test.py`
44 + - `tests/rate_limiter_test.py`
45 + - `tests/test_api_chat_lifetime.py`
46 + - `tests/test_browser_agent_regressions.py`
47 + - `tests/test_chat_compaction.py`
48 + - `tests/test_default_prompt_budget.py`
49 + - `tests/test_document_query_plugin.py`
50 + - `tests/test_download_toast_regressions.py`
51 +
52 +## Child DOX Index
53 +
54 +No child DOX files.
webui/AGENTS.md
+2
@@ -48,3 +48,5 @@ Direct child DOX files:
48 | [components/AGENTS.md](components/AGENTS.md) | Alpine component HTML, component stores, and component-local styles. |
49 | [css/AGENTS.md](css/AGENTS.md) | Shared WebUI stylesheet modules. |
50 | [js/AGENTS.md](js/AGENTS.md) | Shared frontend JavaScript modules and client-side infrastructure. |
51 +| [public/AGENTS.md](public/AGENTS.md) | First-party static WebUI images, icons, splash art, and PWA assets. |
52 +| [vendor/AGENTS.md](vendor/AGENTS.md) | Vendored third-party browser libraries. |
webui/components/AGENTS.md
+18 -1
@@ -56,4 +56,21 @@
56
57 ## Child DOX Index
58
59 -No child DOX files.
59 +Direct child DOX files:
60 +
61 +| Child | Scope |
62 +| --- | --- |
63 +| [_examples/AGENTS.md](_examples/AGENTS.md) | Reference component and store examples. |
64 +| [canvas/AGENTS.md](canvas/AGENTS.md) | Right-canvas component surface and store. |
65 +| [chat/AGENTS.md](chat/AGENTS.md) | Chat composer, attachments, queue, navigation, and top-section components. |
66 +| [dropdown/AGENTS.md](dropdown/AGENTS.md) | Shared dropdown component. |
67 +| [messages/AGENTS.md](messages/AGENTS.md) | Message rendering helpers, action buttons, process groups, and resize behavior. |
68 +| [modals/AGENTS.md](modals/AGENTS.md) | Modal component workflows loaded through the shared modal stack. |
69 +| [notifications/AGENTS.md](notifications/AGENTS.md) | Toasts, notification modal, icons, and notification store. |
70 +| [plugins/AGENTS.md](plugins/AGENTS.md) | Plugin settings, info, list, execution, and toggle components. |
71 +| [projects/AGENTS.md](projects/AGENTS.md) | Project creation, selection, edit, secrets, model, skill, and file-structure components. |
72 +| [settings/AGENTS.md](settings/AGENTS.md) | Settings shell and built-in settings subsections. |
73 +| [sidebar/AGENTS.md](sidebar/AGENTS.md) | Left sidebar layout, chat/task lists, top actions, and preferences. |
74 +| [sync/AGENTS.md](sync/AGENTS.md) | WebUI sync status component and store. |
75 +| [tooltips/AGENTS.md](tooltips/AGENTS.md) | Shared tooltip store and behavior. |
76 +| [welcome/AGENTS.md](welcome/AGENTS.md) | Welcome screen, discovery cards, banners, and welcome state. |
webui/components/_examples/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Component Examples DOX
2 +
3 +## Purpose
4 +
5 +- Own reference component and store examples for WebUI component authors.
6 +
7 +## Ownership
8 +
9 +- `_example-component.html` owns the component markup example.
10 +- `_example-store.js` owns the store pattern example.
11 +
12 +## Local Contracts
13 +
14 +- Keep examples aligned with current component loader, Store Gating, and `createStore` patterns.
15 +- Do not add product behavior or dependencies here.
16 +
17 +## Work Guidance
18 +
19 +- Prefer small examples that demonstrate current conventions clearly.
20 +
21 +## Verification
22 +
23 +- Manually inspect examples after component contract changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
webui/components/canvas/AGENTS.md new
+28
@@ -0,0 +1,28 @@
1 +# Canvas Components DOX
2 +
3 +## Purpose
4 +
5 +- Own the right-canvas component surface and its state.
6 +
7 +## Ownership
8 +
9 +- `right-canvas.html` owns canvas markup.
10 +- `right-canvas-store.js` owns canvas state, surface registration, and actions.
11 +- `right-canvas.css` owns canvas-specific styling.
12 +
13 +## Local Contracts
14 +
15 +- Keep registered surfaces compatible with WebUI extension hooks.
16 +- Preserve responsive layout and avoid overlapping the chat/sidebar shells.
17 +
18 +## Work Guidance
19 +
20 +- Use existing surface and extension helpers before adding new canvas infrastructure.
21 +
22 +## Verification
23 +
24 +- Smoke-test right-canvas open, close, resize, and registered surfaces after changes.
25 +
26 +## Child DOX Index
27 +
28 +No child DOX files.
webui/components/chat/AGENTS.md new
+32
@@ -0,0 +1,32 @@
1 +# Chat Components DOX
2 +
3 +## Purpose
4 +
5 +- Own chat composer, attachments, message queue, navigation, and top-section component groups.
6 +
7 +## Ownership
8 +
9 +- `input/` owns composer input, progress, banners, and bottom action bars.
10 +- `attachments/` owns drag/drop and attachment preview UI.
11 +- `message-queue/` owns queued message display and store state.
12 +- `navigation/` owns chat navigation state.
13 +- `top-section/` owns chat header/top area.
14 +
15 +## Local Contracts
16 +
17 +- Preserve Store Gating for all store-backed chat components.
18 +- Use shared API, WebSocket, notification, and attachment helpers where available.
19 +- Do not bypass CSRF or WebSocket state-sync expectations.
20 +
21 +## Work Guidance
22 +
23 +- Keep composer and attachment changes responsive across desktop and mobile.
24 +- Coordinate payload changes with backend chat, upload, and WebSocket handlers.
25 +
26 +## Verification
27 +
28 +- Smoke-test sending, queued messages, attachments, drag/drop, and navigation after visible changes.
29 +
30 +## Child DOX Index
31 +
32 +No child DOX files.
webui/components/dropdown/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Dropdown Component DOX
2 +
3 +## Purpose
4 +
5 +- Own the shared dropdown component used by WebUI controls.
6 +
7 +## Ownership
8 +
9 +- `dropdown.html` owns dropdown markup, behavior hooks, and component-local styling.
10 +
11 +## Local Contracts
12 +
13 +- Keep keyboard, focus, and click-outside behavior compatible with existing callers.
14 +- Avoid caller-specific assumptions in the shared dropdown.
15 +
16 +## Work Guidance
17 +
18 +- Prefer component attributes and slots over hardcoded option sets.
19 +
20 +## Verification
21 +
22 +- Smoke-test each caller that uses the dropdown after behavior changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
webui/components/messages/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Message Components DOX
2 +
3 +## Purpose
4 +
5 +- Own message rendering helpers, action buttons, process groups, and resize behavior.
6 +
7 +## Ownership
8 +
9 +- `action-buttons/` owns simple message action controls.
10 +- `process-group/` owns grouped process-step DOM and styling helpers.
11 +- `resize/` owns message resize state.
12 +
13 +## Local Contracts
14 +
15 +- Keep message DOM helpers compatible with extension points that modify rendered messages.
16 +- Sanitize or safely render model/user-provided content through shared rendering paths.
17 +- Avoid layout shifts that break long-running message streaming.
18 +
19 +## Work Guidance
20 +
21 +- Coordinate changes with `webui/js/messages.js` and frontend extension hooks.
22 +
23 +## Verification
24 +
25 +- Smoke-test message rendering, action buttons, process groups, and resizing after changes.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
webui/components/modals/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Modal Components DOX
2 +
3 +## Purpose
4 +
5 +- Own WebUI modal component content loaded through the shared modal stack.
6 +
7 +## Ownership
8 +
9 +- Each direct child folder owns one modal workflow and its store.
10 +- Modal HTML files own body content, titles, scoped styles, and `data-modal-footer` content.
11 +- Modal store files own modal-local state and cleanup.
12 +
13 +## Local Contracts
14 +
15 +- Use `openModal(path)` and `closeModal()` from `/js/modals.js`.
16 +- Keep footer content marked with `data-modal-footer` when using pinned modal actions.
17 +- Do not introduce a parallel overlay, backdrop, or teleport modal system.
18 +
19 +## Work Guidance
20 +
21 +- Keep modal state cleanup explicit because stores may outlive DOM nodes.
22 +- Preserve stacked modal, Escape, click-outside, scroll, and footer behavior.
23 +
24 +## Verification
25 +
26 +- Smoke-test open, close, Escape, click-outside, scrolling, stacked modals, and pinned footers after modal changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
webui/components/notifications/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Notification Components DOX
2 +
3 +## Purpose
4 +
5 +- Own WebUI toast, modal, icon, and notification store behavior.
6 +
7 +## Ownership
8 +
9 +- `notification-store.js` owns notification state and public helper actions.
10 +- `notification-toast-stack.html` owns toast rendering.
11 +- `notification-modal.html` owns notification detail modal UI.
12 +- `notification-icons.html` owns shared notification icon markup.
13 +
14 +## Local Contracts
15 +
16 +- Use the notification system for user-facing success, warning, info, and error feedback.
17 +- Keep public helper names stable for core and plugin callers.
18 +- Avoid exposing secrets or raw auth payloads in notification text.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate helper changes with plugin UI contracts and existing frontend imports.
23 +
24 +## Verification
25 +
26 +- Smoke-test toast display, dismiss, modal details, and notification severity styling.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
webui/components/plugins/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Plugin Components DOX
2 +
3 +## Purpose
4 +
5 +- Own core WebUI plugin settings, info, list, execution, and toggle components.
6 +
7 +## Ownership
8 +
9 +- Root plugin component files own shared plugin settings and info screens.
10 +- `list/` owns plugin list and execute modal components.
11 +- `toggle/` owns scoped plugin activation UI.
12 +- Store files own plugin modal and settings state.
13 +
14 +## Local Contracts
15 +
16 +- Keep plugin settings modals bound through `$store.pluginSettingsPrototype` conventions.
17 +- Preserve global and scoped toggle semantics using `.toggle-1` and `.toggle-0`.
18 +- Use notification helpers for plugin UI feedback.
19 +
20 +## Work Guidance
21 +
22 +- Coordinate plugin API payload changes with `helpers/plugins.py` and plugin API handlers.
23 +
24 +## Verification
25 +
26 +- Smoke-test plugin list, settings, scoped toggles, plugin info, and execute modal after changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
webui/components/projects/AGENTS.md new
+30
@@ -0,0 +1,30 @@
1 +# Project Components DOX
2 +
3 +## Purpose
4 +
5 +- Own WebUI project creation, selection, editing, secrets, model, skill, and file-structure components.
6 +
7 +## Ownership
8 +
9 +- `projects-store.js` owns project state and actions.
10 +- `project-create.html`, `project-list.html`, and `project-selector.html` own project creation and navigation UI.
11 +- `project-edit*.html` files own project editing subsections.
12 +- `project-file-structure-test.html` owns file-structure test UI.
13 +
14 +## Local Contracts
15 +
16 +- Keep project API payloads synchronized with backend project handlers.
17 +- Do not expose project secrets in logs, URLs, or long-lived frontend state unnecessarily.
18 +- Preserve scoped settings interactions with plugins, models, and skills.
19 +
20 +## Work Guidance
21 +
22 +- Verify project edit flows when changing shared project store state.
23 +
24 +## Verification
25 +
26 +- Smoke-test create, select, edit, secrets, LLM, skills, and file-structure flows after changes.
27 +
28 +## Child DOX Index
29 +
30 +No child DOX files.
webui/components/settings/AGENTS.md new
+29
@@ -0,0 +1,29 @@
1 +# Settings Components DOX
2 +
3 +## Purpose
4 +
5 +- Own WebUI settings shell and built-in settings subsections.
6 +
7 +## Ownership
8 +
9 +- `settings.html` and `settings-store.js` own the settings shell and state.
10 +- Subdirectories own settings areas such as agent, external, developer, MCP, backup, plugins, secrets, skills, tunnel, and A2A.
11 +
12 +## Local Contracts
13 +
14 +- Keep settings payloads synchronized with backend APIs and plugin settings contracts.
15 +- Do not store secrets in localStorage, URLs, or console output.
16 +- Preserve Store Gating and modal footer conventions in settings components.
17 +
18 +## Work Guidance
19 +
20 +- Prefer subsection-local stores for complex settings areas.
21 +- Coordinate plugin settings UI changes with `webui/components/plugins/` and `plugins/AGENTS.md`.
22 +
23 +## Verification
24 +
25 +- Smoke-test changed settings tabs and save/reload behavior after visible or API changes.
26 +
27 +## Child DOX Index
28 +
29 +No child DOX files.
webui/components/sidebar/AGENTS.md new
+31
@@ -0,0 +1,31 @@
1 +# Sidebar Components DOX
2 +
3 +## Purpose
4 +
5 +- Own left sidebar layout, chat/task lists, top actions, and bottom preferences components.
6 +
7 +## Ownership
8 +
9 +- `left-sidebar.html` and `sidebar-store.js` own sidebar shell and shared state.
10 +- `top-section/` owns header and quick actions.
11 +- `chats/` owns chat list UI and state.
12 +- `tasks/` owns task list UI and state.
13 +- `bottom/` owns lower sidebar controls and preferences panel.
14 +
15 +## Local Contracts
16 +
17 +- Preserve responsive sidebar behavior and collapsed/expanded state.
18 +- Keep chat and task list updates compatible with WebSocket state sync.
19 +- Avoid text or controls overflowing fixed sidebar widths.
20 +
21 +## Work Guidance
22 +
23 +- Coordinate navigation and state changes with WebSocket sync and chat/project stores.
24 +
25 +## Verification
26 +
27 +- Smoke-test sidebar collapse, chat list, task list, quick actions, and preferences after changes.
28 +
29 +## Child DOX Index
30 +
31 +No child DOX files.
webui/components/sync/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Sync Components DOX
2 +
3 +## Purpose
4 +
5 +- Own WebUI state synchronization status UI and store.
6 +
7 +## Ownership
8 +
9 +- `sync-store.js` owns sync status state.
10 +- `sync-status.html` owns sync indicator markup.
11 +
12 +## Local Contracts
13 +
14 +- Keep sync state compatible with WebSocket state-sync events.
15 +- Avoid noisy user-facing alerts for transient sync state unless existing UX expects them.
16 +
17 +## Work Guidance
18 +
19 +- Coordinate sync changes with WebSocket client and backend WebSocket extensions.
20 +
21 +## Verification
22 +
23 +- Smoke-test connection, reconnect, and state refresh indicators after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
webui/components/tooltips/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Tooltip Components DOX
2 +
3 +## Purpose
4 +
5 +- Own shared tooltip state and behavior for WebUI controls.
6 +
7 +## Ownership
8 +
9 +- `tooltip-store.js` owns tooltip state, positioning, and actions.
10 +
11 +## Local Contracts
12 +
13 +- Keep tooltip positioning compatible with desktop and mobile layouts.
14 +- Do not make tooltips required for completing a workflow.
15 +
16 +## Work Guidance
17 +
18 +- Prefer concise tooltip text and stable positioning around icon-only controls.
19 +
20 +## Verification
21 +
22 +- Smoke-test hover/focus tooltip behavior after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.
webui/components/welcome/AGENTS.md new
+28
@@ -0,0 +1,28 @@
1 +# Welcome Components DOX
2 +
3 +## Purpose
4 +
5 +- Own the WebUI welcome screen, discovery cards, banners, and related state.
6 +
7 +## Ownership
8 +
9 +- `welcome-screen.html` owns welcome screen markup and layout.
10 +- `welcome-store.js` owns welcome state, banners, cards, and actions.
11 +
12 +## Local Contracts
13 +
14 +- Keep banner and discovery card behavior compatible with Python `banners` extensions.
15 +- Supported banner/card CTA actions must stay synchronized with plugin discovery contracts.
16 +- Do not show setup prompts for already configured plugins when backend status can prevent it.
17 +
18 +## Work Guidance
19 +
20 +- Coordinate visual card or CTA changes with plugin discovery and onboarding surfaces.
21 +
22 +## Verification
23 +
24 +- Smoke-test alert banners, feature cards, dismissal, priority ordering, and CTA actions after changes.
25 +
26 +## Child DOX Index
27 +
28 +No child DOX files.
webui/public/AGENTS.md new
+32
@@ -0,0 +1,32 @@
1 +# WebUI Public Assets DOX
2 +
3 +## Purpose
4 +
5 +- Own first-party static images, icons, splash art, and PWA assets served by the WebUI.
6 +- Keep visual assets stable for core UI surfaces and settings sections.
7 +
8 +## Ownership
9 +
10 +- SVG files own first-party icons and settings/category symbols.
11 +- Raster files own splash, thumbnail, and app-icon imagery.
12 +- Asset filenames are part of the frontend reference contract when used by HTML, CSS, JS, or plugins.
13 +
14 +## Local Contracts
15 +
16 +- Do not add secrets, user uploads, generated runtime files, or private branding assets here.
17 +- Keep asset paths stable or update every frontend reference in the same change.
18 +- Prefer optimized web formats and reasonable file sizes for assets loaded during startup.
19 +
20 +## Work Guidance
21 +
22 +- Use this folder for shared first-party assets, not component-specific images that belong with a plugin or component.
23 +- Check contrast and legibility for icon changes in both light and dark UI contexts when relevant.
24 +
25 +## Verification
26 +
27 +- Manually smoke-test pages that reference changed assets.
28 +- Run frontend checks when asset references are covered by tests.
29 +
30 +## Child DOX Index
31 +
32 +No child DOX files.
webui/vendor/AGENTS.md new
+42
@@ -0,0 +1,42 @@
1 +# WebUI Vendor Assets DOX
2 +
3 +## Purpose
4 +
5 +- Own vendored third-party browser libraries served by the WebUI.
6 +- Keep external library updates intentional, isolated, and reviewable.
7 +
8 +## Ownership
9 +
10 +- Each direct child directory owns one vendored library or library bundle.
11 +- Vendored files should be treated as upstream artifacts, with local edits avoided unless clearly documented.
12 +
13 +## Local Contracts
14 +
15 +- Do not edit vendored files for application behavior when a wrapper or caller can own the change.
16 +- Preserve license, version, and distribution assumptions for third-party assets.
17 +- Do not add package-manager caches, build outputs, or unrelated downloaded artifacts.
18 +
19 +## Work Guidance
20 +
21 +- Prefer replacing a vendor bundle with a clean upstream build over hand-editing minified files.
22 +- Coordinate library path changes with all HTML, CSS, and JS imports.
23 +
24 +## Verification
25 +
26 +- Manually smoke-test UI paths that load an updated vendor library.
27 +- Run frontend checks when imports or wrappers are covered.
28 +
29 +## Child DOX Index
30 +
31 +Direct child DOX files:
32 +
33 +| Child | Scope |
34 +| --- | --- |
35 +| [_ace/AGENTS.md](_ace/AGENTS.md) | Minimal Ace editor subset used by core editor surfaces. |
36 +| [ace-min/AGENTS.md](ace-min/AGENTS.md) | Full minified Ace distribution and supporting assets. |
37 +| [alpine/AGENTS.md](alpine/AGENTS.md) | Vendored Alpine.js core and collapse plugin. |
38 +| [dompurify/AGENTS.md](dompurify/AGENTS.md) | Vendored DOMPurify sanitizer module. |
39 +| [flatpickr/AGENTS.md](flatpickr/AGENTS.md) | Vendored Flatpickr date/time picker assets. |
40 +| [google/AGENTS.md](google/AGENTS.md) | Vendored Google Material Symbols font and stylesheet. |
41 +| [katex/AGENTS.md](katex/AGENTS.md) | Vendored KaTeX rendering assets. |
42 +| [marked/AGENTS.md](marked/AGENTS.md) | Vendored Marked markdown parser module. |
webui/vendor/_ace/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Ace Minimal Vendor DOX
2 +
3 +## Purpose
4 +
5 +- Own the minimal Ace editor files used by focused WebUI editor flows.
6 +
7 +## Ownership
8 +
9 +- JavaScript mode, theme, worker, and loader files are vendored Ace artifacts.
10 +- `ace.min.css` owns local Ace styling required by the bundled files.
11 +
12 +## Local Contracts
13 +
14 +- Avoid hand-editing Ace source files; replace from a known upstream build when updating.
15 +- Keep filenames stable for existing WebUI imports.
16 +
17 +## Work Guidance
18 +
19 +- Prefer adding only the modes and themes actually needed by core UI surfaces.
20 +
21 +## Verification
22 +
23 +- Smoke-test editor surfaces that load this subset after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
webui/vendor/ace-min/AGENTS.md new
+28
@@ -0,0 +1,28 @@
1 +# Ace Min Vendor DOX
2 +
3 +## Purpose
4 +
5 +- Own the full minified Ace editor distribution and static assets.
6 +
7 +## Ownership
8 +
9 +- `ace.js`, extensions, modes, themes, workers, keybindings, and image assets are vendored Ace artifacts.
10 +
11 +## Local Contracts
12 +
13 +- Treat files as upstream-generated assets.
14 +- Do not hand-edit minified or generated files for product behavior.
15 +- Preserve referenced asset filenames unless all imports are updated.
16 +
17 +## Work Guidance
18 +
19 +- Replace this directory with a clean upstream distribution when updating Ace.
20 +- Keep unrelated generated files and local caches out of this vendor bundle.
21 +
22 +## Verification
23 +
24 +- Smoke-test editor and code-input surfaces after vendor updates.
25 +
26 +## Child DOX Index
27 +
28 +No child DOX files.
webui/vendor/alpine/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Alpine Vendor DOX
2 +
3 +## Purpose
4 +
5 +- Own vendored Alpine.js browser runtime files used by the WebUI.
6 +
7 +## Ownership
8 +
9 +- `alpine.min.js` owns the Alpine core runtime.
10 +- `alpine.collapse.min.js` owns the collapse plugin runtime.
11 +
12 +## Local Contracts
13 +
14 +- Do not modify vendored Alpine runtime files directly.
15 +- Keep load order compatible with `webui/js/initFw.js` and component initialization.
16 +
17 +## Work Guidance
18 +
19 +- Update Alpine as a deliberate vendor bump and smoke-test component lifecycle directives.
20 +
21 +## Verification
22 +
23 +- Smoke-test WebUI startup, component loading, and store initialization after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
webui/vendor/dompurify/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# DOMPurify Vendor DOX
2 +
3 +## Purpose
4 +
5 +- Own the vendored DOMPurify sanitizer module used for safe HTML rendering.
6 +
7 +## Ownership
8 +
9 +- `purify.es.mjs` owns the browser module imported by WebUI sanitization paths.
10 +
11 +## Local Contracts
12 +
13 +- Do not weaken sanitizer behavior through local edits.
14 +- Keep import paths synchronized with markdown and message rendering code.
15 +
16 +## Work Guidance
17 +
18 +- Replace with a clean upstream module when updating.
19 +- Coordinate sanitizer updates with security-sensitive rendering tests.
20 +
21 +## Verification
22 +
23 +- Run or manually exercise HTML/markdown rendering paths after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
webui/vendor/flatpickr/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Flatpickr Vendor DOX
2 +
3 +## Purpose
4 +
5 +- Own vendored Flatpickr date and time picker assets.
6 +
7 +## Ownership
8 +
9 +- `flatpickr.min.js` owns picker runtime behavior.
10 +- `flatpickr.min.css` owns picker vendor styling.
11 +
12 +## Local Contracts
13 +
14 +- Do not hand-edit minified vendor files for application behavior.
15 +- Keep scheduler and date-input imports synchronized with file paths.
16 +
17 +## Work Guidance
18 +
19 +- Replace from a clean upstream release when updating.
20 +
21 +## Verification
22 +
23 +- Smoke-test scheduler or date/time inputs after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
webui/vendor/google/AGENTS.md new
+27
@@ -0,0 +1,27 @@
1 +# Google Icons Vendor DOX
2 +
3 +## Purpose
4 +
5 +- Own vendored Google Material Symbols font and stylesheet assets.
6 +
7 +## Ownership
8 +
9 +- `google-icons.css` owns the font-face and icon class definitions.
10 +- `google-icons.ttf` owns the font binary used by the WebUI.
11 +
12 +## Local Contracts
13 +
14 +- Keep font filenames and CSS references synchronized.
15 +- Do not add unrelated remote font assets or tracking references.
16 +
17 +## Work Guidance
18 +
19 +- Replace font and stylesheet together when updating icon coverage.
20 +
21 +## Verification
22 +
23 +- Smoke-test visible icon surfaces after changes.
24 +
25 +## Child DOX Index
26 +
27 +No child DOX files.
webui/vendor/katex/AGENTS.md new
+28
@@ -0,0 +1,28 @@
1 +# KaTeX Vendor DOX
2 +
3 +## Purpose
4 +
5 +- Own vendored KaTeX assets used for math rendering.
6 +
7 +## Ownership
8 +
9 +- `katex.min.js` owns core rendering behavior.
10 +- `katex.auto-render.min.js` owns auto-render support.
11 +- `katex.min.css` owns KaTeX styling.
12 +
13 +## Local Contracts
14 +
15 +- Do not hand-edit minified vendor files.
16 +- Keep markdown/message rendering imports synchronized with asset paths.
17 +
18 +## Work Guidance
19 +
20 +- Replace from a clean upstream release when updating KaTeX.
21 +
22 +## Verification
23 +
24 +- Smoke-test markdown or message content containing math after changes.
25 +
26 +## Child DOX Index
27 +
28 +No child DOX files.
webui/vendor/marked/AGENTS.md new
+26
@@ -0,0 +1,26 @@
1 +# Marked Vendor DOX
2 +
3 +## Purpose
4 +
5 +- Own the vendored Marked markdown parser module.
6 +
7 +## Ownership
8 +
9 +- `marked.esm.js` owns markdown parsing behavior imported by WebUI rendering code.
10 +
11 +## Local Contracts
12 +
13 +- Do not hand-edit the vendored parser for application behavior.
14 +- Keep parser updates coordinated with sanitization and message rendering expectations.
15 +
16 +## Work Guidance
17 +
18 +- Replace with a clean upstream module when updating.
19 +
20 +## Verification
21 +
22 +- Smoke-test markdown rendering after changes.
23 +
24 +## Child DOX Index
25 +
26 +No child DOX files.