diff --git a/agents/AGENTS.md b/agents/AGENTS.md index cce3cbc96..d2df985b1 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -31,4 +31,13 @@ ## Child DOX Index -No child DOX files. +Direct child DOX files: + +| Child | Scope | +| --- | --- | +| [_example/AGENTS.md](_example/AGENTS.md) | Reference profile demonstrating profile-local prompts, tools, and extensions. | +| [agent0/AGENTS.md](agent0/AGENTS.md) | Main user-facing Agent Zero profile metadata. | +| [default/AGENTS.md](default/AGENTS.md) | Base profile metadata and inherited prompt specifics. | +| [developer/AGENTS.md](developer/AGENTS.md) | Software development specialist profile. | +| [hacker/AGENTS.md](hacker/AGENTS.md) | Cyber security and penetration testing specialist profile. | +| [researcher/AGENTS.md](researcher/AGENTS.md) | Research, data analysis, and reporting specialist profile. | diff --git a/agents/_example/AGENTS.md b/agents/_example/AGENTS.md new file mode 100644 index 000000000..555428ee6 --- /dev/null +++ b/agents/_example/AGENTS.md @@ -0,0 +1,33 @@ +# Example Agent Profile DOX + +## Purpose + +- Own the reference profile used to demonstrate bundled profile layout. +- Show how profile-local prompts, tools, and extensions fit beside `agent.yaml`. + +## Ownership + +- `agent.yaml` owns the example profile metadata. +- `prompts/` owns prompt override examples. +- `tools/` owns profile-local tool examples. +- `extensions/` owns profile-local lifecycle extension examples. + +## Local Contracts + +- Keep this profile generic, minimal, and safe to copy into user or plugin profile work. +- Do not add product behavior here that should live in a real bundled profile. +- Profile-local tools and extensions must follow the same contracts as root tools and extensions. + +## Work Guidance + +- Prefer simple examples that illustrate structure over complex behavior. +- Update related skill guidance when the example profile layout changes. + +## Verification + +- Manually inspect YAML and prompt filenames after edits. +- Run profile-loading tests when changing discovery or profile schema assumptions. + +## Child DOX Index + +No child DOX files. diff --git a/agents/agent0/AGENTS.md b/agents/agent0/AGENTS.md new file mode 100644 index 000000000..65528190a --- /dev/null +++ b/agents/agent0/AGENTS.md @@ -0,0 +1,31 @@ +# Agent 0 Profile DOX + +## Purpose + +- Own the main user-facing Agent Zero profile metadata. +- Keep the primary assistant profile discoverable and distinct from subordinate specialist profiles. + +## Ownership + +- `agent.yaml` owns the profile title, description, and delegation context. +- Prompt behavior is inherited from the default profile unless a local prompt override is added. + +## Local Contracts + +- Keep `Agent 0` suitable as the direct conversation agent for the system. +- Do not add narrow specialist behavior that belongs in `developer/`, `researcher/`, `hacker/`, or a custom user profile. +- Do not store user-specific preferences, provider settings, or secrets in this profile. + +## Work Guidance + +- Keep metadata concise because it appears in profile selection and delegation contexts. +- Coordinate substantial behavior changes with default prompts and WebUI profile selection. + +## Verification + +- Manually inspect `agent.yaml` for valid YAML after edits. +- Run profile-loading tests when changing schema or discovery behavior. + +## Child DOX Index + +No child DOX files. diff --git a/agents/default/AGENTS.md b/agents/default/AGENTS.md new file mode 100644 index 000000000..130d84cc1 --- /dev/null +++ b/agents/default/AGENTS.md @@ -0,0 +1,32 @@ +# Default Agent Profile DOX + +## Purpose + +- Own base profile metadata and default prompt specifics inherited by specialized profiles. +- Provide the shared behavior layer for bundled and custom profiles. + +## Ownership + +- `agent.yaml` owns default profile metadata. +- `agent.system.main.specifics.md` owns default profile-specific system prompt content. +- Additional prompt overrides under this directory become shared defaults unless a child profile overrides them. + +## Local Contracts + +- Keep default behavior broad, framework-compatible, and safe for inheritance. +- Avoid role-specific instructions that belong in specialist profiles. +- Prompt filenames must match the framework prompt override names they target. + +## Work Guidance + +- Prefer small, explicit prompt changes with clear inheritance impact. +- Check bundled specialist profiles after changing default behavior. + +## Verification + +- Manually inspect YAML and prompt rendering assumptions after edits. +- Run prompt/profile tests when changing inherited prompt behavior. + +## Child DOX Index + +No child DOX files. diff --git a/agents/developer/AGENTS.md b/agents/developer/AGENTS.md new file mode 100644 index 000000000..b2d189fff --- /dev/null +++ b/agents/developer/AGENTS.md @@ -0,0 +1,32 @@ +# Developer Agent Profile DOX + +## Purpose + +- Own the bundled software development specialist profile. +- Keep development, debugging, refactoring, and architecture behavior separate from general agent defaults. + +## Ownership + +- `agent.yaml` owns title, description, and delegation context for software development work. +- `prompts/` owns developer-specific prompt overrides when present. +- `extensions/` owns developer-specific lifecycle hooks when present. + +## Local Contracts + +- Keep this profile focused on software engineering tasks. +- Do not hardcode repository-local credentials, paths, or project-specific conventions. +- Prompt overrides must preserve the framework tool-call and response contracts. + +## Work Guidance + +- Align developer behavior with the root engineering and tool contracts. +- Prefer profile prompt edits over core prompt edits when the behavior is specific to development tasks. + +## Verification + +- Manually inspect `agent.yaml` for valid YAML after edits. +- Run prompt/profile tests when changing profile loading or developer prompt behavior. + +## Child DOX Index + +No child DOX files. diff --git a/agents/hacker/AGENTS.md b/agents/hacker/AGENTS.md new file mode 100644 index 000000000..9daeaed00 --- /dev/null +++ b/agents/hacker/AGENTS.md @@ -0,0 +1,31 @@ +# Hacker Agent Profile DOX + +## Purpose + +- Own the bundled cyber security and penetration testing specialist profile. +- Keep security-audit behavior scoped to this profile instead of default agent behavior. + +## Ownership + +- `agent.yaml` owns title, description, and delegation context for security work. +- `prompts/` owns security-specific prompt overrides when present. + +## Local Contracts + +- Keep the profile focused on authorized security analysis, vulnerability research, and defensive audit tasks. +- Do not add secrets, target-specific credentials, or local environment assumptions. +- Preserve the framework tool-call contract and safety expectations. + +## Work Guidance + +- Keep security instructions operational and bounded to legitimate testing contexts. +- Coordinate broad safety changes with core prompts and relevant tests. + +## Verification + +- Manually inspect `agent.yaml` for valid YAML after edits. +- Run prompt/profile tests when changing profile discovery or security prompt behavior. + +## Child DOX Index + +No child DOX files. diff --git a/agents/researcher/AGENTS.md b/agents/researcher/AGENTS.md new file mode 100644 index 000000000..e6ba59c70 --- /dev/null +++ b/agents/researcher/AGENTS.md @@ -0,0 +1,31 @@ +# Researcher Agent Profile DOX + +## Purpose + +- Own the bundled research, data analysis, and reporting specialist profile. +- Keep evidence-gathering and report-oriented behavior separate from general defaults. + +## Ownership + +- `agent.yaml` owns title, description, and delegation context for research work. +- `prompts/` owns researcher-specific prompt overrides when present. + +## Local Contracts + +- Keep this profile focused on information gathering, analysis, synthesis, and reporting. +- Do not bake in project-specific sources, credentials, or local paths. +- Preserve the framework tool-call and response contracts. + +## Work Guidance + +- Prefer prompt changes that improve citation, evidence handling, and analysis quality for research tasks. +- Coordinate broad research behavior changes with document, memory, or browser plugin contracts when relevant. + +## Verification + +- Manually inspect `agent.yaml` for valid YAML after edits. +- Run prompt/profile tests when changing discovery or researcher prompt behavior. + +## Child DOX Index + +No child DOX files. diff --git a/api/AGENTS.md b/api/AGENTS.md index 7e471b399..02344d435 100644 --- a/api/AGENTS.md +++ b/api/AGENTS.md @@ -19,17 +19,23 @@ - Keep CSRF and authentication protections intact for browser-facing state-changing endpoints. - WebSocket handlers must derive from `helpers.ws.WsHandler` and validate event data before using it. - Do not return secrets, raw environment values, private files, or unfiltered exception details to clients. +- This directory is a file-documented DOX profile: every direct `*.py` endpoint or WebSocket module must have a same-directory `*.py.dox.md` file named by appending `.dox.md` to the full Python filename. +- The `*.py.dox.md` file owns endpoint purpose, request/response concepts, auth/CSRF/API-key/loopback assumptions, side effects, important helper dependencies, and verification guidance. +- When a Python endpoint is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change. +- Do not leave stale file-level DOX after endpoint deletion or rename. ## Work Guidance - Use helpers for shared behavior instead of duplicating persistence, auth, file, project, plugin, or notification logic in endpoints. - Keep request and response payloads stable; update frontend callers and tests together when payloads change. - Prefer `Response` for files, redirects, status codes, and plain-text errors; return dictionaries for JSON success payloads. +- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed endpoint behavior is described there. ## Verification - Run targeted `pytest tests/test_*api*.py`, endpoint-specific tests, or WebSocket tests after changing handler behavior. - For auth, CSRF, upload/download, tunnel, or file endpoints, run the nearest security regression tests. +- Check file-level documentation coverage with a script or shell loop that verifies each `api/*.py` has a matching `api/*.py.dox.md`. ## Child DOX Index diff --git a/api/agent_profile_set.py.dox.md b/api/agent_profile_set.py.dox.md new file mode 100644 index 000000000..845ee9b1d --- /dev/null +++ b/api/agent_profile_set.py.dox.md @@ -0,0 +1,46 @@ +# agent_profile_set.py DOX + +## Purpose + +- Own the `agent_profile_set.py` API endpoint. +- This module sets the active agent profile for a chat context and returns profile label metadata. +- Keep this file-level DOX profile synchronized with `agent_profile_set.py` because this directory is intentionally flat. + +## Ownership + +- `agent_profile_set.py` owns the runtime implementation. +- `agent_profile_set.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SetAgentProfile` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` +- Top-level functions: +- `_agent_profile_labels() -> dict[str, str]` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SetAgentProfile` is an `ApiHandler`. +- `SetAgentProfile` defines `process(...)`. +- Observed side-effect areas: filesystem writes, settings/state persistence. +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.persist_chat`, `helpers.state_monitor_integration`, `initialize`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `str.strip`, `context.is_running`, `_agent_profile_labels`, `initialize_agent`, `save_tmp_chat`, `mark_dirty_for_context`, `subagents.get_all_agents_list`, `Response`, `agent.get_data`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/agents.py.dox.md b/api/agents.py.dox.md new file mode 100644 index 000000000..e7f6895ac --- /dev/null +++ b/api/agents.py.dox.md @@ -0,0 +1,48 @@ +# agents.py DOX + +## Purpose + +- Own the `agents.py` API endpoint. +- This module lists available agent profiles for selection and delegation UI flows. +- Keep this file-level DOX profile synchronized with `agents.py` because this directory is intentionally flat. + +## Ownership + +- `agents.py` owns the runtime implementation. +- `agents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Agents` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Agents` is an `ApiHandler`. +- `Agents` defines `process(...)`. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `subagents.get_all_agents_list`, `Exception`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_default_prompt_budget.py` + - `tests/test_office_document_store.py` + - `tests/test_projects.py` + - `tests/test_skills_runtime.py` + - `tests/test_time_travel.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/api_files_get.py.dox.md b/api/api_files_get.py.dox.md new file mode 100644 index 000000000..c14bf9f13 --- /dev/null +++ b/api/api_files_get.py.dox.md @@ -0,0 +1,52 @@ +# api_files_get.py DOX + +## Purpose + +- Own the `api_files_get.py` API endpoint. +- This module returns downloadable or inspectable files exposed through the external API surface. +- Keep this file-level DOX profile synchronized with `api_files_get.py` because this directory is intentionally flat. + +## Ownership + +- `api_files_get.py` owns the runtime implementation. +- `api_files_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ApiFilesGet` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_csrf(cls) -> bool` + - `requires_api_key(cls) -> bool` + - `get_methods(cls) -> list[str]` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `ApiFilesGet` is an `ApiHandler`. +- `ApiFilesGet` defines `process(...)`. +- `ApiFilesGet` defines `get_methods(...)`. +- `ApiFilesGet` defines `requires_auth(...)`. +- `ApiFilesGet` defines `requires_csrf(...)`. +- `ApiFilesGet` defines `requires_api_key(...)`. +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence. +- Imported dependency areas include: `base64`, `helpers`, `helpers.api`, `helpers.print_style`, `json`, `os`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Response`, `PrintStyle.error`, `path.startswith`, `PrintStyle`, `json.dumps`, `path.replace`, `files.get_abs_path`, `os.path.basename`, `os.path.exists`, `PrintStyle.warning`, `f.read`, `base64.b64encode.decode`, `base64.b64encode`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/api_log_get.py.dox.md b/api/api_log_get.py.dox.md new file mode 100644 index 000000000..043a9c9cf --- /dev/null +++ b/api/api_log_get.py.dox.md @@ -0,0 +1,52 @@ +# api_log_get.py DOX + +## Purpose + +- Own the `api_log_get.py` API endpoint. +- This module returns API/chat log data for external API clients. +- Keep this file-level DOX profile synchronized with `api_log_get.py` because this directory is intentionally flat. + +## Ownership + +- `api_log_get.py` owns the runtime implementation. +- `api_log_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ApiLogGet` (`ApiHandler`) + - `get_methods(cls) -> list[str]` + - `requires_auth(cls) -> bool` + - `requires_csrf(cls) -> bool` + - `requires_api_key(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `ApiLogGet` is an `ApiHandler`. +- `ApiLogGet` defines `process(...)`. +- `ApiLogGet` defines `get_methods(...)`. +- `ApiLogGet` defines `requires_auth(...)`. +- `ApiLogGet` defines `requires_csrf(...)`. +- `ApiLogGet` defines `requires_api_key(...)`. +- Observed side-effect areas: settings/state persistence, secret handling. +- Imported dependency areas include: `agent`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `AgentContext.use`, `Response`, `context.log.output`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/api_message.py.dox.md b/api/api_message.py.dox.md new file mode 100644 index 000000000..646939cad --- /dev/null +++ b/api/api_message.py.dox.md @@ -0,0 +1,51 @@ +# api_message.py DOX + +## Purpose + +- Own the `api_message.py` API endpoint. +- This module accepts external API messages and dispatches them into Agent Zero chat processing. +- Keep this file-level DOX profile synchronized with `api_message.py` because this directory is intentionally flat. + +## Ownership + +- `api_message.py` owns the runtime implementation. +- `api_message.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ApiMessage` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_csrf(cls) -> bool` + - `requires_api_key(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `ApiMessage` is an `ApiHandler`. +- `ApiMessage` defines `process(...)`. +- `ApiMessage` defines `requires_auth(...)`. +- `ApiMessage` defines `requires_csrf(...)`. +- `ApiMessage` defines `requires_api_key(...)`. +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `agent`, `base64`, `datetime`, `helpers`, `helpers.api`, `helpers.print_style`, `helpers.projects`, `helpers.security`, `initialize`, `os`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `context.set_data`, `datetime.now`, `Response`, `files.get_abs_path`, `os.makedirs`, `AgentContext.use`, `context.get_data`, `initialize_agent`, `AgentContext`, `context.log.log`, `context.communicate`, `ValueError`, `uuid.uuid4`, `UserMessage`, `task.result`, `PrintStyle.error`, `safe_filename`, `base64.b64decode`, `os.path.join`, `activate_project`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_api_chat_lifetime.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/api_reset_chat.py.dox.md b/api/api_reset_chat.py.dox.md new file mode 100644 index 000000000..5120f46cd --- /dev/null +++ b/api/api_reset_chat.py.dox.md @@ -0,0 +1,52 @@ +# api_reset_chat.py DOX + +## Purpose + +- Own the `api_reset_chat.py` API endpoint. +- This module resets an API-created chat context. +- Keep this file-level DOX profile synchronized with `api_reset_chat.py` because this directory is intentionally flat. + +## Ownership + +- `api_reset_chat.py` owns the runtime implementation. +- `api_reset_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ApiResetChat` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_csrf(cls) -> bool` + - `requires_api_key(cls) -> bool` + - `get_methods(cls) -> list[str]` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `ApiResetChat` is an `ApiHandler`. +- `ApiResetChat` defines `process(...)`. +- `ApiResetChat` defines `get_methods(...)`. +- `ApiResetChat` defines `requires_auth(...)`. +- `ApiResetChat` defines `requires_csrf(...)`. +- `ApiResetChat` defines `requires_api_key(...)`. +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence. +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.print_style`, `json`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `AgentContext.use`, `context.reset`, `persist_chat.save_tmp_chat`, `persist_chat.remove_msg_files`, `Response`, `PrintStyle.error`, `PrintStyle`, `json.dumps`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/api_terminate_chat.py.dox.md b/api/api_terminate_chat.py.dox.md new file mode 100644 index 000000000..541a6d007 --- /dev/null +++ b/api/api_terminate_chat.py.dox.md @@ -0,0 +1,52 @@ +# api_terminate_chat.py DOX + +## Purpose + +- Own the `api_terminate_chat.py` API endpoint. +- This module terminates an API-created chat context. +- Keep this file-level DOX profile synchronized with `api_terminate_chat.py` because this directory is intentionally flat. + +## Ownership + +- `api_terminate_chat.py` owns the runtime implementation. +- `api_terminate_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ApiTerminateChat` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_csrf(cls) -> bool` + - `requires_api_key(cls) -> bool` + - `get_methods(cls) -> list[str]` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `ApiTerminateChat` is an `ApiHandler`. +- `ApiTerminateChat` defines `process(...)`. +- `ApiTerminateChat` defines `get_methods(...)`. +- `ApiTerminateChat` defines `requires_auth(...)`. +- `ApiTerminateChat` defines `requires_csrf(...)`. +- `ApiTerminateChat` defines `requires_api_key(...)`. +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence. +- Imported dependency areas include: `agent`, `helpers.api`, `helpers.persist_chat`, `helpers.print_style`, `json`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `AgentContext.use`, `AgentContext.remove`, `remove_chat`, `Response`, `PrintStyle.error`, `PrintStyle`, `json.dumps`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/backup_create.py.dox.md b/api/backup_create.py.dox.md new file mode 100644 index 000000000..be6076326 --- /dev/null +++ b/api/backup_create.py.dox.md @@ -0,0 +1,49 @@ +# backup_create.py DOX + +## Purpose + +- Own the `backup_create.py` API endpoint. +- This module handles backup create requests. +- Keep this file-level DOX profile synchronized with `backup_create.py` because this directory is intentionally flat. + +## Ownership + +- `backup_create.py` owns the runtime implementation. +- `backup_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `BackupCreate` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_loopback(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `BackupCreate` is an `ApiHandler`. +- `BackupCreate` defines `process(...)`. +- `BackupCreate` defines `requires_auth(...)`. +- `BackupCreate` defines `requires_loopback(...)`. +- Observed side-effect areas: filesystem writes. +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `helpers.persist_chat`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `save_tmp_chats`, `BackupService`, `send_file`, `backup_service.create_backup`, `line.strip`, `line.startswith`, `patterns_string.split`, `line.strip.startswith`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_download_toast_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/backup_get_defaults.py.dox.md b/api/backup_get_defaults.py.dox.md new file mode 100644 index 000000000..8f2c1966d --- /dev/null +++ b/api/backup_get_defaults.py.dox.md @@ -0,0 +1,47 @@ +# backup_get_defaults.py DOX + +## Purpose + +- Own the `backup_get_defaults.py` API endpoint. +- This module handles backup get defaults requests. +- Keep this file-level DOX profile synchronized with `backup_get_defaults.py` because this directory is intentionally flat. + +## Ownership + +- `backup_get_defaults.py` owns the runtime implementation. +- `backup_get_defaults.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `BackupGetDefaults` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_loopback(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `BackupGetDefaults` is an `ApiHandler`. +- `BackupGetDefaults` defines `process(...)`. +- `BackupGetDefaults` defines `requires_auth(...)`. +- `BackupGetDefaults` defines `requires_loopback(...)`. +- Imported dependency areas include: `helpers.api`, `helpers.backup`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `BackupService`, `backup_service.get_default_backup_metadata`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/backup_inspect.py.dox.md b/api/backup_inspect.py.dox.md new file mode 100644 index 000000000..363dd63dc --- /dev/null +++ b/api/backup_inspect.py.dox.md @@ -0,0 +1,47 @@ +# backup_inspect.py DOX + +## Purpose + +- Own the `backup_inspect.py` API endpoint. +- This module handles backup inspect requests. +- Keep this file-level DOX profile synchronized with `backup_inspect.py` because this directory is intentionally flat. + +## Ownership + +- `backup_inspect.py` owns the runtime implementation. +- `backup_inspect.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `BackupInspect` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_loopback(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `BackupInspect` is an `ApiHandler`. +- `BackupInspect` defines `process(...)`. +- `BackupInspect` defines `requires_auth(...)`. +- `BackupInspect` defines `requires_loopback(...)`. +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `werkzeug.datastructures`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `BackupService`, `backup_service.inspect_backup`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/backup_preview_grouped.py.dox.md b/api/backup_preview_grouped.py.dox.md new file mode 100644 index 000000000..24e075981 --- /dev/null +++ b/api/backup_preview_grouped.py.dox.md @@ -0,0 +1,47 @@ +# backup_preview_grouped.py DOX + +## Purpose + +- Own the `backup_preview_grouped.py` API endpoint. +- This module handles backup preview grouped requests. +- Keep this file-level DOX profile synchronized with `backup_preview_grouped.py` because this directory is intentionally flat. + +## Ownership + +- `backup_preview_grouped.py` owns the runtime implementation. +- `backup_preview_grouped.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `BackupPreviewGrouped` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_loopback(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `BackupPreviewGrouped` is an `ApiHandler`. +- `BackupPreviewGrouped` defines `process(...)`. +- `BackupPreviewGrouped` defines `requires_auth(...)`. +- `BackupPreviewGrouped` defines `requires_loopback(...)`. +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `BackupService`, `search_filter.strip`, `backup_service.test_patterns`, `search_filter.lower`, `path.strip.split`, `line.strip`, `line.startswith`, `groups.add`, `patterns_string.split`, `path.strip`, `join`, `f.lower`, `line.strip.startswith`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/backup_restore.py.dox.md b/api/backup_restore.py.dox.md new file mode 100644 index 000000000..78e74737d --- /dev/null +++ b/api/backup_restore.py.dox.md @@ -0,0 +1,49 @@ +# backup_restore.py DOX + +## Purpose + +- Own the `backup_restore.py` API endpoint. +- This module handles backup restore requests. +- Keep this file-level DOX profile synchronized with `backup_restore.py` because this directory is intentionally flat. + +## Ownership + +- `backup_restore.py` owns the runtime implementation. +- `backup_restore.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `BackupRestore` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_loopback(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `BackupRestore` is an `ApiHandler`. +- `BackupRestore` defines `process(...)`. +- `BackupRestore` defines `requires_auth(...)`. +- `BackupRestore` defines `requires_loopback(...)`. +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence. +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `helpers.persist_chat`, `json`, `werkzeug.datastructures`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `request.form.get.lower`, `json.loads`, `BackupService`, `load_tmp_chats`, `backup_service.restore_backup`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_self_update_tag_filter.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/backup_restore_preview.py.dox.md b/api/backup_restore_preview.py.dox.md new file mode 100644 index 000000000..572473a0a --- /dev/null +++ b/api/backup_restore_preview.py.dox.md @@ -0,0 +1,48 @@ +# backup_restore_preview.py DOX + +## Purpose + +- Own the `backup_restore_preview.py` API endpoint. +- This module handles backup restore preview requests. +- Keep this file-level DOX profile synchronized with `backup_restore_preview.py` because this directory is intentionally flat. + +## Ownership + +- `backup_restore_preview.py` owns the runtime implementation. +- `backup_restore_preview.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `BackupRestorePreview` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_loopback(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `BackupRestorePreview` is an `ApiHandler`. +- `BackupRestorePreview` defines `process(...)`. +- `BackupRestorePreview` defines `requires_auth(...)`. +- `BackupRestorePreview` defines `requires_loopback(...)`. +- Observed side-effect areas: filesystem deletion, settings/state persistence. +- Imported dependency areas include: `helpers.api`, `helpers.backup`, `json`, `werkzeug.datastructures`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `request.form.get.lower`, `json.loads`, `BackupService`, `backup_service.preview_restore`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/backup_test.py.dox.md b/api/backup_test.py.dox.md new file mode 100644 index 000000000..c5f01a155 --- /dev/null +++ b/api/backup_test.py.dox.md @@ -0,0 +1,47 @@ +# backup_test.py DOX + +## Purpose + +- Own the `backup_test.py` API endpoint. +- This module handles backup test requests. +- Keep this file-level DOX profile synchronized with `backup_test.py` because this directory is intentionally flat. + +## Ownership + +- `backup_test.py` owns the runtime implementation. +- `backup_test.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `BackupTest` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_loopback(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `BackupTest` is an `ApiHandler`. +- `BackupTest` defines `process(...)`. +- `BackupTest` defines `requires_auth(...)`. +- `BackupTest` defines `requires_loopback(...)`. +- Imported dependency areas include: `helpers.api`, `helpers.backup`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `BackupService`, `backup_service.test_patterns`, `line.strip`, `line.startswith`, `patterns_string.split`, `line.strip.startswith`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/banners.py.dox.md b/api/banners.py.dox.md new file mode 100644 index 000000000..9d007e7d5 --- /dev/null +++ b/api/banners.py.dox.md @@ -0,0 +1,46 @@ +# banners.py DOX + +## Purpose + +- Own the `banners.py` API endpoint. +- This module collects alert banners and discovery cards from backend extensions. +- Keep this file-level DOX profile synchronized with `banners.py` because this directory is intentionally flat. + +## Ownership + +- `banners.py` owns the runtime implementation. +- `banners.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `GetBanners` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `GetBanners` is an `ApiHandler`. +- `GetBanners` defines `process(...)`. +- Imported dependency areas include: `helpers.api`, `helpers.extension`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `call_extensions_async`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_model_config_api_keys.py` + - `tests/test_oauth_static.py` + - `tests/test_webui_extension_surfaces.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/cache_reset.py.dox.md b/api/cache_reset.py.dox.md new file mode 100644 index 000000000..a7164d5d5 --- /dev/null +++ b/api/cache_reset.py.dox.md @@ -0,0 +1,53 @@ +# cache_reset.py DOX + +## Purpose + +- Own the `cache_reset.py` API endpoint. +- This module handles cache reset API requests. +- Keep this file-level DOX profile synchronized with `cache_reset.py` because this directory is intentionally flat. + +## Ownership + +- `cache_reset.py` owns the runtime implementation. +- `cache_reset.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `CacheReset` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_csrf(cls) -> bool` + - `requires_api_key(cls) -> bool` + - `requires_loopback(cls) -> bool` + - `get_methods(cls) -> list[str]` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `CacheReset` is an `ApiHandler`. +- `CacheReset` defines `process(...)`. +- `CacheReset` defines `get_methods(...)`. +- `CacheReset` defines `requires_auth(...)`. +- `CacheReset` defines `requires_csrf(...)`. +- `CacheReset` defines `requires_api_key(...)`. +- `CacheReset` defines `requires_loopback(...)`. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `cache.clear_all`, `cache.clear`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/chat_create.py.dox.md b/api/chat_create.py.dox.md new file mode 100644 index 000000000..3546f4389 --- /dev/null +++ b/api/chat_create.py.dox.md @@ -0,0 +1,45 @@ +# chat_create.py DOX + +## Purpose + +- Own the `chat_create.py` API endpoint. +- This module handles chat create requests. +- Keep this file-level DOX profile synchronized with `chat_create.py` because this directory is intentionally flat. + +## Ownership + +- `chat_create.py` owns the runtime implementation. +- `chat_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `CreateChat` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `CreateChat` is an `ApiHandler`. +- `CreateChat` defines `process(...)`. +- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence. +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.use_context`, `mark_dirty_all`, `guids.generate_id`, `current_context.get_data`, `current_context.get_output_data`, `new_context.set_data`, `new_context.set_output_data`, `is_chat_override_allowed`, `settings.get_settings`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/chat_export.py.dox.md b/api/chat_export.py.dox.md new file mode 100644 index 000000000..03b5a0c91 --- /dev/null +++ b/api/chat_export.py.dox.md @@ -0,0 +1,44 @@ +# chat_export.py DOX + +## Purpose + +- Own the `chat_export.py` API endpoint. +- This module handles chat export requests. +- Keep this file-level DOX profile synchronized with `chat_export.py` because this directory is intentionally flat. + +## Ownership + +- `chat_export.py` owns the runtime implementation. +- `chat_export.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ExportChat` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `ExportChat` is an `ApiHandler`. +- `ExportChat` defines `process(...)`. +- Observed side-effect areas: filesystem writes. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.use_context`, `persist_chat.export_json_chat`, `Exception`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/chat_files_path_get.py.dox.md b/api/chat_files_path_get.py.dox.md new file mode 100644 index 000000000..63f0a2b6e --- /dev/null +++ b/api/chat_files_path_get.py.dox.md @@ -0,0 +1,44 @@ +# chat_files_path_get.py DOX + +## Purpose + +- Own the `chat_files_path_get.py` API endpoint. +- This module handles chat files path get requests. +- Keep this file-level DOX profile synchronized with `chat_files_path_get.py` because this directory is intentionally flat. + +## Ownership + +- `chat_files_path_get.py` owns the runtime implementation. +- `chat_files_path_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `GetChatFilesPath` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `GetChatFilesPath` is an `ApiHandler`. +- `GetChatFilesPath` defines `process(...)`. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.use_context`, `projects.get_context_project_name`, `Exception`, `files.normalize_a0_path`, `projects.get_project_folder`, `settings.get_settings`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/chat_load.py.dox.md b/api/chat_load.py.dox.md new file mode 100644 index 000000000..4718a9fc6 --- /dev/null +++ b/api/chat_load.py.dox.md @@ -0,0 +1,44 @@ +# chat_load.py DOX + +## Purpose + +- Own the `chat_load.py` API endpoint. +- This module handles chat load requests. +- Keep this file-level DOX profile synchronized with `chat_load.py` because this directory is intentionally flat. + +## Ownership + +- `chat_load.py` owns the runtime implementation. +- `chat_load.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `LoadChats` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `LoadChats` is an `ApiHandler`. +- `LoadChats` defines `process(...)`. +- Observed side-effect areas: filesystem writes. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `persist_chat.load_json_chats`, `Exception`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/chat_remove.py.dox.md b/api/chat_remove.py.dox.md new file mode 100644 index 000000000..ac1ffc0f8 --- /dev/null +++ b/api/chat_remove.py.dox.md @@ -0,0 +1,44 @@ +# chat_remove.py DOX + +## Purpose + +- Own the `chat_remove.py` API endpoint. +- This module handles chat remove requests. +- Keep this file-level DOX profile synchronized with `chat_remove.py` because this directory is intentionally flat. + +## Ownership + +- `chat_remove.py` owns the runtime implementation. +- `chat_remove.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `RemoveChat` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `RemoveChat` is an `ApiHandler`. +- `RemoveChat` defines `process(...)`. +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state. +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.task_scheduler`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `scheduler.cancel_tasks_by_context`, `AgentContext.use`, `AgentContext.remove`, `persist_chat.remove_chat`, `scheduler.get_tasks_by_context_id`, `mark_dirty_all`, `context.reset`, `scheduler.reload`, `scheduler.remove_task_by_uuid`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/chat_reset.py.dox.md b/api/chat_reset.py.dox.md new file mode 100644 index 000000000..39a886a53 --- /dev/null +++ b/api/chat_reset.py.dox.md @@ -0,0 +1,44 @@ +# chat_reset.py DOX + +## Purpose + +- Own the `chat_reset.py` API endpoint. +- This module handles chat reset requests. +- Keep this file-level DOX profile synchronized with `chat_reset.py` because this directory is intentionally flat. + +## Ownership + +- `chat_reset.py` owns the runtime implementation. +- `chat_reset.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Reset` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Reset` is an `ApiHandler`. +- `Reset` defines `process(...)`. +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state. +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.task_scheduler`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `TaskScheduler.get.cancel_tasks_by_context`, `self.use_context`, `context.reset`, `persist_chat.save_tmp_chat`, `persist_chat.remove_msg_files`, `mark_dirty_all`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/csrf_token.py.dox.md b/api/csrf_token.py.dox.md new file mode 100644 index 000000000..3570d2471 --- /dev/null +++ b/api/csrf_token.py.dox.md @@ -0,0 +1,57 @@ +# csrf_token.py DOX + +## Purpose + +- Own the `csrf_token.py` API endpoint. +- This module issues or refreshes CSRF tokens for browser API clients. +- Keep this file-level DOX profile synchronized with `csrf_token.py` because this directory is intentionally flat. + +## Ownership + +- `csrf_token.py` owns the runtime implementation. +- `csrf_token.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `GetCsrfToken` (`ApiHandler`) + - `get_methods(cls) -> list[str]` + - `requires_csrf(cls) -> bool` + - `async process(self, input: Input, request: Request) -> Output` + - `async check_allowed_origin(self, request: Request)` + - `async is_allowed_origin(self, request: Request)` + - `get_origin_from_request(self, request: Request)` + - `async get_allowed_origins(self) -> list[str]` + - `get_default_allowed_origins(self) -> list[str]` +- Notable constants/configuration names: `ALLOWED_ORIGINS_KEY`. + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `GetCsrfToken` is an `ApiHandler`. +- `GetCsrfToken` defines `process(...)`. +- `GetCsrfToken` defines `get_methods(...)`. +- `GetCsrfToken` defines `requires_csrf(...)`. +- Observed side-effect areas: filesystem writes, network calls, secret handling, tunnel state. +- Imported dependency areas include: `fnmatch`, `helpers`, `helpers.api`, `secrets`, `urllib.parse`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `login.is_login_required`, `self.initialize_allowed_origins`, `self.get_origin_from_request`, `urlparse`, `dotenv.get_dotenv_value`, `self.get_default_allowed_origins`, `dotenv.save_dotenv_value`, `self.check_allowed_origin`, `secrets.token_urlsafe`, `runtime.get_runtime_id`, `self.is_allowed_origin`, `self.get_allowed_origins`, `origin.strip`, `join`, `fnmatch.fnmatch`, `split`, `tunnel_api_process`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_http_auth_csrf.py` + - `tests/test_self_update_tag_filter.py` + - `tests/test_ws_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/ctx_window_get.py.dox.md b/api/ctx_window_get.py.dox.md new file mode 100644 index 000000000..2de01bf37 --- /dev/null +++ b/api/ctx_window_get.py.dox.md @@ -0,0 +1,44 @@ +# ctx_window_get.py DOX + +## Purpose + +- Own the `ctx_window_get.py` API endpoint. +- This module handles ctx window get API requests. +- Keep this file-level DOX profile synchronized with `ctx_window_get.py` because this directory is intentionally flat. + +## Ownership + +- `ctx_window_get.py` owns the runtime implementation. +- `ctx_window_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `GetCtxWindow` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `GetCtxWindow` is an `ApiHandler`. +- `GetCtxWindow` defines `process(...)`. +- Observed side-effect areas: secret handling. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.use_context`, `agent.get_data`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/delete_work_dir_file.py.dox.md b/api/delete_work_dir_file.py.dox.md new file mode 100644 index 000000000..536b70fcb --- /dev/null +++ b/api/delete_work_dir_file.py.dox.md @@ -0,0 +1,46 @@ +# delete_work_dir_file.py DOX + +## Purpose + +- Own the `delete_work_dir_file.py` API endpoint. +- This module handles workdir file operations for delete work dir file. +- Keep this file-level DOX profile synchronized with `delete_work_dir_file.py` because this directory is intentionally flat. + +## Ownership + +- `delete_work_dir_file.py` owns the runtime implementation. +- `delete_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `DeleteWorkDirFile` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` +- Top-level functions: +- `async delete_file(file_path: str)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `DeleteWorkDirFile` is an `ApiHandler`. +- `DeleteWorkDirFile` defines `process(...)`. +- Observed side-effect areas: filesystem deletion. +- Imported dependency areas include: `api`, `helpers`, `helpers.api`, `helpers.file_browser`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `FileBrowser`, `browser.delete_file`, `file_path.startswith`, `runtime.call_development_function`, `extension.call_extensions_async`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/delete_work_dir_files.py.dox.md b/api/delete_work_dir_files.py.dox.md new file mode 100644 index 000000000..2c68d3ca2 --- /dev/null +++ b/api/delete_work_dir_files.py.dox.md @@ -0,0 +1,47 @@ +# delete_work_dir_files.py DOX + +## Purpose + +- Own the `delete_work_dir_files.py` API endpoint. +- This module handles workdir file operations for delete work dir files. +- Keep this file-level DOX profile synchronized with `delete_work_dir_files.py` because this directory is intentionally flat. + +## Ownership + +- `delete_work_dir_files.py` owns the runtime implementation. +- `delete_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `DeleteWorkDirFiles` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` +- Top-level functions: +- `async delete_files(paths: list[str]) -> dict` +- `collapse_nested_paths(paths: list[str]) -> list[str]` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `DeleteWorkDirFiles` is an `ApiHandler`. +- `DeleteWorkDirFiles` defines `process(...)`. +- Observed side-effect areas: filesystem deletion. +- Imported dependency areas include: `api`, `api.download_work_dir_files`, `helpers`, `helpers.api`, `helpers.file_browser`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `FileBrowser`, `collapse_nested_paths`, `browser.delete_file`, `normalize_paths`, `runtime.call_development_function`, `path.strip`, `extension.call_extensions_async`, `item.count`, `clean_path.startswith`, `parent.rstrip`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/download_work_dir_file.py.dox.md b/api/download_work_dir_file.py.dox.md new file mode 100644 index 000000000..87085765a --- /dev/null +++ b/api/download_work_dir_file.py.dox.md @@ -0,0 +1,53 @@ +# download_work_dir_file.py DOX + +## Purpose + +- Own the `download_work_dir_file.py` API endpoint. +- This module handles workdir file operations for download work dir file. +- Keep this file-level DOX profile synchronized with `download_work_dir_file.py` because this directory is intentionally flat. + +## Ownership + +- `download_work_dir_file.py` owns the runtime implementation. +- `download_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `DownloadFile` (`ApiHandler`) + - `get_methods(cls)` + - `async process(self, input: Input, request: Request) -> Output` +- Top-level functions: +- `stream_file_download(file_source, download_name, chunk_size=...)`: Create a streaming response for file downloads that shows progress in browser. +- `make_disposition(download_name: str) -> str` +- `resolve_download_path(path: str) -> str`: Resolve a requested download path and keep it within the runtime base dir. +- `async fetch_file(path)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `DownloadFile` is an `ApiHandler`. +- `DownloadFile` defines `process(...)`. +- `DownloadFile` defines `get_methods(...)`. +- Observed side-effect areas: filesystem reads, network calls. +- Imported dependency areas include: `api`, `base64`, `flask`, `helpers`, `helpers.api`, `io`, `mimetypes`, `os`, `pathlib`, `urllib.parse`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `mimetypes.guess_type`, `Response`, `quote`, `Path.resolve`, `Path`, `candidate.is_absolute`, `os.path.getsize`, `generate`, `download_name.encode.decode`, `candidate.resolve`, `resolve`, `resolved.relative_to`, `Exception`, `file.read`, `base64.b64encode.decode`, `file_source.tell`, `file_source.seek`, `ValueError`, `file_path.startswith`, `runtime.call_development_function`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_download_toast_regressions.py` + - `tests/test_office_canvas_setup.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/download_work_dir_files.py.dox.md b/api/download_work_dir_files.py.dox.md new file mode 100644 index 000000000..478669fa8 --- /dev/null +++ b/api/download_work_dir_files.py.dox.md @@ -0,0 +1,54 @@ +# download_work_dir_files.py DOX + +## Purpose + +- Own the `download_work_dir_files.py` API endpoint. +- This module handles workdir file operations for download work dir files. +- Keep this file-level DOX profile synchronized with `download_work_dir_files.py` because this directory is intentionally flat. + +## Ownership + +- `download_work_dir_files.py` owns the runtime implementation. +- `download_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `DownloadFiles` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` +- Top-level functions: +- `normalize_paths(paths) -> list[str]` +- `selected_archive_name(count: int) -> str` +- `create_selected_zip(paths: list[str], current_path: str=...) -> str` +- `resolve_download_path(path: str, base_dir: Path) -> Path` +- `collapse_nested_paths(paths: list[Path]) -> list[Path]` +- `archive_root_name(source_path: Path, current_dir: Path | None, base_dir: Path) -> str` +- `unique_archive_name(name: str, used_names: set[str]) -> str` +- `write_zip_entry(zip_file: zipfile.ZipFile, source_path: Path, arc_root: str) -> None` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `DownloadFiles` is an `ApiHandler`. +- `DownloadFiles` defines `process(...)`. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion. +- Imported dependency areas include: `api.download_work_dir_file`, `base64`, `flask`, `helpers`, `helpers.api`, `helpers.localization`, `io`, `os`, `pathlib`, `tempfile`, `zipfile`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Localization.get.now.strftime`, `Path.resolve`, `normalize_paths`, `collapse_nested_paths`, `Path`, `os.path.splitext`, `source_path.is_dir`, `zip_file.write`, `selected_archive_name`, `runtime.is_development`, `stream_file_download`, `ValueError`, `raw_path.strip`, `resolve_download_path`, `current_dir.is_file`, `resolved.exists`, `FileNotFoundError`, `tempfile.NamedTemporaryFile`, `zipfile.ZipFile`, `candidate.is_absolute`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_download_toast_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/edit_work_dir_file.py.dox.md b/api/edit_work_dir_file.py.dox.md new file mode 100644 index 000000000..e5615517b --- /dev/null +++ b/api/edit_work_dir_file.py.dox.md @@ -0,0 +1,50 @@ +# edit_work_dir_file.py DOX + +## Purpose + +- Own the `edit_work_dir_file.py` API endpoint. +- This module handles workdir file operations for edit work dir file. +- Keep this file-level DOX profile synchronized with `edit_work_dir_file.py` because this directory is intentionally flat. + +## Ownership + +- `edit_work_dir_file.py` owns the runtime implementation. +- `edit_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `EditWorkDirFile` (`ApiHandler`) + - `get_methods(cls)` + - `async process(self, input: Input, request: Request) -> Output` +- Top-level functions: +- `async load_file(file_path: str) -> dict` +- `save_file(file_path: str, content: str) -> bool` +- Notable constants/configuration names: `MAX_EDIT_FILE_SIZE`, `BINARY_SAMPLE_SIZE`. + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `EditWorkDirFile` is an `ApiHandler`. +- `EditWorkDirFile` defines `process(...)`. +- `EditWorkDirFile` defines `get_methods(...)`. +- Observed side-effect areas: filesystem reads, filesystem writes. +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.file_browser`, `mimetypes`, `os`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `FileBrowser`, `browser.get_full_path`, `os.path.isdir`, `os.path.getsize`, `files.is_probably_binary_file`, `mimetypes.guess_type`, `browser.save_text_file`, `error_str.strip`, `Exception`, `os.path.basename`, `error_str.split`, `file.read`, `line.split.strip`, `file_path.startswith`, `content.encode`, `runtime.call_development_function`, `extension.call_extensions_async`, `self._extract_error_message`, `line.split`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/file_info.py.dox.md b/api/file_info.py.dox.md new file mode 100644 index 000000000..e3612589d --- /dev/null +++ b/api/file_info.py.dox.md @@ -0,0 +1,47 @@ +# file_info.py DOX + +## Purpose + +- Own the `file_info.py` API endpoint. +- This module handles file info API requests. +- Keep this file-level DOX profile synchronized with `file_info.py` because this directory is intentionally flat. + +## Ownership + +- `file_info.py` owns the runtime implementation. +- `file_info.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `FileInfoApi` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` +- `FileInfo` (`TypedDict`) +- Top-level functions: +- `async get_file_info(path: str) -> FileInfo` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `FileInfoApi` is an `ApiHandler`. +- `FileInfoApi` defines `process(...)`. +- Observed side-effect areas: filesystem reads. +- Imported dependency areas include: `helpers`, `helpers.api`, `os`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `files.get_abs_path`, `os.path.exists`, `os.path.dirname`, `os.path.basename`, `runtime.call_development_function`, `os.path.isdir`, `os.path.isfile`, `os.path.islink`, `os.path.getsize`, `os.path.getmtime`, `os.path.getctime`, `os.path.splitext`, `os.stat`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/get_work_dir_files.py.dox.md b/api/get_work_dir_files.py.dox.md new file mode 100644 index 000000000..3d3048650 --- /dev/null +++ b/api/get_work_dir_files.py.dox.md @@ -0,0 +1,47 @@ +# get_work_dir_files.py DOX + +## Purpose + +- Own the `get_work_dir_files.py` API endpoint. +- This module handles workdir file operations for get work dir files. +- Keep this file-level DOX profile synchronized with `get_work_dir_files.py` because this directory is intentionally flat. + +## Ownership + +- `get_work_dir_files.py` owns the runtime implementation. +- `get_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `GetWorkDirFiles` (`ApiHandler`) + - `get_methods(cls)` + - `async process(self, input: dict, request: Request) -> dict | Response` +- Top-level functions: +- `async get_files(path)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `GetWorkDirFiles` is an `ApiHandler`. +- `GetWorkDirFiles` defines `process(...)`. +- `GetWorkDirFiles` defines `get_methods(...)`. +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.file_browser`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `FileBrowser`, `browser.get_files`, `runtime.call_development_function`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/health.py.dox.md b/api/health.py.dox.md new file mode 100644 index 000000000..236812f56 --- /dev/null +++ b/api/health.py.dox.md @@ -0,0 +1,52 @@ +# health.py DOX + +## Purpose + +- Own the `health.py` API endpoint. +- This module reports process health for probes and startup checks. +- Keep this file-level DOX profile synchronized with `health.py` because this directory is intentionally flat. + +## Ownership + +- `health.py` owns the runtime implementation. +- `health.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `HealthCheck` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `requires_csrf(cls) -> bool` + - `get_methods(cls) -> list[str]` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `HealthCheck` is an `ApiHandler`. +- `HealthCheck` defines `process(...)`. +- `HealthCheck` defines `get_methods(...)`. +- `HealthCheck` defines `requires_auth(...)`. +- `HealthCheck` defines `requires_csrf(...)`. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `git.get_git_info`, `errors.error_text`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_oauth_providers.py` + - `tests/test_office_document_store.py` + - `tests/test_self_update_tag_filter.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/history_get.py.dox.md b/api/history_get.py.dox.md new file mode 100644 index 000000000..8f2f1ddca --- /dev/null +++ b/api/history_get.py.dox.md @@ -0,0 +1,44 @@ +# history_get.py DOX + +## Purpose + +- Own the `history_get.py` API endpoint. +- This module handles history get API requests. +- Keep this file-level DOX profile synchronized with `history_get.py` because this directory is intentionally flat. + +## Ownership + +- `history_get.py` owns the runtime implementation. +- `history_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `GetHistory` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `GetHistory` is an `ApiHandler`. +- `GetHistory` defines `process(...)`. +- Observed side-effect areas: secret handling. +- Imported dependency areas include: `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.use_context`, `agent.history.output_text`, `agent.history.get_tokens`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/image_get.py.dox.md b/api/image_get.py.dox.md new file mode 100644 index 000000000..b9b0da35b --- /dev/null +++ b/api/image_get.py.dox.md @@ -0,0 +1,53 @@ +# image_get.py DOX + +## Purpose + +- Own the `image_get.py` API endpoint. +- This module serves allowed image references and fallback file-type icons. +- Keep this file-level DOX profile synchronized with `image_get.py` because this directory is intentionally flat. + +## Ownership + +- `image_get.py` owns the runtime implementation. +- `image_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ImageGet` (`ApiHandler`) + - `get_methods(cls) -> list[str]` + - `async process(self, input: dict, request: Request) -> dict | Response` +- Top-level functions: +- `_resolve_allowed_image_path(path: str) -> str`: Resolve a requested image path and keep it inside Agent Zero's base dir. +- `_set_image_headers(response: Response, filename: str, file_ext: str) -> None` +- `_send_file_type_icon(file_ext, filename=...)`: Return appropriate icon for file type +- `_send_fallback_icon(icon_name)`: Return fallback icon from public directory +- Notable constants/configuration names: `IMAGE_EXTENSIONS`, `SVG_EXTENSIONS`, `SVG_CONTENT_SECURITY_POLICY`. + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `ImageGet` is an `ApiHandler`. +- `ImageGet` defines `process(...)`. +- `ImageGet` defines `get_methods(...)`. +- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, settings/state persistence. +- Imported dependency areas include: `base64`, `helpers`, `helpers.api`, `io`, `mimetypes`, `os`, `pathlib`, `urllib.parse`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `runtime.is_development`, `Path.resolve`, `candidate.resolve`, `quote`, `_send_fallback_icon`, `files.get_abs_path`, `send_file`, `os.path.splitext.lower`, `os.path.basename`, `Path`, `candidate.is_absolute`, `resolved.relative_to`, `os.path.exists`, `ValueError`, `_set_image_headers`, `_send_file_type_icon`, `files.fix_dev_path`, `_resolve_allowed_image_path`, `files.exists`, `files.get_base_dir`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_image_get_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/load_webui_extensions.py.dox.md b/api/load_webui_extensions.py.dox.md new file mode 100644 index 000000000..c2d41e06a --- /dev/null +++ b/api/load_webui_extensions.py.dox.md @@ -0,0 +1,44 @@ +# load_webui_extensions.py DOX + +## Purpose + +- Own the `load_webui_extensions.py` API endpoint. +- This module returns frontend extension manifests/files for a WebUI extension point. +- Keep this file-level DOX profile synchronized with `load_webui_extensions.py` because this directory is intentionally flat. + +## Ownership + +- `load_webui_extensions.py` owns the runtime implementation. +- `load_webui_extensions.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `LoadWebuiExtensions` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `LoadWebuiExtensions` is an `ApiHandler`. +- `LoadWebuiExtensions` defines `process(...)`. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `extension.get_webui_extensions`, `Response`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_webui_extension_surfaces.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/logout.py.dox.md b/api/logout.py.dox.md new file mode 100644 index 000000000..e125a43e7 --- /dev/null +++ b/api/logout.py.dox.md @@ -0,0 +1,47 @@ +# logout.py DOX + +## Purpose + +- Own the `logout.py` API endpoint. +- This module clears login/session state for the current client. +- Keep this file-level DOX profile synchronized with `logout.py` because this directory is intentionally flat. + +## Ownership + +- `logout.py` owns the runtime implementation. +- `logout.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ApiLogout` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `ApiLogout` is an `ApiHandler`. +- `ApiLogout` defines `process(...)`. +- `ApiLogout` defines `requires_auth(...)`. +- Observed side-effect areas: secret handling. +- Imported dependency areas include: `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `session.clear`, `session.pop`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_office_document_store.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/mcp_server_get_detail.py.dox.md b/api/mcp_server_get_detail.py.dox.md new file mode 100644 index 000000000..e4539d725 --- /dev/null +++ b/api/mcp_server_get_detail.py.dox.md @@ -0,0 +1,43 @@ +# mcp_server_get_detail.py DOX + +## Purpose + +- Own the `mcp_server_get_detail.py` API endpoint. +- This module handles MCP server server get detail requests. +- Keep this file-level DOX profile synchronized with `mcp_server_get_detail.py` because this directory is intentionally flat. + +## Ownership + +- `mcp_server_get_detail.py` owns the runtime implementation. +- `mcp_server_get_detail.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `McpServerGetDetail` (`ApiHandler`) + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `McpServerGetDetail` is an `ApiHandler`. +- `McpServerGetDetail` defines `process(...)`. +- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_server_detail`, `MCPConfig.get_instance`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/mcp_server_get_log.py.dox.md b/api/mcp_server_get_log.py.dox.md new file mode 100644 index 000000000..3baf7453e --- /dev/null +++ b/api/mcp_server_get_log.py.dox.md @@ -0,0 +1,43 @@ +# mcp_server_get_log.py DOX + +## Purpose + +- Own the `mcp_server_get_log.py` API endpoint. +- This module handles MCP server server get log requests. +- Keep this file-level DOX profile synchronized with `mcp_server_get_log.py` because this directory is intentionally flat. + +## Ownership + +- `mcp_server_get_log.py` owns the runtime implementation. +- `mcp_server_get_log.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `McpServerGetLog` (`ApiHandler`) + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `McpServerGetLog` is an `ApiHandler`. +- `McpServerGetLog` defines `process(...)`. +- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_server_log`, `MCPConfig.get_instance`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/mcp_servers_apply.py.dox.md b/api/mcp_servers_apply.py.dox.md new file mode 100644 index 000000000..1a0a0d326 --- /dev/null +++ b/api/mcp_servers_apply.py.dox.md @@ -0,0 +1,44 @@ +# mcp_servers_apply.py DOX + +## Purpose + +- Own the `mcp_servers_apply.py` API endpoint. +- This module handles MCP server servers apply requests. +- Keep this file-level DOX profile synchronized with `mcp_servers_apply.py` because this directory is intentionally flat. + +## Ownership + +- `mcp_servers_apply.py` owns the runtime implementation. +- `mcp_servers_apply.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `McpServersApply` (`ApiHandler`) + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `McpServersApply` is an `ApiHandler`. +- `McpServersApply` defines `process(...)`. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `helpers.settings`, `time`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `set_settings_delta`, `time.sleep`, `MCPConfig.get_instance.get_servers_status`, `MCPConfig.get_instance`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/mcp_servers_status.py.dox.md b/api/mcp_servers_status.py.dox.md new file mode 100644 index 000000000..6a66a3eb3 --- /dev/null +++ b/api/mcp_servers_status.py.dox.md @@ -0,0 +1,43 @@ +# mcp_servers_status.py DOX + +## Purpose + +- Own the `mcp_servers_status.py` API endpoint. +- This module handles MCP server servers status requests. +- Keep this file-level DOX profile synchronized with `mcp_servers_status.py` because this directory is intentionally flat. + +## Ownership + +- `mcp_servers_status.py` owns the runtime implementation. +- `mcp_servers_status.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `McpServersStatuss` (`ApiHandler`) + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `McpServersStatuss` is an `ApiHandler`. +- `McpServersStatuss` defines `process(...)`. +- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_servers_status`, `MCPConfig.get_instance`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/message.py.dox.md b/api/message.py.dox.md new file mode 100644 index 000000000..9ec63fc71 --- /dev/null +++ b/api/message.py.dox.md @@ -0,0 +1,54 @@ +# message.py DOX + +## Purpose + +- Own the `message.py` API endpoint. +- This module submits a user message and runs agent processing synchronously through the UI API. +- Keep this file-level DOX profile synchronized with `message.py` because this directory is intentionally flat. + +## Ownership + +- `message.py` owns the runtime implementation. +- `message.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Message` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + - `async respond(self, task: DeferredTask, context: AgentContext)` + - `async communicate(self, input: dict, request: Request)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Message` is an `ApiHandler`. +- `Message` defines `process(...)`. +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, scheduler state. +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.defer`, `helpers.security`, `os`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `request.content_type.startswith`, `self.use_context`, `mq.log_user_message`, `self.communicate`, `self.respond`, `task.result`, `request.files.getlist`, `files.get_abs_path`, `request.get_json`, `extension.call_extensions_async`, `context.communicate`, `os.makedirs`, `UserMessage`, `safe_filename`, `attachment.save`, `context.get_agent`, `os.path.join`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/email_parser_test.py` + - `tests/rate_limiter_test.py` + - `tests/test_api_chat_lifetime.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_chat_compaction.py` + - `tests/test_docker_release_plan.py` + - `tests/test_document_query_fallback.py` + - `tests/test_download_toast_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/message_async.py.dox.md b/api/message_async.py.dox.md new file mode 100644 index 000000000..6a6ba0093 --- /dev/null +++ b/api/message_async.py.dox.md @@ -0,0 +1,42 @@ +# message_async.py DOX + +## Purpose + +- Own the `message_async.py` API endpoint. +- This module submits a user message for asynchronous agent processing. +- Keep this file-level DOX profile synchronized with `message_async.py` because this directory is intentionally flat. + +## Ownership + +- `message_async.py` owns the runtime implementation. +- `message_async.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `MessageAsync` (`Message`) + - `async respond(self, task: DeferredTask, context: AgentContext)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- Observed side-effect areas: scheduler state. +- Imported dependency areas include: `agent`, `api.message`, `helpers.defer`. + +## Key Concepts + +- This module is primarily declarative or delegates behavior through classes/imported objects. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/message_queue_add.py.dox.md b/api/message_queue_add.py.dox.md new file mode 100644 index 000000000..f727a70f1 --- /dev/null +++ b/api/message_queue_add.py.dox.md @@ -0,0 +1,44 @@ +# message_queue_add.py DOX + +## Purpose + +- Own the `message_queue_add.py` API endpoint. +- This module handles message queue add API requests. +- Keep this file-level DOX profile synchronized with `message_queue_add.py` because this directory is intentionally flat. + +## Ownership + +- `message_queue_add.py` owns the runtime implementation. +- `message_queue_add.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `MessageQueueAdd` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `MessageQueueAdd` is an `ApiHandler`. +- `MessageQueueAdd` defines `process(...)`. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `input.get.strip`, `mq.add`, `mark_dirty_for_context`, `Response`, `mq.get_queue`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/message_queue_remove.py.dox.md b/api/message_queue_remove.py.dox.md new file mode 100644 index 000000000..8bf876b05 --- /dev/null +++ b/api/message_queue_remove.py.dox.md @@ -0,0 +1,44 @@ +# message_queue_remove.py DOX + +## Purpose + +- Own the `message_queue_remove.py` API endpoint. +- This module handles message queue remove API requests. +- Keep this file-level DOX profile synchronized with `message_queue_remove.py` because this directory is intentionally flat. + +## Ownership + +- `message_queue_remove.py` owns the runtime implementation. +- `message_queue_remove.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `MessageQueueRemove` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `MessageQueueRemove` is an `ApiHandler`. +- `MessageQueueRemove` defines `process(...)`. +- Observed side-effect areas: filesystem deletion, settings/state persistence. +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `mq.remove`, `mark_dirty_for_context`, `Response`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/message_queue_send.py.dox.md b/api/message_queue_send.py.dox.md new file mode 100644 index 000000000..4f7294a94 --- /dev/null +++ b/api/message_queue_send.py.dox.md @@ -0,0 +1,44 @@ +# message_queue_send.py DOX + +## Purpose + +- Own the `message_queue_send.py` API endpoint. +- This module handles message queue send API requests. +- Keep this file-level DOX profile synchronized with `message_queue_send.py` because this directory is intentionally flat. + +## Ownership + +- `message_queue_send.py` owns the runtime implementation. +- `message_queue_send.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `MessageQueueSend` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `MessageQueueSend` is an `ApiHandler`. +- `MessageQueueSend` defines `process(...)`. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `mq.send_message`, `mark_dirty_for_context`, `Response`, `mq.has_queue`, `mq.send_all_aggregated`, `mq.pop_item`, `mq.pop_first`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/notification_create.py.dox.md b/api/notification_create.py.dox.md new file mode 100644 index 000000000..a83b82cf4 --- /dev/null +++ b/api/notification_create.py.dox.md @@ -0,0 +1,46 @@ +# notification_create.py DOX + +## Purpose + +- Own the `notification_create.py` API endpoint. +- This module handles notification notification create requests. +- Keep this file-level DOX profile synchronized with `notification_create.py` because this directory is intentionally flat. + +## Ownership + +- `notification_create.py` owns the runtime implementation. +- `notification_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `NotificationCreate` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `NotificationCreate` is an `ApiHandler`. +- `NotificationCreate` defines `process(...)`. +- `NotificationCreate` defines `requires_auth(...)`. +- Imported dependency areas include: `flask`, `helpers.api`, `helpers.notification`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `NotificationManager.send_notification`, `NotificationType`, `notification.output`, `notification_type.lower`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_download_toast_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/notifications_clear.py.dox.md b/api/notifications_clear.py.dox.md new file mode 100644 index 000000000..dc5503b73 --- /dev/null +++ b/api/notifications_clear.py.dox.md @@ -0,0 +1,45 @@ +# notifications_clear.py DOX + +## Purpose + +- Own the `notifications_clear.py` API endpoint. +- This module handles notification notifications clear requests. +- Keep this file-level DOX profile synchronized with `notifications_clear.py` because this directory is intentionally flat. + +## Ownership + +- `notifications_clear.py` owns the runtime implementation. +- `notifications_clear.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `NotificationsClear` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `NotificationsClear` is an `ApiHandler`. +- `NotificationsClear` defines `process(...)`. +- `NotificationsClear` defines `requires_auth(...)`. +- Imported dependency areas include: `agent`, `flask`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.clear_all`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/notifications_history.py.dox.md b/api/notifications_history.py.dox.md new file mode 100644 index 000000000..a14b5bc86 --- /dev/null +++ b/api/notifications_history.py.dox.md @@ -0,0 +1,45 @@ +# notifications_history.py DOX + +## Purpose + +- Own the `notifications_history.py` API endpoint. +- This module handles notification notifications history requests. +- Keep this file-level DOX profile synchronized with `notifications_history.py` because this directory is intentionally flat. + +## Ownership + +- `notifications_history.py` owns the runtime implementation. +- `notifications_history.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `NotificationsHistory` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `NotificationsHistory` is an `ApiHandler`. +- `NotificationsHistory` defines `process(...)`. +- `NotificationsHistory` defines `requires_auth(...)`. +- Imported dependency areas include: `agent`, `flask`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.output_all`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/notifications_mark_read.py.dox.md b/api/notifications_mark_read.py.dox.md new file mode 100644 index 000000000..a06cbbdcf --- /dev/null +++ b/api/notifications_mark_read.py.dox.md @@ -0,0 +1,45 @@ +# notifications_mark_read.py DOX + +## Purpose + +- Own the `notifications_mark_read.py` API endpoint. +- This module handles notification notifications mark read requests. +- Keep this file-level DOX profile synchronized with `notifications_mark_read.py` because this directory is intentionally flat. + +## Ownership + +- `notifications_mark_read.py` owns the runtime implementation. +- `notifications_mark_read.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `NotificationsMarkRead` (`ApiHandler`) + - `requires_auth(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `NotificationsMarkRead` is an `ApiHandler`. +- `NotificationsMarkRead` defines `process(...)`. +- `NotificationsMarkRead` defines `requires_auth(...)`. +- Imported dependency areas include: `agent`, `flask`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.mark_read_by_ids`, `notification_manager.mark_all_read`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/nudge.py.dox.md b/api/nudge.py.dox.md new file mode 100644 index 000000000..f1be2cf3d --- /dev/null +++ b/api/nudge.py.dox.md @@ -0,0 +1,44 @@ +# nudge.py DOX + +## Purpose + +- Own the `nudge.py` API endpoint. +- This module handles nudge API requests. +- Keep this file-level DOX profile synchronized with `nudge.py` because this directory is intentionally flat. + +## Ownership + +- `nudge.py` owns the runtime implementation. +- `nudge.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Nudge` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Nudge` is an `ApiHandler`. +- `Nudge` defines `process(...)`. +- Imported dependency areas include: `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.use_context`, `context.nudge`, `context.log.log`, `Exception`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/pause.py.dox.md b/api/pause.py.dox.md new file mode 100644 index 000000000..37d0528e9 --- /dev/null +++ b/api/pause.py.dox.md @@ -0,0 +1,45 @@ +# pause.py DOX + +## Purpose + +- Own the `pause.py` API endpoint. +- This module handles pause API requests. +- Keep this file-level DOX profile synchronized with `pause.py` because this directory is intentionally flat. + +## Ownership + +- `pause.py` owns the runtime implementation. +- `pause.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Pause` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Pause` is an `ApiHandler`. +- `Pause` defines `process(...)`. +- Imported dependency areas include: `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.use_context`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_multi_tab_isolation.py` + - `tests/test_snapshot_schema_v1.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/plugins.py.dox.md b/api/plugins.py.dox.md new file mode 100644 index 000000000..e64b22dc9 --- /dev/null +++ b/api/plugins.py.dox.md @@ -0,0 +1,52 @@ +# plugins.py DOX + +## Purpose + +- Own the `plugins.py` API endpoint. +- This module manages plugin actions and plugin settings through the core API. +- Keep this file-level DOX profile synchronized with `plugins.py` because this directory is intentionally flat. + +## Ownership + +- `plugins.py` owns the runtime implementation. +- `plugins.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Plugins` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Plugins` is an `ApiHandler`. +- `Plugins` defines `process(...)`. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, plugin state, settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.localization`, `json`, `os`, `subprocess`, `sys`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Response`, `plugins.find_plugin_assets`, `plugins.get_plugin_meta`, `plugins.get_default_plugin_config`, `plugins.save_plugin_config`, `plugins.toggle_plugin`, `plugins.find_plugin_dir`, `files.get_abs_path`, `Localization.get.now_iso`, `plugins.determine_plugin_asset_path`, `self._get_config`, `self._get_toggle_status`, `self._list_configs`, `self._delete_config`, `self._delete_plugin`, `self._get_default_config`, `self._save_config`, `self._toggle_plugin`, `self._get_doc`, `self._run_execute_script`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_a0_connector_computer_use_metadata.py` + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_chat_compaction.py` + - `tests/test_default_prompt_budget.py` + - `tests/test_document_query_plugin.py` + - `tests/test_error_retry_plugin.py` + - `tests/test_host_browser_connector.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/plugins_list.py.dox.md b/api/plugins_list.py.dox.md new file mode 100644 index 000000000..599b5a307 --- /dev/null +++ b/api/plugins_list.py.dox.md @@ -0,0 +1,46 @@ +# plugins_list.py DOX + +## Purpose + +- Own the `plugins_list.py` API endpoint. +- This module returns plugin inventory and activation metadata for plugin UI surfaces. +- Keep this file-level DOX profile synchronized with `plugins_list.py` because this directory is intentionally flat. + +## Ownership + +- `plugins_list.py` owns the runtime implementation. +- `plugins_list.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `PluginsList` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `PluginsList` is an `ApiHandler`. +- `PluginsList` defines `process(...)`. +- Observed side-effect areas: plugin state, settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `plugins.get_enhanced_plugins_list`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_plugin_activation_ui.py` + - `tests/test_speech_plugin_split.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/poll.py.dox.md b/api/poll.py.dox.md new file mode 100644 index 000000000..851a03318 --- /dev/null +++ b/api/poll.py.dox.md @@ -0,0 +1,52 @@ +# poll.py DOX + +## Purpose + +- Own the `poll.py` API endpoint. +- This module returns chat/log/status changes for polling clients. +- Keep this file-level DOX profile synchronized with `poll.py` because this directory is intentionally flat. + +## Ownership + +- `poll.py` owns the runtime implementation. +- `poll.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Poll` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Poll` is an `ApiHandler`. +- `Poll` defines `process(...)`. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `helpers.api`, `helpers.state_snapshot`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `build_snapshot`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_multi_tab_isolation.py` + - `tests/test_oauth_github_copilot.py` + - `tests/test_oauth_providers.py` + - `tests/test_office_document_store.py` + - `tests/test_snapshot_parity.py` + - `tests/test_snapshot_schema_v1.py` + - `tests/test_timezone_regressions.py` + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/projects.py.dox.md b/api/projects.py.dox.md new file mode 100644 index 000000000..d55500c21 --- /dev/null +++ b/api/projects.py.dox.md @@ -0,0 +1,59 @@ +# projects.py DOX + +## Purpose + +- Own the `projects.py` API endpoint. +- This module manages project create, update, delete, clone, and metadata flows. +- Keep this file-level DOX profile synchronized with `projects.py` because this directory is intentionally flat. + +## Ownership + +- `projects.py` owns the runtime implementation. +- `projects.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Projects` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + - `get_active_projects_list(self)` + - `get_active_projects_options(self)` + - `create_project(self, project: dict | None)` + - `clone_project(self, project: dict | None)` + - `load_project(self, name: str | None)` + - `update_project(self, project: dict | None)` + - `delete_project(self, name: str | None)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Projects` is an `ApiHandler`. +- `Projects` defines `process(...)`. +- Observed side-effect areas: filesystem deletion, settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.notification`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `projects.get_active_projects_list`, `projects.BasicProjectData`, `projects.create_project`, `projects.load_edit_project_data`, `NotificationManager.send_notification`, `projects.EditProjectData`, `projects.update_project`, `projects.delete_project`, `projects.activate_project`, `projects.deactivate_project`, `projects.load_basic_project_data`, `projects.get_file_structure`, `self.use_context`, `Exception`, `projects.clone_git_project`, `self.get_active_projects_list`, `self.get_active_projects_options`, `self.load_project`, `self.create_project`, `self.clone_project`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_model_config_project_presets.py` + - `tests/test_office_document_store.py` + - `tests/test_plugin_activation_ui.py` + - `tests/test_projects.py` + - `tests/test_skills_runtime.py` + - `tests/test_task_scheduler_timezone.py` + - `tests/test_time_travel.py` + - `tests/test_tool_action_contracts.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/rename_work_dir_file.py.dox.md b/api/rename_work_dir_file.py.dox.md new file mode 100644 index 000000000..624bedc54 --- /dev/null +++ b/api/rename_work_dir_file.py.dox.md @@ -0,0 +1,47 @@ +# rename_work_dir_file.py DOX + +## Purpose + +- Own the `rename_work_dir_file.py` API endpoint. +- This module handles workdir file operations for rename work dir file. +- Keep this file-level DOX profile synchronized with `rename_work_dir_file.py` because this directory is intentionally flat. + +## Ownership + +- `rename_work_dir_file.py` owns the runtime implementation. +- `rename_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `RenameWorkDirFile` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` +- Top-level functions: +- `async rename_item(file_path: str, new_name: str) -> bool` +- `async create_folder(parent_path: str, folder_name: str) -> bool` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `RenameWorkDirFile` is an `ApiHandler`. +- `RenameWorkDirFile` defines `process(...)`. +- Observed side-effect areas: filesystem writes. +- Imported dependency areas include: `api`, `helpers`, `helpers.api`, `helpers.file_browser`, `posixpath`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `FileBrowser`, `browser.rename_item`, `browser.create_folder`, `strip`, `runtime.call_development_function`, `posixpath.join`, `file_path.startswith`, `extension.call_extensions_async`, `str.rstrip`, `posixpath.dirname`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/restart.py.dox.md b/api/restart.py.dox.md new file mode 100644 index 000000000..4e3156f6e --- /dev/null +++ b/api/restart.py.dox.md @@ -0,0 +1,48 @@ +# restart.py DOX + +## Purpose + +- Own the `restart.py` API endpoint. +- This module requests server restart or reload behavior. +- Keep this file-level DOX profile synchronized with `restart.py` because this directory is intentionally flat. + +## Ownership + +- `restart.py` owns the runtime implementation. +- `restart.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Restart` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Restart` is an `ApiHandler`. +- `Restart` defines `process(...)`. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `process.reload`, `Response`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_download_toast_regressions.py` + - `tests/test_self_update_tag_filter.py` + - `tests/test_timezone_regressions.py` + - `tests/test_ws_manager.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/rfc.py.dox.md b/api/rfc.py.dox.md new file mode 100644 index 000000000..6598649ea --- /dev/null +++ b/api/rfc.py.dox.md @@ -0,0 +1,47 @@ +# rfc.py DOX + +## Purpose + +- Own the `rfc.py` API endpoint. +- This module dispatches remote function calls through the RFC helper layer. +- Keep this file-level DOX profile synchronized with `rfc.py` because this directory is intentionally flat. + +## Ownership + +- `rfc.py` owns the runtime implementation. +- `rfc.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `RFC` (`ApiHandler`) + - `requires_csrf(cls) -> bool` + - `requires_auth(cls) -> bool` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `RFC` is an `ApiHandler`. +- `RFC` defines `process(...)`. +- `RFC` defines `requires_auth(...)`. +- `RFC` defines `requires_csrf(...)`. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `runtime.handle_rfc`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/scheduler_task_create.py.dox.md b/api/scheduler_task_create.py.dox.md new file mode 100644 index 000000000..332118085 --- /dev/null +++ b/api/scheduler_task_create.py.dox.md @@ -0,0 +1,44 @@ +# scheduler_task_create.py DOX + +## Purpose + +- Own the `scheduler_task_create.py` API endpoint. +- This module handles scheduler task create requests. +- Keep this file-level DOX profile synchronized with `scheduler_task_create.py` because this directory is intentionally flat. + +## Ownership + +- `scheduler_task_create.py` owns the runtime implementation. +- `scheduler_task_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SchedulerTaskCreate` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SchedulerTaskCreate` is an `ApiHandler`. +- `SchedulerTaskCreate` defines `process(...)`. +- Observed side-effect areas: filesystem writes, secret handling, scheduler state. +- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.projects`, `helpers.task_scheduler`, `random`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `PrintStyle`, `scheduler.get_task_by_uuid`, `serialize_task`, `Localization.get.set_timezone`, `scheduler.reload`, `ValueError`, `ScheduledTask.create`, `scheduler.add_task`, `requested_project_slug.strip`, `load_basic_project_data`, `random.randint`, `schedule.split`, `TaskSchedule`, `PlannedTask.create`, `AdHocTask.create`, `printer.error`, `type`, `parse_task_plan`, `parse_task_schedule`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/scheduler_task_delete.py.dox.md b/api/scheduler_task_delete.py.dox.md new file mode 100644 index 000000000..2112e95ee --- /dev/null +++ b/api/scheduler_task_delete.py.dox.md @@ -0,0 +1,44 @@ +# scheduler_task_delete.py DOX + +## Purpose + +- Own the `scheduler_task_delete.py` API endpoint. +- This module handles scheduler task delete requests. +- Keep this file-level DOX profile synchronized with `scheduler_task_delete.py` because this directory is intentionally flat. + +## Ownership + +- `scheduler_task_delete.py` owns the runtime implementation. +- `scheduler_task_delete.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SchedulerTaskDelete` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SchedulerTaskDelete` is an `ApiHandler`. +- `SchedulerTaskDelete` defines `process(...)`. +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state. +- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.localization`, `helpers.task_scheduler`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `scheduler.get_task_by_uuid`, `Localization.get.set_timezone`, `scheduler.reload`, `self.use_context`, `scheduler.cancel_running_task`, `AgentContext.remove`, `persist_chat.remove_chat`, `scheduler.remove_task_by_uuid`, `context.reset`, `scheduler.update_task`, `scheduler.save`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/scheduler_task_run.py.dox.md b/api/scheduler_task_run.py.dox.md new file mode 100644 index 000000000..f4aa4b158 --- /dev/null +++ b/api/scheduler_task_run.py.dox.md @@ -0,0 +1,44 @@ +# scheduler_task_run.py DOX + +## Purpose + +- Own the `scheduler_task_run.py` API endpoint. +- This module handles scheduler task run requests. +- Keep this file-level DOX profile synchronized with `scheduler_task_run.py` because this directory is intentionally flat. + +## Ownership + +- `scheduler_task_run.py` owns the runtime implementation. +- `scheduler_task_run.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SchedulerTaskRun` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SchedulerTaskRun` is an `ApiHandler`. +- `SchedulerTaskRun` defines `process(...)`. +- Observed side-effect areas: settings/state persistence, scheduler state. +- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `PrintStyle`, `scheduler.get_task_by_uuid`, `Localization.get.set_timezone`, `scheduler.reload`, `self._printer.error`, `scheduler.serialize_task`, `scheduler.run_task_by_uuid`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/scheduler_task_update.py.dox.md b/api/scheduler_task_update.py.dox.md new file mode 100644 index 000000000..a7c9bfced --- /dev/null +++ b/api/scheduler_task_update.py.dox.md @@ -0,0 +1,44 @@ +# scheduler_task_update.py DOX + +## Purpose + +- Own the `scheduler_task_update.py` API endpoint. +- This module handles scheduler task update requests. +- Keep this file-level DOX profile synchronized with `scheduler_task_update.py` because this directory is intentionally flat. + +## Ownership + +- `scheduler_task_update.py` owns the runtime implementation. +- `scheduler_task_update.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SchedulerTaskUpdate` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SchedulerTaskUpdate` is an `ApiHandler`. +- `SchedulerTaskUpdate` defines `process(...)`. +- Observed side-effect areas: settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.task_scheduler`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `scheduler.get_task_by_uuid`, `serialize_task`, `Localization.get.set_timezone`, `scheduler.reload`, `TaskState`, `scheduler.update_task`, `parse_task_schedule`, `parse_task_plan`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/scheduler_tasks_list.py.dox.md b/api/scheduler_tasks_list.py.dox.md new file mode 100644 index 000000000..5e5533206 --- /dev/null +++ b/api/scheduler_tasks_list.py.dox.md @@ -0,0 +1,44 @@ +# scheduler_tasks_list.py DOX + +## Purpose + +- Own the `scheduler_tasks_list.py` API endpoint. +- This module handles scheduler tasks list requests. +- Keep this file-level DOX profile synchronized with `scheduler_tasks_list.py` because this directory is intentionally flat. + +## Ownership + +- `scheduler_tasks_list.py` owns the runtime implementation. +- `scheduler_tasks_list.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SchedulerTasksList` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SchedulerTasksList` is an `ApiHandler`. +- `SchedulerTasksList` defines `process(...)`. +- Observed side-effect areas: scheduler state. +- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`, `traceback`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `scheduler.serialize_all_tasks`, `Localization.get.set_timezone`, `scheduler.reload`, `PrintStyle.error`, `traceback.format_exc`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/scheduler_tick.py.dox.md b/api/scheduler_tick.py.dox.md new file mode 100644 index 000000000..d19ae305c --- /dev/null +++ b/api/scheduler_tick.py.dox.md @@ -0,0 +1,50 @@ +# scheduler_tick.py DOX + +## Purpose + +- Own the `scheduler_tick.py` API endpoint. +- This module handles scheduler tick requests. +- Keep this file-level DOX profile synchronized with `scheduler_tick.py` because this directory is intentionally flat. + +## Ownership + +- `scheduler_tick.py` owns the runtime implementation. +- `scheduler_tick.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SchedulerTick` (`ApiHandler`) + - `requires_loopback(cls) -> bool` + - `requires_auth(cls) -> bool` + - `requires_csrf(cls) -> bool` + - `async process(self, input: Input, request: Request) -> Output` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SchedulerTick` is an `ApiHandler`. +- `SchedulerTick` defines `process(...)`. +- `SchedulerTick` defines `requires_auth(...)`. +- `SchedulerTick` defines `requires_csrf(...)`. +- `SchedulerTick` defines `requires_loopback(...)`. +- Observed side-effect areas: settings/state persistence, scheduler state. +- Imported dependency areas include: `datetime`, `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `datetime.now.strftime`, `PrintStyle`, `scheduler.get_tasks`, `scheduler.serialize_all_tasks`, `Localization.get.set_timezone`, `scheduler.reload`, `scheduler.tick`, `datetime.now`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/self_update_get.py.dox.md b/api/self_update_get.py.dox.md new file mode 100644 index 000000000..261cac93f --- /dev/null +++ b/api/self_update_get.py.dox.md @@ -0,0 +1,45 @@ +# self_update_get.py DOX + +## Purpose + +- Own the `self_update_get.py` API endpoint. +- This module handles self update get API requests. +- Keep this file-level DOX profile synchronized with `self_update_get.py` because this directory is intentionally flat. + +## Ownership + +- `self_update_get.py` owns the runtime implementation. +- `self_update_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SelfUpdateGet` (`ApiHandler`) + - `get_methods(cls) -> list[str]` + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SelfUpdateGet` is an `ApiHandler`. +- `SelfUpdateGet` defines `process(...)`. +- `SelfUpdateGet` defines `get_methods(...)`. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self_update.get_update_info`, `runtime.is_dockerized`, `self_update.load_pending_update`, `self_update.load_last_status`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/self_update_schedule.py.dox.md b/api/self_update_schedule.py.dox.md new file mode 100644 index 000000000..b865070c9 --- /dev/null +++ b/api/self_update_schedule.py.dox.md @@ -0,0 +1,45 @@ +# self_update_schedule.py DOX + +## Purpose + +- Own the `self_update_schedule.py` API endpoint. +- This module handles self update schedule API requests. +- Keep this file-level DOX profile synchronized with `self_update_schedule.py` because this directory is intentionally flat. + +## Ownership + +- `self_update_schedule.py` owns the runtime implementation. +- `self_update_schedule.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SelfUpdateSchedule` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SelfUpdateSchedule` is an `ApiHandler`. +- `SelfUpdateSchedule` defines `process(...)`. +- Observed side-effect areas: filesystem writes, subprocess/runtime control. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `runtime.is_dockerized`, `self_update.schedule_update`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_self_update_tag_filter.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/self_update_tags.py.dox.md b/api/self_update_tags.py.dox.md new file mode 100644 index 000000000..fdf78cd23 --- /dev/null +++ b/api/self_update_tags.py.dox.md @@ -0,0 +1,43 @@ +# self_update_tags.py DOX + +## Purpose + +- Own the `self_update_tags.py` API endpoint. +- This module handles self update tags API requests. +- Keep this file-level DOX profile synchronized with `self_update_tags.py` because this directory is intentionally flat. + +## Ownership + +- `self_update_tags.py` owns the runtime implementation. +- `self_update_tags.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SelfUpdateTags` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SelfUpdateTags` is an `ApiHandler`. +- `SelfUpdateTags` defines `process(...)`. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `str.strip.lower`, `self_update.get_repo_version_info.get.strip.lower`, `self_update.get_available_branch_values`, `self_update.get_selector_tag_options`, `str.strip`, `self_update.get_repo_version_info.get.strip`, `runtime.is_dockerized`, `self_update.get_repo_version_info`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/settings_get.py.dox.md b/api/settings_get.py.dox.md new file mode 100644 index 000000000..e584283fd --- /dev/null +++ b/api/settings_get.py.dox.md @@ -0,0 +1,46 @@ +# settings_get.py DOX + +## Purpose + +- Own the `settings_get.py` API endpoint. +- This module returns current application settings. +- Keep this file-level DOX profile synchronized with `settings_get.py` because this directory is intentionally flat. + +## Ownership + +- `settings_get.py` owns the runtime implementation. +- `settings_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `GetSettings` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + - `get_methods(cls) -> list[str]` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `GetSettings` is an `ApiHandler`. +- `GetSettings` defines `process(...)`. +- `GetSettings` defines `get_methods(...)`. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `settings.get_settings`, `settings.convert_out`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/settings_set.py.dox.md b/api/settings_set.py.dox.md new file mode 100644 index 000000000..0f08f9862 --- /dev/null +++ b/api/settings_set.py.dox.md @@ -0,0 +1,44 @@ +# settings_set.py DOX + +## Purpose + +- Own the `settings_set.py` API endpoint. +- This module persists application settings updates. +- Keep this file-level DOX profile synchronized with `settings_set.py` because this directory is intentionally flat. + +## Ownership + +- `settings_set.py` owns the runtime implementation. +- `settings_set.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SetSettings` (`ApiHandler`) + - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SetSettings` is an `ApiHandler`. +- `SetSettings` defines `process(...)`. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.api`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `settings.convert_in`, `settings.set_settings`, `settings.convert_out`, `settings.Settings`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/settings_workdir_file_structure.py.dox.md b/api/settings_workdir_file_structure.py.dox.md new file mode 100644 index 000000000..e52a742ef --- /dev/null +++ b/api/settings_workdir_file_structure.py.dox.md @@ -0,0 +1,46 @@ +# settings_workdir_file_structure.py DOX + +## Purpose + +- Own the `settings_workdir_file_structure.py` API endpoint. +- This module handles settings workdir file structure API requests. +- Keep this file-level DOX profile synchronized with `settings_workdir_file_structure.py` because this directory is intentionally flat. + +## Ownership + +- `settings_workdir_file_structure.py` owns the runtime implementation. +- `settings_workdir_file_structure.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SettingsWorkdirFileStructure` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + - `get_methods(cls) -> list[str]` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SettingsWorkdirFileStructure` is an `ApiHandler`. +- `SettingsWorkdirFileStructure` defines `process(...)`. +- `SettingsWorkdirFileStructure` defines `get_methods(...)`. +- Observed side-effect areas: filesystem reads, settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `files.get_abs_path_development`, `Exception`, `file_tree.file_tree`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/skills.py.dox.md b/api/skills.py.dox.md new file mode 100644 index 000000000..8da5af317 --- /dev/null +++ b/api/skills.py.dox.md @@ -0,0 +1,54 @@ +# skills.py DOX + +## Purpose + +- Own the `skills.py` API endpoint. +- This module lists and manages available skills for settings and agent-facing skill flows. +- Keep this file-level DOX profile synchronized with `skills.py` because this directory is intentionally flat. + +## Ownership + +- `skills.py` owns the runtime implementation. +- `skills.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Skills` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + - `list_skills(self, input: Input)` + - `delete_skill(self, input: Input)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Skills` is an `ApiHandler`. +- `Skills` defines `process(...)`. +- Observed side-effect areas: filesystem reads, filesystem deletion. +- Imported dependency areas include: `helpers`, `helpers.api`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `skills.list_skills`, `result.sort`, `str.strip`, `skills.delete_skill`, `projects.get_project_folder`, `runtime.is_development`, `Exception`, `self.list_skills`, `strip`, `files.normalize_a0_path`, `files.get_abs_path`, `self.delete_skill`, `files.is_in_dir`, `projects.get_project_meta`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_document_query_plugin.py` + - `tests/test_fasta2a_client.py` + - `tests/test_office_canvas_setup.py` + - `tests/test_office_document_store.py` + - `tests/test_skills_runtime.py` + - `tests/test_time_travel.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/skills_import.py.dox.md b/api/skills_import.py.dox.md new file mode 100644 index 000000000..4940e833a --- /dev/null +++ b/api/skills_import.py.dox.md @@ -0,0 +1,44 @@ +# skills_import.py DOX + +## Purpose + +- Own the `skills_import.py` API endpoint. +- This module handles skills import API requests. +- Keep this file-level DOX profile synchronized with `skills_import.py` because this directory is intentionally flat. + +## Ownership + +- `skills_import.py` owns the runtime implementation. +- `skills_import.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SkillsImport` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SkillsImport` is an `ApiHandler`. +- `SkillsImport` defines `process(...)`. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion. +- Imported dependency areas include: `__future__`, `helpers`, `helpers.api`, `helpers.skills_import`, `os`, `pathlib`, `time`, `uuid`, `werkzeug.datastructures`, `werkzeug.utils`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.use_context`, `strip.lower`, `Path`, `tmp_dir.mkdir`, `secure_filename`, `time.strftime`, `skills_file.save`, `strip`, `files.get_abs_path`, `base.lower.endswith`, `import_skills`, `files.deabsolute_path`, `uuid.uuid4`, `tmp_path.unlink`, `base.lower`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/skills_import_preview.py.dox.md b/api/skills_import_preview.py.dox.md new file mode 100644 index 000000000..107f55b2a --- /dev/null +++ b/api/skills_import_preview.py.dox.md @@ -0,0 +1,44 @@ +# skills_import_preview.py DOX + +## Purpose + +- Own the `skills_import_preview.py` API endpoint. +- This module handles skills import preview API requests. +- Keep this file-level DOX profile synchronized with `skills_import_preview.py` because this directory is intentionally flat. + +## Ownership + +- `skills_import_preview.py` owns the runtime implementation. +- `skills_import_preview.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SkillsImportPreview` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `SkillsImportPreview` is an `ApiHandler`. +- `SkillsImportPreview` defines `process(...)`. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion. +- Imported dependency areas include: `__future__`, `helpers`, `helpers.api`, `helpers.skills_import`, `os`, `pathlib`, `time`, `uuid`, `werkzeug.datastructures`, `werkzeug.utils`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.use_context`, `strip.lower`, `Path`, `tmp_dir.mkdir`, `secure_filename`, `time.strftime`, `skills_file.save`, `strip`, `files.get_abs_path`, `base.lower.endswith`, `import_skills`, `files.deabsolute_path`, `uuid.uuid4`, `tmp_path.unlink`, `base.lower`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/subagents.py.dox.md b/api/subagents.py.dox.md new file mode 100644 index 000000000..85777218f --- /dev/null +++ b/api/subagents.py.dox.md @@ -0,0 +1,49 @@ +# subagents.py DOX + +## Purpose + +- Own the `subagents.py` API endpoint. +- This module returns subordinate agent profile data for UI and delegation flows. +- Keep this file-level DOX profile synchronized with `subagents.py` because this directory is intentionally flat. + +## Ownership + +- `subagents.py` owns the runtime implementation. +- `subagents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Subagents` (`ApiHandler`) + - `async process(self, input: Input, request: Request) -> Output` + - `get_subagents_list(self)` + - `load_agent(self, name: str | None)` + - `save_agent(self, name: str | None, data: dict | None)` + - `delete_agent(self, name: str | None)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Subagents` is an `ApiHandler`. +- `Subagents` defines `process(...)`. +- Observed side-effect areas: filesystem writes, filesystem deletion. +- Imported dependency areas include: `helpers`, `helpers.api`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `subagents.get_agents_list`, `subagents.load_agent_data`, `subagents.SubAgent`, `subagents.save_agent_data`, `subagents.delete_agent_data`, `self.use_context`, `Exception`, `self.get_subagents_list`, `self.load_agent`, `self.save_agent`, `self.delete_agent`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_skills_runtime.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/tunnel.py.dox.md b/api/tunnel.py.dox.md new file mode 100644 index 000000000..3618edc6e --- /dev/null +++ b/api/tunnel.py.dox.md @@ -0,0 +1,48 @@ +# tunnel.py DOX + +## Purpose + +- Own the `tunnel.py` API endpoint. +- This module manages tunnel provider status, start, and stop actions. +- Keep this file-level DOX profile synchronized with `tunnel.py` because this directory is intentionally flat. + +## Ownership + +- `tunnel.py` owns the runtime implementation. +- `tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Tunnel` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` +- Top-level functions: +- `async process(input: dict) -> dict | Response` +- `stop()` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `Tunnel` is an `ApiHandler`. +- `Tunnel` defines `process(...)`. +- Observed side-effect areas: tunnel state. +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.tunnel_manager`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `TunnelManager.get_instance`, `tunnel_manager.stop_tunnel`, `runtime.get_web_ui_port`, `tunnel_manager.start_tunnel`, `tunnel_manager.get_last_error`, `process`, `tunnel_manager.get_notifications`, `stop`, `tunnel_manager.get_tunnel_url`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/tunnel_proxy.py.dox.md b/api/tunnel_proxy.py.dox.md new file mode 100644 index 000000000..b713482c9 --- /dev/null +++ b/api/tunnel_proxy.py.dox.md @@ -0,0 +1,46 @@ +# tunnel_proxy.py DOX + +## Purpose + +- Own the `tunnel_proxy.py` API endpoint. +- This module proxies tunnel-related HTTP traffic through the configured tunnel provider. +- Keep this file-level DOX profile synchronized with `tunnel_proxy.py` because this directory is intentionally flat. + +## Ownership + +- `tunnel_proxy.py` owns the runtime implementation. +- `tunnel_proxy.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `TunnelProxy` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` +- Top-level functions: +- `async process(input: dict) -> dict | Response` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `TunnelProxy` is an `ApiHandler`. +- `TunnelProxy` defines `process(...)`. +- Observed side-effect areas: network calls, settings/state persistence, tunnel state. +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.tunnel_manager`, `requests`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `runtime.get_arg`, `requests.post`, `process`, `dotenv.get_dotenv_value`, `response.json`, `local_process`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/upload.py.dox.md b/api/upload.py.dox.md new file mode 100644 index 000000000..9fccb571f --- /dev/null +++ b/api/upload.py.dox.md @@ -0,0 +1,47 @@ +# upload.py DOX + +## Purpose + +- Own the `upload.py` API endpoint. +- This module accepts general uploads into runtime upload storage. +- Keep this file-level DOX profile synchronized with `upload.py` because this directory is intentionally flat. + +## Ownership + +- `upload.py` owns the runtime implementation. +- `upload.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `UploadFile` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` + - `allowed_file(self, filename)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `UploadFile` is an `ApiHandler`. +- `UploadFile` defines `process(...)`. +- Observed side-effect areas: filesystem reads, settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.security`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `request.files.getlist`, `Exception`, `self.allowed_file`, `safe_filename`, `file.save`, `files.get_abs_path`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_image_get_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/api/upload_work_dir_files.py.dox.md b/api/upload_work_dir_files.py.dox.md new file mode 100644 index 000000000..6cf9370ae --- /dev/null +++ b/api/upload_work_dir_files.py.dox.md @@ -0,0 +1,47 @@ +# upload_work_dir_files.py DOX + +## Purpose + +- Own the `upload_work_dir_files.py` API endpoint. +- This module handles workdir file operations for upload work dir files. +- Keep this file-level DOX profile synchronized with `upload_work_dir_files.py` because this directory is intentionally flat. + +## Ownership + +- `upload_work_dir_files.py` owns the runtime implementation. +- `upload_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `UploadWorkDirFiles` (`ApiHandler`) + - `async process(self, input: dict, request: Request) -> dict | Response` +- Top-level functions: +- `async upload_files(uploaded_files: list[FileStorage], current_path: str)` +- `async upload_file(current_path: str, filename: str, base64_content: str)` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `UploadWorkDirFiles` is an `ApiHandler`. +- `UploadWorkDirFiles` defines `process(...)`. +- Observed side-effect areas: filesystem writes. +- Imported dependency areas include: `api`, `base64`, `helpers`, `helpers.api`, `helpers.file_browser`, `os`, `posixpath`, `werkzeug.datastructures`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `runtime.is_development`, `FileBrowser`, `browser.save_file_b64`, `request.files.getlist`, `browser.save_files`, `Exception`, `upload_files`, `runtime.call_development_function`, `file.stream.read`, `base64.b64encode.decode`, `extension.call_extensions_async`, `base64.b64encode`, `posixpath.join`, `str.rstrip`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/ws_dev_test.py.dox.md b/api/ws_dev_test.py.dox.md new file mode 100644 index 000000000..aaad42608 --- /dev/null +++ b/api/ws_dev_test.py.dox.md @@ -0,0 +1,44 @@ +# ws_dev_test.py DOX + +## Purpose + +- Own the `ws_dev_test.py` API endpoint. +- This module provides a development WebSocket test namespace. +- Keep this file-level DOX profile synchronized with `ws_dev_test.py` because this directory is intentionally flat. + +## Ownership + +- `ws_dev_test.py` owns the runtime implementation. +- `ws_dev_test.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `WsDevTest` (`WsHandler`) + - `async process(self, event: str, data: dict, sid: str) -> dict[str, Any] | WsResult | None` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `WsDevTest` is a `WsHandler`. +- `WsDevTest` defines `process(...)`. +- Observed side-effect areas: filesystem writes, network calls, WebSocket state. +- Imported dependency areas include: `asyncio`, `helpers`, `helpers.print_style`, `helpers.ws`, `helpers.ws_manager`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `event.startswith`, `self.manager.register_diagnostic_watcher`, `self.manager.unregister_diagnostic_watcher`, `PrintStyle.info`, `PrintStyle.debug`, `PrintStyle.warning`, `runtime.is_development`, `WsResult.error`, `self.broadcast`, `asyncio.sleep`, `self.emit_to`, `self.dispatch_to_all_sids`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/ws_hello.py.dox.md b/api/ws_hello.py.dox.md new file mode 100644 index 000000000..863b99167 --- /dev/null +++ b/api/ws_hello.py.dox.md @@ -0,0 +1,44 @@ +# ws_hello.py DOX + +## Purpose + +- Own the `ws_hello.py` API endpoint. +- This module provides a small WebSocket hello/test namespace. +- Keep this file-level DOX profile synchronized with `ws_hello.py` because this directory is intentionally flat. + +## Ownership + +- `ws_hello.py` owns the runtime implementation. +- `ws_hello.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `WsHello` (`WsHandler`) + - `async process(self, event: str, data: dict, sid: str) -> dict | None` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `WsHello` is a `WsHandler`. +- `WsHello` defines `process(...)`. +- Observed side-effect areas: WebSocket state. +- Imported dependency areas include: `helpers.print_style`, `helpers.ws`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `PrintStyle.info`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/api/ws_webui.py.dox.md b/api/ws_webui.py.dox.md new file mode 100644 index 000000000..a9cebf317 --- /dev/null +++ b/api/ws_webui.py.dox.md @@ -0,0 +1,49 @@ +# ws_webui.py DOX + +## Purpose + +- Own the `ws_webui.py` API endpoint. +- This module owns the primary WebUI WebSocket namespace and event bridge. +- Keep this file-level DOX profile synchronized with `ws_webui.py` because this directory is intentionally flat. + +## Ownership + +- `ws_webui.py` owns the runtime implementation. +- `ws_webui.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `WsWebui` (`WsHandler`) + - `async on_connect(self, sid: str) -> None` + - `async on_disconnect(self, sid: str) -> None` + - `async process(self, event: str, data: dict, sid: str) -> dict | None` + +## Runtime Contracts + +- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`. +- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change. +- `WsWebui` is a `WsHandler`. +- `WsWebui` defines `process(...)`. +- Observed side-effect areas: network calls, WebSocket state, settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.ws`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `extension.call_extensions_async`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes. +- Update frontend callers, plugin callers, and tests together when payload shape changes. +- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies. + +## Verification + +- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists. +- Related tests observed by source search: + - `tests/test_state_sync_handler.py` + - `tests/test_state_sync_welcome_screen.py` + - `tests/test_ws_handlers.py` + +## Child DOX Index + +No child DOX files. diff --git a/docker/AGENTS.md b/docker/AGENTS.md index 0b58f32e8..757608953 100644 --- a/docker/AGENTS.md +++ b/docker/AGENTS.md @@ -31,4 +31,9 @@ ## Child DOX Index -No child DOX files. +Direct child DOX files: + +| Child | Scope | +| --- | --- | +| [base/AGENTS.md](base/AGENTS.md) | Base image Dockerfile, copied filesystem, and installation scripts. | +| [run/AGENTS.md](run/AGENTS.md) | Runnable image Dockerfile, compose example, entrypoints, and install scripts. | diff --git a/docker/base/AGENTS.md b/docker/base/AGENTS.md new file mode 100644 index 000000000..bcfb986d7 --- /dev/null +++ b/docker/base/AGENTS.md @@ -0,0 +1,34 @@ +# Docker Base Image DOX + +## Purpose + +- Own the Agent Zero base image build context. +- Build the operating system, package, Python, SearXNG, SSH, and bootstrap layers reused by runnable images. + +## Ownership + +- `Dockerfile` owns base image layering and installation order. +- `build.txt` owns maintainer build and push command notes. +- `fs/ins/` owns installation scripts copied into the image. +- Files under `fs/` are copied to container root during the base build. + +## Local Contracts + +- Preserve cache-friendly package and runtime installation stages. +- Keep locale and timezone defaults compatible with the root Docker contract. +- Do not add secrets, user data, or local environment files to the image context. +- Installation scripts must be noninteractive and suitable for multi-architecture buildx runs. + +## Work Guidance + +- Keep base dependencies here only when they are common to runnable Agent Zero images. +- Coordinate Python runtime changes with root Docker documentation and runnable image setup. + +## Verification + +- Build `docker/base` when changing Dockerfile or install scripts. +- Run a runnable image smoke check when base runtime behavior changes. + +## Child DOX Index + +No child DOX files. diff --git a/docker/run/AGENTS.md b/docker/run/AGENTS.md new file mode 100644 index 000000000..f2bacfdf2 --- /dev/null +++ b/docker/run/AGENTS.md @@ -0,0 +1,36 @@ +# Docker Runtime Image DOX + +## Purpose + +- Own the runnable Agent Zero image context and local compose example. +- Install Agent Zero from a selected branch onto the base image and prepare runtime entrypoints. + +## Ownership + +- `Dockerfile` owns branch-based image assembly, exposed ports, and container startup command. +- `docker-compose.yml` owns the local compose service example. +- `build.txt` owns maintainer build and push command notes. +- `fs/exe/` owns runtime entrypoint, supervisor, self-update, Node eval, and service scripts. +- `fs/ins/` owns preinstall, installation, virtualenv, Playwright, SSH, and postinstall scripts. +- Files under `fs/` are copied to container root during the runtime build. + +## Local Contracts + +- `BRANCH` is required for branch-based Docker builds. +- Preserve exposed ports for SSH, HTTP, and tunneled services unless docs and workflows are updated together. +- Keep the two-runtime Python model aligned with the root contract. +- Do not bake secrets, local `.env` values, or user data into the image. + +## Work Guidance + +- Keep startup scripts explicit about framework runtime versus execution runtime. +- Coordinate tag, branch, and publishing changes with GitHub workflow automation. + +## Verification + +- Build `docker/run` when changing Dockerfile or install scripts. +- Smoke-test container startup after entrypoint, supervisor, port, or compose changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/AGENTS.md b/extensions/python/AGENTS.md index 53538a8e1..270a98afd 100644 --- a/extensions/python/AGENTS.md +++ b/extensions/python/AGENTS.md @@ -31,4 +31,37 @@ ## Child DOX Index -No child DOX files. +Direct child DOX files: + +| Child | Scope | +| --- | --- | +| [_functions/AGENTS.md](_functions/AGENTS.md) | Implicit `@extensible` backend hook implementations. | +| [agent_init/AGENTS.md](agent_init/AGENTS.md) | Agent context initialization hooks. | +| [banners/AGENTS.md](banners/AGENTS.md) | Backend banner and discovery-card contributions. | +| [before_main_llm_call/AGENTS.md](before_main_llm_call/AGENTS.md) | Pre-main-model-call behavior. | +| [error_format/AGENTS.md](error_format/AGENTS.md) | Error formatting and masking behavior. | +| [hist_add_before/AGENTS.md](hist_add_before/AGENTS.md) | Pre-history-insertion masking behavior. | +| [hist_add_tool_result/AGENTS.md](hist_add_tool_result/AGENTS.md) | Tool-result history side effects. | +| [job_loop/AGENTS.md](job_loop/AGENTS.md) | Periodic backend maintenance jobs. | +| [message_loop_end/AGENTS.md](message_loop_end/AGENTS.md) | End-of-message-loop history and persistence behavior. | +| [message_loop_prompts_after/AGENTS.md](message_loop_prompts_after/AGENTS.md) | Prompt extras appended after message-loop prompt construction. | +| [message_loop_prompts_before/AGENTS.md](message_loop_prompts_before/AGENTS.md) | Pre-prompt-construction message-loop gates. | +| [message_loop_start/AGENTS.md](message_loop_start/AGENTS.md) | Start-of-message-loop iteration state. | +| [monologue_end/AGENTS.md](monologue_end/AGENTS.md) | End-of-monologue UI and cleanup behavior. | +| [monologue_start/AGENTS.md](monologue_start/AGENTS.md) | Start-of-monologue behavior such as chat renaming. | +| [process_chain_end/AGENTS.md](process_chain_end/AGENTS.md) | Process-chain completion and queued-message handling. | +| [reasoning_stream/AGENTS.md](reasoning_stream/AGENTS.md) | Full reasoning stream handling. | +| [reasoning_stream_chunk/AGENTS.md](reasoning_stream_chunk/AGENTS.md) | Reasoning stream chunk masking. | +| [reasoning_stream_end/AGENTS.md](reasoning_stream_end/AGENTS.md) | Reasoning stream finalization. | +| [response_stream/AGENTS.md](response_stream/AGENTS.md) | Full assistant response stream handling. | +| [response_stream_chunk/AGENTS.md](response_stream_chunk/AGENTS.md) | Assistant response chunk masking. | +| [response_stream_end/AGENTS.md](response_stream_end/AGENTS.md) | Assistant response stream finalization. | +| [startup_migration/AGENTS.md](startup_migration/AGENTS.md) | Startup migrations. | +| [system_prompt/AGENTS.md](system_prompt/AGENTS.md) | Core system prompt section construction. | +| [tool_execute_after/AGENTS.md](tool_execute_after/AGENTS.md) | Post-tool-execution processing. | +| [tool_execute_before/AGENTS.md](tool_execute_before/AGENTS.md) | Pre-tool-execution processing. | +| [user_message_ui/AGENTS.md](user_message_ui/AGENTS.md) | User-visible UI message hooks. | +| [util_model_call_before/AGENTS.md](util_model_call_before/AGENTS.md) | Pre-utility-model-call masking. | +| [webui_ws_connect/AGENTS.md](webui_ws_connect/AGENTS.md) | WebUI WebSocket connect behavior. | +| [webui_ws_disconnect/AGENTS.md](webui_ws_disconnect/AGENTS.md) | WebUI WebSocket disconnect behavior. | +| [webui_ws_event/AGENTS.md](webui_ws_event/AGENTS.md) | Incoming WebUI WebSocket event behavior. | diff --git a/extensions/python/_functions/AGENTS.md b/extensions/python/_functions/AGENTS.md new file mode 100644 index 000000000..0b21bd510 --- /dev/null +++ b/extensions/python/_functions/AGENTS.md @@ -0,0 +1,29 @@ +# Python Function Extensions DOX + +## Purpose + +- Own implicit `@extensible` backend hook implementations. +- Preserve nested module, class/function, method, and `start`/`end` extension layout. + +## Ownership + +- Each nested path mirrors a Python module and qualname segment. +- Leaf `start/` and `end/` directories own ordered extension files for that extensible function point. + +## Local Contracts + +- Do not flatten nested qualname paths into retired legacy folder names. +- Extension functions must match the implicit hook's supplied arguments. +- Preserve ordering prefixes where exception handling, watchdog registration, or cleanup depends on them. + +## Work Guidance + +- Keep implicit hook extensions narrow and colocated with the exact function point they extend. + +## Verification + +- Run targeted tests for the affected function point after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/agent_init/AGENTS.md b/extensions/python/agent_init/AGENTS.md new file mode 100644 index 000000000..3121c8244 --- /dev/null +++ b/extensions/python/agent_init/AGENTS.md @@ -0,0 +1,26 @@ +# Agent Init Extensions DOX + +## Purpose + +- Own backend extensions that run when an agent context initializes. + +## Ownership + +- Ordered Python files own initial UI message setup and profile settings load behavior. + +## Local Contracts + +- Keep initialization idempotent for contexts that may be restored or reloaded. +- Preserve ordering between initial message creation and profile settings loading. + +## Work Guidance + +- Coordinate changes with profile loading, settings resolution, and startup smoke checks. + +## Verification + +- Smoke-test new chat/context initialization after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/banners/AGENTS.md b/extensions/python/banners/AGENTS.md new file mode 100644 index 000000000..d49581a27 --- /dev/null +++ b/extensions/python/banners/AGENTS.md @@ -0,0 +1,27 @@ +# Banner Extensions DOX + +## Purpose + +- Own backend banner and discovery-card contributions. + +## Ownership + +- Ordered Python files append alert banners or discovery cards to the mutable `banners` list. + +## Local Contracts + +- Banner IDs must be unique and stable. +- Use supported banner/card fields and types only. +- Do not expose secrets, local paths, or raw system diagnostics in banner text. + +## Work Guidance + +- Gate setup or warning banners on current configuration/status where possible. + +## Verification + +- Smoke-test welcome-screen banner rendering, ordering, dismissal, and CTA behavior after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/before_main_llm_call/AGENTS.md b/extensions/python/before_main_llm_call/AGENTS.md new file mode 100644 index 000000000..36214e3b3 --- /dev/null +++ b/extensions/python/before_main_llm_call/AGENTS.md @@ -0,0 +1,26 @@ +# Before Main LLM Call Extensions DOX + +## Purpose + +- Own backend behavior that runs immediately before the main LLM call. + +## Ownership + +- Ordered Python files own pre-call logging or context preparation for streaming/model execution. + +## Local Contracts + +- Do not mutate prompt or history data unless the hook contract explicitly passes mutable state for that purpose. +- Avoid logging secrets, hidden prompt sections, or private user data. + +## Work Guidance + +- Keep this hook light because it sits on the main model hot path. + +## Verification + +- Run targeted model-call or streaming tests after behavior changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/error_format/AGENTS.md b/extensions/python/error_format/AGENTS.md new file mode 100644 index 000000000..6dd136a73 --- /dev/null +++ b/extensions/python/error_format/AGENTS.md @@ -0,0 +1,26 @@ +# Error Format Extensions DOX + +## Purpose + +- Own backend error formatting and masking before errors are shown or logged. + +## Ownership + +- Ordered Python files own mutation of error-format data passed by the hook. + +## Local Contracts + +- Preserve secret masking and safe user-facing error messages. +- Do not expose raw tokens, credentials, hidden prompts, or private payloads. + +## Work Guidance + +- Keep masking rules conservative and synchronized with tool/model error surfaces. + +## Verification + +- Test or inspect representative masked and unmasked error paths after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/hist_add_before/AGENTS.md b/extensions/python/hist_add_before/AGENTS.md new file mode 100644 index 000000000..7553e0618 --- /dev/null +++ b/extensions/python/hist_add_before/AGENTS.md @@ -0,0 +1,26 @@ +# History Add Before Extensions DOX + +## Purpose + +- Own preprocessing before messages are added to agent history. + +## Ownership + +- Ordered Python files own history content masking before persistence or model reuse. + +## Local Contracts + +- Preserve secret and sensitive-content masking before history storage. +- Do not remove fields required by downstream history organization or replay. + +## Work Guidance + +- Coordinate history mutation changes with message persistence and memory behavior. + +## Verification + +- Test message history insertion for masked content after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/hist_add_tool_result/AGENTS.md b/extensions/python/hist_add_tool_result/AGENTS.md new file mode 100644 index 000000000..0c92126a9 --- /dev/null +++ b/extensions/python/hist_add_tool_result/AGENTS.md @@ -0,0 +1,26 @@ +# History Tool Result Extensions DOX + +## Purpose + +- Own processing after tool results are added to history. + +## Ownership + +- Ordered Python files own tool-call file persistence and related history side effects. + +## Local Contracts + +- Preserve tool result traceability without leaking secrets. +- Keep file artifacts inside expected runtime/user-owned paths. + +## Work Guidance + +- Coordinate changes with tool output storage and chat persistence behavior. + +## Verification + +- Smoke-test a tool call that produces persisted output after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/job_loop/AGENTS.md b/extensions/python/job_loop/AGENTS.md new file mode 100644 index 000000000..afa7597a3 --- /dev/null +++ b/extensions/python/job_loop/AGENTS.md @@ -0,0 +1,26 @@ +# Job Loop Extensions DOX + +## Purpose + +- Own periodic backend maintenance jobs. + +## Ownership + +- Ordered Python files own cleanup of expired API chats, cache trimming, and future job-loop tasks. + +## Local Contracts + +- Jobs must be idempotent and safe to run repeatedly. +- Keep cleanup scoped to owned caches, temporary contexts, or documented runtime state. + +## Work Guidance + +- Avoid expensive work on every loop; use timestamps or thresholds when practical. + +## Verification + +- Run targeted cleanup/cache tests or smoke-test job-loop startup after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/message_loop_end/AGENTS.md b/extensions/python/message_loop_end/AGENTS.md new file mode 100644 index 000000000..8927890a9 --- /dev/null +++ b/extensions/python/message_loop_end/AGENTS.md @@ -0,0 +1,26 @@ +# Message Loop End Extensions DOX + +## Purpose + +- Own backend behavior that runs after a message loop completes. + +## Ownership + +- Ordered Python files own history organization and chat persistence at loop end. + +## Local Contracts + +- Preserve history consistency before saving chats. +- Do not skip persistence for successful loops unless the hook contract explicitly permits it. + +## Work Guidance + +- Coordinate changes with chat serialization, history organization, and WebUI refresh behavior. + +## Verification + +- Smoke-test sending a message, reloading the chat, and checking persisted history after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/message_loop_prompts_after/AGENTS.md b/extensions/python/message_loop_prompts_after/AGENTS.md new file mode 100644 index 000000000..c19db6eb0 --- /dev/null +++ b/extensions/python/message_loop_prompts_after/AGENTS.md @@ -0,0 +1,27 @@ +# Message Loop Prompts After Extensions DOX + +## Purpose + +- Own prompt extras appended after primary message-loop prompt construction. + +## Ownership + +- Ordered Python files own current datetime, skill recall/load context, agent info, and workdir extras injection. + +## Local Contracts + +- Keep injected content bounded and clearly attributed. +- Preserve ordering where later prompt extras depend on earlier recall or load results. +- Do not expose secrets or private files from workdir extras. + +## Work Guidance + +- Coordinate prompt-extra changes with skill, workdir, and profile contracts. + +## Verification + +- Inspect rendered prompt extras or run prompt-construction tests after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/message_loop_prompts_before/AGENTS.md b/extensions/python/message_loop_prompts_before/AGENTS.md new file mode 100644 index 000000000..3483592c7 --- /dev/null +++ b/extensions/python/message_loop_prompts_before/AGENTS.md @@ -0,0 +1,26 @@ +# Message Loop Prompts Before Extensions DOX + +## Purpose + +- Own preprocessing before message-loop prompt construction. + +## Ownership + +- Ordered Python files own history organization waits and related prompt-preparation gates. + +## Local Contracts + +- Preserve history consistency before prompts are assembled. +- Avoid blocking indefinitely on background organization tasks. + +## Work Guidance + +- Keep waiting behavior observable and bounded. + +## Verification + +- Smoke-test prompt construction after chats with pending history organization. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/message_loop_start/AGENTS.md b/extensions/python/message_loop_start/AGENTS.md new file mode 100644 index 000000000..a0c6c1790 --- /dev/null +++ b/extensions/python/message_loop_start/AGENTS.md @@ -0,0 +1,26 @@ +# Message Loop Start Extensions DOX + +## Purpose + +- Own backend behavior that runs at the start of each message loop iteration. + +## Ownership + +- Ordered Python files own iteration counters and future loop-start state setup. + +## Local Contracts + +- Keep per-loop counters deterministic and scoped to the active context. +- Do not reset state owned by monologue-level hooks. + +## Work Guidance + +- Coordinate loop-start state changes with logging, streaming, and process-chain behavior. + +## Verification + +- Smoke-test multi-turn conversations after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/monologue_end/AGENTS.md b/extensions/python/monologue_end/AGENTS.md new file mode 100644 index 000000000..b842ba071 --- /dev/null +++ b/extensions/python/monologue_end/AGENTS.md @@ -0,0 +1,26 @@ +# Monologue End Extensions DOX + +## Purpose + +- Own backend behavior that runs when a monologue ends. + +## Ownership + +- Ordered Python files own waiting-for-input UI message behavior and future monologue-end cleanup. + +## Local Contracts + +- Preserve clear UI state when the agent stops for user input. +- Do not leave loading/processing indicators stale. + +## Work Guidance + +- Coordinate changes with WebUI loading state and message-loop persistence. + +## Verification + +- Smoke-test an agent response that returns to waiting-for-input state. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/monologue_start/AGENTS.md b/extensions/python/monologue_start/AGENTS.md new file mode 100644 index 000000000..93615ed68 --- /dev/null +++ b/extensions/python/monologue_start/AGENTS.md @@ -0,0 +1,26 @@ +# Monologue Start Extensions DOX + +## Purpose + +- Own backend behavior that runs when a monologue starts. + +## Ownership + +- Ordered Python files own automatic chat renaming and future monologue-start setup. + +## Local Contracts + +- Keep automatic rename behavior bounded and non-destructive. +- Do not override explicit user chat names without the intended guard conditions. + +## Work Guidance + +- Coordinate rename behavior with chat persistence and WebUI refresh. + +## Verification + +- Smoke-test new chat naming and existing named chat behavior after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/process_chain_end/AGENTS.md b/extensions/python/process_chain_end/AGENTS.md new file mode 100644 index 000000000..c70340417 --- /dev/null +++ b/extensions/python/process_chain_end/AGENTS.md @@ -0,0 +1,26 @@ +# Process Chain End Extensions DOX + +## Purpose + +- Own backend behavior after process-chain execution completes. + +## Ownership + +- Ordered Python files own queued-message processing and future process-chain completion behavior. + +## Local Contracts + +- Preserve queue ordering and avoid duplicate message processing. +- Keep queue side effects synchronized with chat persistence and WebUI state. + +## Work Guidance + +- Coordinate changes with message queue components and external integration plugins. + +## Verification + +- Smoke-test queued messages and final response handling after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/reasoning_stream/AGENTS.md b/extensions/python/reasoning_stream/AGENTS.md new file mode 100644 index 000000000..6cd3e6b2e --- /dev/null +++ b/extensions/python/reasoning_stream/AGENTS.md @@ -0,0 +1,26 @@ +# Reasoning Stream Extensions DOX + +## Purpose + +- Own handling of full reasoning stream updates. + +## Ownership + +- Ordered Python files own logging reasoning content from stream state. + +## Local Contracts + +- Preserve masking and privacy rules for reasoning content. +- Keep stream logging compatible with chunk and end hooks. + +## Work Guidance + +- Coordinate reasoning stream changes with UI log rendering and hidden-content policy. + +## Verification + +- Smoke-test reasoning stream display/logging when the active model provides reasoning. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/reasoning_stream_chunk/AGENTS.md b/extensions/python/reasoning_stream_chunk/AGENTS.md new file mode 100644 index 000000000..4e7461224 --- /dev/null +++ b/extensions/python/reasoning_stream_chunk/AGENTS.md @@ -0,0 +1,26 @@ +# Reasoning Stream Chunk Extensions DOX + +## Purpose + +- Own handling of incremental reasoning stream chunks. + +## Ownership + +- Ordered Python files own chunk-level masking before reasoning is displayed or stored. + +## Local Contracts + +- Mask secrets and sensitive content before chunk data reaches logs or UI. +- Keep chunk mutation compatible with final stream-end masking. + +## Work Guidance + +- Keep chunk processing lightweight for streaming performance. + +## Verification + +- Smoke-test streamed reasoning with representative sensitive patterns after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/reasoning_stream_end/AGENTS.md b/extensions/python/reasoning_stream_end/AGENTS.md new file mode 100644 index 000000000..d702b22ad --- /dev/null +++ b/extensions/python/reasoning_stream_end/AGENTS.md @@ -0,0 +1,26 @@ +# Reasoning Stream End Extensions DOX + +## Purpose + +- Own finalization of reasoning stream content. + +## Ownership + +- Ordered Python files own final reasoning masking and end-of-stream cleanup. + +## Local Contracts + +- Preserve final masking even if earlier chunk masking missed content. +- Keep end-state consistent with reasoning stream log entries. + +## Work Guidance + +- Coordinate final masking changes with chunk masking and UI rendering. + +## Verification + +- Smoke-test reasoning stream completion with sensitive-content cases. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/response_stream/AGENTS.md b/extensions/python/response_stream/AGENTS.md new file mode 100644 index 000000000..53a42df09 --- /dev/null +++ b/extensions/python/response_stream/AGENTS.md @@ -0,0 +1,27 @@ +# Response Stream Extensions DOX + +## Purpose + +- Own handling of full assistant response stream updates. + +## Ownership + +- Ordered Python files own response logging, include-alias replacement, and live response updates. + +## Local Contracts + +- Keep streaming output synchronized with UI log items. +- Preserve include-alias replacement semantics where prompts/tools rely on them. +- Do not expose unmasked secrets in live responses. + +## Work Guidance + +- Coordinate stream changes with chunk/end hooks and message rendering. + +## Verification + +- Smoke-test streamed responses, live updates, and include alias replacement after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/response_stream_chunk/AGENTS.md b/extensions/python/response_stream_chunk/AGENTS.md new file mode 100644 index 000000000..9ceff97a6 --- /dev/null +++ b/extensions/python/response_stream_chunk/AGENTS.md @@ -0,0 +1,26 @@ +# Response Stream Chunk Extensions DOX + +## Purpose + +- Own handling of incremental assistant response chunks. + +## Ownership + +- Ordered Python files own chunk-level response masking. + +## Local Contracts + +- Mask secrets before response chunks reach UI or persisted logs. +- Keep chunk processing compatible with final response stream masking. + +## Work Guidance + +- Keep per-chunk work lightweight for streaming responsiveness. + +## Verification + +- Smoke-test streaming responses with sensitive patterns after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/response_stream_end/AGENTS.md b/extensions/python/response_stream_end/AGENTS.md new file mode 100644 index 000000000..963620e5d --- /dev/null +++ b/extensions/python/response_stream_end/AGENTS.md @@ -0,0 +1,26 @@ +# Response Stream End Extensions DOX + +## Purpose + +- Own finalization of assistant response stream content. + +## Ownership + +- Ordered Python files own final masking and stream-end log updates. + +## Local Contracts + +- Preserve final masking before response content is considered complete. +- Keep log state consistent with streamed chunks and final response text. + +## Work Guidance + +- Coordinate finalization changes with live response and message rendering behavior. + +## Verification + +- Smoke-test response completion and persisted message display after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/startup_migration/AGENTS.md b/extensions/python/startup_migration/AGENTS.md new file mode 100644 index 000000000..a4c9e202a --- /dev/null +++ b/extensions/python/startup_migration/AGENTS.md @@ -0,0 +1,27 @@ +# Startup Migration Extensions DOX + +## Purpose + +- Own backend startup migrations. + +## Ownership + +- Ordered Python files in this folder own idempotent migration steps that run during startup. + +## Local Contracts + +- Migrations must be safe to run repeatedly. +- Preserve user data and create backups or reversible paths when changing durable state. +- Keep long-running work bounded and observable. + +## Work Guidance + +- Add migrations only for durable state changes that cannot be handled lazily elsewhere. + +## Verification + +- Smoke-test startup on a clean checkout and on representative existing user state when practical. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/system_prompt/AGENTS.md b/extensions/python/system_prompt/AGENTS.md new file mode 100644 index 000000000..bc4ee6448 --- /dev/null +++ b/extensions/python/system_prompt/AGENTS.md @@ -0,0 +1,27 @@ +# System Prompt Extensions DOX + +## Purpose + +- Own construction of core system prompt sections. + +## Ownership + +- Ordered Python files own main, tools, MCP, secrets, skills, and project prompt sections. + +## Local Contracts + +- Preserve ordering where sections depend on earlier context. +- Keep secret-related prompt sections masked and scoped. +- Prompt additions must be bounded and compatible with tool-call contracts. + +## Work Guidance + +- Coordinate broad system prompt changes with profiles, skills, tools, plugins, and prompt tests. + +## Verification + +- Inspect rendered system prompts or run prompt-construction tests after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/tool_execute_after/AGENTS.md b/extensions/python/tool_execute_after/AGENTS.md new file mode 100644 index 000000000..54c4557c5 --- /dev/null +++ b/extensions/python/tool_execute_after/AGENTS.md @@ -0,0 +1,26 @@ +# Tool Execute After Extensions DOX + +## Purpose + +- Own backend processing immediately after tool execution. + +## Ownership + +- Ordered Python files own post-tool secret masking and future tool-result postprocessing. + +## Local Contracts + +- Mask secrets before tool results reach history, UI, or model-visible context. +- Do not alter tool `break_loop` or response semantics unless the hook contract owns that behavior. + +## Work Guidance + +- Coordinate with tool implementations and history hooks when changing tool result data. + +## Verification + +- Smoke-test tool execution with sensitive output after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/tool_execute_before/AGENTS.md b/extensions/python/tool_execute_before/AGENTS.md new file mode 100644 index 000000000..6d5f6f8bf --- /dev/null +++ b/extensions/python/tool_execute_before/AGENTS.md @@ -0,0 +1,27 @@ +# Tool Execute Before Extensions DOX + +## Purpose + +- Own backend processing immediately before tool execution. + +## Ownership + +- Ordered Python files own prior tool-output replacement and secret unmasking before execution. + +## Local Contracts + +- Unmask only values required by the target tool. +- Preserve safety checks and do not expose secrets to logs or unrelated tools. +- Keep ordering stable where replacement must occur before unmasking or execution. + +## Work Guidance + +- Coordinate with secret handling, tool argument preparation, and plugin tool gates. + +## Verification + +- Smoke-test tool execution with masked secret arguments and prior-output references after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/user_message_ui/AGENTS.md b/extensions/python/user_message_ui/AGENTS.md new file mode 100644 index 000000000..55428a4d7 --- /dev/null +++ b/extensions/python/user_message_ui/AGENTS.md @@ -0,0 +1,26 @@ +# User Message UI Extensions DOX + +## Purpose + +- Own backend behavior triggered around user-visible UI messages. + +## Ownership + +- Ordered Python files own update-check messaging and future user-message UI hooks. + +## Local Contracts + +- Keep proactive UI messages relevant, non-spammy, and safe for display. +- Do not expose local diagnostics or update data that should stay internal. + +## Work Guidance + +- Gate recurring messages so they do not repeat unnecessarily across chats or tabs. + +## Verification + +- Smoke-test UI message rendering after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/util_model_call_before/AGENTS.md b/extensions/python/util_model_call_before/AGENTS.md new file mode 100644 index 000000000..dc0bd77f8 --- /dev/null +++ b/extensions/python/util_model_call_before/AGENTS.md @@ -0,0 +1,26 @@ +# Utility Model Call Before Extensions DOX + +## Purpose + +- Own preprocessing before utility model calls. + +## Ownership + +- Ordered Python files own secret masking and future utility-call preparation. + +## Local Contracts + +- Mask secrets before utility prompts leave the framework. +- Keep utility model inputs compatible with callers expecting structured outputs. + +## Work Guidance + +- Coordinate masking changes with main model call and error-format masking behavior. + +## Verification + +- Test utility model calls that include masked secret patterns after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/webui_ws_connect/AGENTS.md b/extensions/python/webui_ws_connect/AGENTS.md new file mode 100644 index 000000000..f722ae7b2 --- /dev/null +++ b/extensions/python/webui_ws_connect/AGENTS.md @@ -0,0 +1,26 @@ +# WebUI WebSocket Connect Extensions DOX + +## Purpose + +- Own backend behavior when a WebUI WebSocket client connects. + +## Ownership + +- Ordered Python files own state-sync behavior for new WebSocket connections. + +## Local Contracts + +- Preserve WebSocket auth/session assumptions. +- Send only state the connected client is allowed to receive. + +## Work Guidance + +- Coordinate connect behavior with frontend WebSocket client and sync store. + +## Verification + +- Smoke-test WebUI connection and initial state sync after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/webui_ws_disconnect/AGENTS.md b/extensions/python/webui_ws_disconnect/AGENTS.md new file mode 100644 index 000000000..703652891 --- /dev/null +++ b/extensions/python/webui_ws_disconnect/AGENTS.md @@ -0,0 +1,26 @@ +# WebUI WebSocket Disconnect Extensions DOX + +## Purpose + +- Own backend behavior when a WebUI WebSocket client disconnects. + +## Ownership + +- Ordered Python files own state-sync cleanup for disconnect events. + +## Local Contracts + +- Cleanup must be idempotent and safe for repeated disconnect events. +- Do not remove shared state still needed by other active clients. + +## Work Guidance + +- Coordinate disconnect behavior with frontend reconnect and sync indicators. + +## Verification + +- Smoke-test disconnect and reconnect behavior after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/python/webui_ws_event/AGENTS.md b/extensions/python/webui_ws_event/AGENTS.md new file mode 100644 index 000000000..a47e147b2 --- /dev/null +++ b/extensions/python/webui_ws_event/AGENTS.md @@ -0,0 +1,26 @@ +# WebUI WebSocket Event Extensions DOX + +## Purpose + +- Own backend behavior for incoming WebUI WebSocket events. + +## Ownership + +- Ordered Python files own state-sync event handling and future WebSocket event extensions. + +## Local Contracts + +- Validate event names and payloads before acting on them. +- Preserve auth/session boundaries for all WebSocket events. + +## Work Guidance + +- Coordinate event changes with frontend WebSocket client and sync store. + +## Verification + +- Smoke-test relevant WebSocket events after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/AGENTS.md b/extensions/webui/AGENTS.md index 11f949ca5..d2421a144 100644 --- a/extensions/webui/AGENTS.md +++ b/extensions/webui/AGENTS.md @@ -31,4 +31,17 @@ ## Child DOX Index -No child DOX files. +Direct child DOX files: + +| Child | Scope | +| --- | --- | +| [fetch_api_call_after/AGENTS.md](fetch_api_call_after/AGENTS.md) | Frontend hooks after raw `fetchApi()` calls. | +| [fetch_api_call_before/AGENTS.md](fetch_api_call_before/AGENTS.md) | Frontend hooks before raw `fetchApi()` calls. | +| [get_message_handler/AGENTS.md](get_message_handler/AGENTS.md) | Message rendering handler extensions. | +| [initFw_end/AGENTS.md](initFw_end/AGENTS.md) | Post-WebUI-framework-initialization extensions. | +| [json_api_call_after/AGENTS.md](json_api_call_after/AGENTS.md) | Frontend hooks after `callJsonApi()` calls. | +| [json_api_call_before/AGENTS.md](json_api_call_before/AGENTS.md) | Frontend hooks before `callJsonApi()` calls. | +| [right_canvas_register_surfaces/AGENTS.md](right_canvas_register_surfaces/AGENTS.md) | Built-in right-canvas surface registrations. | +| [set_messages_after_loop/AGENTS.md](set_messages_after_loop/AGENTS.md) | Frontend hooks after message DOM updates. | +| [set_messages_before_loop/AGENTS.md](set_messages_before_loop/AGENTS.md) | Frontend hooks before message DOM updates. | +| [webui_ws_push/AGENTS.md](webui_ws_push/AGENTS.md) | WebUI WebSocket push-event behavior. | diff --git a/extensions/webui/fetch_api_call_after/AGENTS.md b/extensions/webui/fetch_api_call_after/AGENTS.md new file mode 100644 index 000000000..963be5f11 --- /dev/null +++ b/extensions/webui/fetch_api_call_after/AGENTS.md @@ -0,0 +1,26 @@ +# Fetch API Call After Extensions DOX + +## Purpose + +- Own frontend extension hooks that run after raw `fetchApi()` calls. + +## Ownership + +- Files in this folder own after-call behavior for CSRF-aware raw fetch flows. + +## Local Contracts + +- JavaScript modules must export a default function when present. +- Do not consume response bodies unless the hook contract explicitly passes a clone or mutable context for that purpose. + +## Work Guidance + +- Keep after-call extensions lightweight and safe for all fetch callers. + +## Verification + +- Smoke-test frontend API calls after adding behavior here. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/fetch_api_call_before/AGENTS.md b/extensions/webui/fetch_api_call_before/AGENTS.md new file mode 100644 index 000000000..c715757d5 --- /dev/null +++ b/extensions/webui/fetch_api_call_before/AGENTS.md @@ -0,0 +1,26 @@ +# Fetch API Call Before Extensions DOX + +## Purpose + +- Own frontend extension hooks that run before raw `fetchApi()` calls. + +## Ownership + +- Files in this folder own before-call behavior for CSRF-aware raw fetch flows. + +## Local Contracts + +- JavaScript modules must export a default function when present. +- Preserve CSRF, auth, and redirect behavior owned by `/js/api.js`. + +## Work Guidance + +- Avoid broad request mutation that surprises unrelated API callers. + +## Verification + +- Smoke-test affected frontend API calls after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/get_message_handler/AGENTS.md b/extensions/webui/get_message_handler/AGENTS.md new file mode 100644 index 000000000..ea0a36977 --- /dev/null +++ b/extensions/webui/get_message_handler/AGENTS.md @@ -0,0 +1,27 @@ +# Get Message Handler Extensions DOX + +## Purpose + +- Own frontend extensions that provide or modify message rendering handlers. + +## Ownership + +- Files in this folder own handler registration behavior for rendered chat messages. + +## Local Contracts + +- JavaScript modules must export a default function when present. +- Preserve mutable context contracts used by `/js/messages.js`. +- Do not render unsanitized model or user content. + +## Work Guidance + +- Coordinate handler changes with message components and plugin message extensions. + +## Verification + +- Smoke-test message rendering for affected message types after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/initFw_end/AGENTS.md b/extensions/webui/initFw_end/AGENTS.md new file mode 100644 index 000000000..5f18507b4 --- /dev/null +++ b/extensions/webui/initFw_end/AGENTS.md @@ -0,0 +1,27 @@ +# Init Framework End Extensions DOX + +## Purpose + +- Own frontend extensions that run after WebUI framework initialization. + +## Ownership + +- JavaScript files own post-bootstrap global setup such as self-update helpers. + +## Local Contracts + +- JavaScript modules must export a default function. +- Setup must be idempotent across reloads and cache resets. +- Do not register duplicate global listeners. + +## Work Guidance + +- Coordinate initialization changes with `/js/initFw.js` and component lifecycle directives. + +## Verification + +- Smoke-test WebUI startup and browser console after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/json_api_call_after/AGENTS.md b/extensions/webui/json_api_call_after/AGENTS.md new file mode 100644 index 000000000..96f356b8d --- /dev/null +++ b/extensions/webui/json_api_call_after/AGENTS.md @@ -0,0 +1,26 @@ +# JSON API Call After Extensions DOX + +## Purpose + +- Own frontend extension hooks that run after `callJsonApi()` calls. + +## Ownership + +- JavaScript files own after-call behavior such as cache reset handling. + +## Local Contracts + +- JavaScript modules must export a default function. +- Preserve JSON API response contracts and avoid hiding errors from callers. + +## Work Guidance + +- Keep global side effects narrow and tied to explicit API results or mutable contexts. + +## Verification + +- Smoke-test JSON API callers affected by extension changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/json_api_call_before/AGENTS.md b/extensions/webui/json_api_call_before/AGENTS.md new file mode 100644 index 000000000..b14f04ea9 --- /dev/null +++ b/extensions/webui/json_api_call_before/AGENTS.md @@ -0,0 +1,26 @@ +# JSON API Call Before Extensions DOX + +## Purpose + +- Own frontend extension hooks that run before `callJsonApi()` calls. + +## Ownership + +- Files in this folder own before-call behavior for JSON API requests. + +## Local Contracts + +- JavaScript modules must export a default function when present. +- Preserve CSRF/auth behavior and JSON payload shape expected by `/js/api.js`. + +## Work Guidance + +- Avoid broad request mutation that affects unrelated plugin or core API calls. + +## Verification + +- Smoke-test affected JSON API calls after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/right_canvas_register_surfaces/AGENTS.md b/extensions/webui/right_canvas_register_surfaces/AGENTS.md new file mode 100644 index 000000000..d62eb20da --- /dev/null +++ b/extensions/webui/right_canvas_register_surfaces/AGENTS.md @@ -0,0 +1,27 @@ +# Right Canvas Surface Extensions DOX + +## Purpose + +- Own frontend registration of built-in right-canvas surfaces. + +## Ownership + +- JavaScript files own registration of remote link, space agent, and future core canvas surfaces. + +## Local Contracts + +- JavaScript modules must export a default function. +- Surface IDs must be unique and stable. +- Registered surfaces must point to valid components or handlers. + +## Work Guidance + +- Coordinate surface registration changes with `webui/components/canvas/` and related plugin panels. + +## Verification + +- Smoke-test opening each registered right-canvas surface after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/set_messages_after_loop/AGENTS.md b/extensions/webui/set_messages_after_loop/AGENTS.md new file mode 100644 index 000000000..724987ba7 --- /dev/null +++ b/extensions/webui/set_messages_after_loop/AGENTS.md @@ -0,0 +1,26 @@ +# Set Messages After Loop Extensions DOX + +## Purpose + +- Own frontend extensions that run after message DOM updates complete. + +## Ownership + +- Files in this folder own after-render message behavior. + +## Local Contracts + +- JavaScript modules must export a default function when present. +- Preserve message DOM stability and avoid duplicate controls on repeated renders. + +## Work Guidance + +- Use stable markers when injecting controls into message elements. + +## Verification + +- Smoke-test message rerendering and extension-injected controls after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/set_messages_before_loop/AGENTS.md b/extensions/webui/set_messages_before_loop/AGENTS.md new file mode 100644 index 000000000..d417ba566 --- /dev/null +++ b/extensions/webui/set_messages_before_loop/AGENTS.md @@ -0,0 +1,26 @@ +# Set Messages Before Loop Extensions DOX + +## Purpose + +- Own frontend extensions that run before message DOM updates. + +## Ownership + +- Files in this folder own pre-render message behavior. + +## Local Contracts + +- JavaScript modules must export a default function when present. +- Do not remove DOM state needed by message rendering unless the mutable context owns it. + +## Work Guidance + +- Coordinate pre-render behavior with `/js/messages.js` and message components. + +## Verification + +- Smoke-test message updates after changes. + +## Child DOX Index + +No child DOX files. diff --git a/extensions/webui/webui_ws_push/AGENTS.md b/extensions/webui/webui_ws_push/AGENTS.md new file mode 100644 index 000000000..58d838730 --- /dev/null +++ b/extensions/webui/webui_ws_push/AGENTS.md @@ -0,0 +1,27 @@ +# WebUI WebSocket Push Extensions DOX + +## Purpose + +- Own frontend behavior for WebUI WebSocket push events. + +## Ownership + +- JavaScript files own push-event side effects such as cache clearing. + +## Local Contracts + +- JavaScript modules must export a default function. +- Validate event payload shape before acting. +- Keep cache or state resets scoped to the event type. + +## Work Guidance + +- Coordinate push behavior with backend WebSocket event extensions and frontend stores. + +## Verification + +- Smoke-test relevant WebSocket push events after changes. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/AGENTS.md b/helpers/AGENTS.md index bb70bf289..dc7584d32 100644 --- a/helpers/AGENTS.md +++ b/helpers/AGENTS.md @@ -18,17 +18,23 @@ - Project metadata defaults must remain backwards-compatible; missing `include_agents_md` is treated as enabled and project instruction file content is injected with an explicit source path. - Do not hardcode secrets, provider keys, local absolute paths, or environment-specific values. - Use `RepairableException` for errors an agent may be able to fix. +- This directory is a file-documented DOX profile: every direct `*.py` helper module must have a same-directory `*.py.dox.md` file named by appending `.dox.md` to the full Python filename. +- The `*.py.dox.md` file owns helper purpose, public classes/functions, cross-module contracts, persistence or side effects, path/security assumptions, important dependencies, and verification guidance. +- When a helper module is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change. +- Do not leave stale file-level DOX after helper deletion or rename. ## Work Guidance - Prefer cohesive helper modules over adding unrelated utilities to large files. - Keep imports acyclic where possible; defer imports inside functions only when needed to avoid startup cycles. - For changes touching auth, CSRF, files, plugins, tunnels, WebSockets, or model calls, read the caller and tests before editing. +- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed helper behavior is described there. ## Verification - Run targeted tests for changed helper modules. - Run security regression tests for auth, CSRF, filesystem, WebSocket, tunnel, upload, or image-serving changes. +- Check file-level documentation coverage with a script or shell loop that verifies each `helpers/*.py` has a matching `helpers/*.py.dox.md`. ## Child DOX Index diff --git a/helpers/api.py.dox.md b/helpers/api.py.dox.md new file mode 100644 index 000000000..d9d6bb546 --- /dev/null +++ b/helpers/api.py.dox.md @@ -0,0 +1,71 @@ +# api.py DOX + +## Purpose + +- Own the `api.py` helper module. +- This module defines API handler registration, request security gates, CSRF checks, and watchdog registration. +- Keep this file-level DOX profile synchronized with `api.py` because this directory is intentionally flat. + +## Ownership + +- `api.py` owns the runtime implementation. +- `api.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ApiHandler` (no explicit base class) + - `requires_loopback(cls) -> bool` + - `requires_api_key(cls) -> bool` + - `requires_auth(cls) -> bool` + - `get_methods(cls) -> list[str]` + - `requires_csrf(cls) -> bool` + - `async process(self, input: Input, request: Request) -> Output` + - `async handle_request(self, request: Request) -> Response` + - `use_context(self, ctxid: str, create_if_not_exists: bool=...)` +- Top-level functions: +- `requires_api_key(f)` +- `requires_loopback(f)` +- `requires_auth(f)` +- `csrf_protect(f)` +- `register_api_route(app: Flask, lock: ThreadLockType) -> None` +- `register_watchdogs()` +- Notable constants/configuration names: `CACHE_AREA`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- `ApiHandler` defines `process(...)`. +- `ApiHandler` defines `get_methods(...)`. +- `ApiHandler` defines `requires_auth(...)`. +- `ApiHandler` defines `requires_csrf(...)`. +- `ApiHandler` defines `requires_api_key(...)`. +- `ApiHandler` defines `requires_loopback(...)`. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `abc`, `flask`, `functools`, `helpers`, `helpers.errors`, `helpers.network`, `helpers.print_style`, `json`, `pathlib`, `threading`, `typing`, `werkzeug.wrappers.response`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `wraps`, `app.add_url_rule`, `watchdog.add_watchdog`, `cls.requires_auth`, `_use_context`, `login.get_credentials_hash`, `files.get_abs_path`, `handler_cls.requires_csrf`, `handler_cls.requires_api_key`, `handler_cls.requires_auth`, `handler_cls.requires_loopback`, `cache.add`, `PrintStyle.debug`, `cache.clear`, `get_settings`, `f`, `is_loopback_address`, `Response`, `redirect`, `files.is_in_dir`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_api_chat_lifetime.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_download_toast_regressions.py` + - `tests/test_fasta2a_client.py` + - `tests/test_fastmcp_openapi_security.py` + - `tests/test_host_browser_connector.py` + - `tests/test_image_get_security.py` + - `tests/test_model_config_api_keys.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/attachment_manager.py.dox.md b/helpers/attachment_manager.py.dox.md new file mode 100644 index 000000000..46dd4a930 --- /dev/null +++ b/helpers/attachment_manager.py.dox.md @@ -0,0 +1,47 @@ +# attachment_manager.py DOX + +## Purpose + +- Own the `attachment_manager.py` helper module. +- This module tracks uploaded or generated attachments associated with chat contexts. +- Keep this file-level DOX profile synchronized with `attachment_manager.py` because this directory is intentionally flat. + +## Ownership + +- `attachment_manager.py` owns the runtime implementation. +- `attachment_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `AttachmentManager` (no explicit base class) + - `is_allowed_file(self, filename: str) -> bool` + - `get_file_type(self, filename: str) -> str` + - `get_file_extension(filename: str) -> str` + - `validate_mime_type(self, file) -> bool` + - `save_file(self, file: FileStorage, name: str) -> Tuple[str, Dict]` + - `generate_image_preview(self, image_path: str, max_size: int=...) -> Optional[str]` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence. +- Imported dependency areas include: `PIL`, `base64`, `helpers.print_style`, `helpers.security`, `io`, `os`, `typing`, `werkzeug.datastructures`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `os.makedirs`, `self.get_file_extension`, `set.union`, `filename.rsplit.lower`, `safe_filename`, `os.path.join`, `self.get_file_type`, `file.save`, `ValueError`, `self.generate_image_preview`, `PrintStyle.error`, `img.thumbnail`, `io.BytesIO`, `img.save`, `base64.b64encode.decode`, `mime_type.split`, `img.convert`, `filename.rsplit`, `base64.b64encode`, `buffer.getvalue`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/backup.py.dox.md b/helpers/backup.py.dox.md new file mode 100644 index 000000000..a72c49377 --- /dev/null +++ b/helpers/backup.py.dox.md @@ -0,0 +1,50 @@ +# backup.py DOX + +## Purpose + +- Own the `backup.py` helper module. +- This module builds, inspects, previews, tests, and restores Agent Zero backup archives. +- Keep this file-level DOX profile synchronized with `backup.py` because this directory is intentionally flat. + +## Ownership + +- `backup.py` owns the runtime implementation. +- `backup.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `BackupService` (no explicit base class) + - `get_default_backup_metadata(self) -> Dict[str, Any]` + - `async test_patterns(self, metadata: Dict[str, Any], max_files: int=...) -> List[Dict[str, Any]]` + - `async create_backup(self, include_patterns: List[str], exclude_patterns: List[str], include_hidden: bool=..., backup_name: str=...) -> str` + - `async inspect_backup(self, backup_file) -> Dict[str, Any]` + - `async preview_restore(self, backup_file, restore_include_patterns: Optional[List[str]]=..., restore_exclude_patterns: Optional[List[str]]=..., overwrite_policy: str=..., clean_before_restore: bool=..., user_edited_metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]` + - `async restore_backup(self, backup_file, restore_include_patterns: Optional[List[str]]=..., restore_exclude_patterns: Optional[List[str]]=..., overwrite_policy: str=..., clean_before_restore: bool=..., user_edited_metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, secret handling. +- Imported dependency areas include: `datetime`, `helpers`, `helpers.localization`, `helpers.print_style`, `json`, `os`, `pathspec`, `platform`, `tempfile`, `typing`, `zipfile`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self._get_agent_zero_version`, `files.get_abs_path`, `Localization.get.now_iso`, `self._get_default_patterns`, `self._parse_patterns`, `self.agent_zero_root.rstrip`, `patterns.split`, `join`, `file_path.lstrip`, `backed_up_agent_root.rstrip`, `current_agent_root.rstrip`, `self._patterns_to_string`, `self._get_explicit_patterns`, `tempfile.mkdtemp`, `os.path.join`, `self._translate_patterns`, `git.get_git_info`, `line.strip`, `line.startswith`, `getpass.getuser`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_download_toast_regressions.py` + - `tests/test_office_document_store.py` + - `tests/test_self_update_tag_filter.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/browser.py.dox.md b/helpers/browser.py.dox.md new file mode 100644 index 000000000..0ac4afcca --- /dev/null +++ b/helpers/browser.py.dox.md @@ -0,0 +1,46 @@ +# browser.py DOX + +## Purpose + +- Own the `browser.py` helper module. +- This module holds shared browser helper state used by browser-facing integrations. +- Keep this file-level DOX profile synchronized with `browser.py` because this directory is intentionally flat. + +## Ownership + +- `browser.py` owns the runtime implementation. +- `browser.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem deletion. + +## Key Concepts + +- This module is primarily declarative or delegates behavior through classes/imported objects. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_download_toast_regressions.py` + - `tests/test_host_browser_connector.py` + - `tests/test_oauth_gemini_api.py` + - `tests/test_oauth_providers.py` + - `tests/test_oauth_static.py` + - `tests/test_oauth_xai_grok.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/cache.py.dox.md b/helpers/cache.py.dox.md new file mode 100644 index 000000000..abe865f75 --- /dev/null +++ b/helpers/cache.py.dox.md @@ -0,0 +1,64 @@ +# cache.py DOX + +## Purpose + +- Own the `cache.py` helper module. +- This module provides in-process cache areas with optional global and area toggles. +- Keep this file-level DOX profile synchronized with `cache.py` because this directory is intentionally flat. + +## Ownership + +- `cache.py` owns the runtime implementation. +- `cache.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `CacheEntry` (no explicit base class) +- Top-level functions: +- `toggle_global(enabled: bool) -> None` +- `toggle_area(area: str, enabled: bool) -> None` +- `has(area: str, key: Any) -> bool` +- `add(area: str, key: Any, data: Any) -> None` +- `get(area: str, key: Any, default: Any=...) -> Any` +- `remove(area: str, key: Any) -> None` +- `clear(area: str) -> None` +- `trim_cache(area: str, seconds: float=...) -> None` +- `clear_all() -> None` +- `_is_enabled(area: str) -> bool` +- `_create_entry(value: Any) -> CacheEntry` +- `_touch_entry(entry: CacheEntry) -> None` +- `_get_matching_areas(area: str) -> list[str]` +- `determine_cache_key(agent, *additional)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem deletion, plugin state, settings/state persistence. +- Imported dependency areas include: `dataclasses`, `fnmatch`, `threading`, `time`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `threading.RLock`, `dataclass`, `CacheEntry`, `time.time`, `_is_enabled`, `_touch_entry`, `_create_entry`, `_cache.pop`, `_get_matching_areas`, `_cache.clear`, `agent.context.get_data`, `area_cache.pop`, `fnmatch.fnmatch`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_file_tree_visualize.py` + - `tests/test_office_canvas_setup.py` + - `tests/test_office_document_store.py` + - `tests/test_self_update_tag_filter.py` + - `tests/test_time_travel.py` + - `tests/test_webui_extension_surfaces.py` + - `tests/test_whatsapp_bridge_manager.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/call_llm.py.dox.md b/helpers/call_llm.py.dox.md new file mode 100644 index 000000000..0ba5bd966 --- /dev/null +++ b/helpers/call_llm.py.dox.md @@ -0,0 +1,43 @@ +# call_llm.py DOX + +## Purpose + +- Own the `call_llm.py` helper module. +- This module wraps LiteLLM/model calls with examples, streaming, and extension hooks. +- Keep this file-level DOX profile synchronized with `call_llm.py` because this directory is intentionally flat. + +## Ownership + +- `call_llm.py` owns the runtime implementation. +- `call_llm.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Example` (`TypedDict`) +- Top-level functions: +- `async call_llm(system: str, model: BaseChatModel | BaseLLM, message: str, examples: list[Example]=..., callback: Callable[[str], None] | None=...)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: model calls. +- Imported dependency areas include: `langchain.prompts`, `langchain.schema`, `langchain_core.language_models.chat_models`, `langchain_core.language_models.llms`, `langchain_core.messages`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `ChatPromptTemplate.from_messages`, `FewShotChatMessagePromptTemplate`, `few_shot_prompt.format`, `chain.astream`, `HumanMessage`, `AIMessage`, `SystemMessage`, `callback`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/chat_media.py.dox.md b/helpers/chat_media.py.dox.md new file mode 100644 index 000000000..5aa9af9fb --- /dev/null +++ b/helpers/chat_media.py.dox.md @@ -0,0 +1,60 @@ +# chat_media.py DOX + +## Purpose + +- Own the `chat_media.py` helper module. +- This module materializes, stores, and resolves chat-scoped image/media artifacts. +- Keep this file-level DOX profile synchronized with `chat_media.py` because this directory is intentionally flat. + +## Ownership + +- `chat_media.py` owns the runtime implementation. +- `chat_media.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ChatImage` (no explicit base class) +- Top-level functions: +- `screenshot_dir(context_id: str, source: str) -> Path` +- `artifact_dir(context_id: str, category: ImageCategory=..., source: str=...) -> Path` +- `save_image_bytes(context_id: str, payload: bytes, mime_type: str=..., category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage` +- `save_image_base64(context_id: str, data: str, mime_type: str=..., category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage` +- `save_image_file(context_id: str, path: str | Path, category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage` +- `save_image_data_url(context_id: str, data_url: str, category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage` +- `materialize_image_ref(context_id: str, url: str, source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> str` +- `is_chat_scoped_path(context_id: str, path: str | Path) -> bool` +- `infer_source(value: str=..., preferred_name: str=...) -> str` +- `category_for_source(source: str) -> ImageCategory` +- `_guess_image_mime(path: Path) -> str` +- `_is_data_image_url(value: str) -> bool` +- `_split_image_data_url(data_url: str) -> tuple[str, str]` +- Notable constants/configuration names: `DEFAULT_MAX_IMAGE_BYTES`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion. +- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `pathlib`, `time`, `typing`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `dataclass`, `artifact_dir`, `bytes`, `media_artifacts.normalize_mime`, `media_artifacts.guess_extension`, `media_artifacts.safe_filename`, `Path`, `time.strftime`, `path.parent.mkdir`, `path.write_bytes`, `ChatImage`, `media_artifacts.decode_base64_payload`, `save_image_bytes`, `image_path.read_bytes`, `_split_image_data_url`, `save_image_base64`, `str.strip`, `category_for_source`, `_is_data_image_url`, `images.resolve_ref`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_host_browser_connector.py` + - `tests/test_tool_action_contracts.py` + - `tests/test_vision_load_image_refs.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/cli_tunnel.py.dox.md b/helpers/cli_tunnel.py.dox.md new file mode 100644 index 000000000..da8fc4a0c --- /dev/null +++ b/helpers/cli_tunnel.py.dox.md @@ -0,0 +1,54 @@ +# cli_tunnel.py DOX + +## Purpose + +- Own the `cli_tunnel.py` helper module. +- This module provides shared download and install mechanics for CLI-based tunnel providers. +- Keep this file-level DOX profile synchronized with `cli_tunnel.py` because this directory is intentionally flat. + +## Ownership + +- `cli_tunnel.py` owns the runtime implementation. +- `cli_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `CliTunnelHelper` (`TunnelHelper`) + - `start(self)` + - `stop(self)` +- Top-level functions: +- `executable_name(name)` +- `chmod_executable(path)` +- `notify_download(notify, message, data=...)` +- `notify_download_complete(notify, message, data=...)` +- `download_file(url, destination, notify=...)` +- `platform_parts()` +- `extract_named_members_from_tar(archive_path, destination_dir, member_names)` +- `extract_named_members_from_zip(archive_path, destination_dir, member_names)` +- Notable constants/configuration names: `RUNTIME_BIN_DIR`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, tunnel state. +- Imported dependency areas include: `collections`, `flaredantic`, `helpers`, `helpers.tunnel_common`, `os`, `pathlib`, `platform`, `queue`, `shutil`, `subprocess`, `tarfile`, `tempfile`, `threading`, `time`, `urllib.request`, `zipfile`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Path`, `files.get_abs_path`, `callable`, `destination.parent.mkdir`, `notify_download`, `tempfile.mkstemp`, `os.close`, `platform.system.lower`, `platform.machine.lower`, `destination_dir.mkdir`, `path.chmod`, `notify`, `temp_path.replace`, `notify_download_complete`, `RuntimeError`, `archive.getmembers`, `zipfile.ZipFile`, `archive.infolist`, `super.__init__`, `self.url_pattern.search`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/cloudflare_tunnel.py.dox.md b/helpers/cloudflare_tunnel.py.dox.md new file mode 100644 index 000000000..e2172dcae --- /dev/null +++ b/helpers/cloudflare_tunnel.py.dox.md @@ -0,0 +1,43 @@ +# cloudflare_tunnel.py DOX + +## Purpose + +- Own the `cloudflare_tunnel.py` helper module. +- This module implements Cloudflare tunnel provider lifecycle behavior. +- Keep this file-level DOX profile synchronized with `cloudflare_tunnel.py` because this directory is intentionally flat. + +## Ownership + +- `cloudflare_tunnel.py` owns the runtime implementation. +- `cloudflare_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `CloudflareTunnel` (`FlaredanticTunnelHelper`) + - `build_tunnel(self)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: settings/state persistence, tunnel state. +- Imported dependency areas include: `flaredantic`, `helpers.tunnel_common`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `FlareConfig`, `FlareTunnel`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/context.py.dox.md b/helpers/context.py.dox.md new file mode 100644 index 000000000..8b6e76a51 --- /dev/null +++ b/helpers/context.py.dox.md @@ -0,0 +1,54 @@ +# context.py DOX + +## Purpose + +- Own the `context.py` helper module. +- This module provides compatibility helpers for reading and writing `AgentContext` data. +- Keep this file-level DOX profile synchronized with `context.py` because this directory is intentionally flat. + +## Ownership + +- `context.py` owns the runtime implementation. +- `context.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `_ensure_context() -> Dict[str, Any]`: Make sure a context dict exists, and return it. +- `set_context_data(key: str, value: Any)`: Set context data for the current async/task context. +- `delete_context_data(key: str)`: Delete a key from the current async/task context. +- `get_context_data(key: Optional[str]=..., default: T=...) -> T`: Get a key from the current context, or the full dict if key is None. +- `clear_context_data()`: Completely clear the context dict. +- Notable constants/configuration names: `T`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem deletion, scheduler state. +- Imported dependency areas include: `contextvars`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `TypeVar`, `ContextVar`, `_ensure_context`, `cast`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_api_chat_lifetime.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_document_query_plugin.py` + - `tests/test_error_retry_plugin.py` + - `tests/test_extensions_stress.py` + - `tests/test_file_tree_visualize.py` + - `tests/test_history_compression_wait.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/context_utils.py.dox.md b/helpers/context_utils.py.dox.md new file mode 100644 index 000000000..725340ecd --- /dev/null +++ b/helpers/context_utils.py.dox.md @@ -0,0 +1,41 @@ +# context_utils.py DOX + +## Purpose + +- Own the `context_utils.py` helper module. +- This module provides context managers/utilities for current context binding. +- Keep this file-level DOX profile synchronized with `context_utils.py` because this directory is intentionally flat. + +## Ownership + +- `context_utils.py` owns the runtime implementation. +- `context_utils.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `use_context(lock: ThreadLockType, ctxid: str, create_if_not_exists: bool=...)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: WebSocket state, settings/state persistence. +- Imported dependency areas include: `threading`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `AgentContext.use`, `AgentContext.first`, `AgentContext`, `Exception`, `initialize_agent`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/crypto.py.dox.md b/helpers/crypto.py.dox.md new file mode 100644 index 000000000..a66e730ca --- /dev/null +++ b/helpers/crypto.py.dox.md @@ -0,0 +1,48 @@ +# crypto.py DOX + +## Purpose + +- Own the `crypto.py` helper module. +- This module hashes, verifies, encrypts, and decrypts data for signed or protected payloads. +- Keep this file-level DOX profile synchronized with `crypto.py` because this directory is intentionally flat. + +## Ownership + +- `crypto.py` owns the runtime implementation. +- `crypto.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `hash_data(data: str, password: str)` +- `verify_data(data: str, hash: str, password: str)` +- `_generate_private_key()` +- `_generate_public_key(private_key: rsa.RSAPrivateKey)` +- `_decode_public_key(public_key: str) -> rsa.RSAPublicKey` +- `encrypt_data(data: str, public_key_pem: str)` +- `_encrypt_data(data: bytes, public_key: rsa.RSAPublicKey)` +- `decrypt_data(data: str, private_key: rsa.RSAPrivateKey)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: secret handling. +- Imported dependency areas include: `cryptography.hazmat.primitives`, `cryptography.hazmat.primitives.asymmetric`, `hashlib`, `hmac`, `os`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `hmac.new.hexdigest`, `rsa.generate_private_key`, `private_key.public_key.public_bytes.hex`, `bytes.fromhex`, `serialization.load_pem_public_key`, `_encrypt_data`, `public_key.encrypt`, `b.hex`, `private_key.decrypt`, `b.decode`, `hash_data`, `TypeError`, `data.encode`, `_decode_public_key`, `padding.OAEP`, `hmac.new`, `private_key.public_key.public_bytes`, `password.encode`, `padding.MGF1`, `hashes.SHA256`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/defer.py.dox.md b/helpers/defer.py.dox.md new file mode 100644 index 000000000..cccc3da9f --- /dev/null +++ b/helpers/defer.py.dox.md @@ -0,0 +1,55 @@ +# defer.py DOX + +## Purpose + +- Own the `defer.py` helper module. +- This module runs deferred or child async tasks on managed event-loop threads. +- Keep this file-level DOX profile synchronized with `defer.py` because this directory is intentionally flat. + +## Ownership + +- `defer.py` owns the runtime implementation. +- `defer.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `EventLoopThread` (no explicit base class) + - `terminate(self)` + - `run_coroutine(self, coro)` +- `ChildTask` (no explicit base class) +- `DeferredTask` (no explicit base class) + - `start_task(self, func: Callable[..., Coroutine[Any, Any, Any]], *args, **kwargs)` + - `is_ready(self) -> bool` + - `result_sync(self, timeout: Optional[float]=...) -> Any` + - `async result(self, timeout: Optional[float]=...) -> Any` + - `kill(self, terminate_thread: bool=...) -> None` + - `kill_children(self) -> None` + - `is_alive(self) -> bool` + - `restart(self, terminate_thread: bool=...) -> None` +- Notable constants/configuration names: `T`, `THREAD_BACKGROUND`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: scheduler state. +- Imported dependency areas include: `asyncio`, `concurrent.futures`, `dataclasses`, `threading`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `TypeVar`, `threading.Lock`, `self._start`, `asyncio.set_event_loop`, `self.loop.run_forever`, `loop.is_running`, `asyncio.run_coroutine_threadsafe`, `EventLoopThread`, `self._start_task`, `self.kill`, `self.event_loop_thread.run_coroutine`, `self.kill_children`, `asyncio.get_running_loop`, `func`, `asyncio.iscoroutine`, `Future`, `asyncio.wrap_future`, `asyncio.current_task`, `asyncio.new_event_loop`, `threading.Thread`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_office_document_store.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/dirty_json.py b/helpers/dirty_json.py index 8b731bee4..8e7b21012 100644 --- a/helpers/dirty_json.py +++ b/helpers/dirty_json.py @@ -214,7 +214,7 @@ class DirtyJson: def _parse_key(self): self._skip_whitespace() if self.current_char in ['"', "'"]: - return self._parse_string() + return self._parse_string(is_key=True) else: return self._parse_unquoted_key() @@ -260,11 +260,18 @@ class DirtyJson: self._pop_stack() return - def _parse_string(self): + def _parse_string(self, is_key: bool = False): result = "" quote_char = self.current_char self._advance() # Skip opening quote - while self.current_char is not None and self.current_char != quote_char: + while self.current_char is not None: + if self.current_char == quote_char: + if self._is_closing_quote(is_key): + break + result += self.current_char + self._advance() + continue + if self.current_char == "\\": self._advance() if self.current_char in ['"', "'", "\\", "/", "b", "f", "n", "r", "t"]: @@ -298,6 +305,67 @@ class DirtyJson: self._advance() # Skip closing quote return result + def _is_closing_quote(self, is_key: bool) -> bool: + next_index = self._skip_padding_from(self.index + 1) + if next_index >= len(self.json_string): + return True + + next_char = self.json_string[next_index] + if is_key: + return next_char in [":", ",", "}", "]"] + + if next_char in [",", "}", "]"]: + return True + + return self._looks_like_missing_comma_before_key(next_index) + + def _looks_like_missing_comma_before_key(self, index: int) -> bool: + if not self.stack or not isinstance(self.stack[-1], dict): + return False + if index >= len(self.json_string) or self.json_string[index] not in ['"', "'"]: + return False + + quote_char = self.json_string[index] + index += 1 + while index < len(self.json_string): + char = self.json_string[index] + if char == "\\": + index += 2 + continue + if char == quote_char: + next_index = self._skip_padding_from(index + 1) + return ( + next_index < len(self.json_string) + and self.json_string[next_index] == ":" + ) + if char in ["\n", "\r", "{", "}", "[", "]", ","]: + return False + index += 1 + + return False + + def _skip_padding_from(self, index: int) -> int: + while index < len(self.json_string): + char = self.json_string[index] + if char.isspace(): + index += 1 + elif char == "/" and index + 1 < len(self.json_string): + next_char = self.json_string[index + 1] + if next_char == "/": + index += 2 + while index < len(self.json_string) and self.json_string[index] != "\n": + index += 1 + elif next_char == "*": + end = self.json_string.find("*/", index + 2) + if end == -1: + return len(self.json_string) + index = end + 2 + else: + break + else: + break + return index + def _parse_multiline_string(self): result = "" quote_char = self.current_char diff --git a/helpers/dirty_json.py.dox.md b/helpers/dirty_json.py.dox.md new file mode 100644 index 000000000..030a5c652 --- /dev/null +++ b/helpers/dirty_json.py.dox.md @@ -0,0 +1,51 @@ +# dirty_json.py DOX + +## Purpose + +- Own the `dirty_json.py` helper module. +- This module parses and serializes relaxed JSON-like model output. +- Keep this file-level DOX profile synchronized with `dirty_json.py` because this directory is intentionally flat. + +## Ownership + +- `dirty_json.py` owns the runtime implementation. +- `dirty_json.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `DirtyJson` (no explicit base class) + - `parse_string(json_string)` + - `parse(self, json_string)` + - `feed(self, chunk)` + - `get_start_pos(self, input_str: str) -> int` +- Top-level functions: +- `try_parse(json_string: str)` +- `parse(json_string: str)` +- `stringify(obj, **kwargs)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, settings/state persistence. +- Imported dependency areas include: `json`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `DirtyJson.parse_string`, `json.dumps`, `json.loads`, `self._reset`, `self.stack.pop`, `DirtyJson`, `parser.parse`, `self.get_start_pos`, `self._parse`, `self._advance`, `self._skip_whitespace`, `self._parse_object_content`, `self._parse_array_content`, `self._skip_padding_from`, `self._looks_like_missing_comma_before_key`, `result.strip`, `self.current_char.isspace`, `self._parse_value`, `self._continue_parsing`, `self._parse_object`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_dirty_json.py` + - `tests/test_projects.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/docker.py.dox.md b/helpers/docker.py.dox.md new file mode 100644 index 000000000..e932e7bcc --- /dev/null +++ b/helpers/docker.py.dox.md @@ -0,0 +1,53 @@ +# docker.py DOX + +## Purpose + +- Own the `docker.py` helper module. +- This module manages Docker container operations used by runtime helpers. +- Keep this file-level DOX profile synchronized with `docker.py` because this directory is intentionally flat. + +## Ownership + +- `docker.py` owns the runtime implementation. +- `docker.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `DockerContainerManager` (no explicit base class) + - `init_docker(self)` + - `cleanup_container(self) -> None` + - `get_image_containers(self)` + - `start_container(self) -> None` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem deletion, subprocess/runtime control, WebSocket state. +- Imported dependency areas include: `atexit`, `docker`, `helpers.errors`, `helpers.files`, `helpers.log`, `helpers.print_style`, `time`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.init_docker`, `PrintStyle.standard`, `self.client.containers.run`, `time.sleep`, `docker.from_env`, `self.container.stop`, `self.container.remove`, `existing_container.start`, `self.logger.log`, `format_error`, `PrintStyle.error`, `PrintStyle.hint`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_default_prompt_budget.py` + - `tests/test_docker_release_plan.py` + - `tests/test_document_query_plugin.py` + - `tests/test_host_browser_connector.py` + - `tests/test_model_search.py` + - `tests/test_office_canvas_setup.py` + - `tests/test_office_document_store.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/document_query.py.dox.md b/helpers/document_query.py.dox.md new file mode 100644 index 000000000..7d205d988 --- /dev/null +++ b/helpers/document_query.py.dox.md @@ -0,0 +1,41 @@ +# document_query.py DOX + +## Purpose + +- Own the `document_query.py` helper module. +- This module provides compatibility exports for document query behavior. +- Keep this file-level DOX profile synchronized with `document_query.py` because this directory is intentionally flat. + +## Ownership + +- `document_query.py` owns the runtime implementation. +- `document_query.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: plugin state. +- Imported dependency areas include: `plugins._document_query.helpers.document_query`. + +## Key Concepts + +- This module is primarily declarative or delegates behavior through classes/imported objects. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_document_query_fallback.py` + - `tests/test_document_query_plugin.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/dotenv.py.dox.md b/helpers/dotenv.py.dox.md new file mode 100644 index 000000000..2e142d657 --- /dev/null +++ b/helpers/dotenv.py.dox.md @@ -0,0 +1,48 @@ +# dotenv.py DOX + +## Purpose + +- Own the `dotenv.py` helper module. +- This module loads and updates `.env` configuration values. +- Keep this file-level DOX profile synchronized with `dotenv.py` because this directory is intentionally flat. + +## Ownership + +- `dotenv.py` owns the runtime implementation. +- `dotenv.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `load_dotenv()` +- `get_dotenv_file_path()` +- `get_dotenv_value(key: str, default: Any=...)` +- `save_dotenv_value(key: str, value: str)` +- Notable constants/configuration names: `KEY_AUTH_LOGIN`, `KEY_AUTH_PASSWORD`, `KEY_RFC_PASSWORD`, `KEY_ROOT_PASSWORD`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, secret handling. +- Imported dependency areas include: `dotenv`, `files`, `os`, `re`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `_load_dotenv`, `get_abs_path`, `os.getenv`, `get_dotenv_file_path`, `load_dotenv`, `os.path.isfile`, `f.readlines`, `f.seek`, `f.writelines`, `f.truncate`, `f.write`, `re.match`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/email_parser_test.py` + - `tests/test_model_config_api_keys.py` + - `tests/test_timezone_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/duckduckgo_search.py.dox.md b/helpers/duckduckgo_search.py.dox.md new file mode 100644 index 000000000..5090f5042 --- /dev/null +++ b/helpers/duckduckgo_search.py.dox.md @@ -0,0 +1,40 @@ +# duckduckgo_search.py DOX + +## Purpose + +- Own the `duckduckgo_search.py` helper module. +- This module queries DuckDuckGo search through the configured helper path. +- Keep this file-level DOX profile synchronized with `duckduckgo_search.py` because this directory is intentionally flat. + +## Ownership + +- `duckduckgo_search.py` owns the runtime implementation. +- `duckduckgo_search.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `search(query: str, results=..., region=..., time=...) -> list[str]` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `duckduckgo_search`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `DDGS`, `ddgs.text`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/email_client.py.dox.md b/helpers/email_client.py.dox.md new file mode 100644 index 000000000..976e32cd9 --- /dev/null +++ b/helpers/email_client.py.dox.md @@ -0,0 +1,39 @@ +# email_client.py DOX + +## Purpose + +- Own the `email_client.py` helper module. +- This module provides shared email client plumbing for mail integrations. +- Keep this file-level DOX profile synchronized with `email_client.py` because this directory is intentionally flat. + +## Ownership + +- `email_client.py` owns the runtime implementation. +- `email_client.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, settings/state persistence, secret handling. + +## Key Concepts + +- This module is primarily declarative or delegates behavior through classes/imported objects. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/email_parser_test.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/ephemeral_images.py.dox.md b/helpers/ephemeral_images.py.dox.md new file mode 100644 index 000000000..62b7a36a0 --- /dev/null +++ b/helpers/ephemeral_images.py.dox.md @@ -0,0 +1,58 @@ +# ephemeral_images.py DOX + +## Purpose + +- Own the `ephemeral_images.py` helper module. +- This module stores temporary image payloads by reference for safe short-lived access. +- Keep this file-level DOX profile synchronized with `ephemeral_images.py` because this directory is intentionally flat. + +## Ownership + +- `ephemeral_images.py` owns the runtime implementation. +- `ephemeral_images.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `EphemeralImage` (no explicit base class) + - `data_url(self) -> str` + - `display_name(self) -> str` +- Top-level functions: +- `put_image_bytes(context_id: str, mime: str, payload: bytes, name: str=..., ttl_seconds: float=...) -> str` +- `put_image(context_id: str, mime: str, data: str, name: str=..., ttl_seconds: float=...) -> str` +- `is_ref(value: object) -> bool` +- `display_ref(ref: str) -> str` +- `get_image(ref: str, context_id: str=...) -> EphemeralImage | None` +- `consume_image(ref: str, context_id: str=...) -> EphemeralImage | None` +- `delete_image(ref: str) -> None` +- `clear_context(context_id: str) -> None` +- `_resolve_image(ref: str, context_id: str=..., consume: bool) -> EphemeralImage | None` +- `_compact_base64(data: str) -> str` +- `_normalize_mime(mime: str) -> str` +- `_prune_expired_locked(now: float | None=...) -> None` +- Notable constants/configuration names: `REF_PREFIX`, `DEFAULT_TTL_SECONDS`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem deletion. +- Imported dependency areas include: `__future__`, `base64`, `dataclasses`, `threading`, `time`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `dataclass`, `threading.RLock`, `base64.b64encode.decode`, `put_image`, `_compact_base64`, `base64.b64decode`, `_normalize_mime`, `time.time`, `EphemeralImage`, `str.strip.startswith`, `str.strip`, `_resolve_image`, `join`, `str.strip.lower`, `ValueError`, `_prune_expired_locked`, `is_ref`, `_store.pop`, `value.startswith`, `display_ref`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/errors.py.dox.md b/helpers/errors.py.dox.md new file mode 100644 index 000000000..c551fc8d5 --- /dev/null +++ b/helpers/errors.py.dox.md @@ -0,0 +1,54 @@ +# errors.py DOX + +## Purpose + +- Own the `errors.py` helper module. +- This module defines framework exceptions and safe error formatting. +- Keep this file-level DOX profile synchronized with `errors.py` because this directory is intentionally flat. + +## Ownership + +- `errors.py` owns the runtime implementation. +- `errors.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `RepairableException` (`Exception`) +- `InterventionException` (`Exception`) +- `HandledException` (`Exception`) +- Top-level functions: +- `handle_error(e: Exception)` +- `error_text(e: Exception)` +- `format_error(e: Exception, start_entries=..., end_entries=..., error_message_position: Literal['top', 'bottom', 'none']=...)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `asyncio`, `re`, `traceback`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `join`, `traceback_text.split`, `traceback.format_exception`, `re.match`, `type`, `line.strip.startswith`, `trimmed_lines.strip`, `error_message.strip`, `line.strip`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_fasta2a_client.py` + - `tests/test_host_browser_connector.py` + - `tests/test_office_desktop_state.py` + - `tests/test_office_document_store.py` + - `tests/test_skills_runtime.py` + - `tests/test_speech_plugin_split.py` + - `tests/test_time_travel.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/extension.py.dox.md b/helpers/extension.py.dox.md new file mode 100644 index 000000000..4271cc57c --- /dev/null +++ b/helpers/extension.py.dox.md @@ -0,0 +1,63 @@ +# extension.py DOX + +## Purpose + +- Own the `extension.py` helper module. +- This module discovers and dispatches Python and WebUI extension hooks. +- Keep this file-level DOX profile synchronized with `extension.py` because this directory is intentionally flat. + +## Ownership + +- `extension.py` owns the runtime implementation. +- `extension.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `_Unset` (no explicit base class) +- `Extension` (no explicit base class) + - `execute(self, **kwargs) -> None | Awaitable[None]` +- Top-level functions: +- `_log_extension_call(name: str)` +- `extensible(func)`: Make a function emit two implicit extension points around its execution. +- `async call_extensions_async(extension_point: str, agent: 'Agent|None'=..., **kwargs)` +- `call_extensions_sync(extension_point: str, agent: 'Agent|None'=..., **kwargs)` +- `get_webui_extensions(agent: 'Agent | None', extension_point: str, filters: list[str] | None=...)` +- `_get_extension_classes(extension_point: str, agent: 'Agent|None'=..., **kwargs) -> list[Type[Extension]]` +- `_get_file_from_module(module_name: str) -> str` +- `_get_extensions(folder: str)` +- `register_extensions_watchdogs()` +- Notable constants/configuration names: `DEFAULT_EXTENSIONS_FOLDER`, `USER_EXTENSIONS_FOLDER`, `_EXTENSIONS_CACHE_AREA`, `_CLASSES_CACHE_AREA`, `_UNSET`, `_EXTENSIONS_LOG_COUNTS`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- `Extension` defines `execute(...)`. +- Observed side-effect areas: filesystem reads, WebSocket state, plugin state. +- Imported dependency areas include: `abc`, `functools`, `helpers`, `helpers.print_style`, `inspect`, `os`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `_Unset`, `inspect.iscoroutinefunction`, `wraps`, `_log_extension_call`, `_get_extension_classes`, `subagents.get_paths`, `cache.determine_cache_key`, `cache.add`, `files.get_abs_path`, `modules.load_classes_from_folder`, `watchdog.add_watchdog`, `os.path.join`, `_get_agent`, `_prepare_inputs`, `_process_result`, `call_extensions_sync`, `cls.execute`, `files.deabsolute_path`, `_get_file_from_module`, `module_name.split`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_api_chat_lifetime.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_error_retry_plugin.py` + - `tests/test_extensions_stress.py` + - `tests/test_history_compression_wait.py` + - `tests/test_model_config_api_keys.py` + - `tests/test_oauth_codex.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/extract_tools.py.dox.md b/helpers/extract_tools.py.dox.md new file mode 100644 index 000000000..9c65b8ced --- /dev/null +++ b/helpers/extract_tools.py.dox.md @@ -0,0 +1,48 @@ +# extract_tools.py DOX + +## Purpose + +- Own the `extract_tools.py` helper module. +- This module normalizes and repairs model-emitted tool-call JSON. +- Keep this file-level DOX profile synchronized with `extract_tools.py` because this directory is intentionally flat. + +## Ownership + +- `extract_tools.py` owns the runtime implementation. +- `extract_tools.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `json_parse_dirty(json: str) -> dict[str, Any] | None` +- `normalize_tool_request(tool_request: Any) -> tuple[str, dict]` +- `extract_json_root_string(content: str) -> str | None` +- `extract_json_object_string(content)` +- `extract_json_string(content)` +- `fix_json_string(json_string)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `dirty_json`, `helpers.modules`, `re`, `regex`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `extract_json_object_string`, `content.find`, `DirtyJson`, `content.rfind`, `regex.search`, `re.sub`, `json.strip`, `ValueError`, `tool_name.split`, `parser.parse`, `match.group`, `match.group.replace`, `DirtyJson.parse_string`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_stream_tool_early_stop.py` + - `tests/test_tool_request_normalization.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/faiss_monkey_patch.py.dox.md b/helpers/faiss_monkey_patch.py.dox.md new file mode 100644 index 000000000..bfbacf50a --- /dev/null +++ b/helpers/faiss_monkey_patch.py.dox.md @@ -0,0 +1,38 @@ +# faiss_monkey_patch.py DOX + +## Purpose + +- Own the `faiss_monkey_patch.py` helper module. +- This module applies compatibility patches for FAISS behavior. +- Keep this file-level DOX profile synchronized with `faiss_monkey_patch.py` because this directory is intentionally flat. + +## Ownership + +- `faiss_monkey_patch.py` owns the runtime implementation. +- `faiss_monkey_patch.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `numpy`, `sys`, `types`, `warnings`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `types.ModuleType`, `SimpleNamespace`, `warnings.catch_warnings`, `warnings.simplefilter`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/fasta2a_client.py.dox.md b/helpers/fasta2a_client.py.dox.md new file mode 100644 index 000000000..e5ef5b6a8 --- /dev/null +++ b/helpers/fasta2a_client.py.dox.md @@ -0,0 +1,50 @@ +# fasta2a_client.py DOX + +## Purpose + +- Own the `fasta2a_client.py` helper module. +- This module connects Agent Zero to external A2A agents. +- Keep this file-level DOX profile synchronized with `fasta2a_client.py` because this directory is intentionally flat. + +## Ownership + +- `fasta2a_client.py` owns the runtime implementation. +- `fasta2a_client.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `AgentConnection` (no explicit base class) + - `async get_agent_card(self) -> Dict[str, Any]` + - `async send_message(self, message: str, attachments: Optional[List[str]]=..., context_id: Optional[str]=..., metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]` + - `async get_task(self, task_id: str) -> Dict[str, Any]` + - `async wait_for_completion(self, task_id: str, poll_interval: int=..., max_wait: int=...) -> Dict[str, Any]` + - `async close(self)` +- Top-level functions: +- `async connect_to_agent(agent_url: str, timeout: int=...) -> AgentConnection`: Create a connection to a remote agent. +- `is_client_available() -> bool`: Check if FastA2A client is available. +- Notable constants/configuration names: `_PRINTER`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, network calls, WebSocket state, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `helpers.print_style`, `typing`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `PrintStyle`, `AgentConnection`, `PrintStyle.warning`, `agent_url.rstrip`, `httpx.AsyncClient`, `A2AClient`, `TimeoutError`, `connection.get_agent_card`, `RuntimeError`, `agent_url.startswith`, `os.getenv`, `self._http_client.aclose`, `self.close`, `response.raise_for_status`, `response.json`, `self.get_agent_card`, `uuid.uuid4`, `self._a2a_client.send_message`, `self._a2a_client.get_task`, `self.get_task`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/fasta2a_server.py.dox.md b/helpers/fasta2a_server.py.dox.md new file mode 100644 index 000000000..cd8e00755 --- /dev/null +++ b/helpers/fasta2a_server.py.dox.md @@ -0,0 +1,52 @@ +# fasta2a_server.py DOX + +## Purpose + +- Own the `fasta2a_server.py` helper module. +- This module serves Agent Zero through a dynamic A2A proxy. +- Keep this file-level DOX profile synchronized with `fasta2a_server.py` because this directory is intentionally flat. + +## Ownership + +- `fasta2a_server.py` owns the runtime implementation. +- `fasta2a_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `AgentZeroWorker` (`Worker`) + - `async run_task(self, params: Any) -> None` + - `async cancel_task(self, params: Any) -> None` + - `build_message_history(self, history: List[Any]) -> List[Message]` + - `build_artifacts(self, result: Any) -> List[Artifact]` +- `DynamicA2AProxy` (no explicit base class) + - `get_instance()` + - `reconfigure(self, token: str)` +- Top-level functions: +- `is_available()`: Check if FastA2A is available and properly configured. +- `get_proxy()`: Get the FastA2A proxy instance. +- Notable constants/configuration names: `_PRINTER`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `agent`, `asyncio`, `atexit`, `contextlib`, `helpers`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `starlette.requests`, `threading`, `typing`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `PrintStyle`, `DynamicA2AProxy.get_instance`, `super.__init__`, `join`, `UserMessage`, `threading.Lock`, `atexit.register`, `self._configure`, `settings.get_settings`, `path.startswith`, `self._convert_message`, `initialize_agent`, `AgentContext`, `context.log.log`, `context.communicate`, `context.reset`, `AgentContext.remove`, `remove_chat`, `self.storage.update_task`, `self._register_shutdown`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/file_browser.py.dox.md b/helpers/file_browser.py.dox.md new file mode 100644 index 000000000..3f8f2e43a --- /dev/null +++ b/helpers/file_browser.py.dox.md @@ -0,0 +1,51 @@ +# file_browser.py DOX + +## Purpose + +- Own the `file_browser.py` helper module. +- This module builds safe file-browser views over allowed filesystem roots. +- Keep this file-level DOX profile synchronized with `file_browser.py` because this directory is intentionally flat. + +## Ownership + +- `file_browser.py` owns the runtime implementation. +- `file_browser.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `FileBrowser` (no explicit base class) + - `save_file_b64(self, current_path: str, filename: str, base64_content: str)` + - `save_files(self, files: List, current_path: str=...) -> Tuple[List[str], List[str]]` + - `delete_file(self, file_path: str) -> bool` + - `rename_item(self, file_path: str, new_name: str) -> bool` + - `create_folder(self, parent_path: str, folder_name: str) -> bool` + - `save_text_file(self, file_path: str, content: str) -> bool` + - `get_files(self, current_path: str=...) -> Dict` + - `get_full_path(self, file_path: str, allow_dir: bool=...) -> str` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, settings/state persistence. +- Imported dependency areas include: `base64`, `datetime`, `helpers`, `helpers.localization`, `helpers.print_style`, `helpers.security`, `os`, `pathlib`, `shutil`, `subprocess`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Path`, `files.get_abs_path`, `self._get_file_extension`, `file.seek`, `file.tell`, `resolve`, `os.makedirs`, `os.path.exists`, `full_path.with_name`, `new_path.exists`, `os.rename`, `target_dir.exists`, `filename.rsplit.lower`, `subprocess.run`, `result.stdout.strip.split`, `self._get_files_via_ls`, `files.exists`, `ValueError`, `str.startswith`, `file.write`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_download_toast_regressions.py` + - `tests/test_office_document_store.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/file_tree.py.dox.md b/helpers/file_tree.py.dox.md new file mode 100644 index 000000000..db3625d70 --- /dev/null +++ b/helpers/file_tree.py.dox.md @@ -0,0 +1,63 @@ +# file_tree.py DOX + +## Purpose + +- Own the `file_tree.py` helper module. +- This module renders bounded file-tree summaries for prompts and UI surfaces. +- Keep this file-level DOX profile synchronized with `file_tree.py` because this directory is intentionally flat. + +## Ownership + +- `file_tree.py` owns the runtime implementation. +- `file_tree.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `_TreeEntry` (no explicit base class) + - `as_dict(self) -> dict[str, Any]` +- Top-level functions: +- `_from_timestamp(timestamp: float) -> datetime` +- `file_tree(relative_path: str, max_depth: int=..., max_lines: int=..., folders_first: bool=..., max_folders: int=..., max_files: int=..., sort: tuple[Literal['name', 'created', 'modified'], Literal['asc', 'desc']]=..., ignore: str | None=..., output_mode: Literal['string', 'flat', 'nested']=...) -> str | list[dict]`: Render a directory tree relative to the repository base path. +- `_normalize_relative_path(path: str) -> str` +- `_directory_has_visible_entries(directory: str, root_abs_path: str, ignore_spec: PathSpec, cache: dict[str, bool], max_depth_remaining: int) -> bool` +- `_create_summary_comment(parent: _TreeEntry, noun: str, count: int) -> _TreeEntry` +- `_create_global_limit_comment(parent: _TreeEntry, hidden_children: Sequence[_TreeEntry]) -> _TreeEntry` +- `_create_folder_unprocessed_comment(folder_node: _TreeEntry, folder_path: str, abs_root: str, ignore_spec: Optional[PathSpec]) -> Optional[_TreeEntry]` +- `_prune_to_visible(node: _TreeEntry, visible_ids: set[int]) -> None` +- `_mark_last_flags(node: _TreeEntry) -> None` +- `_refresh_render_metadata(node: _TreeEntry) -> None` +- `_resolve_ignore_patterns(ignore: str | None, root_abs_path: str) -> Optional[PathSpec]` +- `_list_directory_children(directory: str, root_abs_path: str, ignore_spec: Optional[PathSpec], max_depth_remaining: int, cache: dict[str, bool]) -> tuple[list[os.DirEntry], list[os.DirEntry]]` +- `_apply_sorting_and_limits(folders: list[_TreeEntry], files: list[_TreeEntry], folders_first: bool, sort: tuple[str, str], max_folders: int | None, max_files: int | None, directory_node: _TreeEntry) -> list[_TreeEntry]` +- `_format_line(node: _TreeEntry) -> str` +- `_build_tree_items_flat(items: Sequence[_TreeEntry]) -> list[dict]` +- `_to_nested_structure(items: Sequence[_TreeEntry]) -> list[dict]` +- `_iter_depth_first(items: Sequence[_TreeEntry]) -> Iterable[_TreeEntry]` +- Notable constants/configuration names: `SORT_BY_NAME`, `SORT_BY_CREATED`, `SORT_BY_MODIFIED`, `SORT_ASC`, `SORT_DESC`, `OUTPUT_MODE_STRING`, `OUTPUT_MODE_FLAT`, `OUTPUT_MODE_NESTED`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, subprocess/runtime control, WebSocket state. +- Imported dependency areas include: `__future__`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.localization`, `os`, `pathspec`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `dataclass`, `datetime.fromtimestamp`, `files_helper.get_abs_path`, `files_helper.get_abs_path_dockerized`, `_resolve_ignore_patterns`, `os.stat`, `_TreeEntry`, `deque`, `queue.clear`, `_mark_last_flags`, `_refresh_render_metadata`, `path.replace`, `normalized.startswith`, `join`, `_create_global_limit_comment`, `ignore.startswith`, `PathSpec.from_lines`, `segments.reverse`, `os.path.exists`, `FileNotFoundError`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_file_tree_visualize.py` + - `tests/test_skills_runtime.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/files.py.dox.md b/helpers/files.py.dox.md new file mode 100644 index 000000000..b4f153240 --- /dev/null +++ b/helpers/files.py.dox.md @@ -0,0 +1,82 @@ +# files.py DOX + +## Purpose + +- Own the `files.py` helper module. +- This module owns repository/user path helpers and file read/write/parsing primitives. +- Keep this file-level DOX profile synchronized with `files.py` because this directory is intentionally flat. + +## Ownership + +- `files.py` owns the runtime implementation. +- `files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `VariablesPlugin` (`ABC`) + - `get_variables(self, file: str, backup_dirs: list[str] | None=..., **kwargs) -> dict[str, Any]` +- Top-level functions: +- `load_plugin_variables(file: str, backup_dirs: list[str] | None=..., **kwargs) -> dict[str, Any]` +- `parse_file(_filename: str, _directories: list[str] | None=..., _encoding=..., **kwargs)` +- `read_prompt_file(_file: str, _directories: list[str] | None=..., _encoding=..., **kwargs)` +- `evaluate_text_conditions(_content: str, **kwargs)` +- `read_file(relative_path: str, encoding=...)` +- `read_file_json(relative_path: str, encoding=...)` +- `read_file_yaml(relative_path: str, encoding=...)` +- `read_file_bin(relative_path: str)` +- `read_file_base64(relative_path)` +- `is_probably_binary_bytes(data: bytes, threshold: float=...) -> bool`: Binary detection. +- `is_probably_binary_file(file_path: str, sample_size: int=..., threshold: float=...) -> bool`: Binary detection by reading only the first ~sample_size bytes of a file. +- `replace_placeholders_text(_content: str, **kwargs)` +- `replace_placeholders_json(_content: str, **kwargs)` +- `replace_placeholders_dict(_content: dict, **kwargs)` +- `process_includes(_content: str, _directories: list[str], _source_file: str=..., _source_dir: str=..., **kwargs)` +- `_get_dirs_after(_directories: list[str], _source_dir: str) -> list[str]`: Return directories after _source_dir in the priority list. +- `find_file_in_dirs(_filename: str, _directories: list[str])`: This function searches for a filename in a list of directories in order. +- `get_unique_filenames_in_dirs(dir_paths: list[str], pattern: str=..., type: Literal['file', 'dir', 'any']=...)` +- `find_existing_paths_by_pattern(pattern: str)` +- `remove_code_fences(text)` +- `is_full_json_template(text)` +- `write_file(relative_path: str, content: str, encoding: str=...)` +- `delete_file(relative_path: str)` +- `write_file_bin(relative_path: str, content: bytes)` +- `write_file_base64(relative_path: str, content: str)` +- `delete_dir(relative_path: str)` +- `move_dir(old_path: str, new_path: str)` +- `move_dir_safe(src, dst, rename_format=...)` +- `create_dir_safe(dst, rename_format=...)` +- `create_dir(relative_path: str)` +- Notable constants/configuration names: `AGENTS_DIR`, `PLUGINS_DIR`, `PROJECTS_DIR`, `EXTENSIONS_DIR`, `USER_DIR`, `TEMP_DIR`, `API_DIR`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `abc`, `base64`, `fnmatch`, `glob`, `helpers`, `helpers.strings`, `json`, `mimetypes`, `os`, `re`, `shutil`, `simpleeval`, `tempfile`, `typing`, `zipfile`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `os.path.dirname`, `os.path.abspath`, `find_file_in_dirs`, `is_full_json_template`, `remove_code_fences`, `evaluate_text_conditions`, `replace_placeholders_text`, `process_includes`, `re.compile`, `_process`, `get_abs_path`, `is_probably_binary_bytes`, `replace_value`, `re.sub`, `os.path.normpath`, `FileNotFoundError`, `result.sort`, `glob.glob`, `matches.sort`, `re.fullmatch`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_default_prompt_budget.py` + - `tests/test_document_query_plugin.py` + - `tests/test_download_toast_regressions.py` + - `tests/test_file_tree_visualize.py` + - `tests/test_host_browser_connector.py` + - `tests/test_image_get_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/functions.py.dox.md b/helpers/functions.py.dox.md new file mode 100644 index 000000000..c2e00daac --- /dev/null +++ b/helpers/functions.py.dox.md @@ -0,0 +1,45 @@ +# functions.py DOX + +## Purpose + +- Own the `functions.py` helper module. +- This module provides safe generic callable execution helpers. +- Keep this file-level DOX profile synchronized with `functions.py` because this directory is intentionally flat. + +## Ownership + +- `functions.py` owns the runtime implementation. +- `functions.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `safe_call(func, *args, **kwargs)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `inspect`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `inspect.signature`, `func`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_error_retry_plugin.py` + - `tests/test_oauth_codex.py` + - `tests/test_oauth_providers.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/git.py.dox.md b/helpers/git.py.dox.md new file mode 100644 index 000000000..857c3966c --- /dev/null +++ b/helpers/git.py.dox.md @@ -0,0 +1,70 @@ +# git.py DOX + +## Purpose + +- Own the `git.py` helper module. +- This module reads local and remote Git release/commit metadata safely. +- Keep this file-level DOX profile synchronized with `git.py` because this directory is intentionally flat. + +## Ownership + +- `git.py` owns the runtime implementation. +- `git.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `GitHeadInfo` (no explicit base class) +- `GitReleaseInfo` (no explicit base class) +- `GitRemoteReleaseInfo` (no explicit base class) +- `GitRemoteReleasesResult` (no explicit base class) +- `GitRemoteCommitsInfo` (no explicit base class) +- `GitRepoReleaseInfo` (no explicit base class) +- Top-level functions: +- `strip_auth_from_url(url: str) -> str`: Remove any authentication info from URL. +- `extract_author_repo(url: str) -> tuple[str, str]` +- `_format_git_timestamp(timestamp: int) -> str` +- `_split_describe_version(describe: str) -> tuple[str, int]` +- `_format_release_version(branch: str, short_tag: str, commits_since_tag: int, commit_hash: str) -> str` +- `get_remote_releases(author: str, repo: str) -> GitRemoteReleasesResult` +- `get_remote_commits_since_local(repo_path: str) -> GitRemoteCommitsInfo` +- `get_repo_release_info(repo_path: str) -> GitRepoReleaseInfo` +- `get_git_info()` +- `get_version()` +- `is_official_agent_zero_repo() -> bool`: Return True when origin points to agent0ai/agent-zero. +- `clone_repo(url: str, dest: str, token: str | None=...)`: Clone a git repository. Uses http.extraHeader for token auth (never stored in URL/config). +- `update_repo(repo_path: str) -> Repo` +- `get_repo_status(repo_path: str) -> dict`: Get Git repository status, ignoring A0 project metadata files. +- Notable constants/configuration names: `A0_IGNORE_PATTERNS`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, filesystem deletion, network calls, subprocess/runtime control, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `base64`, `dataclasses`, `datetime`, `git`, `giturlparse`, `helpers`, `helpers.localization`, `os`, `re`, `subprocess`, `urllib.parse`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `urlparse`, `urlunparse`, `parse`, `strip`, `repo.endswith`, `datetime.fromtimestamp.strftime`, `describe.strip`, `re.fullmatch`, `files.get_base_dir`, `get_repo_release_info`, `os.environ.copy`, `subprocess.run`, `Repo`, `repo.active_branch.tracking_branch`, `strip_auth_from_url`, `ValueError`, `match.group`, `branch.upper`, `author.strip`, `repo.strip`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_docker_release_plan.py` + - `tests/test_git_version_label.py` + - `tests/test_model_config_api_keys.py` + - `tests/test_model_config_project_presets.py` + - `tests/test_model_search.py` + - `tests/test_oauth_github_copilot.py` + - `tests/test_oauth_providers.py` + - `tests/test_onboarding_static.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/guids.py.dox.md b/helpers/guids.py.dox.md new file mode 100644 index 000000000..9fea993bf --- /dev/null +++ b/helpers/guids.py.dox.md @@ -0,0 +1,40 @@ +# guids.py DOX + +## Purpose + +- Own the `guids.py` helper module. +- This module generates framework IDs. +- Keep this file-level DOX profile synchronized with `guids.py` because this directory is intentionally flat. + +## Ownership + +- `guids.py` owns the runtime implementation. +- `guids.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `generate_id(length: int=...) -> str` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `random`, `string`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `join`, `random.choices`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/history.py.dox.md b/helpers/history.py.dox.md new file mode 100644 index 000000000..0e07d4a9e --- /dev/null +++ b/helpers/history.py.dox.md @@ -0,0 +1,109 @@ +# history.py DOX + +## Purpose + +- Own the `history.py` helper module. +- This module owns chat history message records and model-output conversion. +- Keep this file-level DOX profile synchronized with `history.py` because this directory is intentionally flat. + +## Ownership + +- `history.py` owns the runtime implementation. +- `history.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `RawMessage` (`TypedDict`) +- `OutputMessage` (`TypedDict`) +- `Record` (no explicit base class) + - `get_tokens(self) -> int` + - `async compress(self) -> bool` + - `output(self) -> list[OutputMessage]` + - `async summarize(self) -> str` + - `to_dict(self) -> dict` + - `from_dict(data: dict, history: 'History')` + - `output_langchain(self)` + - `output_text(self, human_label=..., ai_label=...)` +- `Message` (`Record`) + - `get_tokens(self) -> int` + - `calculate_tokens(self)` + - `set_summary(self, summary: str)` + - `async compress(self)` + - `output(self)` + - `output_langchain(self)` + - `output_text(self, human_label=..., ai_label=...)` + - `to_dict(self)` +- `Topic` (`Record`) + - `get_tokens(self)` + - `add_message(self, ai: bool, content: MessageContent, tokens: int=..., id: str=...) -> Message` + - `output(self) -> list[OutputMessage]` + - `async summarize(self)` + - `compress_large_messages(self, message_ratio: float=...) -> bool` + - `async compress(self) -> bool` + - `async compress_attention(self, ratio: float=...) -> bool` + - `async summarize_messages(self, messages: list[Message])` +- `Bulk` (`Record`) + - `get_tokens(self)` + - `output(self, human_label: str=..., ai_label: str=...) -> list[OutputMessage]` + - `async compress(self)` + - `async summarize(self)` + - `to_dict(self)` + - `from_dict(data: dict, history: 'History')` +- `History` (`Record`) + - `get_tokens(self) -> int` + - `is_over_limit(self)` + - `get_bulks_tokens(self) -> int` + - `get_topics_tokens(self) -> int` + - `get_current_topic_tokens(self) -> int` + - `add_message(self, ai: bool, content: MessageContent, tokens: int=..., id: str=...) -> Message` + - `new_topic(self)` + - `output(self) -> list[OutputMessage]` +- Top-level functions: +- `deserialize_history(json_data: str, agent) -> History` +- `_stringify_output(output: OutputMessage, ai_label=..., human_label=...)` +- `_stringify_content(content: MessageContent) -> str` +- `_output_content_langchain(content: MessageContent)` +- `group_outputs_abab(outputs: list[OutputMessage]) -> list[OutputMessage]` +- `group_messages_abab(messages: list[BaseMessage]) -> list[BaseMessage]` +- `output_langchain(messages: list[OutputMessage])` +- `output_text(messages: list[OutputMessage], ai_label=..., human_label=...)` +- `_merge_outputs(a: MessageContent, b: MessageContent) -> MessageContent` +- `_merge_properties(a: Dict[str, MessageContent], b: Dict[str, MessageContent]) -> Dict[str, MessageContent]` +- `_is_raw_message(obj: object) -> bool` +- `_is_embedded_data(obj: object) -> bool` +- `_json_dumps(obj)` +- `_json_loads(obj)` +- Notable constants/configuration names: `BULK_MERGE_COUNT`, `TOPICS_MERGE_COUNT`, `CURRENT_TOPIC_RATIO`, `HISTORY_TOPIC_RATIO`, `HISTORY_BULK_RATIO`, `CURRENT_TOPIC_ATTENTION_COMPRESSION`, `HISTORY_TOPIC_ATTENTION_COMPRESSION`, `LARGE_MESSAGE_TO_CURRENT_TOPIC_RATIO`, `LARGE_MESSAGE_TO_HISTORY_TOPIC_RATIO`, `RAW_MESSAGE_OUTPUT_TEXT_TRIM`, `COMPRESSION_TARGET_RATIO`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, filesystem deletion, model calls, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `abc`, `asyncio`, `collections`, `collections.abc`, `enum`, `helpers`, `json`, `langchain_core.messages`, `math`, `plugins._model_config.helpers.model_config`, `typing`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `History`, `_is_raw_message`, `_json_dumps`, `group_messages_abab`, `join`, `make_list`, `cast`, `a.copy`, `json.dumps`, `json.loads`, `globals.from_dict`, `output_langchain`, `output_text`, `self.output_text`, `tokens.approximate_tokens`, `self.calculate_tokens`, `Message`, `get_chat_model_config`, `large_msgs.sort`, `self.compress_large_messages`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_chat_compaction.py` + - `tests/test_error_retry_plugin.py` + - `tests/test_history_compression_wait.py` + - `tests/test_mcp_handler_multimodal.py` + - `tests/test_memory_quality.py` + - `tests/test_model_config_project_presets.py` + - `tests/test_office_document_store.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/images.py.dox.md b/helpers/images.py.dox.md new file mode 100644 index 000000000..1d2cd0320 --- /dev/null +++ b/helpers/images.py.dox.md @@ -0,0 +1,48 @@ +# images.py DOX + +## Purpose + +- Own the `images.py` helper module. +- This module resolves, compresses, and serializes image references for model inputs. +- Keep this file-level DOX profile synchronized with `images.py` because this directory is intentionally flat. + +## Ownership + +- `images.py` owns the runtime implementation. +- `images.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `prepare_content(content: Any) -> Any` +- `is_local_ref(url: str) -> bool` +- `to_data_url(url: str) -> str` +- `resolve_ref(url: str) -> Path` +- `compress_image(image_data: bytes, max_pixels: int=..., quality: int=...) -> bytes`: Compress an image by scaling it down and converting to JPEG with quality settings. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, network calls, settings/state persistence. +- Imported dependency areas include: `PIL`, `base64`, `io`, `math`, `mimetypes`, `pathlib`, `typing`, `urllib.parse`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `url.lower`, `lowered.startswith`, `resolve_ref`, `base64.b64encode.decode`, `Path.expanduser`, `raw_path.startswith`, `FileNotFoundError`, `io.BytesIO`, `img.save`, `output.getvalue`, `prepare_content`, `url.startswith`, `mimetypes.guess_type`, `ValueError`, `url.lower.startswith`, `unquote`, `seen.add`, `math.sqrt`, `img.resize`, `img.convert`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_image_get_security.py` + - `tests/test_vision_load_image_refs.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/integration_commands.py.dox.md b/helpers/integration_commands.py.dox.md new file mode 100644 index 000000000..b7462926e --- /dev/null +++ b/helpers/integration_commands.py.dox.md @@ -0,0 +1,53 @@ +# integration_commands.py DOX + +## Purpose + +- Own the `integration_commands.py` helper module. +- This module parses external integration slash commands such as project/config/send controls. +- Keep this file-level DOX profile synchronized with `integration_commands.py` because this directory is intentionally flat. + +## Ownership + +- `integration_commands.py` owns the runtime implementation. +- `integration_commands.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `extract_command_line(text: str) -> str` +- `parse_command(text: str) -> tuple[str, str] | None` +- `try_handle_command(context: 'AgentContext', text: str) -> str | None` +- `_handle_queue(context: 'AgentContext', args: str) -> str` +- `_handle_project(context: 'AgentContext', args: str) -> str` +- `_handle_config(context: 'AgentContext', args: str) -> str` +- `_format_project_entry(item: dict) -> str` +- `_describe_project(items: list[dict], current_name: str) -> str` +- `_describe_override(override: dict | None) -> str` +- `_strip_quotes(value: str) -> str` +- `_normalize_lookup(value: str) -> str` +- `_match_named_item(items: list[dict], desired: str, keys: tuple[str, ...]) -> tuple[dict | None, list[dict]]` +- Notable constants/configuration names: `_CLEAR_VALUES`, `_SUPPORTED_COMMANDS`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence. +- Imported dependency areas include: `__future__`, `helpers`, `helpers.persist_chat`, `helpers.state_monitor_integration`, `plugins._model_config.helpers`, `re`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `splitlines`, `extract_command_line`, `line.partition`, `command.strip.lower`, `parse_command`, `mq.get_queue`, `args.strip.lower`, `mq.send_all_aggregated`, `mark_dirty_for_context`, `_strip_quotes`, `_match_named_item`, `projects.activate_project`, `model_config.is_chat_override_allowed`, `context.get_data`, `context.set_data`, `save_tmp_chat`, `str.strip`, `value.strip`, `value.lower.strip`, `re.sub`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/job_loop.py.dox.md b/helpers/job_loop.py.dox.md new file mode 100644 index 000000000..b0414749d --- /dev/null +++ b/helpers/job_loop.py.dox.md @@ -0,0 +1,46 @@ +# job_loop.py DOX + +## Purpose + +- Own the `job_loop.py` helper module. +- This module runs periodic scheduler and maintenance loops. +- Keep this file-level DOX profile synchronized with `job_loop.py` because this directory is intentionally flat. + +## Ownership + +- `job_loop.py` owns the runtime implementation. +- `job_loop.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `async run_loop()` +- `async scheduler_tick()` +- `pause_loop()` +- `resume_loop()` +- Notable constants/configuration names: `SLEEP_TIME`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: scheduler state. +- Imported dependency areas include: `asyncio`, `datetime`, `helpers`, `helpers.print_style`, `helpers.task_scheduler`, `time`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `time.time`, `runtime.is_development`, `scheduler.tick`, `call_extensions_async`, `resume_loop`, `asyncio.sleep`, `runtime.call_development_function`, `PrintStyle.error`, `scheduler_tick`, `errors.format_error`, `PrintStyle`, `errors.error_text`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_api_chat_lifetime.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/kvp.py.dox.md b/helpers/kvp.py.dox.md new file mode 100644 index 000000000..d7e6e0de0 --- /dev/null +++ b/helpers/kvp.py.dox.md @@ -0,0 +1,52 @@ +# kvp.py DOX + +## Purpose + +- Own the `kvp.py` helper module. +- This module provides runtime and persistent key-value storage helpers. +- Keep this file-level DOX profile synchronized with `kvp.py` because this directory is intentionally flat. + +## Ownership + +- `kvp.py` owns the runtime implementation. +- `kvp.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `_persistent_dir() -> str` +- `_validate_key(key: str) -> None` +- `_key_to_path(key: str) -> str` +- `get_runtime(key: str, default: Any=...) -> Any` +- `set_runtime(key: str, value: Any) -> None` +- `remove_runtime(key: str) -> None` +- `find_runtime(pattern: str) -> list[str]` +- `get_persistent(key: str, default: Any=...) -> Any` +- `set_persistent(key: str, value: Any) -> None` +- `remove_persistent(key: str) -> None` +- `find_persistent(pattern: str) -> list[str]` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence. +- Imported dependency areas include: `fnmatch`, `glob`, `helpers.files`, `json`, `os`, `tempfile`, `threading`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `threading.RLock`, `get_abs_path`, `_validate_key`, `os.path.join`, `_key_to_path`, `os.path.dirname`, `_persistent_dir`, `ValueError`, `_runtime_store.pop`, `os.makedirs`, `tempfile.mkstemp`, `glob.glob`, `keys.sort`, `os.replace`, `os.unlink`, `os.path.isdir`, `json.load`, `os.fdopen`, `json.dump`, `f.flush`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/localization.py.dox.md b/helpers/localization.py.dox.md new file mode 100644 index 000000000..b33e410b8 --- /dev/null +++ b/helpers/localization.py.dox.md @@ -0,0 +1,50 @@ +# localization.py DOX + +## Purpose + +- Own the `localization.py` helper module. +- This module loads and resolves localized UI/application text. +- Keep this file-level DOX profile synchronized with `localization.py` because this directory is intentionally flat. + +## Ownership + +- `localization.py` owns the runtime implementation. +- `localization.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Localization` (no explicit base class) + - `get(cls, *args, **kwargs)` + - `get_timezone(self) -> str` + - `get_tzinfo(self)` + - `get_offset_minutes(self) -> int` + - `apply_process_timezone(self) -> None` + - `now(self) -> datetime` + - `now_iso(self, sep: str=..., timespec: str=...) -> str` + - `localize_naive_datetime(self, dt: datetime) -> datetime` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, settings/state persistence. +- Imported dependency areas include: `datetime`, `helpers.dotenv`, `helpers.print_style`, `os`, `pytz`, `time`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `get_dotenv_value`, `pytz.timezone`, `datetime.now`, `now_in_tz.utcoffset`, `self.now.isoformat`, `self.get_tzinfo`, `cls`, `self.set_timezone`, `self._compute_offset_minutes`, `self.apply_process_timezone`, `tzinfo.localize`, `PrintStyle.debug`, `save_dotenv_value`, `localtime_str.strip.replace`, `local_datetime_obj.astimezone`, `utc_dt.astimezone`, `local_datetime_obj.isoformat`, `dt.astimezone`, `local_dt.isoformat`, `time.tzset`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_timezone_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/log.py.dox.md b/helpers/log.py.dox.md new file mode 100644 index 000000000..ce74dec69 --- /dev/null +++ b/helpers/log.py.dox.md @@ -0,0 +1,68 @@ +# log.py DOX + +## Purpose + +- Own the `log.py` helper module. +- This module owns chat log items, outputs, truncation, and dirty-state integration. +- Keep this file-level DOX profile synchronized with `log.py` because this directory is intentionally flat. + +## Ownership + +- `log.py` owns the runtime implementation. +- `log.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `LogItem` (no explicit base class) + - `update(self, type: Type | None=..., heading: str | None=..., content: str | None=..., kvps: dict | None=..., update_progress: ProgressUpdate | None=..., **kwargs)` + - `stream(self, heading: str | None=..., content: str | None=..., **kwargs)` + - `output(self)` +- `LogOutput` (no explicit base class) +- `Log` (no explicit base class) + - `log(self, type: Type, heading: str | None=..., content: str | None=..., kvps: dict | None=..., update_progress: ProgressUpdate | None=..., id: Optional[str]=..., **kwargs) -> LogItem` + - `set_progress(self, progress: str, no: int=..., active: bool=...)` + - `set_initial_progress(self)` + - `output(self, start=..., end=...)` + - `reset(self)` +- Top-level functions: +- `_lazy_mark_dirty_all(reason: str | None=...) -> None` +- `_lazy_mark_dirty_for_context(context_id: str, reason: str | None=...) -> None` +- `_truncate_heading(text: str | None) -> str` +- `_truncate_progress(text: str | None) -> str` +- `_truncate_key(text: str) -> str` +- `_truncate_value(val: T) -> T` +- `_truncate_content(text: str | None, type: Type) -> str` +- Notable constants/configuration names: `_MARK_DIRTY_ALL`, `_MARK_DIRTY_FOR_CONTEXT`, `T`, `HEADING_MAX_LEN`, `CONTENT_MAX_LEN`, `RESPONSE_CONTENT_MAX_LEN`, `KEY_MAX_LEN`, `VALUE_MAX_LEN`, `PROGRESS_MAX_LEN`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `collections`, `copy`, `dataclasses`, `helpers.secrets`, `helpers.strings`, `json`, `threading`, `time`, `typing`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `TypeVar`, `dataclass`, `_MARK_DIRTY_ALL`, `_MARK_DIRTY_FOR_CONTEXT`, `truncate_text_by_ratio`, `cast`, `threading.RLock`, `self.set_initial_progress`, `self._update_item`, `self._notify_state_monitor`, `_lazy_mark_dirty_all`, `_lazy_mark_dirty_for_context`, `self._mask_recursive`, `_truncate_progress`, `self.set_progress`, `LogOutput`, `_truncate_value`, `json.dumps`, `time.time`, `self.log._update_item`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_chat_compaction.py` + - `tests/test_error_retry_plugin.py` + - `tests/test_fasta2a_client.py` + - `tests/test_file_tree_visualize.py` + - `tests/test_history_compression_wait.py` + - `tests/test_http_auth_csrf.py` + - `tests/test_mcp_handler_multimodal.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/login.py.dox.md b/helpers/login.py.dox.md new file mode 100644 index 000000000..344895198 --- /dev/null +++ b/helpers/login.py.dox.md @@ -0,0 +1,49 @@ +# login.py DOX + +## Purpose + +- Own the `login.py` helper module. +- This module checks login requirements and credential hashes. +- Keep this file-level DOX profile synchronized with `login.py` because this directory is intentionally flat. + +## Ownership + +- `login.py` owns the runtime implementation. +- `login.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `get_credentials_hash()` +- `is_login_required()` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: secret handling. +- Imported dependency areas include: `hashlib`, `helpers`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `dotenv.get_dotenv_value`, `hashlib.sha256.hexdigest`, `hashlib.sha256`, `encode`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_http_auth_csrf.py` + - `tests/test_oauth_gemini_api.py` + - `tests/test_oauth_github_copilot.py` + - `tests/test_oauth_providers.py` + - `tests/test_oauth_xai_grok.py` + - `tests/test_tunnel_remote_link.py` + - `tests/test_ws_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/mcp_handler.py.dox.md b/helpers/mcp_handler.py.dox.md new file mode 100644 index 000000000..fc98db4f0 --- /dev/null +++ b/helpers/mcp_handler.py.dox.md @@ -0,0 +1,90 @@ +# mcp_handler.py DOX + +## Purpose + +- Own the `mcp_handler.py` helper module. +- This module loads MCP server configuration and exposes MCP tools to agents. +- Keep this file-level DOX profile synchronized with `mcp_handler.py` because this directory is intentionally flat. + +## Ownership + +- `mcp_handler.py` owns the runtime implementation. +- `mcp_handler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `MCPTool` (`Tool`) + - `get_log_object(self) -> LogItem` + - `async execute(self, **kwargs)` + - `async before_execution(self, **kwargs)` + - `async after_execution(self, response: Response, **kwargs)` +- `MCPServerRemote` (`BaseModel`) + - `get_error(self) -> str` + - `get_log(self) -> str` + - `get_tools(self) -> List[dict[str, Any]]` + - `has_tool(self, tool_name: str) -> bool` + - `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult` + - `update(self, config: dict[str, Any]) -> 'MCPServerRemote'` + - `async initialize(self) -> 'MCPServerRemote'` +- `MCPServerLocal` (`BaseModel`) + - `get_error(self) -> str` + - `get_log(self) -> str` + - `get_tools(self) -> List[dict[str, Any]]` + - `has_tool(self, tool_name: str) -> bool` + - `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult` + - `update(self, config: dict[str, Any]) -> 'MCPServerLocal'` + - `async initialize(self) -> 'MCPServerLocal'` +- `MCPConfig` (`BaseModel`) + - `get_instance(cls) -> 'MCPConfig'` + - `wait_for_lock(cls)` + - `update(cls, config_str: str) -> Any` + - `normalize_config(cls, servers: Any)` + - `get_server_log(self, server_name: str) -> str` + - `get_servers_status(self) -> list[dict[str, Any]]` + - `get_server_detail(self, server_name: str) -> dict[str, Any]` + - `is_initialized(self) -> bool` +- `MCPClientBase` (`ABC`) + - `async update_tools(self) -> 'MCPClientBase'` + - `has_tool(self, tool_name: str) -> bool` + - `get_tools(self) -> List[dict[str, Any]]` + - `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult` + - `get_log(self)` +- `MCPClientLocal` (`MCPClientBase`) +- `CustomHTTPClientFactory` (`ABC`) +- `MCPClientRemote` (`MCPClientBase`) + - `get_session_id(self) -> Optional[str]` +- Top-level functions: +- `_mcp_get(item: Any, key: str, default: Any=...) -> Any` +- `normalize_name(name: str) -> str` +- `_determine_server_type(config_dict: dict) -> str`: Determine the server type based on configuration, with backward compatibility. +- `_is_streaming_http_type(server_type: str) -> bool`: Check if the server type is a streaming HTTP variant. +- `initialize_mcp(mcp_servers_config: str)` +- Notable constants/configuration names: `MCP_MEDIA_TOKENS_ESTIMATE`, `MAX_MCP_RESOURCE_TEXT_CHARS`, `T`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- `MCPTool` is a `Tool`. +- `MCPTool` defines `execute(...)`. +- Observed side-effect areas: filesystem writes, network calls, WebSocket state, settings/state persistence, secret handling. +- Imported dependency areas include: `abc`, `anyio.streams.memory`, `asyncio`, `contextlib`, `datetime`, `helpers`, `helpers.log`, `helpers.print_style`, `helpers.tool`, `httpx`, `json`, `mcp`, `mcp.client.sse`, `mcp.client.stdio`, `mcp.client.streamable_http`, `mcp.shared.message`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `TypeVar`, `name.strip.lower`, `re.sub`, `Field`, `PrivateAttr`, `threading.Lock`, `config_dict.lower`, `server_type.lower`, `MCPConfig.get_instance.is_initialized`, `self.agent.context.log.log`, `str.strip`, `media_artifacts.guess_extension`, `callable`, `self._content_item_dump`, `join`, `Response`, `self.get_log_object`, `self._raw_tool_response`, `additional.pop`, `self._coerce_media_token_estimate`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_mcp_handler_multimodal.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/mcp_server.py.dox.md b/helpers/mcp_server.py.dox.md new file mode 100644 index 000000000..4151d3d89 --- /dev/null +++ b/helpers/mcp_server.py.dox.md @@ -0,0 +1,54 @@ +# mcp_server.py DOX + +## Purpose + +- Own the `mcp_server.py` helper module. +- This module serves Agent Zero chats through a dynamic MCP proxy. +- Keep this file-level DOX profile synchronized with `mcp_server.py` because this directory is intentionally flat. + +## Ownership + +- `mcp_server.py` owns the runtime implementation. +- `mcp_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ToolResponse` (`BaseModel`) +- `ToolError` (`BaseModel`) +- `DynamicMcpProxy` (no explicit base class) + - `get_instance()` + - `reconfigure(self, token: str)` +- Top-level functions: +- `async send_message(message: Annotated[str, Field(description='The message to send to the remote Agent Zero Instance', title='message')], attachments: Annotated[list[str], Field(description='Optional: A list of attachments (file paths or web urls) to send to the remote Agent Zero Instance with the message. Default: Empty list', title='attachments')] | None=..., chat_id: Annotated[str, Field(description='Optional: ID of the chat. Used to continue a chat. This value is returned in response to sending previous message. Default: Empty string', title='chat_id')] | None=..., persistent_chat: Annotated[bool, Field(description='Optional: Whether to use a persistent chat. If true, the chat will be saved and can be continued later. Default: False.', title='persistent_chat')] | None=...) -> Annotated[Union[ToolResponse, ToolError], Field(description='The response from the remote Agent Zero Instance', title='response')]` +- `async finish_chat(chat_id: Annotated[str, Field(description='ID of the chat to be finished. This value is returned in response to sending previous message.', title='chat_id')]) -> Annotated[Union[ToolResponse, ToolError], Field(description='The response from the remote Agent Zero Instance', title='response')]` +- `async _run_chat(context: AgentContext, message: str, attachments: list[str] | None=...)` +- `async mcp_middleware(request: Request, call_next)`: Middleware to check if MCP server is enabled. +- Notable constants/configuration names: `_PRINTER`, `SEND_MESSAGE_DESCRIPTION`, `FINISH_CHAT_DESCRIPTION`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `agent`, `asyncio`, `contextvars`, `fastmcp`, `fastmcp.server.http`, `helpers`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `openai`, `os`, `pydantic`, `starlette.exceptions`, `starlette.middleware`, `starlette.middleware.base`, `starlette.requests`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `PrintStyle`, `contextvars.ContextVar`, `FastMCP`, `mcp_server.tool`, `Field`, `settings.get_settings`, `initialize_agent`, `AgentContext`, `ToolError`, `ToolResponse`, `context.reset`, `AgentContext.remove`, `remove_chat`, `context.communicate`, `threading.RLock`, `self.reconfigure`, `StreamableHTTPSessionManager`, `mcp_server._get_additional_http_routes`, `create_base_app`, `PrintStyle.error`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_default_prompt_budget.py` + - `tests/test_fasta2a_client.py` + - `tests/test_ws_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/media_artifacts.py.dox.md b/helpers/media_artifacts.py.dox.md new file mode 100644 index 000000000..9f4d0c39f --- /dev/null +++ b/helpers/media_artifacts.py.dox.md @@ -0,0 +1,60 @@ +# media_artifacts.py DOX + +## Purpose + +- Own the `media_artifacts.py` helper module. +- This module validates, decodes, names, and normalizes media artifact payloads. +- Keep this file-level DOX profile synchronized with `media_artifacts.py` because this directory is intentionally flat. + +## Ownership + +- `media_artifacts.py` owns the runtime implementation. +- `media_artifacts.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `MediaArtifactError` (`ValueError`) +- `EmptyBase64Data` (`MediaArtifactError`) +- `InvalidBase64Data` (`MediaArtifactError`) +- `ArtifactTooLarge` (`MediaArtifactError`) +- `Base64Payload` (no explicit base class) +- `ImageDataUrl` (no explicit base class) +- `SavedArtifact` (no explicit base class) +- Top-level functions: +- `compact_base64(data: str) -> str` +- `estimated_base64_decoded_size(data: str) -> int` +- `decode_base64_payload(data: str, max_bytes: int | None=...) -> Base64Payload` +- `normalize_mime(mime_type: str, default: str=..., required_prefix: str=...) -> str` +- `guess_extension(mime_type: str, fallback: str=...) -> str` +- `filename_from_uri(uri: str) -> str` +- `safe_filename(value: str, default: str=..., default_extension: str=...) -> str` +- `image_data_url_from_base64(data: str, mime_type: str=..., max_bytes: int | None=...) -> ImageDataUrl` +- `save_base64_artifact(data: str, mime_type: str=..., directory_parts: tuple[str, ...], preferred_name: str=..., default_filename: str=..., max_bytes: int | None=...) -> SavedArtifact` +- Notable constants/configuration names: `DEFAULT_MAX_ARTIFACT_SIZE_BYTES`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, network calls. +- Imported dependency areas include: `__future__`, `base64`, `binascii`, `dataclasses`, `helpers`, `mimetypes`, `pathlib`, `urllib.parse`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `dataclass`, `join`, `compact_base64`, `Base64Payload`, `str.strip.lower`, `str.strip`, `urlparse`, `decode_base64_payload`, `normalize_mime`, `ImageDataUrl`, `guess_extension`, `safe_filename`, `Path`, `artifact_dir.mkdir`, `path.write_bytes`, `SavedArtifact`, `super.__init__`, `EmptyBase64Data`, `estimated_base64_decoded_size`, `base64.b64decode`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_mcp_handler_multimodal.py` + - `tests/test_media_artifacts.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/message_queue.py.dox.md b/helpers/message_queue.py.dox.md new file mode 100644 index 000000000..df300ed67 --- /dev/null +++ b/helpers/message_queue.py.dox.md @@ -0,0 +1,53 @@ +# message_queue.py DOX + +## Purpose + +- Own the `message_queue.py` helper module. +- This module stores and drains queued user messages for a context. +- Keep this file-level DOX profile synchronized with `message_queue.py` because this directory is intentionally flat. + +## Ownership + +- `message_queue.py` owns the runtime implementation. +- `message_queue.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `get_queue(context: 'AgentContext') -> list`: Get current queue from context.data. +- `_get_next_seq(context: 'AgentContext') -> int`: Get next sequence number. +- `_sync_output(context: 'AgentContext')`: Sync queue to output_data for frontend polling. +- `add(context: 'AgentContext', text: str, attachments: list[str] | None=..., item_id: str | None=...) -> dict`: Add message to queue. Attachments should be filenames, will be converted to full paths. +- `remove(context: 'AgentContext', item_id: str | None=...) -> int`: Remove item(s). If item_id is None, clears all. Returns remaining count. +- `pop_first(context: 'AgentContext') -> dict | None`: Remove and return first item. +- `pop_item(context: 'AgentContext', item_id: str) -> dict | None`: Remove and return specific item. +- `has_queue(context: 'AgentContext') -> bool`: Check if queue has items. +- `log_user_message(context: 'AgentContext', message: str, attachment_paths: list[str], message_id: str | None=..., source: str=...)`: Log user message to console and UI. Used by message API and queue processing. +- `send_message(context: 'AgentContext', item: dict, source: str=...)`: Send a single queued message (log + communicate). +- `send_next(context: 'AgentContext') -> bool`: Send next queued message. Returns True if sent, False if queue empty. +- `send_all_aggregated(context: 'AgentContext') -> int`: Aggregate and send all queued messages as one. Returns count of items sent. +- Notable constants/configuration names: `QUEUE_KEY`, `QUEUE_SEQ_KEY`, `UPLOAD_FOLDER`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem deletion, settings/state persistence. +- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `typing`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `context.set_data`, `get_queue`, `context.set_output_data`, `_sync_output`, `queue.pop`, `context.log.log`, `log_user_message`, `context.communicate`, `pop_first`, `has_queue`, `join`, `context.get_data`, `att.startswith`, `_get_next_seq`, `uuid.uuid4`, `UserMessage`, `send_message`, `guids.generate_id`, `os.path.basename`, `PrintStyle`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/messages.py.dox.md b/helpers/messages.py.dox.md new file mode 100644 index 000000000..e61772114 --- /dev/null +++ b/helpers/messages.py.dox.md @@ -0,0 +1,50 @@ +# messages.py DOX + +## Purpose + +- Own the `messages.py` helper module. +- This module truncates message payloads for display and storage safety. +- Keep this file-level DOX profile synchronized with `messages.py` because this directory is intentionally flat. + +## Ownership + +- `messages.py` owns the runtime implementation. +- `messages.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `truncate_text(agent, output, threshold=...)` +- `truncate_dict_by_ratio(agent, data: dict | list | str, threshold_chars: int, truncate_to: int)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence. +- Imported dependency areas include: `json`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `agent.read_prompt`, `process_item`, `json.dumps`, `truncate_text`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/email_parser_test.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_chat_compaction.py` + - `tests/test_document_query_fallback.py` + - `tests/test_download_toast_regressions.py` + - `tests/test_fasta2a_client.py` + - `tests/test_mcp_handler_multimodal.py` + - `tests/test_oauth_codex.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/microsoft_tunnel.py.dox.md b/helpers/microsoft_tunnel.py.dox.md new file mode 100644 index 000000000..32ee7027c --- /dev/null +++ b/helpers/microsoft_tunnel.py.dox.md @@ -0,0 +1,50 @@ +# microsoft_tunnel.py DOX + +## Purpose + +- Own the `microsoft_tunnel.py` helper module. +- This module implements Microsoft Dev Tunnel provider behavior. +- Keep this file-level DOX profile synchronized with `microsoft_tunnel.py` because this directory is intentionally flat. + +## Ownership + +- `microsoft_tunnel.py` owns the runtime implementation. +- `microsoft_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `AgentZeroMicrosoftTunnel` (`MicrosoftTunnel`) + - `notify(self, event, message, data=...)` + - `agent_zero_notifications(self)` +- `MicrosoftDevTunnel` (`FlaredanticTunnelHelper`) + - `build_tunnel(self)` + - `start(self)` +- Top-level functions: +- `default_microsoft_tunnel_id()` +- Notable constants/configuration names: `MICROSOFT_TUNNEL_ID_ENV_KEYS`, `MICROSOFT_TUNNEL_TIMEOUT`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, network calls, settings/state persistence, tunnel state. +- Imported dependency areas include: `flaredantic`, `getpass`, `hashlib`, `helpers`, `helpers.tunnel_common`, `os`, `socket`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `join`, `strip`, `hashlib.sha256.hexdigest`, `self.notify`, `callable`, `self._notify_progress`, `self._run_cmd`, `MicrosoftConfig`, `AgentZeroMicrosoftTunnel`, `getpass.getuser`, `socket.gethostname`, `files.get_abs_path`, `super.notify`, `parent`, `super.start`, `hashlib.sha256`, `MicrosoftTunnelError`, `default_microsoft_tunnel_id`, `RuntimeError`, `seed.encode`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/migration.py.dox.md b/helpers/migration.py.dox.md new file mode 100644 index 000000000..c548951ab --- /dev/null +++ b/helpers/migration.py.dox.md @@ -0,0 +1,52 @@ +# migration.py DOX + +## Purpose + +- Own the `migration.py` helper module. +- This module migrates legacy user data and runtime layout at startup. +- Keep this file-level DOX profile synchronized with `migration.py` because this directory is intentionally flat. + +## Ownership + +- `migration.py` owns the runtime implementation. +- `migration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `startup_migration() -> None` +- `migrate_user_data() -> None`: Migrate user data from /tmp and other locations to /usr. +- `convert_agents_json_yaml() -> None` +- `_move_dir(src: str, dst: str, overwrite: bool=...) -> None`: Move a directory from src to dst if src exists and dst does not. +- `_move_file(src: str, dst: str, overwrite: bool=...) -> None`: Move a file from src to dst if src exists and dst does not. +- `_migrate_memory(base_path: str=...) -> None`: Migrate memory subdirectories. +- `_merge_dir_contents(src_parent: str, dst_parent: str) -> None`: Moves all items from src_parent to dst_parent. +- `_cleanup_obsolete() -> None`: Remove directories that are no longer needed. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `helpers`, `helpers.print_style`, `json`, `os`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `migrate_user_data`, `convert_agents_json_yaml`, `extension.call_extensions_sync`, `_move_dir`, `_move_file`, `_migrate_memory`, `_merge_dir_contents`, `_cleanup_obsolete`, `subagents.get_agents_roots`, `files.get_subdirectories`, `files.list_files`, `files.deabsolute_path`, `files.exists`, `files.move_dir`, `files.move_file`, `files.get_abs_path`, `os.path.isdir`, `os.path.join`, `files.delete_dir`, `os.path.isfile`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_office_canvas_setup.py` + - `tests/test_office_document_store.py` + - `tests/test_speech_plugin_split.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/modules.py.dox.md b/helpers/modules.py.dox.md new file mode 100644 index 000000000..9f42143ed --- /dev/null +++ b/helpers/modules.py.dox.md @@ -0,0 +1,53 @@ +# modules.py DOX + +## Purpose + +- Own the `modules.py` helper module. +- This module imports modules and classes dynamically with namespace cache control. +- Keep this file-level DOX profile synchronized with `modules.py` because this directory is intentionally flat. + +## Ownership + +- `modules.py` owns the runtime implementation. +- `modules.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `import_module(file_path: str) -> ModuleType` +- `load_classes_from_folder(folder: str, name_pattern: str, base_class: Type[T], one_per_file: bool=...) -> list[Type[T]]` +- `load_classes_from_file(file: str, base_class: type[T], one_per_file: bool=...) -> list[type[T]]` +- `purge_namespace(namespace: str)` +- Notable constants/configuration names: `T`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem deletion. +- Imported dependency areas include: `fnmatch`, `helpers.files`, `importlib`, `importlib.util`, `inspect`, `os`, `re`, `sys`, `types`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `TypeVar`, `get_abs_path`, `os.path.basename.replace`, `importlib.util.spec_from_file_location`, `importlib.util.module_from_spec`, `spec.loader.exec_module`, `import_module`, `inspect.getmembers`, `to_delete.sort`, `importlib.invalidate_caches`, `ImportError`, `os.path.join`, `os.path.basename`, `issubclass`, `os.listdir`, `name.startswith`, `n.count`, `fnmatch`, `file_name.endswith`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_docker_release_plan.py` + - `tests/test_error_retry_plugin.py` + - `tests/test_file_tree_visualize.py` + - `tests/test_git_version_label.py` + - `tests/test_mcp_handler_multimodal.py` + - `tests/test_memory_quality.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/network.py.dox.md b/helpers/network.py.dox.md new file mode 100644 index 000000000..792836311 --- /dev/null +++ b/helpers/network.py.dox.md @@ -0,0 +1,55 @@ +# network.py DOX + +## Purpose + +- Own the `network.py` helper module. +- This module validates public URLs and fetches remote resources safely. +- Keep this file-level DOX profile synchronized with `network.py` because this directory is intentionally flat. + +## Ownership + +- `network.py` owns the runtime implementation. +- `network.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `HttpFetchResult` (no explicit base class) +- `UnsafeUrlError` (`ValueError`) +- Top-level functions: +- `_build_request_headers() -> dict[str, str]` +- `_normalize_content_type(content_type: str | None) -> str | None` +- `resolve_host_ips(hostname: str) -> tuple[ipaddress._BaseAddress, ...]` +- `validate_public_http_url(url: str) -> tuple[ipaddress._BaseAddress, ...]` +- `fetch_public_http_resource(url: str, max_bytes: int, max_redirects: int=..., timeout: tuple[float, float]=...) -> HttpFetchResult` +- `is_loopback_address(address: str) -> bool`: Check whether *address* resolves to a loopback interface. +- Notable constants/configuration names: `SAFE_HTTP_SCHEMES`, `DEFAULT_FETCH_TIMEOUT`, `DEFAULT_HTTP_USER_AGENT`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: network calls, secret handling. +- Imported dependency areas include: `__future__`, `dataclasses`, `ipaddress`, `os`, `requests`, `socket`, `struct`, `urllib.parse`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `frozenset`, `dataclass`, `strip`, `urlparse`, `parsed.hostname.rstrip.lower`, `resolve_host_ips`, `requests.Session`, `ValueError`, `content_type.split.strip.lower`, `socket.getaddrinfo`, `ipaddress.ip_address`, `seen.add`, `UnsafeUrlError`, `hostname.endswith`, `validate_public_http_url`, `socket.inet_pton`, `_checkers`, `parsed.hostname.rstrip`, `os.getenv`, `content_type.split.strip`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_oauth_gemini_api.py` + - `tests/test_oauth_github_copilot.py` + - `tests/test_oauth_xai_grok.py` + - `tests/test_plugin_scan_prompt.py` + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/notification.py.dox.md b/helpers/notification.py.dox.md new file mode 100644 index 000000000..d8f198f4a --- /dev/null +++ b/helpers/notification.py.dox.md @@ -0,0 +1,62 @@ +# notification.py DOX + +## Purpose + +- Own the `notification.py` helper module. +- This module owns notification data models and notification manager state. +- Keep this file-level DOX profile synchronized with `notification.py` because this directory is intentionally flat. + +## Ownership + +- `notification.py` owns the runtime implementation. +- `notification.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `NotificationType` (`Enum`) +- `NotificationPriority` (`Enum`) +- `NotificationItem` (no explicit base class) + - `mark_read(self)` + - `output(self)` +- `NotificationManager` (no explicit base class) + - `send_notification(type: NotificationType, priority: NotificationPriority, message: str, title: str=..., detail: str=..., display_time: int=..., group: str=..., id: str=...) -> NotificationItem` + - `add_notification(self, type: NotificationType, priority: NotificationPriority, message: str, title: str=..., detail: str=..., display_time: int=..., group: str=..., id: str=...) -> NotificationItem` + - `get_recent_notifications(self, seconds: int=...) -> list[NotificationItem]` + - `output(self, start: int | None=..., end: int | None=...) -> list[dict]` + - `output_all(self) -> list[dict]` + - `mark_read_by_ids(self, notification_ids: list[str]) -> int` + - `update_item(self, no: int, **kwargs) -> None` + - `mark_all_read(self)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem deletion, settings/state persistence. +- Imported dependency areas include: `dataclasses`, `datetime`, `enum`, `helpers.localization`, `threading`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.manager.update_item`, `threading.RLock`, `AgentContext.get_notification_manager.add_notification`, `mark_dirty_all`, `self._update_item`, `NotificationType`, `Localization.get.serialize_datetime`, `uuid.uuid4`, `Localization.get.now`, `timedelta`, `n.output`, `AgentContext.get_notification_manager`, `next`, `NotificationPriority`, `NotificationItem`, `self._enforce_limit`, `seen.add`, `notifications.output`, `nid.strip`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_download_toast_regressions.py` + - `tests/test_multi_tab_isolation.py` + - `tests/test_self_update_tag_filter.py` + - `tests/test_snapshot_parity.py` + - `tests/test_snapshot_schema_v1.py` + - `tests/test_state_monitor.py` + - `tests/test_state_sync_handler.py` + - `tests/test_state_sync_welcome_screen.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/performance.py.dox.md b/helpers/performance.py.dox.md new file mode 100644 index 000000000..36181986d --- /dev/null +++ b/helpers/performance.py.dox.md @@ -0,0 +1,42 @@ +# performance.py DOX + +## Purpose + +- Own the `performance.py` helper module. +- This module provides lightweight performance tracing helpers. +- Keep this file-level DOX profile synchronized with `performance.py` because this directory is intentionally flat. + +## Ownership + +- `performance.py` owns the runtime implementation. +- `performance.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `trace_performance(show_all=..., color=..., unicode=...)`: Decorator that profiles a function and prints a call tree when it finishes. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `functools`, `inspect`, `pyinstrument`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `inspect.iscoroutinefunction`, `functools.wraps`, `Profiler`, `profiler.start`, `profiler.stop`, `func`, `profiler.output_text`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_extensions_stress.py` + - `tests/test_ws_manager.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/perplexity_search.py.dox.md b/helpers/perplexity_search.py.dox.md new file mode 100644 index 000000000..1144ec0e9 --- /dev/null +++ b/helpers/perplexity_search.py.dox.md @@ -0,0 +1,41 @@ +# perplexity_search.py DOX + +## Purpose + +- Own the `perplexity_search.py` helper module. +- This module queries Perplexity search using configured model/provider credentials. +- Keep this file-level DOX profile synchronized with `perplexity_search.py` because this directory is intentionally flat. + +## Ownership + +- `perplexity_search.py` owns the runtime implementation. +- `perplexity_search.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `perplexity_search(query: str, model_name=..., api_key=..., base_url=...)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: secret handling. +- Imported dependency areas include: `models`, `openai`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `OpenAI`, `client.chat.completions.create`, `models.get_api_key`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/persist_chat.py.dox.md b/helpers/persist_chat.py.dox.md new file mode 100644 index 000000000..bf251b8e7 --- /dev/null +++ b/helpers/persist_chat.py.dox.md @@ -0,0 +1,65 @@ +# persist_chat.py DOX + +## Purpose + +- Own the `persist_chat.py` helper module. +- This module persists and reloads chat contexts and message artifacts. +- Keep this file-level DOX profile synchronized with `persist_chat.py` because this directory is intentionally flat. + +## Ownership + +- `persist_chat.py` owns the runtime implementation. +- `persist_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `_fallback_datetime_iso() -> str` +- `_parse_persisted_datetime(value: str | None) -> datetime` +- `get_chat_folder_path(ctxid: str)`: Get the folder path for any context (chat or task). +- `get_chat_msg_files_folder(ctxid: str)` +- `save_tmp_chat(context: AgentContext)`: Save context to the chats folder +- `save_tmp_chats()`: Save all contexts to the chats folder +- `load_tmp_chats()`: Load all contexts from the chats folder +- `_get_chat_file_path(ctxid: str)` +- `_convert_v080_chats()` +- `load_json_chats(jsons: list[str])`: Load contexts from JSON strings +- `export_json_chat(context: AgentContext)`: Export context as JSON string +- `remove_chat(ctxid)`: Remove a chat or task context +- `remove_msg_files(ctxid)`: Remove all message files for a chat or task context +- `_serialize_context(context: AgentContext)` +- `_serialize_agent(agent: Agent)` +- `_serialize_log(log: Log)` +- `_deserialize_context(data)` +- `_deserialize_agents(agents: list[dict[str, Any]], config: AgentConfig, context: AgentContext) -> Agent` +- `_deserialize_log(data: dict[str, Any]) -> 'Log'` +- `_safe_json_serialize(obj, **kwargs)` +- Notable constants/configuration names: `CHATS_FOLDER`, `LOG_SIZE`, `CHAT_FILE_NAME`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, scheduler state. +- Imported dependency areas include: `agent`, `collections`, `datetime`, `helpers`, `helpers.localization`, `helpers.log`, `initialize`, `json`, `typing`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `datetime.fromtimestamp.isoformat`, `datetime.fromisoformat`, `files.get_abs_path`, `_get_chat_file_path`, `files.make_dirs`, `_serialize_context`, `_safe_json_serialize`, `files.write_file`, `_convert_v080_chats`, `files.list_files`, `get_chat_folder_path`, `files.delete_dir`, `get_chat_msg_files_folder`, `agent.history.serialize`, `initialize_agent`, `_deserialize_log`, `AgentContext`, `_deserialize_agents`, `Log`, `log.set_initial_progress`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_api_chat_lifetime.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_persist_chat_log_ids.py` + - `tests/test_tool_action_contracts.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/plugins.py.dox.md b/helpers/plugins.py.dox.md new file mode 100644 index 000000000..4447d8850 --- /dev/null +++ b/helpers/plugins.py.dox.md @@ -0,0 +1,81 @@ +# plugins.py DOX + +## Purpose + +- Own the `plugins.py` helper module. +- This module discovers plugins, resolves plugin config/toggles, runs hooks, and tracks plugin updates. +- Keep this file-level DOX profile synchronized with `plugins.py` because this directory is intentionally flat. + +## Ownership + +- `plugins.py` owns the runtime implementation. +- `plugins.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `PluginAssetFile` (`TypedDict`) +- `PluginMetadata` (`BaseModel`) +- `PluginListItem` (`BaseModel`) +- `PluginUpdateInfo` (`BaseModel`) +- Top-level functions: +- `register_watchdogs()` +- `after_plugin_change(plugin_names: list[str] | None=..., python_change: bool=...)` +- `refresh_plugin_modules(plugin_names: list[str] | None=...)` +- `clear_plugin_cache(plugin_names: list[str] | None=...)` +- `get_plugin_roots(plugin_name: str=...) -> List[str]`: Plugin root directories, ordered by priority (user first). +- `get_plugins_list()` +- `get_enhanced_plugins_list(custom: bool=..., builtin: bool=..., plugin_names: list[str] | None=...) -> List[PluginListItem]`: Discover plugins by directory convention. First root wins on ID conflict. +- `get_custom_plugins_updates(plugin_names: list[str] | None=...) -> List[PluginUpdateInfo]` +- `get_plugin_meta(plugin_name: str)` +- `find_plugin_dir(plugin_name: str)` +- `uninstall_plugin(plugin_name)` +- `delete_plugin(plugin_name: str)` +- `get_plugin_paths(*subpaths) -> List[str]` +- `get_enabled_plugin_paths(agent: Agent | None, *subpaths) -> List[str]` +- `get_enabled_plugins(agent: Agent | None)` +- `determined_toggle_from_paths(default: bool, paths: Iterator[str])` +- `get_toggle_state(plugin_name: str) -> ToggleState` +- `toggle_plugin(plugin_name: str, enabled: bool, project_name: str=..., agent_profile: str=..., clear_overrides: bool=...)` +- `get_plugin_config(plugin_name: str, agent: Agent | None=..., project_name: str | None=..., agent_profile: str | None=...)` +- `get_default_plugin_config(plugin_name: str)` +- `save_plugin_config(plugin_name: str, project_name: str, agent_profile: str, settings: dict)` +- `find_plugin_asset(plugin_name: str, *subpaths, project_name=..., agent_profile=...)` +- `find_plugin_assets(*subpaths, plugin_name: str=..., project_name: str=..., agent_profile: str=..., only_first: bool=...) -> list[PluginAssetFile]` +- `determine_plugin_asset_path(plugin_name: str, project_name: str, agent_profile: str, *subpaths)` +- `send_frontend_reload_notification(plugin_names: list[str] | None=...)`: If the plugin changed has webui extensions, notify frontend to reload the page +- `call_plugin_hook(plugin_name: str, hook_name: str, default: Any=..., *args, **kwargs)` +- `_apply_defaults_from_env(plugin_name: str, config: dict[str, Any])` +- Notable constants/configuration names: `_META_TARGET_RE`, `META_FILE_NAME`, `CONFIG_FILE_NAME`, `CONFIG_DEFAULT_FILE_NAME`, `DISABLED_FILE_NAME`, `ENABLED_FILE_NAME`, `TOGGLE_FILE_PATTERN`, `HOOKS_SCRIPT`, `HOOKS_CACHE_AREA`, `PLUGINS_LIST_CACHE_AREA`, `ENABLED_PLUGINS_LIST_CACHE_AREA`, `ENABLED_PLUGINS_PATHS_CACHE_AREA`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `__future__`, `asyncio`, `glob`, `helpers`, `helpers.defer`, `helpers.watchdog`, `json`, `pathlib`, `pydantic`, `re`, `regex`, `time`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `re.compile`, `Field`, `watchdog.add_watchdog`, `clear_plugin_cache`, `send_frontend_reload_notification`, `DeferredTask.start_task`, `get_plugin_roots`, `result.sort`, `cache.add`, `get_enhanced_plugins_list`, `find_plugin_dir`, `files.get_abs_path`, `files.exists`, `call_plugin_hook`, `delete_plugin`, `files.delete_dir`, `after_plugin_change`, `get_enabled_plugins`, `get_plugins_list`, `get_plugin_meta`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_computer_use_metadata.py` + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_chat_compaction.py` + - `tests/test_default_prompt_budget.py` + - `tests/test_document_query_plugin.py` + - `tests/test_error_retry_plugin.py` + - `tests/test_host_browser_connector.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/print_catch.py.dox.md b/helpers/print_catch.py.dox.md new file mode 100644 index 000000000..16c630d70 --- /dev/null +++ b/helpers/print_catch.py.dox.md @@ -0,0 +1,40 @@ +# print_catch.py DOX + +## Purpose + +- Own the `print_catch.py` helper module. +- This module captures printed output from async callables. +- Keep this file-level DOX profile synchronized with `print_catch.py` because this directory is intentionally flat. + +## Ownership + +- `print_catch.py` owns the runtime implementation. +- `print_catch.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `capture_prints_async(func: Callable[..., Awaitable[Any]], *args, **kwargs) -> Tuple[Awaitable[Any], Callable[[], str]]` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `asyncio`, `io`, `sys`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `io.StringIO`, `captured_output.getvalue`, `wrapped_func`, `func`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/print_style.py.dox.md b/helpers/print_style.py.dox.md new file mode 100644 index 000000000..193a9bb26 --- /dev/null +++ b/helpers/print_style.py.dox.md @@ -0,0 +1,54 @@ +# print_style.py DOX + +## Purpose + +- Own the `print_style.py` helper module. +- This module formats console/debug output consistently. +- Keep this file-level DOX profile synchronized with `print_style.py` because this directory is intentionally flat. + +## Ownership + +- `print_style.py` owns the runtime implementation. +- `print_style.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `PrintStyle` (no explicit base class) + - `get(self, *args, sep=..., **kwargs)` + - `print(self, *args, sep=..., end=..., flush=...)` + - `stream(self, *args, sep=..., flush=...)` + - `is_last_line_empty(self)` + - `standard(*args, sep=..., end=..., flush=...)` + - `hint(*args, sep=..., end=..., flush=...)` + - `info(*args, sep=..., end=..., flush=...)` + - `success(*args, sep=..., end=..., flush=...)` +- Top-level functions: +- `_get_runtime()` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, WebSocket state, secret handling. +- Imported dependency areas include: `atexit`, `collections.abc`, `datetime`, `html`, `os`, `strings`, `sys`, `webcolors`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `atexit.register`, `self._get_rgb_color_code`, `join`, `html.escape.replace`, `sep.join`, `self._format_args`, `sanitize_string`, `self._add_padding_if_needed`, `end.endswith`, `self._log_html`, `sys.stdin.readlines`, `PrintStyle._prefixed_args`, `files.get_abs_path`, `os.makedirs`, `datetime.now.strftime`, `os.path.join`, `f.write`, `self.secrets_mgr.mask_values`, `self._get_styled_text`, `self._get_html_styled_text`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_print_style.py` + - `tests/test_tool_action_contracts.py` + - `tests/test_ws_manager.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/process.py.dox.md b/helpers/process.py.dox.md new file mode 100644 index 000000000..217a7b3aa --- /dev/null +++ b/helpers/process.py.dox.md @@ -0,0 +1,54 @@ +# process.py DOX + +## Purpose + +- Own the `process.py` helper module. +- This module manages process reload, restart, exit, and server references. +- Keep this file-level DOX profile synchronized with `process.py` because this directory is intentionally flat. + +## Ownership + +- `process.py` owns the runtime implementation. +- `process.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `set_server(server)` +- `get_server(server)` +- `stop_server()` +- `reload()` +- `restart_process()` +- `exit_process()` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: subprocess/runtime control. +- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `sys`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `stop_server`, `runtime.is_dockerized`, `PrintStyle.standard`, `os.execv`, `sys.exit`, `_server.shutdown`, `exit_process`, `restart_process`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_api_chat_lifetime.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_docker_release_plan.py` + - `tests/test_document_query_plugin.py` + - `tests/test_download_toast_regressions.py` + - `tests/test_git_version_label.py` + - `tests/test_image_get_security.py` + - `tests/test_model_config_project_presets.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/projects.py.dox.md b/helpers/projects.py.dox.md new file mode 100644 index 000000000..08b674859 --- /dev/null +++ b/helpers/projects.py.dox.md @@ -0,0 +1,85 @@ +# projects.py DOX + +## Purpose + +- Own the `projects.py` helper module. +- This module owns project metadata, workspace creation, Git status, and project-scoped settings. +- Keep this file-level DOX profile synchronized with `projects.py` because this directory is intentionally flat. + +## Ownership + +- `projects.py` owns the runtime implementation. +- `projects.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `FileStructureInjectionSettings` (`TypedDict`) +- `SubAgentSettings` (`TypedDict`) +- `BasicProjectData` (`TypedDict`) +- `GitStatusData` (`TypedDict`) +- `EditProjectData` (`BasicProjectData`) +- Top-level functions: +- `get_projects_parent_folder()` +- `get_project_folder(name: str)` +- `get_project_meta(name: str, *sub_dirs)` +- `delete_project(name: str)` +- `create_project(name: str, data: BasicProjectData)` +- `clone_git_project(name: str, git_url: str, git_token: str, data: BasicProjectData)`: Clone a git repository as a new A0 project. Token is used only for cloning via http header. +- `load_project_header(name: str)` +- `_default_file_structure_settings()` +- `_normalizeBasicData(data: BasicProjectData) -> BasicProjectData` +- `_normalizeEditData(data: EditProjectData) -> EditProjectData` +- `_edit_data_to_basic_data(data: EditProjectData)` +- `_basic_data_to_edit_data(data: BasicProjectData) -> EditProjectData` +- `update_project(name: str, data: EditProjectData)` +- `load_basic_project_data(name: str) -> BasicProjectData` +- `load_edit_project_data(name: str) -> EditProjectData` +- `save_project_header(name: str, data: BasicProjectData)` +- `load_project_llm_data(name: str) -> dict` +- `save_project_llm_settings(name: str, llm_data: object)` +- `get_active_projects_list()` +- `_get_projects_list(parent_dir)` +- `activate_project(context_id: str, name: str, mark_dirty: bool=...)` +- `deactivate_project(context_id: str, mark_dirty: bool=...)` +- `reactivate_project_in_chats(name: str)` +- `deactivate_project_in_chats(name: str)` +- `build_system_prompt_vars(name: str)` +- `get_additional_instructions_files(name: str)` +- `get_project_instruction_files(name: str, include_agents_md: bool=...) -> list[tuple[str, str]]` +- `get_project_agents_md_instruction_file(name: str) -> tuple[str, str] | None` +- `_format_project_instruction_files(instruction_files: list[tuple[str, str]]) -> str` +- `_normalize_include_agents_md(value: object) -> bool` +- Notable constants/configuration names: `PROJECTS_PARENT_DIR`, `PROJECT_META_DIR`, `PROJECT_INSTRUCTIONS_DIR`, `PROJECT_KNOWLEDGE_DIR`, `PROJECT_HEADER_FILE`, `PROJECT_AGENTS_MD_FILES`, `CONTEXT_DATA_KEY_PROJECT`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `files.get_abs_path`, `files.delete_dir`, `deactivate_project_in_chats`, `files.create_dir_safe`, `create_project_meta_folders`, `_normalizeBasicData`, `save_project_header`, `save_project_llm_settings`, `files.basename`, `dirty_json.parse`, `FileStructureInjectionSettings`, `cast`, `_normalizeEditData`, `load_edit_project_data`, `_edit_data_to_basic_data`, `save_project_variables`, `save_project_secrets`, `save_project_subagents`, `reactivate_project_in_chats`, `load_basic_project_data`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_model_config_project_presets.py` + - `tests/test_office_document_store.py` + - `tests/test_plugin_activation_ui.py` + - `tests/test_projects.py` + - `tests/test_skills_runtime.py` + - `tests/test_task_scheduler_timezone.py` + - `tests/test_time_travel.py` + - `tests/test_tool_action_contracts.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/providers.py.dox.md b/helpers/providers.py.dox.md new file mode 100644 index 000000000..083ccecfc --- /dev/null +++ b/helpers/providers.py.dox.md @@ -0,0 +1,61 @@ +# providers.py DOX + +## Purpose + +- Own the `providers.py` helper module. +- This module loads model provider configuration and provider metadata. +- Keep this file-level DOX profile synchronized with `providers.py` because this directory is intentionally flat. + +## Ownership + +- `providers.py` owns the runtime implementation. +- `providers.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `FieldOption` (`TypedDict`) +- `ProviderManager` (no explicit base class) + - `get_instance(cls)` + - `reload(cls)` + - `get_providers(self, provider_type: ModelType) -> List[FieldOption]` + - `get_raw_providers(self, provider_type: ModelType) -> List[Dict[str, str]]` + - `get_provider_config(self, provider_type: ModelType, provider_id: str) -> Optional[Dict[str, str]]` +- Top-level functions: +- `get_providers(provider_type: ModelType) -> List[FieldOption]`: Convenience function to get providers of a specific type. +- `get_raw_providers(provider_type: ModelType) -> List[Dict[str, str]]`: Return full metadata for providers of a given type. +- `get_provider_config(provider_type: ModelType, provider_id: str) -> Optional[Dict[str, str]]`: Return metadata for a single provider (None if not found). +- `reload_providers()`: Re-merge base + plugin provider configs. Call after plugin changes. +- Notable constants/configuration names: `PROVIDER_MANAGER_CACHE_AREA`, `PROVIDER_MANAGER_CACHE_KEY`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem deletion, plugin state, settings/state persistence. +- Imported dependency areas include: `helpers`, `typing`, `yaml`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `ProviderManager.get_instance.get_providers`, `ProviderManager.get_instance.get_raw_providers`, `ProviderManager.get_instance.get_provider_config`, `ProviderManager.reload`, `cache.remove`, `cls.get_instance`, `inst._load_providers`, `files.get_abs_path`, `self._normalise_yaml`, `get_enabled_plugin_paths`, `provider_id.lower`, `self.get_raw_providers`, `cls`, `cache.add`, `self._load_providers`, `self._load_yaml`, `items.sort`, `ProviderManager.get_instance`, `lower`, `yaml.safe_load`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_fastmcp_openapi_security.py` + - `tests/test_model_config_api_keys.py` + - `tests/test_oauth_codex.py` + - `tests/test_oauth_gemini_api.py` + - `tests/test_oauth_github_copilot.py` + - `tests/test_oauth_providers.py` + - `tests/test_oauth_xai_grok.py` + - `tests/test_onboarding_static.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/rate_limiter.py.dox.md b/helpers/rate_limiter.py.dox.md new file mode 100644 index 000000000..22572ec2b --- /dev/null +++ b/helpers/rate_limiter.py.dox.md @@ -0,0 +1,45 @@ +# rate_limiter.py DOX + +## Purpose + +- Own the `rate_limiter.py` helper module. +- This module provides simple rate-limiting primitives. +- Keep this file-level DOX profile synchronized with `rate_limiter.py` because this directory is intentionally flat. + +## Ownership + +- `rate_limiter.py` owns the runtime implementation. +- `rate_limiter.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `RateLimiter` (no explicit base class) + - `add(self, **kwargs)` + - `async cleanup(self)` + - `async get_total(self, key: str) -> int` + - `async wait(self, callback: Callable[[str, str, int, int], Awaitable[bool]] | None=...)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `asyncio`, `time`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `asyncio.Lock`, `time.time`, `self.cleanup`, `asyncio.sleep`, `self.get_total`, `callback`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_stream_tool_early_stop.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/rfc.py.dox.md b/helpers/rfc.py.dox.md new file mode 100644 index 000000000..dbe29b918 --- /dev/null +++ b/helpers/rfc.py.dox.md @@ -0,0 +1,48 @@ +# rfc.py DOX + +## Purpose + +- Own the `rfc.py` helper module. +- This module implements remote function call dispatch and serialization. +- Keep this file-level DOX profile synchronized with `rfc.py` because this directory is intentionally flat. + +## Ownership + +- `rfc.py` owns the runtime implementation. +- `rfc.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `RFCInput` (`TypedDict`) +- `RFCCall` (`TypedDict`) +- Top-level functions: +- `async call_rfc(url: str, password: str, module: str, function_name: str, args: list, kwargs: dict)` +- `async handle_rfc(rfc_call: RFCCall, password: str)` +- `async _call_function(module: str, function_name: str, *args, **kwargs)` +- `_get_function(module: str, function_name: str)` +- `async _send_json_data(url: str, data)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, network calls, settings/state persistence, secret handling. +- Imported dependency areas include: `aiohttp`, `helpers`, `importlib`, `inspect`, `json`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `RFCInput`, `RFCCall`, `json.loads`, `_get_function`, `inspect.iscoroutinefunction`, `importlib.import_module`, `_send_json_data`, `crypto.verify_data`, `Exception`, `_call_function`, `func`, `aiohttp.ClientSession`, `json.dumps`, `crypto.hash_data`, `session.post`, `response.json`, `response.text`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/rfc_exchange.py.dox.md b/helpers/rfc_exchange.py.dox.md new file mode 100644 index 000000000..c960dabd9 --- /dev/null +++ b/helpers/rfc_exchange.py.dox.md @@ -0,0 +1,42 @@ +# rfc_exchange.py DOX + +## Purpose + +- Own the `rfc_exchange.py` helper module. +- This module handles privileged RFC exchange data such as root password provisioning. +- Keep this file-level DOX profile synchronized with `rfc_exchange.py` because this directory is intentionally flat. + +## Ownership + +- `rfc_exchange.py` owns the runtime implementation. +- `rfc_exchange.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `async get_root_password()` +- `_provide_root_password(public_key_pem: str)` +- `_get_root_password()` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `helpers`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `runtime.is_dockerized`, `_get_root_password`, `crypto.encrypt_data`, `crypto._generate_private_key`, `crypto._generate_public_key`, `crypto.decrypt_data`, `dotenv.get_dotenv_value`, `runtime.call_development_function`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/rfc_files.py.dox.md b/helpers/rfc_files.py.dox.md new file mode 100644 index 000000000..d05d75828 --- /dev/null +++ b/helpers/rfc_files.py.dox.md @@ -0,0 +1,70 @@ +# rfc_files.py DOX + +## Purpose + +- Own the `rfc_files.py` helper module. +- This module exposes RFC-safe filesystem operations. +- Keep this file-level DOX profile synchronized with `rfc_files.py` because this directory is intentionally flat. + +## Ownership + +- `rfc_files.py` owns the runtime implementation. +- `rfc_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `get_abs_path(*relative_paths)`: Convert relative paths to absolute paths based on the base directory. +- `read_file_bin(relative_path: str, backup_dirs=...) -> bytes`: Read binary file content. +- `read_file_base64(relative_path: str, backup_dirs=...) -> str`: Read file content and return as base64 string. +- `write_file_binary(relative_path: str, content: bytes) -> bool`: Write binary content to a file. +- `write_file_base64(relative_path: str, content: str) -> bool`: Write base64 content to a file. +- `delete_file(relative_path: str) -> bool`: Delete a file. +- `delete_directory(relative_path: str) -> bool`: Delete a directory recursively. +- `list_directory(relative_path: str, include_hidden: bool=...) -> list`: List directory contents. +- `make_directories(relative_path: str) -> bool`: Create directories recursively. +- `path_exists(relative_path: str) -> bool`: Check if a path exists. +- `file_exists(relative_path: str) -> bool`: Check if a file exists. +- `folder_exists(relative_path: str) -> bool`: Check if a folder exists. +- `get_subdirectories(relative_path: str, include: str | list[str]=..., exclude: str | list[str] | None=...) -> list[str]`: Get subdirectories in a directory. +- `zip_directory(relative_path: str) -> str`: Create a zip archive of a directory. +- `move_file(source_path: str, destination_path: str) -> bool`: Move a file from source to destination. +- `read_directory_as_zip(relative_path: str) -> bytes`: Read entire directory contents as a zip file. +- `find_file_in_dirs(file_path: str, backup_dirs: list[str]) -> str`: Find a file in the main directory or backup directories. +- `_read_file_binary_impl(file_path: str) -> str`: Implementation function to read a file in binary mode. +- `_write_file_binary_impl(file_path: str, b64_content: str) -> bool`: Implementation function to write binary content to a file. +- `_delete_file_impl(file_path: str) -> bool`: Implementation function to delete a file. +- `_delete_folder_impl(folder_path: str) -> bool`: Implementation function to delete a folder recursively. +- `_list_folder_impl(folder_path: str, include_hidden: bool=...) -> list`: Implementation function to list folder contents. +- `_make_dirs_impl(folder_path: str) -> bool`: Implementation function to create directories. +- `_path_exists_impl(file_path: str) -> bool`: Implementation function to check if path exists. +- `_file_exists_impl(file_path: str) -> bool`: Implementation function to check if file exists. +- `_folder_exists_impl(folder_path: str) -> bool`: Implementation function to check if folder exists. +- `_get_subdirectories_impl(folder_path: str, include: str | list[str], exclude: str | list[str] | None) -> list[str]`: Implementation function to get subdirectories. +- `_zip_dir_impl(folder_path: str) -> str`: Implementation function to create a zip archive of a directory. +- `_move_file_impl(source_path: str, destination_path: str) -> bool`: Implementation function to move a file. +- `_read_directory_impl(dir_path: str) -> str`: Implementation function to zip a directory and return base64 encoded zip. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion. +- Imported dependency areas include: `base64`, `fnmatch`, `helpers`, `os`, `shutil`, `tempfile`, `zipfile`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `os.path.abspath`, `os.path.join`, `find_file_in_dirs`, `runtime.call_development_function_sync`, `base64.b64decode`, `get_abs_path`, `base64.b64encode.decode`, `FileNotFoundError`, `os.path.exists`, `os.path.basename`, `os.path.isfile`, `Exception`, `os.makedirs`, `os.remove`, `os.path.isdir`, `shutil.rmtree`, `os.listdir`, `items.sort`, `tempfile.NamedTemporaryFile`, `zipfile.ZipFile`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/runtime.py.dox.md b/helpers/runtime.py.dox.md new file mode 100644 index 000000000..e9e5ae922 --- /dev/null +++ b/helpers/runtime.py.dox.md @@ -0,0 +1,69 @@ +# runtime.py DOX + +## Purpose + +- Own the `runtime.py` helper module. +- This module owns runtime identity, environment flags, and startup arguments. +- Keep this file-level DOX profile synchronized with `runtime.py` because this directory is intentionally flat. + +## Ownership + +- `runtime.py` owns the runtime implementation. +- `runtime.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `initialize()` +- `get_arg(name: str)` +- `has_arg(name: str)` +- `is_dockerized() -> bool` +- `is_development() -> bool` +- `get_local_url()` +- `get_runtime_id() -> str` +- `get_persistent_id() -> str` +- `async call_development_function(func: Callable[..., Awaitable[T]], *args, **kwargs) -> T` +- `async call_development_function(func: Callable[..., T], *args, **kwargs) -> T` +- `async call_development_function(func: Union[Callable[..., T], Callable[..., Awaitable[T]]], *args, **kwargs) -> T` +- `async handle_rfc(rfc_call: rfc.RFCCall)` +- `_get_rfc_password() -> str` +- `_get_rfc_url() -> str` +- `call_development_function_sync(func: Union[Callable[..., T], Callable[..., Awaitable[T]]], *args, **kwargs) -> T` +- `get_web_ui_port()` +- `get_tunnel_api_port()` +- `get_platform()` +- `is_windows()` +- `get_terminal_executable()` +- Notable constants/configuration names: `T`, `R`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, subprocess/runtime control, settings/state persistence, secret handling, tunnel state. +- Imported dependency areas include: `argparse`, `asyncio`, `helpers`, `inspect`, `nest_asyncio`, `pathlib`, `queue`, `secrets`, `sys`, `threading`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `nest_asyncio.apply`, `TypeVar`, `argparse.ArgumentParser`, `parser.add_argument`, `parser.parse_known_args`, `vars`, `is_dockerized`, `dotenv.get_dotenv_value`, `is_development`, `settings.get_settings`, `url.endswith`, `queue.Queue`, `threading.Thread`, `thread.start`, `thread.join`, `thread.is_alive`, `result_queue.get_nowait`, `cast`, `is_windows`, `get_arg`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_computer_use_metadata.py` + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_default_prompt_budget.py` + - `tests/test_document_query_plugin.py` + - `tests/test_host_browser_connector.py` + - `tests/test_http_auth_csrf.py` + - `tests/test_image_get_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/searxng.py.dox.md b/helpers/searxng.py.dox.md new file mode 100644 index 000000000..889e62df1 --- /dev/null +++ b/helpers/searxng.py.dox.md @@ -0,0 +1,43 @@ +# searxng.py DOX + +## Purpose + +- Own the `searxng.py` helper module. +- This module queries SearXNG search. +- Keep this file-level DOX profile synchronized with `searxng.py` because this directory is intentionally flat. + +## Ownership + +- `searxng.py` owns the runtime implementation. +- `searxng.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `async search(query: str)` +- `async _search(query: str)` +- Notable constants/configuration names: `URL`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: network calls, settings/state persistence. +- Imported dependency areas include: `aiohttp`, `helpers`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `runtime.call_development_function`, `aiohttp.ClientSession`, `session.post`, `response.json`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/secrets.py.dox.md b/helpers/secrets.py.dox.md new file mode 100644 index 000000000..2824362aa --- /dev/null +++ b/helpers/secrets.py.dox.md @@ -0,0 +1,62 @@ +# secrets.py DOX + +## Purpose + +- Own the `secrets.py` helper module. +- This module loads, aliases, masks, and streams secret values safely. +- Keep this file-level DOX profile synchronized with `secrets.py` because this directory is intentionally flat. + +## Ownership + +- `secrets.py` owns the runtime implementation. +- `secrets.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `EnvLine` (no explicit base class) +- `StreamingSecretsFilter` (no explicit base class) + - `process_chunk(self, chunk: str) -> str` + - `finalize(self) -> str` +- `SecretsManager` (no explicit base class) + - `get_instance(cls, *secrets_files) -> 'SecretsManager'` + - `read_secrets_raw(self) -> str` + - `load_secrets(self) -> Dict[str, str]` + - `save_secrets(self, secrets_content: str)` + - `save_secrets_with_merge(self, submitted_content: str)` + - `get_keys(self) -> List[str]` + - `get_secrets_for_prompt(self) -> str` + - `create_streaming_filter(self) -> 'StreamingSecretsFilter'` +- Top-level functions: +- `alias_for_key(key: str, placeholder: str=...) -> str` +- `get_secrets_manager(context: 'AgentContext|None'=...) -> SecretsManager` +- `get_project_secrets_manager(project_name: str, merge_with_global: bool=...) -> SecretsManager` +- `get_default_secrets_manager() -> SecretsManager` +- Notable constants/configuration names: `ALIAS_PATTERN`, `DEFAULT_SECRETS_FILE`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, settings/state persistence, secret handling. +- Imported dependency areas include: `dataclasses`, `dotenv.parser`, `helpers`, `helpers.errors`, `helpers.extension`, `io`, `os`, `re`, `threading`, `time`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `key.upper`, `placeholder.format`, `SecretsManager.get_instance`, `self._replace_full_values`, `self._longest_suffix_prefix`, `threading.RLock`, `join`, `files.write_file`, `self._invalidate_all_caches`, `self.load_secrets`, `self.read_secrets_raw`, `self.parse_env_lines`, `self._serialize_env_lines`, `StreamingSecretsFilter`, `re.sub`, `self.parse_env_content`, `parse_stream`, `AgentContext.current`, `projects.get_context_project_name`, `files.get_abs_path`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_plugin_scan_prompt.py` + - `tests/test_print_style.py` + - `tests/test_time_travel.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/security.py.dox.md b/helpers/security.py.dox.md new file mode 100644 index 000000000..882286b52 --- /dev/null +++ b/helpers/security.py.dox.md @@ -0,0 +1,45 @@ +# security.py DOX + +## Purpose + +- Own the `security.py` helper module. +- This module contains small security helpers such as filename sanitization. +- Keep this file-level DOX profile synchronized with `security.py` because this directory is intentionally flat. + +## Ownership + +- `security.py` owns the runtime implementation. +- `security.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `safe_filename(filename: str) -> Optional[str]` +- Notable constants/configuration names: `FORBIDDEN_CHARS_RE`, `WINDOWS_RESERVED`, `FILENAME_MAX_LENGTH`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem deletion. +- Imported dependency areas include: `pathlib`, `re`, `typing`, `unicodedata`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `re.compile`, `frozenset`, `unicodedata.normalize`, `FORBIDDEN_CHARS_RE.sub`, `filename.lstrip.rstrip`, `Path`, `join`, `stem.upper`, `filename.lstrip`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_fastmcp_openapi_security.py` + - `tests/test_image_get_security.py` + - `tests/test_ws_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/self_update.py.dox.md b/helpers/self_update.py.dox.md new file mode 100644 index 000000000..b1e552539 --- /dev/null +++ b/helpers/self_update.py.dox.md @@ -0,0 +1,77 @@ +# self_update.py DOX + +## Purpose + +- Own the `self_update.py` helper module. +- This module manages self-update status, scheduling, tag selection, and durable scripts. +- Keep this file-level DOX profile synchronized with `self_update.py` because this directory is intentionally flat. + +## Ownership + +- `self_update.py` owns the runtime implementation. +- `self_update.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `PendingUpdateConfig` (`TypedDict`) +- `UpdateStatus` (`TypedDict`) +- `SelectorTagOption` (`TypedDict`) +- Top-level functions: +- `_now_iso() -> str` +- `get_update_file_path() -> Path` +- `get_status_file_path() -> Path` +- `get_log_file_path() -> Path` +- `get_durable_exe_dir() -> Path` +- `get_durable_self_update_manager_path() -> Path` +- `_load_yaml(path: Path) -> dict[str, Any] | None` +- `_write_yaml(path: Path, payload: dict[str, Any]) -> None` +- `load_pending_update() -> PendingUpdateConfig | None` +- `load_last_status() -> UpdateStatus | None` +- `get_log_text() -> str` +- `get_default_backup_dir(repo_dir: str | Path | None=...) -> Path` +- `get_repo_dir(repo_dir: str | Path | None=...) -> Path` +- `get_repo_self_update_manager_path(repo_dir: str | Path | None=...) -> Path` +- `_get_official_remote_url() -> str` +- `_run_git_raw(*args) -> str` +- `_run_git(repo_dir: str | Path, *args) -> str` +- `_normalize_describe_to_version(describe: str) -> str` +- `_split_describe_version(describe: str) -> tuple[str, int]` +- `_is_latest_selector_tag(tag: str) -> bool` +- `_get_tag_release_time_in_repo(repo_dir: str | Path, tag: str) -> str` +- `get_repo_version_info(repo_dir: str | Path | None=...) -> dict[str, str]` +- `_sanitize_filename(name: str, default_name: str) -> str` +- `_slugify_version(text: str) -> str` +- `build_default_backup_name(current_version: str, target_tag: str | None=...) -> str` +- `_resolve_backup_path(backup_path: str, repo_dir: str | Path | None=...) -> Path` +- `_is_excluded_self_update_branch(branch: str) -> bool` +- `_sort_branch_names(branches: list[str]) -> list[str]` +- `_get_remote_branch_names() -> list[str]` +- `_get_local_origin_branch_names(repo_dir: str | Path | None=...) -> list[str]` +- Notable constants/configuration names: `OFFICIAL_REPO_AUTHOR`, `OFFICIAL_REPO_NAME`, `BRANCH_OPTIONS`, `SUPPORTED_BRANCHES`, `BACKUP_CONFLICT_POLICIES`, `MIN_SELECTOR_VERSION`, `REMOTE_BRANCH_TAG_CACHE_TTL_SECONDS`, `REMOTE_BRANCH_LIST_CACHE_TTL_SECONDS`, `UPDATE_FILE_PATH`, `STATUS_FILE_PATH`, `LOG_FILE_PATH`, `DURABLE_EXE_DIR`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, subprocess/runtime control, settings/state persistence. +- Imported dependency areas include: `__future__`, `datetime`, `helpers`, `helpers.localization`, `os`, `pathlib`, `re`, `subprocess`, `tempfile`, `time`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Path`, `Localization.get.now_iso`, `yaml.loads`, `path.parent.mkdir`, `path.write_text`, `_load_yaml`, `get_log_file_path`, `path.read_text`, `subprocess.run`, `completed.stdout.strip`, `re.fullmatch`, `describe.strip`, `tag.strip`, `get_repo_dir`, `_run_git`, `_normalize_describe_to_version`, `strip`, `re.sub.strip`, `Localization.get.now.strftime`, `path.resolve`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_office_document_store.py` + - `tests/test_self_update_tag_filter.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/serveo_tunnel.py.dox.md b/helpers/serveo_tunnel.py.dox.md new file mode 100644 index 000000000..c209237f1 --- /dev/null +++ b/helpers/serveo_tunnel.py.dox.md @@ -0,0 +1,43 @@ +# serveo_tunnel.py DOX + +## Purpose + +- Own the `serveo_tunnel.py` helper module. +- This module implements Serveo tunnel provider behavior. +- Keep this file-level DOX profile synchronized with `serveo_tunnel.py` because this directory is intentionally flat. + +## Ownership + +- `serveo_tunnel.py` owns the runtime implementation. +- `serveo_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ServeoTunnelHelper` (`FlaredanticTunnelHelper`) + - `build_tunnel(self)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: settings/state persistence, tunnel state. +- Imported dependency areas include: `flaredantic`, `helpers.tunnel_common`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `ServeoConfig`, `ServeoTunnel`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/server_startup.py.dox.md b/helpers/server_startup.py.dox.md new file mode 100644 index 000000000..a8417341c --- /dev/null +++ b/helpers/server_startup.py.dox.md @@ -0,0 +1,62 @@ +# server_startup.py DOX + +## Purpose + +- Own the `server_startup.py` helper module. +- This module runs Uvicorn startup with health checks and retry tracking. +- Keep this file-level DOX profile synchronized with `server_startup.py` because this directory is intentionally flat. + +## Ownership + +- `server_startup.py` owns the runtime implementation. +- `server_startup.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `StartupConfig` (no explicit base class) + - `from_env(cls) -> 'StartupConfig'` +- `StartupStageRecord` (no explicit base class) +- `StartupMonitor` (no explicit base class) + - `mark(self, stage: str, detail: str | None=...) -> None` + - `stage(self, stage: str, detail: str | None=...) -> Iterator[None]` + - `lifespan(self)` + - `attach_server(self, server: uvicorn.Server) -> None` + - `start_watchdog(self) -> None` + - `mark_ready(self, source: str=...) -> None` + - `is_ready(self) -> bool` + - `close(self) -> None` +- `_UvicornServerWrapper` (no explicit base class) + - `shutdown(self) -> None` +- Top-level functions: +- `_env_int(name: str, default: int, minimum: int=...) -> int` +- `_env_float(name: str, default: float, minimum: float=...) -> float` +- `get_health_probe_host(bind_host: str) -> str` +- `run_uvicorn_with_retries(host: str, port: int, build_asgi_app: Callable[[StartupMonitor], object], flush_callback: Callable[[str], None], access_log: bool=..., log_level: str=..., ws: str=..., startup_config: StartupConfig | None=...) -> None` +- `_run_server_attempt(host: str, health_host: str, port: int, startup_monitor: StartupMonitor, build_asgi_app: Callable[[StartupMonitor], object], flush_callback: Callable[[str], None], access_log: bool, log_level: str, ws: str) -> bool` +- `wait_for_health(host: str, port: int, startup_monitor: StartupMonitor) -> None` +- `_serve_uvicorn(server: uvicorn.Server) -> None` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, network calls, subprocess/runtime control, settings/state persistence. +- Imported dependency areas include: `asyncio`, `collections`, `contextlib`, `dataclasses`, `faulthandler`, `helpers`, `helpers.print_style`, `os`, `sys`, `threading`, `time`, `typing`, `urllib.request`, `uvicorn`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `dataclass`, `get_health_probe_host`, `PrintStyle.debug`, `RuntimeError`, `startup_monitor.start_watchdog`, `server.config.get_loop_factory`, `cls`, `time.monotonic`, `deque`, `threading.Event`, `threading.RLock`, `self.mark`, `threading.Thread`, `self._watchdog_thread.start`, `self._ready.is_set`, `self.snapshot`, `PrintStyle.error`, `join`, `StartupConfig.from_env`, `StartupMonitor`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/settings.py.dox.md b/helpers/settings.py.dox.md new file mode 100644 index 000000000..ef35d05c0 --- /dev/null +++ b/helpers/settings.py.dox.md @@ -0,0 +1,88 @@ +# settings.py DOX + +## Purpose + +- Own the `settings.py` helper module. +- This module defines settings models, defaults, validation, and serialization. +- Keep this file-level DOX profile synchronized with `settings.py` because this directory is intentionally flat. + +## Ownership + +- `settings.py` owns the runtime implementation. +- `settings.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Settings` (`TypedDict`) +- `PartialSettings` (`Settings`) +- `FieldOption` (`TypedDict`) +- `SettingsField` (`TypedDict`) +- `SettingsSection` (`TypedDict`) +- `ModelProvider` (`ProvidersFO`) +- `SettingsOutputAdditional` (`TypedDict`) +- `SettingsOutput` (`TypedDict`) +- Top-level functions: +- `get_default_value(name: str, value: T) -> T`: Load setting value from .env with A0_SET_ prefix, falling back to default. +- `_ensure_option_present(options: list[OptionT] | None, current_value: str | None) -> list[OptionT]`: Ensure the currently selected value exists in a dropdown options list. +- `_is_valid_timezone(value: str) -> bool` +- `_normalize_timezone_setting(value: Any, default: str=...) -> str` +- `_normalize_time_format(value: Any, default: str=...) -> str` +- `_resolve_runtime_timezone(setting_value: str, browser_timezone: str | None=...) -> str` +- `_timezone_options() -> list[FieldOption]` +- `convert_out(settings: Settings) -> SettingsOutput` +- `_get_api_key_field(settings: Settings, provider: str, title: str) -> SettingsField` +- `convert_in(settings: Settings) -> Settings` +- `get_settings() -> Settings` +- `reload_settings() -> Settings` +- `set_runtime_settings_snapshot(settings: Settings) -> None` +- `set_settings(settings: Settings, apply: bool=..., browser_timezone: str | None=...)` +- `set_settings_delta(delta: dict, apply: bool=...)` +- `merge_settings(original: Settings, delta: dict) -> Settings` +- `normalize_settings(settings: Settings) -> Settings` +- `_adjust_to_version(settings: Settings, default: Settings)` +- `_load_sensitive_settings(settings: Settings)` +- `_read_settings_file() -> Settings | None` +- `_write_settings_file(settings: Settings)` +- `_remove_sensitive_settings(settings: Settings)` +- `_write_sensitive_settings(settings: Settings)` +- `get_default_settings() -> Settings` +- `_apply_timezone_setting(previous: Settings | None, browser_timezone: str | None=...) -> None` +- `_apply_settings(previous: Settings | None, browser_timezone: str | None=...)` +- `_env_to_dict(data: str)` +- `_dict_to_env(data_dict)` +- `set_root_password(password: str)` +- `get_runtime_config(set: Settings)` +- Notable constants/configuration names: `T`, `PASSWORD_PLACEHOLDER`, `API_KEY_PLACEHOLDER`, `TIMEZONE_AUTO`, `TIME_FORMAT_12H`, `TIME_FORMAT_24H`, `SETTINGS_FILE`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, model calls, WebSocket state, plugin state, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `base64`, `hashlib`, `helpers`, `helpers.notification`, `helpers.print_style`, `helpers.providers`, `helpers.secrets`, `json`, `models`, `os`, `pytz`, `re`, `subprocess`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `TypeVar`, `files.get_abs_path`, `dotenv.get_dotenv_value`, `opts.insert`, `str.strip`, `_is_valid_timezone`, `str.strip.lower`, `_normalize_timezone_setting`, `SettingsOutput`, `get_default_settings`, `_ensure_option_present`, `_resolve_runtime_timezone`, `get_default_secrets_manager`, `get_settings`, `normalize_settings`, `_load_sensitive_settings`, `settings.copy`, `_write_settings_file`, `reload_settings`, `set_settings`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_document_query_plugin.py` + - `tests/test_download_toast_regressions.py` + - `tests/test_fasta2a_client.py` + - `tests/test_mcp_handler_multimodal.py` + - `tests/test_model_config_api_keys.py` + - `tests/test_model_config_project_presets.py` + - `tests/test_oauth_static.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/skills.py.dox.md b/helpers/skills.py.dox.md new file mode 100644 index 000000000..dd23b4aba --- /dev/null +++ b/helpers/skills.py.dox.md @@ -0,0 +1,83 @@ +# skills.py DOX + +## Purpose + +- Own the `skills.py` helper module. +- This module discovers, parses, filters, and resolves Agent Zero skills. +- Keep this file-level DOX profile synchronized with `skills.py` because this directory is intentionally flat. + +## Ownership + +- `skills.py` owns the runtime implementation. +- `skills.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ActiveSkillEntry` (`TypedDict`) +- `CatalogSkill` (`TypedDict`) +- `Skill` (no explicit base class) +- Top-level functions: +- `get_skills_base_dir() -> Path` +- `get_skill_roots(agent: Agent | None=...) -> List[str]` +- `_is_hidden_path(path: Path) -> bool` +- `discover_skill_md_files(root: Path) -> List[Path]`: Recursively discover SKILL.md files under a root directory. +- `_coerce_list(value: Any) -> List[str]` +- `_normalize_name(name: str) -> str` +- `_read_text(path: Path) -> str` +- `split_frontmatter(markdown: str) -> Tuple[Dict[str, Any], str, List[str]]`: Splits a SKILL.md into (frontmatter_dict, body_text, errors). +- `_parse_frontmatter_fallback(frontmatter_text: str) -> Dict[str, Any]` +- `parse_frontmatter(frontmatter_text: str) -> Tuple[Dict[str, Any], List[str]]`: Parse YAML frontmatter with PyYAML when available, +- `skill_from_markdown(skill_md_path: Path, include_content: bool=..., validate: bool=...) -> Optional[Skill]` +- `list_skills(agent: Agent | None=..., include_content: bool=..., include_hidden: bool=...) -> List[Skill]`: List skills, optionally filtered by agent scope. +- `delete_skill(skill_path: str) -> None`: Delete a skill directory. +- `find_skill(skill_name: str, agent: Agent | None=..., include_content: bool=..., include_hidden: bool=...) -> Optional[Skill]` +- `load_skill_for_agent(skill_name: str, agent: Agent | None=...) -> str`: Load skill and format it as a complete string for agent context. +- `_get_skill_files(skill_dir: Path) -> str`: Get file tree for skill directory. +- `search_skills(query: str, limit: int=..., agent: Agent | None=..., include_hidden: bool=...) -> List[Skill]` +- `validate_skill(skill: Skill) -> List[str]` +- `validate_skill_md(skill_md_path: Path) -> List[str]` +- `_normalize_max_active_skills(value: Any) -> int` +- `get_max_active_skills(agent: Agent | None=..., project_name: str | None=...) -> int` +- `normalize_skills_config(config: dict[str, Any] | None) -> dict[str, Any]` +- `normalize_active_skills(raw: Any, limit: int | None=...) -> list[ActiveSkillEntry]` +- `normalize_hidden_skills(raw: Any) -> list[ActiveSkillEntry]` +- `normalize_skill_entries(raw: Any, limit: int | None=...) -> list[ActiveSkillEntry]` +- `list_skill_catalog(project_name: str=..., agent: Agent | None=...) -> list[CatalogSkill]` +- `get_scope_active_skills(agent: Agent | None) -> list[ActiveSkillEntry]` +- `get_scope_hidden_skills(agent: Agent | None) -> list[ActiveSkillEntry]` +- `get_chat_active_skills(context: Any | None) -> list[ActiveSkillEntry]` +- `get_chat_disabled_skills(context: Any | None) -> list[ActiveSkillEntry]` +- Notable constants/configuration names: `MAX_ACTIVE_SKILLS`, `ACTIVE_SKILLS_PLUGIN_NAME`, `AGENT_DATA_NAME_LOADED_SKILLS`, `CONTEXT_DATA_NAME_CHAT_ACTIVE_SKILLS`, `CONTEXT_DATA_NAME_CHAT_DISABLED_SKILLS`, `CONTEXT_DATA_NAME_CHAT_VISIBLE_SKILLS`, `_NAME_RE`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem deletion, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `os`, `pathlib`, `re`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `dataclass`, `re.compile`, `field`, `Path`, `root.rglob`, `results.sort`, `re.sub`, `path.read_text`, `text.splitlines`, `join.strip`, `parse_frontmatter`, `frontmatter_text.splitlines`, `_parse_frontmatter_fallback`, `split_frontmatter`, `str.strip`, `_coerce_list`, `Skill`, `get_skill_roots`, `_filter_hidden_skills`, `files.get_abs_path`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_document_query_plugin.py` + - `tests/test_fasta2a_client.py` + - `tests/test_office_canvas_setup.py` + - `tests/test_office_document_store.py` + - `tests/test_skills_runtime.py` + - `tests/test_time_travel.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/skills_cli.py.dox.md b/helpers/skills_cli.py.dox.md new file mode 100644 index 000000000..02aa7922d --- /dev/null +++ b/helpers/skills_cli.py.dox.md @@ -0,0 +1,51 @@ +# skills_cli.py DOX + +## Purpose + +- Own the `skills_cli.py` helper module. +- This module provides command-line skill listing, search, validation, and creation helpers. +- Keep this file-level DOX profile synchronized with `skills_cli.py` because this directory is intentionally flat. + +## Ownership + +- `skills_cli.py` owns the runtime implementation. +- `skills_cli.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Skill` (no explicit base class) +- Top-level functions: +- `get_skills_dirs() -> List[Path]`: Get all skill directories +- `parse_skill_file(skill_path: Path) -> Optional[Skill]`: Parse a SKILL.md file and return a Skill object +- `list_skills() -> List[Skill]`: List all available skills +- `find_skill(name: str) -> Optional[Skill]`: Find a skill by name +- `search_skills(query: str) -> List[Skill]`: Search skills by name, description, or tags +- `validate_skill(skill: Skill) -> List[str]`: Validate a skill and return list of issues +- `create_skill(name: str, description: str=..., author: str=...) -> Path`: Create a new skill from template +- `print_skill_table(skills: List[Skill])`: Print skills in a formatted table +- `main()` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, secret handling. +- Imported dependency areas include: `argparse`, `dataclasses`, `datetime`, `helpers`, `os`, `pathlib`, `re`, `sys`, `typing`, `yaml`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `sys.path.insert`, `field`, `Path`, `get_skills_dirs`, `list_skills`, `query.lower`, `exists`, `custom_dir.mkdir`, `skill_dir.exists`, `skill_dir.mkdir`, `mkdir`, `skill_file.write_text`, `readme.write_text`, `argparse.ArgumentParser`, `parser.add_subparsers`, `subparsers.add_parser`, `list_parser.add_argument`, `create_parser.add_argument`, `show_parser.add_argument`, `validate_parser.add_argument`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/skills_import.py.dox.md b/helpers/skills_import.py.dox.md new file mode 100644 index 000000000..9da611849 --- /dev/null +++ b/helpers/skills_import.py.dox.md @@ -0,0 +1,55 @@ +# skills_import.py DOX + +## Purpose + +- Own the `skills_import.py` helper module. +- This module plans and imports skill bundles into user, project, or profile scopes. +- Keep this file-level DOX profile synchronized with `skills_import.py` because this directory is intentionally flat. + +## Ownership + +- `skills_import.py` owns the runtime implementation. +- `skills_import.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ImportPlanItem` (no explicit base class) +- `ImportResult` (no explicit base class) +- Top-level functions: +- `_is_within(child: Path, parent: Path) -> bool` +- `_derive_namespace(source: Path) -> str` +- `_candidate_skill_roots(source_dir: Path) -> List[Path]`: Heuristics to find likely skill roots inside a repo/pack: +- `_unzip_to_temp_dir(zip_path: Path) -> Path`: Extract a zip into a temp folder under tmp/skill_imports (inside Agent Zero base dir). +- `build_import_plan(source: Path, dest_root: Path, namespace: Optional[str]=...) -> Tuple[List[ImportPlanItem], Path]`: Build a copy plan for importing skills from a source folder. +- `_resolve_conflict(dest: Path, policy: ConflictPolicy) -> Tuple[Path, bool]`: Returns (final_dest_path, should_copy). +- `get_project_skills_folder(project_name: str) -> Path`: Get the skills folder path for a project. +- `get_agent_profile_skills_folder(profile_name: str) -> Path` +- `get_project_agent_profile_skills_folder(project_name: str, profile_name: str) -> Path` +- `resolve_skills_destination_root(project_name: Optional[str], agent_profile: Optional[str]) -> Path` +- `import_skills(source_path: str, namespace: Optional[str]=..., conflict: ConflictPolicy=..., dry_run: bool=..., project_name: Optional[str]=..., agent_profile: Optional[str]=...) -> ImportResult`: Import external Skills into usr/skills//... +- Notable constants/configuration names: `PROJECT_SKILLS_DIR`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state. +- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `helpers.skills`, `os`, `pathlib`, `shutil`, `tempfile`, `time`, `typing`, `zipfile`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `dataclass`, `strip`, `plugins.is_dir`, `Path`, `base_tmp.mkdir`, `time.strftime`, `target.mkdir`, `_candidate_skill_roots`, `Path.expanduser`, `resolve_skills_destination_root`, `dest_root.mkdir`, `build_import_plan`, `ImportResult`, `child.resolve.relative_to`, `direct.is_dir`, `discover_skill_md_files`, `plugins.iterdir`, `files.get_abs_path`, `zipfile.ZipFile`, `z.extractall`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/state_migration.py.dox.md b/helpers/state_migration.py.dox.md new file mode 100644 index 000000000..9af4faa8c --- /dev/null +++ b/helpers/state_migration.py.dox.md @@ -0,0 +1,45 @@ +# state_migration.py DOX + +## Purpose + +- Own the `state_migration.py` helper module. +- This module moves retired state tree paths to current runtime locations. +- Keep this file-level DOX profile synchronized with `state_migration.py` because this directory is intentionally flat. + +## Ownership + +- `state_migration.py` owns the runtime implementation. +- `state_migration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `migrate_retired_state_tree(source: Path, destination: Path, owner: str, migrated: list[str], warnings: list[str], errors: list[str]) -> None`: Move retired plugin state into its plugin-owned state directory. +- `_move_path(source: Path, target: Path, migrated: list[str]) -> None` +- `_next_conflict_path(path: Path) -> Path` +- `_remove_empty_dir(path: Path, owner: str, warnings: list[str]) -> None` +- `_same_path(left: Path, right: Path) -> bool` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, plugin state, settings/state persistence. +- Imported dependency areas include: `__future__`, `pathlib`, `shutil`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `_same_path`, `final_target.parent.mkdir`, `shutil.move`, `path.with_name`, `_move_path`, `source.is_dir`, `target.is_dir`, `source.rmdir`, `target.exists`, `target.is_symlink`, `_next_conflict_path`, `candidate.exists`, `candidate.is_symlink`, `path.rmdir`, `source.exists`, `source.is_symlink`, `destination.mkdir`, `_remove_empty_dir`, `source.iterdir`, `left.resolve`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/state_monitor.py.dox.md b/helpers/state_monitor.py.dox.md new file mode 100644 index 000000000..a84115652 --- /dev/null +++ b/helpers/state_monitor.py.dox.md @@ -0,0 +1,59 @@ +# state_monitor.py DOX + +## Purpose + +- Own the `state_monitor.py` helper module. +- This module tracks dirty state and connection projections for WebUI sync. +- Keep this file-level DOX profile synchronized with `state_monitor.py` because this directory is intentionally flat. + +## Ownership + +- `state_monitor.py` owns the runtime implementation. +- `state_monitor.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ConnectionProjection` (no explicit base class) +- `StateMonitor` (no explicit base class) + - `bind_manager(self, manager: 'WsManager', handler_id: str | None=...) -> None` + - `register_sid(self, namespace: str, sid: str) -> None` + - `unregister_sid(self, namespace: str, sid: str) -> None` + - `mark_dirty_all(self, reason: str | None=...) -> None` + - `mark_dirty_for_context(self, context_id: str, reason: str | None=...) -> None` + - `update_projection(self, namespace: str, sid: str, request: StateRequestV1, seq_base: int) -> None` + - `mark_dirty(self, namespace: str, sid: str, reason: str | None=..., wave_id: str | None=...) -> None` +- Top-level functions: +- `get_state_monitor() -> StateMonitor` +- `_reset_state_monitor_for_testing() -> None` +- Notable constants/configuration names: `_STATE_MONITOR_HOLDER`, `_STATE_MONITOR_LOCK`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem deletion, WebSocket state, settings/state persistence, scheduler state. +- Imported dependency areas include: `__future__`, `asyncio`, `dataclasses`, `helpers`, `helpers.print_style`, `helpers.state_snapshot`, `helpers.ws`, `helpers.ws_manager`, `os`, `threading`, `time`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `threading.RLock`, `field`, `ws_debug`, `_ws_debug_enabled`, `context_id.strip`, `loop.call_soon_threadsafe`, `self._schedule_debounce_on_loop`, `asyncio.get_running_loop`, `asyncio.current_task`, `loop.is_closed`, `self._debounce_handles.pop`, `self._push_tasks.pop`, `self._projections.pop`, `self.mark_dirty`, `self._mark_dirty_on_loop`, `runtime.is_development`, `loop.call_later`, `StateMonitor`, `ConnectionProjection`, `handle.cancel`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_model_config_api_keys.py` + - `tests/test_multi_tab_isolation.py` + - `tests/test_state_monitor.py` + - `tests/test_state_sync_handler.py` + - `tests/test_state_sync_welcome_screen.py` + - `tests/test_ws_handlers.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/state_monitor_integration.py.dox.md b/helpers/state_monitor_integration.py.dox.md new file mode 100644 index 000000000..15c7e3530 --- /dev/null +++ b/helpers/state_monitor_integration.py.dox.md @@ -0,0 +1,43 @@ +# state_monitor_integration.py DOX + +## Purpose + +- Own the `state_monitor_integration.py` helper module. +- This module bridges dirty-state calls into the shared state monitor. +- Keep this file-level DOX profile synchronized with `state_monitor_integration.py` because this directory is intentionally flat. + +## Ownership + +- `state_monitor_integration.py` owns the runtime implementation. +- `state_monitor_integration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `mark_dirty_all(reason: str | None=...) -> None` +- `mark_dirty_for_context(context_id: str, reason: str | None=...) -> None` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `__future__`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `get_state_monitor.mark_dirty_all`, `get_state_monitor.mark_dirty_for_context`, `get_state_monitor`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_model_config_api_keys.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/state_snapshot.py.dox.md b/helpers/state_snapshot.py.dox.md new file mode 100644 index 000000000..ac27b97c5 --- /dev/null +++ b/helpers/state_snapshot.py.dox.md @@ -0,0 +1,63 @@ +# state_snapshot.py DOX + +## Purpose + +- Own the `state_snapshot.py` helper module. +- This module builds and validates typed WebUI state snapshots. +- Keep this file-level DOX profile synchronized with `state_snapshot.py` because this directory is intentionally flat. + +## Ownership + +- `state_snapshot.py` owns the runtime implementation. +- `state_snapshot.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SnapshotV1` (`TypedDict`) +- `StateRequestV1` (no explicit base class) +- `StateRequestValidationError` (`ValueError`) +- Top-level functions: +- `_annotation_to_isinstance_types(annotation: Any) -> tuple[type, ...]`: Convert type annotation to tuple suitable for isinstance(). +- `_build_schema_from_typeddict(td: type) -> dict[str, tuple[type, ...]]`: Extract field names and isinstance-compatible types from TypedDict. +- `validate_snapshot_schema_v1(snapshot: Mapping[str, Any]) -> None` +- `_coerce_non_negative_int(value: Any, default: int=...) -> int` +- `_get_agent_profile_labels() -> dict[str, str]` +- `_apply_agent_profile_metadata(context_data: dict[str, Any], ctx: AgentContext, labels: dict[str, str]) -> None` +- `parse_state_request_payload(payload: Mapping[str, Any]) -> StateRequestV1` +- `_coerce_state_request_inputs(context: Any, log_from: Any, notifications_from: Any, timezone: Any) -> StateRequestV1` +- `advance_state_request_after_snapshot(request: StateRequestV1, snapshot: Mapping[str, Any]) -> StateRequestV1` +- `async build_snapshot_from_request(request: StateRequestV1) -> SnapshotV1`: Build a poll-shaped snapshot for both /poll and state_push. +- `_notify_timezone_changed(previous_timezone: str, current_timezone: str) -> None` +- `async build_snapshot(context: str | None, log_from: int, notifications_from: int, timezone: str | None) -> SnapshotV1` +- Notable constants/configuration names: `_SNAPSHOT_V1_SCHEMA`, `SNAPSHOT_SCHEMA_V1_KEYS`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: plugin state, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `__future__`, `agent`, `dataclasses`, `helpers.dotenv`, `helpers.localization`, `helpers.task_scheduler`, `pytz`, `types`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `dataclass`, `_build_schema_from_typeddict`, `get_origin`, `timezone.strip`, `StateRequestV1`, `localization.get_timezone`, `localization.set_timezone`, `ctxid.strip`, `_coerce_non_negative_int`, `AgentContext.get_notification_manager`, `notification_manager.output`, `_get_agent_profile_labels`, `ctxs.sort`, `tasks.sort`, `validate_snapshot_schema_v1`, `_coerce_state_request_inputs`, `super.__init__`, `get_args`, `_annotation_to_isinstance_types`, `TypeError`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_multi_tab_isolation.py` + - `tests/test_snapshot_parity.py` + - `tests/test_snapshot_schema_v1.py` + - `tests/test_state_monitor.py` + - `tests/test_state_sync_handler.py` + - `tests/test_state_sync_welcome_screen.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/strings.py.dox.md b/helpers/strings.py.dox.md new file mode 100644 index 000000000..ccc055650 --- /dev/null +++ b/helpers/strings.py.dox.md @@ -0,0 +1,49 @@ +# strings.py DOX + +## Purpose + +- Own the `strings.py` helper module. +- This module sanitizes, formats, truncates, and expands framework string content. +- Keep this file-level DOX profile synchronized with `strings.py` because this directory is intentionally flat. + +## Ownership + +- `strings.py` owns the runtime implementation. +- `strings.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `sanitize_string(s: str, encoding: str=...) -> str` +- `calculate_valid_match_lengths(first: bytes | str, second: bytes | str, deviation_threshold: int=..., deviation_reset: int=..., ignore_patterns: list[bytes | str]=..., debug: bool=...) -> tuple[int, int]` +- `format_key(key: str) -> str`: Format a key string to be more readable. +- `dict_to_text(d: dict) -> str` +- `truncate_text(text: str, length: int, at_end: bool=..., replacement: str=...) -> str` +- `truncate_text_by_ratio(text: str, threshold: int, replacement: str=..., ratio: float=...) -> str`: Truncate text with replacement at a specified ratio position. +- `replace_file_includes(text: str, placeholder_pattern: str=...) -> str` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem deletion. +- Imported dependency areas include: `helpers`, `re`, `sys`, `time`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `s.encode.decode`, `join`, `join.rstrip`, `re.sub`, `skip_ignored_patterns`, `match.group`, `s.encode`, `sys.stdout.write`, `sys.stdout.flush`, `time.sleep`, `c.isupper`, `result.islower`, `word.capitalize`, `files.fix_dev_path`, `files.read_file`, `re.match`, `formatted.split`, `c.isalnum`, `format_key`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_model_search.py` + - `tests/test_whatsapp_number_utils.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/subagents.py.dox.md b/helpers/subagents.py.dox.md new file mode 100644 index 000000000..9b954ff80 --- /dev/null +++ b/helpers/subagents.py.dox.md @@ -0,0 +1,61 @@ +# subagents.py DOX + +## Purpose + +- Own the `subagents.py` helper module. +- This module discovers, merges, loads, and saves agent profile definitions. +- Keep this file-level DOX profile synchronized with `subagents.py` because this directory is intentionally flat. + +## Ownership + +- `subagents.py` owns the runtime implementation. +- `subagents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SubAgentListItem` (`BaseModel`) + - `post_validator(self)` +- `SubAgent` (`SubAgentListItem`) +- Top-level functions: +- `get_agents_list(project_name: str | None=...) -> list[SubAgentListItem]` +- `get_agents_dict(project_name: str | None=...) -> dict[str, SubAgentListItem]` +- `_get_agents_list_from_dir(dir: str, origin: Origin) -> dict[str, SubAgentListItem]` +- `load_agent_data(name: str, project_name: str | None=...) -> SubAgent` +- `save_agent_data(name: str, subagent: SubAgent) -> None` +- `delete_agent_data(name: str) -> None` +- `_load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent | None` +- `_merge_agents(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None` +- `_merge_agent_list_items(base: SubAgentListItem, override: SubAgentListItem) -> SubAgentListItem` +- `get_agents_roots() -> list[str]` +- `get_all_agents_list() -> list[dict[str, str]]` +- `_merge_origins(base: list[Origin], override: list[Origin]) -> list[Origin]` +- `get_default_promp_file_names() -> list[str]` +- `get_available_agents_dict(project_name: str | None) -> dict[str, SubAgentListItem]` +- `get_paths(agent: 'Agent|None', *subpaths, must_exist_completely: bool=..., include_project: bool=..., include_user: bool=..., include_default: bool=..., include_plugins: bool=..., default_root: str=...) -> list[str]`: Returns list of file paths for the given agent and subpaths, searched in order of priority: +- Notable constants/configuration names: `GLOBAL_DIR`, `USER_DIR`, `DEFAULT_AGENTS_DIR`, `USER_AGENTS_DIR`, `PATHS_CACHE_AREA`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence. +- Imported dependency areas include: `helpers`, `json`, `os`, `pydantic`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `cache.toggle_area`, `model_validator`, `_get_agents_list_from_dir`, `plugins.get_enabled_plugin_paths`, `_merge_agent_dicts`, `files.get_subdirectories`, `_load_agent_data_from_dir`, `_merge_agent`, `files.write_file`, `files.delete_dir`, `SubAgent`, `SubAgentListItem`, `files.find_existing_paths_by_pattern`, `get_agents_roots`, `files.list_files`, `get_agents_dict`, `cache.determine_cache_key`, `cache.add`, `projects.get_project_meta`, `FileNotFoundError`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_skills_runtime.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/system_packages.py.dox.md b/helpers/system_packages.py.dox.md new file mode 100644 index 000000000..f1078d3b7 --- /dev/null +++ b/helpers/system_packages.py.dox.md @@ -0,0 +1,44 @@ +# system_packages.py DOX + +## Purpose + +- Own the `system_packages.py` helper module. +- This module runs apt operations with retry behavior. +- Keep this file-level DOX profile synchronized with `system_packages.py` because this directory is intentionally flat. + +## Ownership + +- `system_packages.py` owns the runtime implementation. +- `system_packages.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `run_apt_with_retries(runner: Callable[[], subprocess.CompletedProcess[str]], lock_timeout_seconds: int=..., retry_seconds: int=...) -> subprocess.CompletedProcess[str]`: Run an apt/dpkg command, serializing in-process callers and waiting out apt locks. +- `is_apt_lock_error(result: subprocess.CompletedProcess[str]) -> bool` +- Notable constants/configuration names: `APT_LOCK_TIMEOUT_SECONDS`, `APT_LOCK_RETRY_SECONDS`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: subprocess/runtime control. +- Imported dependency areas include: `__future__`, `subprocess`, `threading`, `time`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `threading.RLock`, `lower`, `time.monotonic`, `runner`, `time.sleep`, `is_apt_lock_error`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_office_document_store.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/tailscale_tunnel.py.dox.md b/helpers/tailscale_tunnel.py.dox.md new file mode 100644 index 000000000..90afd506e --- /dev/null +++ b/helpers/tailscale_tunnel.py.dox.md @@ -0,0 +1,64 @@ +# tailscale_tunnel.py DOX + +## Purpose + +- Own the `tailscale_tunnel.py` helper module. +- This module implements Tailscale tunnel install and provider lifecycle behavior. +- Keep this file-level DOX profile synchronized with `tailscale_tunnel.py` because this directory is intentionally flat. + +## Ownership + +- `tailscale_tunnel.py` owns the runtime implementation. +- `tailscale_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `TailscaleTunnel` (`CliTunnelHelper`) + - `stop(self)` +- Top-level functions: +- `tailscale_arch()` +- `tailscale_archive_url()` +- `install_tailscale(notify=...)` +- `resolve_tailscaled_binary(binary_path)` +- `notify_info(notify, message, data=...)` +- `tailscale_socket_args(socket_path=...)` +- `tailscale_command(binary_path, args, socket_path=...)` +- `tailscale_status(binary_path, socket_path=...)` +- `tailscale_funnel_help(binary_path, socket_path=...)` +- `compact_output(lines)` +- `tailscale_daemon_hint(output)` +- `tailscale_daemon_ready(binary_path, socket_path)` +- `read_recent_tailscaled_log()` +- `start_tailscaled(binary_path, notify=...)` +- `stop_managed_tailscaled()` +- `tailscale_up_failure_message(output, timed_out=...)` +- `run_tailscale_up(binary_path, notify=..., timeout=..., socket_path=...)` +- `ensure_tailscale_funnel_command(binary_path, socket_path=...)` +- `ensure_tailscale_ready(binary_path, notify=...)` +- Notable constants/configuration names: `TAILSCALE_URL_RE`, `TAILSCALE_LOGIN_URL_RE`, `TAILSCALE_STABLE_PACKAGES_URL`, `TAILSCALE_UP_TIMEOUT`, `TAILSCALE_FUNNEL_TIMEOUT`, `TAILSCALE_FUNNEL_HTTPS_PORT`, `TAILSCALE_DAEMON_START_TIMEOUT`, `TAILSCALE_RUNTIME_DIR`, `TAILSCALE_STATE_DIR`, `TAILSCALE_SOCKET_PATH`, `TAILSCALE_DAEMON_LOG_PATH`, `TAILSCALE_DAEMON_PID_PATH`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, WebSocket state, settings/state persistence, tunnel state. +- Imported dependency areas include: `collections`, `flaredantic`, `helpers`, `helpers.cli_tunnel`, `json`, `os`, `pathlib`, `queue`, `re`, `shutil`, `subprocess`, `threading`, `time`, `urllib.parse`, `urllib.request`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `re.compile`, `Path`, `files.get_abs_path`, `cli_tunnel.platform_parts`, `tailscale_arch`, `pattern.search`, `urllib.parse.urljoin`, `shutil.which`, `tailscale_archive_url`, `cli_tunnel.download_file`, `Path.with_name`, `sibling.exists`, `callable`, `subprocess.run`, `join`, `output.lower`, `tailscale_status`, `compact_output`, `resolve_tailscaled_binary`, `tailscale_daemon_ready`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/task_scheduler.py.dox.md b/helpers/task_scheduler.py.dox.md new file mode 100644 index 000000000..7292b4faf --- /dev/null +++ b/helpers/task_scheduler.py.dox.md @@ -0,0 +1,112 @@ +# task_scheduler.py DOX + +## Purpose + +- Own the `task_scheduler.py` helper module. +- This module models, serializes, schedules, runs, and persists scheduled tasks. +- Keep this file-level DOX profile synchronized with `task_scheduler.py` because this directory is intentionally flat. + +## Ownership + +- `task_scheduler.py` owns the runtime implementation. +- `task_scheduler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `TaskState` (`str`, `Enum`) +- `TaskType` (`str`, `Enum`) +- `TaskSchedule` (`BaseModel`) + - `to_crontab(self) -> str` +- `TaskPlan` (`BaseModel`) + - `create(cls, todo: list[datetime] | None=..., in_progress: datetime | None=..., done: list[datetime] | None=...)` + - `add_todo(self, launch_time: datetime)` + - `set_in_progress(self, launch_time: datetime)` + - `set_done(self, launch_time: datetime)` + - `get_next_launch_time(self) -> datetime | None` + - `should_launch(self) -> datetime | None` +- `BaseTask` (`BaseModel`) + - `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., **kwargs)` + - `check_schedule(self, frequency_seconds: float=...) -> bool` + - `get_next_run(self) -> datetime | None` + - `is_dedicated(self) -> bool` + - `get_next_run_minutes(self) -> int | None` + - `async on_run(self)` + - `async on_finish(self)` + - `async on_error(self, error: str)` +- `AdHocTask` (`BaseTask`) + - `create(cls, name: str, system_prompt: str, prompt: str, token: str, attachments: list[str] | None=..., context_id: str | None=..., project_name: str | None=..., project_color: str | None=...)` + - `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., token: str | None=..., **kwargs)` +- `ScheduledTask` (`BaseTask`) + - `create(cls, name: str, system_prompt: str, prompt: str, schedule: TaskSchedule, attachments: list[str] | None=..., context_id: str | None=..., timezone: str | None=..., project_name: str | None=..., project_color: str | None=...)` + - `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., schedule: TaskSchedule | None=..., **kwargs)` + - `check_schedule(self, frequency_seconds: float=...) -> bool` + - `get_next_run(self) -> datetime | None` +- `PlannedTask` (`BaseTask`) + - `create(cls, name: str, system_prompt: str, prompt: str, plan: TaskPlan, attachments: list[str] | None=..., context_id: str | None=..., project_name: str | None=..., project_color: str | None=...)` + - `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., plan: TaskPlan | None=..., **kwargs)` + - `check_schedule(self, frequency_seconds: float=...) -> bool` + - `get_next_run(self) -> datetime | None` + - `async on_run(self)` + - `async on_finish(self)` + - `async on_success(self, result: str)` + - `async on_error(self, error: str)` +- `SchedulerTaskList` (`BaseModel`) + - `get(cls) -> 'SchedulerTaskList'` + - `async reload(self) -> 'SchedulerTaskList'` + - `async add_task(self, task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> 'SchedulerTaskList'` + - `async save(self) -> 'SchedulerTaskList'` + - `async update_task_by_uuid(self, task_uuid: str, updater_func: Callable[[Union[ScheduledTask, AdHocTask, PlannedTask]], None], verify_func: Callable[[Union[ScheduledTask, AdHocTask, PlannedTask]], bool]=...) -> Union[ScheduledTask, AdHocTask, PlannedTask] | None` + - `get_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]` + - `get_tasks_by_context_id(self, context_id: str, only_running: bool=...) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]` + - `async get_due_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]` +- `TaskScheduler` (no explicit base class) + - `get(cls) -> 'TaskScheduler'` + - `cancel_running_task(self, task_uuid: str, terminate_thread: bool=...) -> bool` + - `cancel_tasks_by_context(self, context_id: str, terminate_thread: bool=...) -> bool` + - `async reload(self)` + - `get_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]` + - `get_tasks_by_context_id(self, context_id: str, only_running: bool=...) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]` + - `async add_task(self, task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> 'TaskScheduler'` + - `async remove_task_by_uuid(self, task_uuid: str) -> 'TaskScheduler'` +- Top-level functions: +- `normalize_schedule_timezone(timezone_name: str | None) -> str` +- `_now() -> datetime` +- `_localize_task_datetime(dt: datetime) -> datetime` +- `serialize_datetime(dt: Optional[datetime]) -> Optional[str]`: Serialize a datetime object to ISO format string in the user's timezone. +- `parse_datetime(dt_str: Optional[str]) -> Optional[datetime]`: Parse ISO format datetime string with timezone awareness. +- `serialize_task_schedule(schedule: TaskSchedule) -> Dict[str, str]`: Convert TaskSchedule to a standardized dictionary format. +- `parse_task_schedule(schedule_data: Dict[str, str]) -> TaskSchedule`: Parse dictionary into TaskSchedule with validation. +- `serialize_task_plan(plan: TaskPlan) -> Dict[str, Any]`: Convert TaskPlan to a standardized dictionary format. +- `parse_task_plan(plan_data: Dict[str, Any]) -> TaskPlan`: Parse dictionary into TaskPlan with validation. +- `serialize_task(task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> Dict[str, Any]`: Standardized serialization for task objects with proper handling of all complex types. +- `serialize_tasks(tasks: list[Union[ScheduledTask, AdHocTask, PlannedTask]]) -> list[Dict[str, Any]]`: Serialize a list of tasks to a list of dictionaries. +- `deserialize_task(task_data: Dict[str, Any], task_class: Optional[Type[T]]=...) -> T`: Deserialize dictionary into appropriate task object with validation. +- Notable constants/configuration names: `SCHEDULER_FOLDER`, `LOCAL_TIMEZONE_ALIASES`, `T`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `agent`, `asyncio`, `crontab`, `datetime`, `enum`, `helpers`, `helpers.defer`, `helpers.files`, `helpers.localization`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `nest_asyncio`, `os`, `os.path`, `pydantic`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `nest_asyncio.apply`, `TypeVar`, `str.strip`, `callable`, `datetime.now`, `tzinfo.localize`, `Field`, `PrivateAttr`, `Localization.get.serialize_datetime`, `normalize_schedule_timezone`, `Localization.get.get_timezone`, `pytz.timezone`, `now`, `localize`, `cls`, `_localize_task_datetime`, `self.todo.remove`, `self.get_next_launch_time`, `super.__init__`, `threading.RLock`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_task_scheduler_timezone.py` + - `tests/test_timezone_regressions.py` + - `tests/test_tool_action_contracts.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/timed_input.py.dox.md b/helpers/timed_input.py.dox.md new file mode 100644 index 000000000..5bcc3ce95 --- /dev/null +++ b/helpers/timed_input.py.dox.md @@ -0,0 +1,40 @@ +# timed_input.py DOX + +## Purpose + +- Own the `timed_input.py` helper module. +- This module reads terminal input with timeout handling. +- Keep this file-level DOX profile synchronized with `timed_input.py` because this directory is intentionally flat. + +## Ownership + +- `timed_input.py` owns the runtime implementation. +- `timed_input.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `timeout_input(prompt, timeout=...)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `inputimeout`, `sys`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `inputimeout`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/tokens.py.dox.md b/helpers/tokens.py.dox.md new file mode 100644 index 000000000..c42637a8e --- /dev/null +++ b/helpers/tokens.py.dox.md @@ -0,0 +1,54 @@ +# tokens.py DOX + +## Purpose + +- Own the `tokens.py` helper module. +- This module counts and approximates tokens and trims text to budgets. +- Keep this file-level DOX profile synchronized with `tokens.py` because this directory is intentionally flat. + +## Ownership + +- `tokens.py` owns the runtime implementation. +- `tokens.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `count_tokens(text: str, encoding_name=...) -> int` +- `approximate_tokens(text: str) -> int` +- `sanitize_embedded_image_data_urls(text: str) -> str` +- `approximate_prompt_tokens(text: str) -> int` +- `trim_to_tokens(text: str, max_tokens: int, direction: Literal['start', 'end'], ellipsis: str=...) -> str` +- Notable constants/configuration names: `APPROX_BUFFER`, `TRIM_BUFFER`, `EMBEDDED_IMAGE_DATA_PLACEHOLDER`, `_EMBEDDED_IMAGE_DATA_URL_PATTERN`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: secret handling. +- Imported dependency areas include: `re`, `tiktoken`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `re.compile`, `tiktoken.get_encoding`, `encoding.encode`, `_EMBEDDED_IMAGE_DATA_URL_PATTERN.sub`, `approximate_tokens`, `count_tokens`, `sanitize_embedded_image_data_urls`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_chat_compaction.py` + - `tests/test_default_prompt_budget.py` + - `tests/test_history_compression_wait.py` + - `tests/test_mcp_handler_multimodal.py` + - `tests/test_oauth_codex.py` + - `tests/test_oauth_gemini_api.py` + - `tests/test_oauth_xai_grok.py` + - `tests/test_ws_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/tool.py.dox.md b/helpers/tool.py.dox.md new file mode 100644 index 000000000..5577d7fbc --- /dev/null +++ b/helpers/tool.py.dox.md @@ -0,0 +1,58 @@ +# tool.py DOX + +## Purpose + +- Own the `tool.py` helper module. +- This module defines the base agent tool class and response contract. +- Keep this file-level DOX profile synchronized with `tool.py` because this directory is intentionally flat. + +## Ownership + +- `tool.py` owns the runtime implementation. +- `tool.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Response` (no explicit base class) +- `Tool` (no explicit base class) + - `async execute(self, **kwargs) -> Response` + - `async set_progress(self, content: str | None)` + - `add_progress(self, content: str | None)` + - `async before_execution(self, **kwargs)` + - `async after_execution(self, response: Response, **kwargs)` + - `get_log_object(self)` + - `nice_key(self, key: str)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- `Tool` defines `execute(...)`. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `abc`, `agent`, `dataclasses`, `helpers.extension`, `helpers.print_style`, `helpers.strings`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.get_log_object`, `sanitize_string`, `self.agent.hist_add_tool_result`, `self.agent.context.log.log`, `key.split`, `join`, `call_extensions_async`, `response.message.strip`, `uuid.uuid4`, `PrintStyle`, `PrintStyle.stream`, `words.capitalize`, `word.lower`, `self.nice_key`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_default_prompt_budget.py` + - `tests/test_dirty_json.py` + - `tests/test_document_query_plugin.py` + - `tests/test_fastmcp_openapi_security.py` + - `tests/test_host_browser_connector.py` + - `tests/test_mcp_handler_multimodal.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/tunnel_common.py.dox.md b/helpers/tunnel_common.py.dox.md new file mode 100644 index 000000000..2aa35d8ca --- /dev/null +++ b/helpers/tunnel_common.py.dox.md @@ -0,0 +1,51 @@ +# tunnel_common.py DOX + +## Purpose + +- Own the `tunnel_common.py` helper module. +- This module contains shared tunnel provider helper classes and event parsing. +- Keep this file-level DOX profile synchronized with `tunnel_common.py` because this directory is intentionally flat. + +## Ownership + +- `tunnel_common.py` owns the runtime implementation. +- `tunnel_common.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `TunnelHelper` (no explicit base class) + - `notify_starting(self, label)` + - `notify_url_ready(self, label, url)` + - `notify_stopped(self, label)` +- `FlaredanticTunnelHelper` (`TunnelHelper`) + - `build_tunnel(self)` + - `start(self)` + - `stop(self)` +- Top-level functions: +- `event_value(event)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: tunnel state. +- Imported dependency areas include: `flaredantic`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `callable`, `self._notify`, `self.notify_starting`, `self.build_tunnel`, `self.tunnel.start`, `self.notify_stopped`, `self.notify_callback`, `self.notify_url_ready`, `self.tunnel.stop`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/tunnel_manager.py.dox.md b/helpers/tunnel_manager.py.dox.md new file mode 100644 index 000000000..c90749a20 --- /dev/null +++ b/helpers/tunnel_manager.py.dox.md @@ -0,0 +1,51 @@ +# tunnel_manager.py DOX + +## Purpose + +- Own the `tunnel_manager.py` helper module. +- This module selects and coordinates configured tunnel providers. +- Keep this file-level DOX profile synchronized with `tunnel_manager.py` because this directory is intentionally flat. + +## Ownership + +- `tunnel_manager.py` owns the runtime implementation. +- `tunnel_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `TunnelManager` (no explicit base class) + - `get_instance(cls)` + - `get_notifications(self)` + - `get_last_error(self)` + - `start_tunnel(self, port=..., provider=...)` + - `stop_tunnel(self)` + - `get_tunnel_url(self)` +- Top-level functions: +- `normalize_provider(provider)` +- Notable constants/configuration names: `SUPPORTED_TUNNEL_PROVIDERS`, `TUNNEL_PROVIDER_ALIASES`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: tunnel state. +- Imported dependency areas include: `collections`, `flaredantic`, `helpers.cloudflare_tunnel`, `helpers.microsoft_tunnel`, `helpers.print_style`, `helpers.serveo_tunnel`, `helpers.tailscale_tunnel`, `helpers.tunnel_common`, `threading`, `time`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `strip.lower`, `threading.Lock`, `join`, `ValueError`, `deque`, `self.notifications.clear`, `ServeoTunnelHelper`, `self._ensure_subscribed`, `strip`, `notifier.subscribe`, `CloudflareTunnel`, `MicrosoftDevTunnel`, `TailscaleTunnel`, `normalize_provider`, `threading.Thread`, `tunnel_thread.start`, `cls`, `event_value`, `PrintStyle.error`, `self._append_notification`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_tunnel_remote_link.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/ui_server.py.dox.md b/helpers/ui_server.py.dox.md new file mode 100644 index 000000000..5f634884e --- /dev/null +++ b/helpers/ui_server.py.dox.md @@ -0,0 +1,57 @@ +# ui_server.py DOX + +## Purpose + +- Own the `ui_server.py` helper module. +- This module configures and owns Flask/WebUI runtime route handlers. +- Keep this file-level DOX profile synchronized with `ui_server.py` because this directory is intentionally flat. + +## Ownership + +- `ui_server.py` owns the runtime implementation. +- `ui_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `UiServerRuntime` (no explicit base class) + - `create(cls) -> 'UiServerRuntime'` + - `refresh_runtime_settings(self) -> None` + - `register_http_routes(self) -> None` + - `register_transport_handlers(self) -> None` + - `build_asgi_app(self, startup_monitor: StartupMonitor)` + - `access_log_enabled(self) -> bool` +- `UiRouteHandlers` (no explicit base class) + - `async login_handler(self)` + - `async logout_handler(self)` + - `async serve_index(self)` + - `async serve_builtin_plugin_asset(self, plugin_name, asset_path)` + - `async serve_plugin_asset(self, plugin_name, asset_path)` + - `async serve_extension_asset(self, asset_path)` +- Top-level functions: +- `configure_process_environment() -> None` +- Notable constants/configuration names: `UPLOAD_LIMIT_BYTES`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, WebSocket state, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `asyncio`, `dataclasses`, `datetime`, `flask`, `helpers`, `helpers.api`, `helpers.extension`, `helpers.files`, `helpers.print_style`, `helpers.server_startup`, `helpers.ws`, `helpers.ws_manager`, `logging`, `os`, `secrets`, `socketio`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `logging.getLogger.setLevel`, `Localization.get.apply_process_timezone`, `field`, `Flask`, `threading.RLock`, `socketio.AsyncServer`, `WsManager`, `set_shared_ws_manager`, `cls`, `server_runtime.refresh_runtime_settings`, `settings_helper.get_settings`, `settings_helper.set_runtime_settings_snapshot`, `self.ws_manager.set_server_restart_broadcast`, `UiRouteHandlers`, `self.webapp.add_url_rule`, `register_api_route`, `register_ws_namespace`, `files.read_file`, `render_template_string`, `session.pop`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/update_check.py.dox.md b/helpers/update_check.py.dox.md new file mode 100644 index 000000000..f25ef598a --- /dev/null +++ b/helpers/update_check.py.dox.md @@ -0,0 +1,41 @@ +# update_check.py DOX + +## Purpose + +- Own the `update_check.py` helper module. +- This module checks available Agent Zero updates. +- Keep this file-level DOX profile synchronized with `update_check.py` because this directory is intentionally flat. + +## Ownership + +- `update_check.py` owns the runtime implementation. +- `update_check.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `async check_version()` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: network calls, settings/state persistence. +- Imported dependency areas include: `hashlib`, `helpers`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `git.get_version`, `git.is_official_agent_zero_repo`, `hashlib.sha256.hexdigest`, `httpx.AsyncClient`, `response.json`, `client.post`, `hashlib.sha256`, `runtime.get_persistent_id.encode`, `runtime.get_persistent_id`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/vector_db.py.dox.md b/helpers/vector_db.py.dox.md new file mode 100644 index 000000000..bc88f84a1 --- /dev/null +++ b/helpers/vector_db.py.dox.md @@ -0,0 +1,53 @@ +# vector_db.py DOX + +## Purpose + +- Own the `vector_db.py` helper module. +- This module wraps FAISS vector storage, retrieval, and comparator behavior. +- Keep this file-level DOX profile synchronized with `vector_db.py` because this directory is intentionally flat. + +## Ownership + +- `vector_db.py` owns the runtime implementation. +- `vector_db.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `MyFaiss` (`FAISS`) + - `get_by_ids(self, ids: Sequence[str]) -> List[Document]` + - `async aget_by_ids(self, ids: Sequence[str]) -> List[Document]` + - `get_all_docs(self) -> dict[str, Document]` +- `VectorDB` (no explicit base class) + - `async search_by_similarity_threshold(self, query: str, limit: int, threshold: float, filter: str=...)` + - `async search_by_metadata(self, filter: str, limit: int=...) -> list[Document]` + - `async insert_documents(self, docs: list[Document])` + - `async delete_documents_by_ids(self, ids: list[str])` +- Top-level functions: +- `format_docs_plain(docs: list[Document]) -> list[str]` +- `cosine_normalizer(val: float) -> float` +- `get_comparator(condition: str)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem deletion. +- Imported dependency areas include: `agent`, `faiss`, `helpers`, `langchain.embeddings`, `langchain.storage`, `langchain_community.docstore.in_memory`, `langchain_community.vectorstores`, `langchain_community.vectorstores.utils`, `langchain_core.documents`, `simpleeval`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.get_by_ids`, `agent.get_embedding_model`, `self._get_embeddings`, `faiss.IndexFlatIP`, `MyFaiss`, `get_comparator`, `self.db.get_all_docs`, `InMemoryByteStore`, `CacheBackedEmbeddings.from_bytes_store`, `self.db.asearch`, `comparator`, `guids.generate_id`, `zip`, `self.db.add_documents`, `self.db.aget_by_ids`, `simple_eval`, `self.embeddings.embed_query`, `InMemoryDocstore`, `self.db.adelete`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/helpers/virtual_desktop.py.dox.md b/helpers/virtual_desktop.py.dox.md new file mode 100644 index 000000000..34e7b2510 --- /dev/null +++ b/helpers/virtual_desktop.py.dox.md @@ -0,0 +1,74 @@ +# virtual_desktop.py DOX + +## Purpose + +- Own the `virtual_desktop.py` helper module. +- This module registers and proxies virtual desktop sessions. +- Keep this file-level DOX profile synchronized with `virtual_desktop.py` because this directory is intentionally flat. + +## Ownership + +- `virtual_desktop.py` owns the runtime implementation. +- `virtual_desktop.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `VirtualDesktopEndpoint` (no explicit base class) +- `VirtualDesktopRegistry` (no explicit base class) + - `register(self, endpoint: VirtualDesktopEndpoint) -> None` + - `unregister(self, token: str) -> None` + - `proxy_for_token(self, token: str) -> VirtualDesktopEndpoint | None` + - `resize(self, token: str, width: int, height: int) -> dict[str, Any]` +- Top-level functions: +- `register_session(token: str, host: str, port: int, owner: str=..., title: str=..., resize: ResizeCallback | None=...) -> None` +- `unregister_session(token: str) -> None` +- `proxy_for_token(token: str) -> VirtualDesktopEndpoint | None` +- `resize_session(token: str, width: int, height: int) -> dict[str, Any]` +- `get_registry() -> VirtualDesktopRegistry` +- `session_url(token: str, title: str=...) -> str` +- `collect_status() -> dict[str, Any]` +- `find_xpra_html_root() -> Path | None` +- `_package_installed(package: str) -> bool` +- `normalize_size(width: int | float | str, height: int | float | str, max_width: int=..., max_height: int=..., min_width: int=..., min_height: int=...) -> tuple[int, int]` +- `normalize_desktop_display_size(width: int | float | str, height: int | float | str, max_width: int=..., max_height: int=..., min_width: int=..., min_height: int=..., min_aspect_ratio: float=...) -> tuple[int, int]` +- `resize_display(display: int, width: int, height: int, max_width: int=..., max_height: int=..., window_class: str=..., keys: tuple[str, ...]=..., xauthority: str=..., home: str=...) -> dict[str, Any]` +- `_ensure_xrandr_mode(env: dict[str, str], width: int, height: int) -> None` +- `_select_xrandr_mode(env: dict[str, str], width: int, height: int) -> subprocess.CompletedProcess[str]` +- `_xrandr_output_modes(env: dict[str, str]) -> tuple[str, set[str]]` +- `current_display_size(display: int, xauthority: str=..., home: str=...) -> tuple[int, int] | None` +- `fit_window_until(display: int, width: int, height: int, window_class: str=..., keys: tuple[str, ...]=..., settle_seconds: float=..., timeout_seconds: float=..., process: subprocess.Popen[Any] | None=..., xauthority: str=..., home: str=...) -> None` +- `fit_window(display: int, width: int, height: int, window_class: str=..., keys: tuple[str, ...]=..., xauthority: str=..., home: str=...) -> bool` +- `has_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> bool` +- `find_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> str` +- `close_windows(display: int, names: tuple[str, ...]=..., window_class: str=..., xauthority: str=..., home: str=...) -> int` +- `_find_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> str` +- `_display_env(display: int, xauthority: str=..., home: str=...) -> dict[str, str]` +- Notable constants/configuration names: `STATE_DIR`, `DEFAULT_WIDTH`, `DEFAULT_HEIGHT`, `MAX_WIDTH`, `MAX_HEIGHT`, `MIN_WIDTH`, `MIN_HEIGHT`, `MIN_DESKTOP_ASPECT_RATIO`, `SESSION_PATH`, `XPRA_HTML_ROOT_CANDIDATES`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, network calls, subprocess/runtime control, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `helpers.localization`, `math`, `os`, `pathlib`, `re`, `shutil`, `subprocess`, `threading`, `time`, `typing`, `urllib.parse`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Path`, `files.get_abs_path`, `get_registry.register`, `get_registry.unregister`, `get_registry.proxy_for_token`, `get_registry.resize`, `quote`, `urlencode`, `find_xpra_html_root`, `subprocess.run`, `normalize_size`, `shutil.which`, `_display_env`, `current_display_size`, `_ensure_xrandr_mode`, `_select_xrandr_mode`, `time.sleep`, `strip`, `_xrandr_output_modes`, `result.stdout.splitlines`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_office_canvas_setup.py` + - `tests/test_office_desktop_state.py` + - `tests/test_office_document_store.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/virtual_desktop_routes.py.dox.md b/helpers/virtual_desktop_routes.py.dox.md new file mode 100644 index 000000000..b784fca80 --- /dev/null +++ b/helpers/virtual_desktop_routes.py.dox.md @@ -0,0 +1,55 @@ +# virtual_desktop_routes.py DOX + +## Purpose + +- Own the `virtual_desktop_routes.py` helper module. +- This module installs virtual desktop gateway route hooks. +- Keep this file-level DOX profile synchronized with `virtual_desktop_routes.py` because this directory is intentionally flat. + +## Ownership + +- `virtual_desktop_routes.py` owns the runtime implementation. +- `virtual_desktop_routes.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `VirtualDesktopGateway` (no explicit base class) + - `async http(self, scope: Scope, receive: Receive, send: Send) -> None` + - `async resize(self, scope: Scope, receive: Receive, send: Send) -> None` + - `async proxy_http(self, scope: Scope, receive: Receive, send: Send, token: str, upstream_path: str) -> None` + - `async websocket(self, scope: Scope, receive: Receive, send: Send) -> None` + - `async open_websocket(self, endpoint: virtual_desktop.VirtualDesktopEndpoint, target: str, subprotocols: tuple[str, ...]) -> tuple[asyncio.StreamReader, asyncio.StreamWriter, WSConnection, str | None]` + - `async browser_to_xpra(self, websocket: WebSocket, upstream: WSConnection, writer: asyncio.StreamWriter) -> None` + - `async xpra_to_browser(self, websocket: WebSocket, upstream: WSConnection, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None` + - `session_request(self, path: str) -> tuple[str, str] | None` +- Top-level functions: +- `install_route_hooks() -> None` +- `is_installed() -> bool` +- Notable constants/configuration names: `HOP_BY_HOP_HEADERS`, `XPRA_MENU_CUSTOM_PATCH`, `XPRA_WINDOW_OFFSET_WARNING`, `XPRA_WINDOW_OFFSET_WARNING_PATCH`, `XPRA_WINDOW_SCRIPT`, `XPRA_WINDOW_SCRIPT_PATCH`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem deletion, network calls, subprocess/runtime control, WebSocket state, settings/state persistence, secret handling. +- Imported dependency areas include: `__future__`, `asyncio`, `flask.sessions`, `helpers`, `http.client`, `http.cookies`, `starlette.requests`, `starlette.responses`, `starlette.types`, `starlette.websockets`, `urllib.parse`, `wsproto`, `wsproto.events`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.relative_path`, `self.session_request`, `self.query`, `virtual_desktop.proxy_for_token`, `WebSocket`, `self.upstream_target`, `WSConnection`, `writer.write`, `rest.partition`, `unquote`, `quote`, `http.client.HTTPConnection`, `query_string.decode`, `urlsplit`, `location.startswith`, `path.startswith`, `parse_qs`, `login.get_credentials_hash`, `SecureCookieSessionInterface.get_signing_serializer`, `dict.get.decode`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_office_canvas_setup.py` + - `tests/test_office_document_store.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/wait.py.dox.md b/helpers/wait.py.dox.md new file mode 100644 index 000000000..a647c28ef --- /dev/null +++ b/helpers/wait.py.dox.md @@ -0,0 +1,49 @@ +# wait.py DOX + +## Purpose + +- Own the `wait.py` helper module. +- This module formats and runs managed waits with progress updates. +- Keep this file-level DOX profile synchronized with `wait.py` because this directory is intentionally flat. + +## Ownership + +- `wait.py` owns the runtime implementation. +- `wait.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `format_remaining_time(total_seconds: float) -> str` +- `async managed_wait(agent, target_time, is_duration_wait, log, get_heading_callback)` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Imported dependency areas include: `asyncio`, `helpers.localization`, `helpers.print_style`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `divmod`, `join`, `Localization.get.now`, `total_seconds`, `agent.handle_intervention`, `asyncio.sleep`, `pause_duration.total_seconds`, `PrintStyle.info`, `get_heading_callback`, `format_remaining_time`, `Localization.get.serialize_datetime`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/email_parser_test.py` + - `tests/rate_limiter_test.py` + - `tests/test_api_chat_lifetime.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_chat_compaction.py` + - `tests/test_default_prompt_budget.py` + - `tests/test_document_query_plugin.py` + - `tests/test_download_toast_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/watchdog.py.dox.md b/helpers/watchdog.py.dox.md new file mode 100644 index 000000000..920b4703c --- /dev/null +++ b/helpers/watchdog.py.dox.md @@ -0,0 +1,72 @@ +# watchdog.py DOX + +## Purpose + +- Own the `watchdog.py` helper module. +- This module registers filesystem watchdogs with debouncing and path filtering. +- Keep this file-level DOX profile synchronized with `watchdog.py` because this directory is intentionally flat. + +## Ownership + +- `watchdog.py` owns the runtime implementation. +- `watchdog.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `_DispatchHandler` (no explicit base class) + - `dispatch(self, event: Any)` +- `_Watch` (no explicit base class) +- `_PendingBatch` (no explicit base class) +- `_WatchRegistry` (no explicit base class) + - `add(self, id: str, roots: list[str], patterns: list[str] | None, ignore_patterns: list[str] | None, events: WatchEvents, debounce: float, handler: WatchHandler) -> None` + - `remove(self, id: str) -> bool` + - `clear(self) -> None` + - `start(self) -> None` + - `stop(self) -> None` + - `dispatch(self, scheduled_root: str, event: Any) -> None` +- Top-level functions: +- `_normalize_root(root: str) -> str` +- `_normalize_roots(roots: list[str]) -> list[str]` +- `_normalize_patterns(patterns: list[str] | None, default: list[str] | None=...) -> list[str]` +- `_normalize_events(events: WatchEvents) -> frozenset[WatchEvent]` +- `_map_event_type(event_type: str) -> WatchEvent | None` +- `_normalize_debounce(debounce: float) -> float` +- `_covering_roots(roots: Iterable[str]) -> set[str]` +- `_is_same_or_nested(path: str, root: str) -> bool` +- `_is_under_watch(path: str, watch: _Watch) -> bool` +- `_compile_matcher(root: str, patterns: list[str], ignore_patterns: list[str]) -> PatternMatcher` +- `_compile_single_matcher(root: str, patterns: list[str]) -> PatternMatcher` +- `add_watchdog(id: str, roots: list[str], patterns: list[str] | None=..., ignore_patterns: list[str] | None=..., events: WatchEvents=..., debounce: float=..., handler: WatchHandler | None=...) -> None` +- `remove_watchdog(id: str) -> bool` +- `clear_watchdogs() -> None` +- `start_watchdog_daemon() -> None` +- `stop_watchdog_daemon() -> None` +- Notable constants/configuration names: `_DEFAULT_PATTERNS`, `_DEFAULT_IGNORE_PATTERNS`, `_VALID_EVENTS`, `_EVENT_ALIASES`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion. +- Imported dependency areas include: `__future__`, `dataclasses`, `os`, `pathlib`, `threading`, `typing`, `watchdog.observers`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `frozenset`, `dataclass`, `_WatchRegistry`, `_registry.start`, `os.path.abspath`, `_compile_single_matcher`, `_registry.add`, `_registry.remove`, `_registry.clear`, `_registry.stop`, `self.registry.dispatch`, `threading.RLock`, `self._ensure_watchdog_available`, `_normalize_roots`, `_normalize_patterns`, `_normalize_events`, `_normalize_debounce`, `self._stop_observer`, `_map_event_type`, `_covering_roots`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_model_config_api_keys.py` + - `tests/test_model_config_project_presets.py` + - `tests/test_time_travel.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/ws.py.dox.md b/helpers/ws.py.dox.md new file mode 100644 index 000000000..5eb7279f6 --- /dev/null +++ b/helpers/ws.py.dox.md @@ -0,0 +1,75 @@ +# ws.py DOX + +## Purpose + +- Own the `ws.py` helper module. +- This module defines WebSocket handler registration, origin validation, and security checks. +- Keep this file-level DOX profile synchronized with `ws.py` because this directory is intentionally flat. + +## Ownership + +- `ws.py` owns the runtime implementation. +- `ws.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ConnectionNotFoundError` (`RuntimeError`) +- `_SecurityContext` (no explicit base class) +- `WsHandler` (no explicit base class) + - `namespace(self) -> str` + - `manager(self) -> 'WsManager'` + - `identifier(self) -> str` + - `bind_manager(self, manager: 'WsManager', namespace: str | None=...) -> None` + - `requires_loopback(cls) -> bool` + - `requires_api_key(cls) -> bool` + - `requires_auth(cls) -> bool` + - `requires_csrf(cls) -> bool` +- Top-level functions: +- `_ws_debug_enabled() -> bool`: Check A0_WS_DEBUG env var - lightweight, no heavy imports. +- `ws_debug(message: str) -> None`: Log *message* via :class:`PrintStyle` when ``A0_WS_DEBUG`` is active. +- `_default_port_for_scheme(scheme: str) -> int | None` +- `normalize_origin(value: Any) -> str | None`: Normalize an Origin/Referer header value to scheme://host[:port]. +- `_parse_host_header(value: Any) -> tuple[str | None, int | None]` +- `validate_ws_origin(environ: dict[str, Any]) -> tuple[bool, str | None]`: Validate the browser Origin during the Socket.IO handshake. +- `_check_security(handler_cls: type[WsHandler], ctx: _SecurityContext) -> dict[str, Any] | None`: Return an error payload dict if the check fails, or ``None`` on success. +- `register_ws_namespace(socketio_server: socketio.AsyncServer, webapp: Flask, lock: ThreadLockType, manager: 'WsManager | None'=...) -> None` +- `_error_response(code: str, message: str, correlation_id: str) -> dict[str, Any]` +- Notable constants/configuration names: `NAMESPACE`, `CACHE_AREA`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- `WsHandler` defines `process(...)`. +- `WsHandler` defines `requires_auth(...)`. +- `WsHandler` defines `requires_csrf(...)`. +- `WsHandler` defines `requires_api_key(...)`. +- `WsHandler` defines `requires_loopback(...)`. +- Observed side-effect areas: filesystem reads, filesystem deletion, network calls, WebSocket state, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `abc`, `dataclasses`, `flask`, `helpers`, `helpers.errors`, `helpers.network`, `helpers.print_style`, `os`, `pathlib`, `socketio`, `threading`, `typing`, `urllib.parse`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `threading.Lock`, `os.getenv.strip.lower`, `_ws_debug_enabled`, `urlparse`, `normalize_origin`, `_parse_host_header`, `handler_cls.requires_loopback`, `handler_cls.requires_auth`, `handler_cls.requires_csrf`, `handler_cls.requires_api_key`, `socketio_server.on`, `PrintStyle.debug`, `value.strip`, `origin_parsed.hostname.lower`, `_default_port_for_scheme`, `req_host.lower`, `forwarded_host_raw.strip`, `forwarded_host_raw.split.strip`, `forwarded_proto_raw.strip`, `forwarded_proto_raw.split.strip.lower`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_computer_use_metadata.py` + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_docker_release_plan.py` + - `tests/test_download_toast_regressions.py` + - `tests/test_git_version_label.py` + - `tests/test_host_browser_connector.py` + - `tests/test_multi_tab_isolation.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/ws_manager.py.dox.md b/helpers/ws_manager.py.dox.md new file mode 100644 index 000000000..3d8f6da61 --- /dev/null +++ b/helpers/ws_manager.py.dox.md @@ -0,0 +1,70 @@ +# ws_manager.py DOX + +## Purpose + +- Own the `ws_manager.py` helper module. +- This module manages WebSocket connections, event validation, buffering, and dispatch. +- Keep this file-level DOX profile synchronized with `ws_manager.py` because this directory is intentionally flat. + +## Ownership + +- `ws_manager.py` owns the runtime implementation. +- `ws_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `WsResult` (no explicit base class) + - `ok(cls, data: dict[str, Any] | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'` + - `error(cls, code: str, message: str, details: Any | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'` + - `as_result(self, handler_id: str, fallback_correlation_id: str | None, duration_ms: float | None=...) -> dict[str, Any]` +- `BufferedEvent` (no explicit base class) +- `ConnectionInfo` (no explicit base class) +- `_HandlerExecution` (no explicit base class) +- `WsManager` (no explicit base class) + - `register_diagnostic_watcher(self, namespace: str, sid: str) -> bool` + - `unregister_diagnostic_watcher(self, namespace: str, sid: str) -> None` + - `register_handlers(self, handlers_by_namespace: dict[str, Iterable[WsHandler]]) -> None` + - `iter_namespaces(self) -> list[str]` + - `async process_client_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, handlers: list[WsHandler]) -> dict[str, Any]` + - `async handle_connect(self, namespace: str, sid: str, user_id: str | None=...) -> None` + - `async handle_disconnect(self, namespace: str, sid: str) -> None` + - `async route_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, ack: Optional[Callable[[Any], None]]=..., include_handlers: Set[str] | None=..., exclude_handlers: Set[str] | None=..., allow_exclude: bool=..., handler_id: str | None=...) -> dict[str, Any]` +- Top-level functions: +- `validate_event_type(event_type: str) -> str`: Validate an event name: must be lowercase_snake_case and not reserved. +- `async send_data(event_type: str, data: dict[str, Any], endpoint_name: str=..., connection_id: str | None=...) -> None`: Convenience wrapper around :pymeth:`WsManager.send_data`. +- `_utcnow() -> datetime` +- `set_shared_ws_manager(manager: 'WsManager') -> None` +- `get_shared_ws_manager() -> 'WsManager'` +- Notable constants/configuration names: `_EVENT_NAME_PATTERN`, `_RESERVED_EVENT_NAMES`, `BUFFER_MAX_SIZE`, `BUFFER_TTL`, `DIAGNOSTIC_EVENT`, `LIFECYCLE_CONNECT_EVENT`, `LIFECYCLE_DISCONNECT_EVENT`, `STATE_PUSH_EVENT`, `SERVER_RESTART_EVENT`, `ERR_NO_HANDLERS`, `ERR_HANDLER_ERROR`, `ERR_INVALID_FILTER`, `ERR_INVALID_EVENT`, `ERR_CONNECTION_NOT_FOUND`, `ERR_TIMEOUT`. + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem deletion, network calls, WebSocket state, settings/state persistence, scheduler state. +- Imported dependency areas include: `__future__`, `asyncio`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.defer`, `helpers.print_style`, `helpers.ws`, `os`, `re`, `socketio`, `threading`, `time`, `typing`, `uuid`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `re.compile`, `timedelta`, `get_shared_ws_manager`, `datetime.now`, `field`, `cls`, `TypeError`, `_EVENT_NAME_PATTERN.fullmatch`, `ValueError`, `manager.send_data`, `RuntimeError`, `defaultdict`, `runtime.is_development`, `ws_debug`, `self._ensure_dispatcher_loop`, `dispatcher_loop.is_closed`, `asyncio.run_coroutine_threadsafe`, `_utcnow.isoformat.replace`, `self._copy_diagnostic_watchers`, `self._lifecycle_tasks.add`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_host_browser_connector.py` + - `tests/test_state_sync_handler.py` + - `tests/test_state_sync_welcome_screen.py` + - `tests/test_tool_action_contracts.py` + - `tests/test_ws_handlers.py` + - `tests/test_ws_manager.py` + +## Child DOX Index + +No child DOX files. diff --git a/helpers/yaml.py.dox.md b/helpers/yaml.py.dox.md new file mode 100644 index 000000000..41f1da445 --- /dev/null +++ b/helpers/yaml.py.dox.md @@ -0,0 +1,52 @@ +# yaml.py DOX + +## Purpose + +- Own the `yaml.py` helper module. +- This module wraps YAML loading/dumping and JSON conversion helpers. +- Keep this file-level DOX profile synchronized with `yaml.py` because this directory is intentionally flat. + +## Ownership + +- `yaml.py` owns the runtime implementation. +- `yaml.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Top-level functions: +- `loads(text: str)` +- `dumps(obj, **kwargs) -> str` +- `from_json(text: str, **yaml_dump_kwargs) -> str` +- `to_json(text: str, **json_dump_kwargs) -> str` + +## Runtime Contracts + +- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. +- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. +- Observed side-effect areas: filesystem writes, settings/state persistence. +- Imported dependency areas include: `json`, `yaml`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `yaml.safe_load`, `yaml.safe_dump`, `dumps`, `loads`, `json.dumps`, `json.loads`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Preserve public helper APIs used by core code and plugins unless every caller is updated. +- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. +- Prefer adding cohesive helper functions here only when behavior is reused across modules. + +## Verification + +- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. +- Related tests observed by source search: + - `tests/test_a0_connector_prompt_gating.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_document_query_plugin.py` + - `tests/test_model_config_api_keys.py` + - `tests/test_model_config_project_presets.py` + - `tests/test_oauth_codex.py` + - `tests/test_oauth_providers.py` + - `tests/test_office_canvas_setup.py` + +## Child DOX Index + +No child DOX files. diff --git a/plugins/AGENTS.md b/plugins/AGENTS.md index ba9e518d3..2a60a0c5d 100644 --- a/plugins/AGENTS.md +++ b/plugins/AGENTS.md @@ -60,4 +60,35 @@ ## Child DOX Index -No child DOX files. +Direct child DOX files: + +| Child | Scope | +| --- | --- | +| [_a0_connector/AGENTS.md](_a0_connector/AGENTS.md) | HTTP and WebSocket connector integration with remote tools and runtime bridges. | +| [_browser/AGENTS.md](_browser/AGENTS.md) | Playwright browser tool, helpers, viewer, and browser panel UI. | +| [_chat_branching/AGENTS.md](_chat_branching/AGENTS.md) | Chat branching from an existing message. | +| [_chat_compaction/AGENTS.md](_chat_compaction/AGENTS.md) | Full-chat compaction into a summary message. | +| [_code_execution/AGENTS.md](_code_execution/AGENTS.md) | Terminal, Python, and Node.js execution tools and shell runtimes. | +| [_desktop/AGENTS.md](_desktop/AGENTS.md) | Linux desktop runtime, sessions, and desktop surface. | +| [_discovery/AGENTS.md](_discovery/AGENTS.md) | Welcome-screen plugin discovery cards and promotions. | +| [_document_query/AGENTS.md](_document_query/AGENTS.md) | Document parsing, indexing, and Q&A tools. | +| [_editor/AGENTS.md](_editor/AGENTS.md) | Native Markdown editor surface and sessions. | +| [_email_integration/AGENTS.md](_email_integration/AGENTS.md) | IMAP/Exchange polling and SMTP reply integration. | +| [_error_retry/AGENTS.md](_error_retry/AGENTS.md) | Critical exception retry lifecycle hooks. | +| [_infection_check/AGENTS.md](_infection_check/AGENTS.md) | Prompt-injection safety analysis before tool execution. | +| [_kokoro_tts/AGENTS.md](_kokoro_tts/AGENTS.md) | Kokoro text-to-speech integration. | +| [_memory/AGENTS.md](_memory/AGENTS.md) | Persistent vector memory, knowledge import, tools, and dashboard. | +| [_model_config/AGENTS.md](_model_config/AGENTS.md) | Model selection, presets, API-key checks, and scoped overrides. | +| [_oauth/AGENTS.md](_oauth/AGENTS.md) | OAuth-backed model-provider connections and local proxy routes. | +| [_office/AGENTS.md](_office/AGENTS.md) | LibreOffice office artifacts and office canvas sessions. | +| [_onboarding/AGENTS.md](_onboarding/AGENTS.md) | First-time model onboarding wizard. | +| [_plugin_installer/AGENTS.md](_plugin_installer/AGENTS.md) | Plugin install and update flows from ZIP, Git, and Plugin Index. | +| [_plugin_scan/AGENTS.md](_plugin_scan/AGENTS.md) | LLM-guided security scanner for third-party plugins. | +| [_plugin_validator/AGENTS.md](_plugin_validator/AGENTS.md) | Plugin manifest, structure, convention, and security validator. | +| [_promptinclude/AGENTS.md](_promptinclude/AGENTS.md) | Promptinclude scanning and prompt injection. | +| [_skills/AGENTS.md](_skills/AGENTS.md) | Active and hidden skill configuration and prompt injection. | +| [_telegram_integration/AGENTS.md](_telegram_integration/AGENTS.md) | Telegram bot integration and per-user chat sessions. | +| [_text_editor/AGENTS.md](_text_editor/AGENTS.md) | Native text read, write, and patch tool. | +| [_time_travel/AGENTS.md](_time_travel/AGENTS.md) | Workspace history, diff, travel, snapshot, and revert flows. | +| [_whatsapp_integration/AGENTS.md](_whatsapp_integration/AGENTS.md) | WhatsApp Baileys bridge integration. | +| [_whisper_stt/AGENTS.md](_whisper_stt/AGENTS.md) | Whisper speech-to-text integration. | diff --git a/plugins/_a0_connector/AGENTS.md b/plugins/_a0_connector/AGENTS.md new file mode 100644 index 000000000..3a9e483c2 --- /dev/null +++ b/plugins/_a0_connector/AGENTS.md @@ -0,0 +1,31 @@ +# A0 Connector Plugin DOX + +## Purpose + +- Own the current Agent Zero connector plugin for HTTP and WebSocket integration. +- Provide remote execution, text-editing freshness, and connector runtime bridges. + +## Ownership + +- `plugin.yaml` owns plugin metadata and settings scope. +- `api/` owns connector WebSocket and API entry points. +- `helpers/` owns chat context, event bridge, execution config, freshness, version, and WebSocket runtime helpers. +- `tools/`, `prompts/`, `skills/`, `extensions/`, and `webui/` own connector-facing agent and UI contributions. + +## Local Contracts + +- Preserve session-auth and `auth.handlers` activation assumptions. +- Keep remote tool prompts synchronized with remote tool behavior. +- Do not bypass WebSocket authentication or leak connector session data. + +## Work Guidance + +- Coordinate connector runtime changes with API, tools, prompts, and WebUI viewer behavior together. + +## Verification + +- Run connector-specific tests or smoke-test HTTP and `/ws` integration when changing runtime behavior. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_browser/AGENTS.md b/plugins/_browser/AGENTS.md new file mode 100644 index 000000000..96d9f905c --- /dev/null +++ b/plugins/_browser/AGENTS.md @@ -0,0 +1,32 @@ +# Browser Plugin DOX + +## Purpose + +- Own the built-in Playwright browser tool and WebUI browser viewer. +- Bridge browser automation, page inspection helpers, and browser panel UI. + +## Ownership + +- `plugin.yaml` and `default_config.yaml` own metadata and browser settings defaults. +- `tools/browser.py` owns the agent-facing browser tool. +- `helpers/` owns Playwright runtime, selectors, URL helpers, extension management, and connector runtime logic. +- `api/` owns status, extension, and browser WebSocket handlers. +- `assets/`, `prompts/`, `skills/`, `extensions/`, and `webui/` own browser scripts, prompts, skill guidance, hook contributions, and UI. + +## Local Contracts + +- Keep browser actions safe around external pages, credentials, and user data. +- Preserve Playwright lifecycle cleanup and WebSocket viewer compatibility. +- Do not hardcode user-specific browser paths or secrets. + +## Work Guidance + +- Coordinate tool, helper, and panel changes so browser state shown in the UI matches tool behavior. + +## Verification + +- Smoke-test browser launch, navigation, DOM capture, and WebUI viewer after runtime changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_chat_branching/AGENTS.md b/plugins/_chat_branching/AGENTS.md new file mode 100644 index 000000000..b10df9993 --- /dev/null +++ b/plugins/_chat_branching/AGENTS.md @@ -0,0 +1,31 @@ +# Chat Branching Plugin DOX + +## Purpose + +- Own branching a chat from any existing message. +- Keep log and history trimming behavior consistent when creating a branched conversation. + +## Ownership + +- `plugin.yaml` and `README.md` own metadata and user-facing behavior notes. +- `api/branch_chat.py` owns branch creation, clone, trim, persist, and refresh behavior. +- `extensions/` owns WebUI button injection. +- `webui/` owns plugin thumbnail assets. + +## Local Contracts + +- Preserve UUID-based linking between log entries and history messages. +- Branched chats must include history only up to the selected message. +- Do not mutate the source chat while creating a branch. + +## Work Guidance + +- Coordinate UI button injection with message rendering extension points. + +## Verification + +- Smoke-test branching from several message positions and confirm source chat remains unchanged. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_chat_compaction/AGENTS.md b/plugins/_chat_compaction/AGENTS.md new file mode 100644 index 000000000..c1d7b418a --- /dev/null +++ b/plugins/_chat_compaction/AGENTS.md @@ -0,0 +1,32 @@ +# Chat Compaction Plugin DOX + +## Purpose + +- Own compacting an entire chat history into a single optimized summary message. +- Keep compaction prompt, helper, API, and modal behavior aligned. + +## Ownership + +- `plugin.yaml` and `default_config.yaml` own metadata and compaction defaults. +- `api/compact_chat.py` owns the compaction endpoint. +- `helpers/compactor.py` owns summary generation and history rewrite logic. +- `prompts/` owns compaction system and message prompts. +- `webui/` owns the compaction modal and store. + +## Local Contracts + +- Preserve chat history integrity and persistence after compaction. +- Keep generated summaries bounded by configured model and token limits. +- Do not discard original context data unless the compaction flow explicitly owns that behavior. + +## Work Guidance + +- Coordinate prompt changes with helper behavior and UI confirmation text. + +## Verification + +- Smoke-test compacting a chat and reloading it after persistence. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_code_execution/AGENTS.md b/plugins/_code_execution/AGENTS.md new file mode 100644 index 000000000..2de8457f1 --- /dev/null +++ b/plugins/_code_execution/AGENTS.md @@ -0,0 +1,30 @@ +# Code Execution Plugin DOX + +## Purpose + +- Own terminal, Python, and Node.js code execution through persistent local or SSH-backed sessions. + +## Ownership + +- `tools/` owns the code execution and input tools. +- `helpers/` owns local shell, SSH shell, and TTY session management. +- `prompts/` owns execution prompt and runtime response fragments. +- `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own settings, metadata, hooks, and UI config. + +## Local Contracts + +- Keep session concurrency, timeout, streaming, and reset behavior predictable. +- Explicitly target local versus SSH execution runtimes. +- Do not hardcode secrets, SSH credentials, or local user paths. + +## Work Guidance + +- Preserve long-running command output retrieval and busy-session guards when changing execution flow. + +## Verification + +- Smoke-test terminal, Python, Node.js, output polling, and reset paths after tool changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_desktop/AGENTS.md b/plugins/_desktop/AGENTS.md new file mode 100644 index 000000000..2f2b300fd --- /dev/null +++ b/plugins/_desktop/AGENTS.md @@ -0,0 +1,30 @@ +# Desktop Plugin DOX + +## Purpose + +- Own the Agent Zero Linux desktop runtime, Xpra/Xfce session integration, and live desktop surface. + +## Ownership + +- `helpers/` owns desktop routes, session lifecycle, state, and prompt context. +- `api/desktop_session.py` owns desktop session API behavior. +- `hooks.py` owns route registration and plugin lifecycle hooks. +- `prompts/`, `assets/`, `skills/`, `extensions/`, and `webui/` own desktop context, assets, skill guidance, hooks, and panel UI. + +## Local Contracts + +- Preserve session startup, cleanup, and route protection for desktop access. +- Keep desktop state injected into prompts accurate and bounded. +- Do not expose desktop routes without the expected auth protections. + +## Work Guidance + +- Coordinate runtime and panel changes so live UI reflects actual desktop session state. + +## Verification + +- Smoke-test desktop startup, panel connection, route access, and session cleanup after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_discovery/AGENTS.md b/plugins/_discovery/AGENTS.md new file mode 100644 index 000000000..d2440d5ab --- /dev/null +++ b/plugins/_discovery/AGENTS.md @@ -0,0 +1,29 @@ +# Plugin Discovery DOX + +## Purpose + +- Own contextual plugin discovery cards and welcome-screen promotions. + +## Ownership + +- `plugin.yaml` owns metadata and always-enabled status. +- `extensions/` owns backend or WebUI discovery contributions. +- `webui/discovery-store.js` owns discovery UI state and actions. + +## Local Contracts + +- Discovery cards must be accurate, dismissible where appropriate, and avoid advertising already-complete setup. +- CTA actions must match supported welcome-screen action contracts. +- Keep card IDs unique and plugin-prefixed. + +## Work Guidance + +- Prefer backend status checks before surfacing setup or integration prompts. + +## Verification + +- Smoke-test welcome-screen discovery cards, ordering, dismissal, and CTA behavior after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_document_query/AGENTS.md b/plugins/_document_query/AGENTS.md new file mode 100644 index 000000000..c39208f94 --- /dev/null +++ b/plugins/_document_query/AGENTS.md @@ -0,0 +1,30 @@ +# Document Query Plugin DOX + +## Purpose + +- Own document loading, parsing, indexing, and Q&A over local and remote documents. + +## Ownership + +- `tools/document_query.py` owns the agent-facing query tool. +- `helpers/` owns fetching, parser routing, indexing, and query orchestration. +- `prompts/` owns document-query tool and optimization prompts. +- `hooks.py`, `default_config.yaml`, `plugin.yaml`, `skills/`, `extensions/`, and `webui/` own dependency bootstrap, settings, metadata, skill guidance, hooks, and UI. + +## Local Contracts + +- Respect configured size, timeout, retry, parser concurrency, and OCR limits. +- Fetch local and remote resources safely and avoid leaking document contents beyond intended prompt/tool use. +- Keep optional dependency installation targeted to the framework runtime. + +## Work Guidance + +- Coordinate parser changes with timeout handling and fallback behavior. + +## Verification + +- Smoke-test representative PDF, text/HTML, image/OCR, and remote-document queries after parser changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_editor/AGENTS.md b/plugins/_editor/AGENTS.md new file mode 100644 index 000000000..92969d629 --- /dev/null +++ b/plugins/_editor/AGENTS.md @@ -0,0 +1,30 @@ +# Editor Plugin DOX + +## Purpose + +- Own the native Markdown editor surface for canvas and floating modal workflows. + +## Ownership + +- `api/` owns editor session and WebSocket handlers. +- `helpers/` owns markdown session and open-file context helpers. +- `prompts/` owns agent-visible open-file context. +- `webui/` owns editor panel, preview, store, and main surface. +- `extensions/` owns editor hook contributions. + +## Local Contracts + +- Keep editor session state synchronized across API, WebSocket, and WebUI panel behavior. +- Do not expose unsaved content or local paths beyond intended chat/context surfaces. + +## Work Guidance + +- Coordinate editor preview and session changes with canvas surface registration. + +## Verification + +- Smoke-test opening, editing, previewing, and reconnecting editor sessions after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_email_integration/AGENTS.md b/plugins/_email_integration/AGENTS.md new file mode 100644 index 000000000..8d3d09c7e --- /dev/null +++ b/plugins/_email_integration/AGENTS.md @@ -0,0 +1,30 @@ +# Email Integration Plugin DOX + +## Purpose + +- Own communicating with Agent Zero through email inboxes and SMTP replies. + +## Ownership + +- `helpers/handler.py` owns mailbox polling, state, dispatch, routing, and reply flow. +- `helpers/imap_client.py` and `helpers/smtp_client.py` own inbound and outbound mail transports. +- `helpers/dispatcher.py`, `prompts/`, and attachment helpers own routing decisions and message formatting. +- `api/`, `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own tests, settings, metadata, hooks, and config UI. + +## Local Contracts + +- Treat mailbox credentials and downloaded attachments as sensitive. +- Preserve UID/state tracking so restarts do not duplicate old mail. +- Keep SMTP replies threaded and safe around user-visible errors. + +## Work Guidance + +- Coordinate polling, dispatch prompts, and WebUI settings when adding account or routing behavior. + +## Verification + +- Smoke-test connection checks, polling, attachment handling, dispatch routing, and SMTP replies when practical. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_error_retry/AGENTS.md b/plugins/_error_retry/AGENTS.md new file mode 100644 index 000000000..ae1a15541 --- /dev/null +++ b/plugins/_error_retry/AGENTS.md @@ -0,0 +1,30 @@ +# Error Retry Plugin DOX + +## Purpose + +- Own retry behavior for unexpected critical exceptions in agent loops. + +## Ownership + +- `extensions/` owns retry counter reset and critical-exception retry hooks. +- `default_config.yaml` owns retry count defaults. +- `webui/config.html` owns settings UI. +- `plugin.yaml` and `README.md` own metadata and behavior notes. + +## Local Contracts + +- Do not retry controlled flow exceptions such as `HandledException` and `RepairableException`. +- Keep retry counts scoped per monologue. +- Preserve clear agent-facing history injection when retrying a critical exception. + +## Work Guidance + +- Keep retry behavior conservative and observable through logs/UI. + +## Verification + +- Test or simulate critical, handled, and repairable exception paths after hook changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_infection_check/AGENTS.md b/plugins/_infection_check/AGENTS.md new file mode 100644 index 000000000..6f88ee127 --- /dev/null +++ b/plugins/_infection_check/AGENTS.md @@ -0,0 +1,29 @@ +# Infection Check Plugin DOX + +## Purpose + +- Own prompt-injection safety checks over streamed reasoning/response content before tool execution. + +## Ownership + +- `helpers/checker.py` owns safety analysis orchestration and gate behavior. +- `extensions/` owns stream collection and tool-execution blocking hooks. +- `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own settings, metadata, behavior notes, and config UI. + +## Local Contracts + +- Preserve configured `thoughts` and `complete` analysis modes. +- Tool execution must wait for required safety verdicts. +- Do not log or expose chain-of-thought or sensitive prompt content beyond intended warning flows. + +## Work Guidance + +- Keep termination and clarification loops bounded and explicit. + +## Verification + +- Smoke-test ok, clarify, and terminate verdicts around tool execution after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_kokoro_tts/AGENTS.md b/plugins/_kokoro_tts/AGENTS.md new file mode 100644 index 000000000..8e7ffc6bf --- /dev/null +++ b/plugins/_kokoro_tts/AGENTS.md @@ -0,0 +1,31 @@ +# Kokoro TTS Plugin DOX + +## Purpose + +- Own built-in Kokoro text-to-speech integration and browser TTS fallback coordination. + +## Ownership + +- `api/` owns synthesize and status endpoints. +- `helpers/` owns runtime and migration behavior. +- `hooks.py` owns provider registration/lifecycle behavior. +- `webui/` owns settings and speech UI integration. +- `default_config.yaml`, `plugin.yaml`, and `README.md` own defaults, metadata, and behavior notes. + +## Local Contracts + +- Keep Kokoro dependencies on Docker/bootstrap paths, not opportunistic runtime installs. +- Preserve browser-native fallback when the plugin is disabled or unavailable. +- Do not expose generated speech artifacts outside intended response paths. + +## Work Guidance + +- Coordinate status endpoint behavior with frontend fallback decisions. + +## Verification + +- Smoke-test status, synthesis, configured voice/speed, and disabled fallback behavior after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_memory/AGENTS.md b/plugins/_memory/AGENTS.md new file mode 100644 index 000000000..622026f57 --- /dev/null +++ b/plugins/_memory/AGENTS.md @@ -0,0 +1,31 @@ +# Memory Plugin DOX + +## Purpose + +- Own persistent memory, knowledge import, vector indexing, and memory management UI. + +## Ownership + +- `helpers/memory.py` owns FAISS store loading, embedding metadata, and knowledge preload. +- `helpers/knowledge_import.py` and `helpers/memory_consolidation.py` own import and consolidation behavior. +- `tools/` owns memory save/load/delete/forget and behavior adjustment tools. +- `api/` and `webui/` own memory dashboard and knowledge reindex/import flows. +- `prompts/`, `default_config.yaml`, and `plugin.yaml` own memory prompts, defaults, and metadata. + +## Local Contracts + +- Keep memory scoped by configured subdirectory/context. +- Preserve embedding metadata needed to rebuild indexes safely. +- Avoid storing transient action-history noise as durable memory. + +## Work Guidance + +- Coordinate tool, prompt, and consolidation changes so saved memories remain useful and bounded. + +## Verification + +- Smoke-test save, recall, delete, dashboard search/update, and knowledge import/reindex after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_model_config/AGENTS.md b/plugins/_model_config/AGENTS.md new file mode 100644 index 000000000..be2979411 --- /dev/null +++ b/plugins/_model_config/AGENTS.md @@ -0,0 +1,30 @@ +# Model Configuration Plugin DOX + +## Purpose + +- Own LLM model selection, presets, API-key checks, scoped overrides, and model settings UI. + +## Ownership + +- `helpers/model_config.py` owns config resolution, presets, overrides, and runtime model object construction. +- `api/` owns model config, override, preset, search, and API-key endpoints. +- `webui/` owns model settings, summaries, switcher, and API-key UI. +- `default_config.yaml`, `default_presets.yaml`, `provider_metadata.yaml`, `hooks.py`, and `plugin.yaml` own defaults, metadata, hooks, and manifest. + +## Local Contracts + +- Preserve global, project, agent, and chat override resolution order. +- Keep provider metadata and API-key checks safe around secrets. +- Coordinate OAuth-backed providers with `_oauth` instead of hardcoding provider-specific auth here. + +## Work Guidance + +- Keep backend model config shape and frontend settings fields synchronized. + +## Verification + +- Run model-config and onboarding-related tests when model provider, preset, or API-key behavior changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_office/AGENTS.md b/plugins/_office/AGENTS.md new file mode 100644 index 000000000..2e0c54b0e --- /dev/null +++ b/plugins/_office/AGENTS.md @@ -0,0 +1,30 @@ +# LibreOffice Plugin DOX + +## Purpose + +- Own ODF-first LibreOffice office artifact workflows for Writer, Calc, and Impress files. + +## Ownership + +- `tools/office_artifact.py` owns the agent-facing office artifact tool. +- `helpers/` owns artifact editing, canvas context, document storage, LibreOffice runtime, and presentation writing. +- `api/` owns office session and WebSocket handlers. +- `hooks.py`, `prompts/`, `skills/`, `extensions/`, and `webui/` own lifecycle behavior, prompts, skill guidance, hooks, and office panel UI. + +## Local Contracts + +- Preserve document storage integrity and live session synchronization. +- Keep LibreOffice operations bounded to intended workspaces and artifact paths. +- Do not expose document contents or temporary files beyond intended UI/tool flows. + +## Work Guidance + +- Coordinate tool, session, and panel changes so canvas state reflects document state. + +## Verification + +- Smoke-test creating, editing, previewing, and reconnecting office artifact sessions after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_onboarding/AGENTS.md b/plugins/_onboarding/AGENTS.md new file mode 100644 index 000000000..3bfcd8d2c --- /dev/null +++ b/plugins/_onboarding/AGENTS.md @@ -0,0 +1,28 @@ +# Onboarding Plugin DOX + +## Purpose + +- Own the built-in first-time onboarding wizard for model configuration. + +## Ownership + +- `plugin.yaml` owns metadata and always-enabled status. +- `webui/` owns onboarding providers, wizard store, modal/page markup, and thumbnail. + +## Local Contracts + +- Keep onboarding provider choices synchronized with model configuration and provider metadata. +- Do not ask for or expose API keys outside approved settings/API flows. +- Avoid blocking already-configured users with unnecessary onboarding prompts. + +## Work Guidance + +- Coordinate provider changes with `_model_config` and `_oauth` when account-backed providers are involved. + +## Verification + +- Smoke-test first-run onboarding, provider selection, completion, and skip/close behavior after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_plugin_installer/AGENTS.md b/plugins/_plugin_installer/AGENTS.md new file mode 100644 index 000000000..6e213ec7e --- /dev/null +++ b/plugins/_plugin_installer/AGENTS.md @@ -0,0 +1,30 @@ +# Plugin Installer DOX + +## Purpose + +- Own installing and updating plugins from ZIP uploads, Git repositories, and the community Plugin Index. + +## Ownership + +- `helpers/install.py` owns archive extraction, Git install/update, validation, hook execution, and install finalization. +- `api/plugin_install.py` owns install/update/index API dispatch. +- `webui/` owns Plugin Hub, ZIP, Git, detail, and shared install UI. +- `plugin.yaml` and `README.md` own metadata and behavior notes. + +## Local Contracts + +- Install third-party plugins into `usr/plugins/`, not bundled `plugins/`. +- Reject unsafe archive paths, missing manifests, invalid manifests, and plugin name conflicts. +- Run plugin install hooks and refresh plugin state after successful changes. + +## Work Guidance + +- Keep installer validation aligned with plugin contracts and Plugin Index expectations. + +## Verification + +- Smoke-test ZIP install, Git install, Plugin Hub install, and Git update paths after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_plugin_scan/AGENTS.md b/plugins/_plugin_scan/AGENTS.md new file mode 100644 index 000000000..c51293e84 --- /dev/null +++ b/plugins/_plugin_scan/AGENTS.md @@ -0,0 +1,30 @@ +# Plugin Scanner DOX + +## Purpose + +- Own LLM-guided security scanning for third-party Agent Zero plugins. + +## Ownership + +- `helpers/prompt.py` owns scan prompt construction from selectable checks. +- `api/` owns scan queue, start, and synchronous run endpoints. +- `webui/` owns scan checks, prompt template, store, UI, and thumbnail. +- `plugin.yaml` and `README.md` own metadata and behavior notes. + +## Local Contracts + +- Keep scan prompts explicit about source handling, security categories, and report expectations. +- Temporary scan contexts must be isolated and cleaned up as intended. +- Do not install or execute scanned plugin code as part of scanning unless explicitly designed and documented. + +## Work Guidance + +- Coordinate check schema changes with prompt builder and frontend selection UI. + +## Verification + +- Smoke-test a synchronous scan and selected-check scan after prompt or API changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_plugin_validator/AGENTS.md b/plugins/_plugin_validator/AGENTS.md new file mode 100644 index 000000000..abd194f30 --- /dev/null +++ b/plugins/_plugin_validator/AGENTS.md @@ -0,0 +1,30 @@ +# Plugin Validator DOX + +## Purpose + +- Own structured validation of Agent Zero plugins against manifest, structure, code-pattern, and security conventions. + +## Ownership + +- `helpers/prompt.py` owns validation prompt construction. +- `api/` owns ZIP preparation, queue, start, and synchronous run endpoints. +- `webui/` owns validation checks, guidance, prompt template, store, UI, and thumbnail. +- `plugin.yaml` and `README.md` own metadata and behavior notes. + +## Local Contracts + +- Keep validation criteria aligned with `plugins/AGENTS.md`, WebUI contracts, and Plugin Index requirements. +- Temporary validation source directories and contexts must be cleaned up as intended. +- Do not confuse runtime `plugin.yaml` with Plugin Index `index.yaml`. + +## Work Guidance + +- Coordinate checklist changes with prompt builder and frontend check selection. + +## Verification + +- Smoke-test local, Git, and ZIP validation paths when API or prompt behavior changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_promptinclude/AGENTS.md b/plugins/_promptinclude/AGENTS.md new file mode 100644 index 000000000..8fab1b39f --- /dev/null +++ b/plugins/_promptinclude/AGENTS.md @@ -0,0 +1,30 @@ +# Prompt Include Plugin DOX + +## Purpose + +- Own automatic prompt injection of persistent behavioral rules and preferences from `*.promptinclude.md` files. + +## Ownership + +- `helpers/scanner.py` owns workspace scanning, ignore handling, token budgeting, and trimming. +- `prompts/` owns prompt-inclusion fragments. +- `extensions/` owns prompt injection hooks. +- `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own defaults, metadata, behavior notes, and settings UI. + +## Local Contracts + +- Respect gitignore-style filtering, per-file budgets, and total token budgets. +- Include only intended promptinclude files from configured workspaces. +- Keep scan result status fields accurate for skipped, cropped, and included files. + +## Work Guidance + +- Coordinate scanner changes with prompt fragments so included content is clearly attributed. + +## Verification + +- Smoke-test include, ignore, crop, and over-budget cases after scanner changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_skills/AGENTS.md b/plugins/_skills/AGENTS.md new file mode 100644 index 000000000..1371f2bf9 --- /dev/null +++ b/plugins/_skills/AGENTS.md @@ -0,0 +1,31 @@ +# Skills Plugin DOX + +## Purpose + +- Own active and hidden skill configuration injected into prompt extras on each turn. + +## Ownership + +- `hooks.py` owns skill prompt injection and plugin lifecycle behavior. +- `api/skills_catalog.py` owns skill catalog access. +- `prompts/agent.system.active_skills.md` owns injected active-skill prompt content. +- `webui/` owns skill settings UI and store. +- `default_config.yaml`, `plugin.yaml`, `README.md`, and `LICENSE` own defaults, metadata, docs, and license. + +## Local Contracts + +- Keep active skill lists bounded by configured caps. +- Store configured skills in normalized portable paths. +- Hidden skills affect catalog/search/load visibility but must not be injected as active prompt content. + +## Work Guidance + +- Coordinate active-skill resolution changes with core skill loading and settings UI. + +## Verification + +- Run skill runtime/catalog tests or smoke-test active, hidden, global, project, and chat-scope behavior after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_telegram_integration/AGENTS.md b/plugins/_telegram_integration/AGENTS.md new file mode 100644 index 000000000..bbbc062f0 --- /dev/null +++ b/plugins/_telegram_integration/AGENTS.md @@ -0,0 +1,30 @@ +# Telegram Integration Plugin DOX + +## Purpose + +- Own Telegram bot integration for Agent Zero with polling, webhook, per-user sessions, and file exchange. + +## Ownership + +- `helpers/bot_manager.py` owns bot lifecycle. +- `helpers/handler.py` and `helpers/telegram_client.py` own message routing, replies, and Telegram API interaction. +- `helpers/dependencies.py` and `requirements.txt` own framework-runtime dependency bootstrap. +- `api/`, `prompts/`, `extensions/`, `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own tests/webhook endpoints, prompt fragments, hooks, settings, metadata, docs, and UI. + +## Local Contracts + +- Treat bot tokens, chat IDs, attachments, and user data as sensitive. +- Keep allowed-user, group-mode, project, model, and `/send` controls enforced. +- Install Telegram dependencies into the framework runtime only when required. + +## Work Guidance + +- Coordinate bot lifecycle changes with job-loop hooks and settings reload behavior. + +## Verification + +- Smoke-test connection checks, polling or webhook delivery, per-user context reuse, attachments, and replies when practical. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_text_editor/AGENTS.md b/plugins/_text_editor/AGENTS.md new file mode 100644 index 000000000..f18d552d3 --- /dev/null +++ b/plugins/_text_editor/AGENTS.md @@ -0,0 +1,30 @@ +# Text Editor Plugin DOX + +## Purpose + +- Own the native LLM-friendly text editing tool for reading, writing, and patching text files. + +## Ownership + +- `tools/text_editor.py` owns method dispatch and agent-facing tool behavior. +- `helpers/` owns file operations, patch requests, context patching, stale-read tracking, and patch state. +- `prompts/` owns read/write/patch success and error messages. +- `default_config.yaml`, `plugin.yaml`, `README.md`, `extensions/`, and `webui/` own defaults, metadata, docs, hooks, and config UI. + +## Local Contracts + +- Preserve stale-read protection before patch operations. +- Validate patch structures before applying edits. +- Read back changed regions after writes or patches where the tool contract requires confirmation. + +## Work Guidance + +- Coordinate helper changes with prompt responses so the agent receives actionable edit feedback. + +## Verification + +- Smoke-test read, write, patch, stale-read rejection, and error handling after tool changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_time_travel/AGENTS.md b/plugins/_time_travel/AGENTS.md new file mode 100644 index 000000000..0998d949f --- /dev/null +++ b/plugins/_time_travel/AGENTS.md @@ -0,0 +1,30 @@ +# Time Travel Plugin DOX + +## Purpose + +- Own Agent Zero workspace history, diff inspection, travel, snapshots, and revert for active `/a0/usr` workspaces. + +## Ownership + +- `helpers/time_travel.py` owns history storage, diff, travel, snapshot, preview, and revert mechanics. +- `api/` owns history list, diff, preview, revert, snapshot, and travel endpoints. +- `webui/` owns the time-travel panel, store, main surface, and thumbnail. +- `plugin.yaml` and `extensions/` own metadata and hook contributions. + +## Local Contracts + +- Keep history operations scoped to Agent Zero-owned workspaces. +- Revert and travel operations must avoid unintended writes outside managed workspace paths. +- Preserve enough metadata for clear preview and diff inspection before destructive actions. + +## Work Guidance + +- Coordinate API and UI changes so users can inspect effects before applying travel or revert operations. + +## Verification + +- Smoke-test snapshot, list, diff, preview, travel, and revert flows after changes. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_whatsapp_integration/AGENTS.md b/plugins/_whatsapp_integration/AGENTS.md new file mode 100644 index 000000000..ebb14eef4 --- /dev/null +++ b/plugins/_whatsapp_integration/AGENTS.md @@ -0,0 +1,31 @@ +# WhatsApp Integration Plugin DOX + +## Purpose + +- Own WhatsApp communication through a Baileys-based Node.js bridge. + +## Ownership + +- `helpers/bridge_manager.py` owns bridge lifecycle. +- `helpers/handler.py` and `helpers/wa_client.py` own message routing and bridge API interaction. +- `helpers/storage_paths.py`, attachment helpers, and number utilities own storage, attachment, and phone-number handling. +- `whatsapp-bridge/` owns the Node.js bridge package. +- `api/`, `prompts/`, `extensions/`, `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own QR/start/disconnect/test endpoints, prompt fragments, hooks, settings, metadata, docs, and UI. + +## Local Contracts + +- Treat WhatsApp sessions, QR data, phone numbers, attachments, and bridge state as sensitive. +- Keep allowed-number and group-response controls enforced. +- Do not leave unmanaged bridge services outside plugin-owned runtime paths. + +## Work Guidance + +- Coordinate Node bridge changes with Python bridge client and settings UI. + +## Verification + +- Smoke-test dependency install, bridge start, QR pairing, allowed-number filtering, message routing, and replies when practical. + +## Child DOX Index + +No child DOX files. diff --git a/plugins/_whisper_stt/AGENTS.md b/plugins/_whisper_stt/AGENTS.md new file mode 100644 index 000000000..4509ccb5a --- /dev/null +++ b/plugins/_whisper_stt/AGENTS.md @@ -0,0 +1,31 @@ +# Whisper STT Plugin DOX + +## Purpose + +- Own built-in Whisper speech-to-text integration, microphone runtime settings, and transcription delivery behavior. + +## Ownership + +- `api/` owns transcribe and status endpoints. +- `helpers/` owns runtime and migration behavior. +- `hooks.py` owns provider registration/lifecycle behavior. +- `webui/` owns settings, main speech UI, store, and styling. +- `default_config.yaml`, `plugin.yaml`, and `README.md` own defaults, metadata, and behavior notes. + +## Local Contracts + +- Keep dependency installation and model bootstrap on Docker/bootstrap paths. +- Preserve configured message mode, language, silence threshold, silence duration, and waiting timeout behavior. +- Do not expose raw audio or transcriptions beyond intended UI/API paths. + +## Work Guidance + +- Coordinate status endpoint behavior with frontend microphone and transcription state. + +## Verification + +- Smoke-test status, transcription, model/language settings, send/draft modes, and silence handling after changes. + +## Child DOX Index + +No child DOX files. diff --git a/skills/AGENTS.md b/skills/AGENTS.md index 92f7a9dd0..28cc26b15 100644 --- a/skills/AGENTS.md +++ b/skills/AGENTS.md @@ -31,4 +31,17 @@ ## Child DOX Index -No child DOX files. +Direct child DOX files: + +| Child | Scope | +| --- | --- | +| [a0-contribute-plugin/AGENTS.md](a0-contribute-plugin/AGENTS.md) | Publishing plugins to the community Plugin Index. | +| [a0-create-agent/AGENTS.md](a0-create-agent/AGENTS.md) | Creating Agent Zero agent profiles. | +| [a0-create-plugin/AGENTS.md](a0-create-plugin/AGENTS.md) | Creating or extending Agent Zero plugins. | +| [a0-debug-plugin/AGENTS.md](a0-debug-plugin/AGENTS.md) | Diagnosing plugin loading, API, frontend, and extension issues. | +| [a0-development/AGENTS.md](a0-development/AGENTS.md) | Broad Agent Zero framework development guidance. | +| [a0-manage-plugin/AGENTS.md](a0-manage-plugin/AGENTS.md) | Plugin install, update, scan, enable, disable, and removal workflows. | +| [a0-plugin-router/AGENTS.md](a0-plugin-router/AGENTS.md) | Routing plugin-related user requests to specialist skills. | +| [a0-review-plugin/AGENTS.md](a0-review-plugin/AGENTS.md) | Full plugin audit workflow and checklists. | +| [build-skill/AGENTS.md](build-skill/AGENTS.md) | Building and improving Agent Zero skills. | +| [scheduled-tasks/AGENTS.md](scheduled-tasks/AGENTS.md) | Managing scheduled, planned, and adhoc tasks. | diff --git a/skills/a0-contribute-plugin/AGENTS.md b/skills/a0-contribute-plugin/AGENTS.md new file mode 100644 index 000000000..2067e5306 --- /dev/null +++ b/skills/a0-contribute-plugin/AGENTS.md @@ -0,0 +1,29 @@ +# Plugin Contribution Skill DOX + +## Purpose + +- Own the workflow for publishing an Agent Zero plugin to the community Plugin Index. +- Keep contribution guidance aligned with current Plugin Hub and `a0-plugins` repository requirements. + +## Ownership + +- `SKILL.md` owns trigger metadata and the contribution procedure. + +## Local Contracts + +- Keep repository, `index.yaml`, manifest, license, validation, and PR guidance current. +- Do not hardcode user credentials, personal repository names, or private URLs. +- Keep handoffs to plugin review and management skills accurate. + +## Work Guidance + +- Update this skill when Plugin Index CI rules, manifest expectations, or submission flow changes. +- Prefer concise command examples that a user can adapt. + +## Verification + +- Manually read `SKILL.md` for broken links, stale paths, and invalid relative references. + +## Child DOX Index + +No child DOX files. diff --git a/skills/a0-create-agent/AGENTS.md b/skills/a0-create-agent/AGENTS.md new file mode 100644 index 000000000..bb455953b --- /dev/null +++ b/skills/a0-create-agent/AGENTS.md @@ -0,0 +1,29 @@ +# Agent Creation Skill DOX + +## Purpose + +- Own the workflow for creating Agent Zero agent profiles. +- Keep guidance for user, plugin-distributed, and project-scoped profiles accurate. + +## Ownership + +- `SKILL.md` owns trigger metadata, intake flow, profile blueprint schema, and file creation guidance. + +## Local Contracts + +- Default new user profiles to `usr/agents/`, not bundled `agents/`. +- Keep `agent.yaml`, prompt inheritance, tools, and extension guidance synchronized with profile loader behavior. +- Do not encourage storing secrets or provider credentials in profiles. + +## Work Guidance + +- Keep intake lightweight and progressive for user-facing profile creation. +- Update examples when the bundled `_example/` or profile schema changes. + +## Verification + +- Manually read `SKILL.md` for stale paths and blueprint/schema drift. + +## Child DOX Index + +No child DOX files. diff --git a/skills/a0-create-plugin/AGENTS.md b/skills/a0-create-plugin/AGENTS.md new file mode 100644 index 000000000..758c25df9 --- /dev/null +++ b/skills/a0-create-plugin/AGENTS.md @@ -0,0 +1,29 @@ +# Plugin Creation Skill DOX + +## Purpose + +- Own the workflow for creating, extending, or modifying Agent Zero plugins. +- Keep full-stack plugin conventions accurate for API, tools, extensions, settings UI, and WebUI integration. + +## Ownership + +- `SKILL.md` owns trigger metadata, plugin scaffold guidance, manifest rules, and frontend/backend patterns. + +## Local Contracts + +- New custom plugins must default to `usr/plugins/`. +- Keep plugin manifest, settings, extension layout, Store Gating, and notification guidance synchronized with `plugins/AGENTS.md` and WebUI contracts. +- Do not recommend hardcoding secrets, bypassing auth, or persistent unmanaged side effects. + +## Work Guidance + +- Update this skill when plugin loader, Plugin Hub, settings modal, extension, or WebUI patterns change. +- Keep code examples short and aligned with current helper APIs. + +## Verification + +- Manually read `SKILL.md` for stale paths and broken handoffs to related plugin skills. + +## Child DOX Index + +No child DOX files. diff --git a/skills/a0-debug-plugin/AGENTS.md b/skills/a0-debug-plugin/AGENTS.md new file mode 100644 index 000000000..42abc66c3 --- /dev/null +++ b/skills/a0-debug-plugin/AGENTS.md @@ -0,0 +1,28 @@ +# Plugin Debug Skill DOX + +## Purpose + +- Own the troubleshooting workflow for Agent Zero plugin loading, activation, API, frontend, extension, settings, and hook problems. + +## Ownership + +- `SKILL.md` owns diagnostic order, commands, and common failure cases. + +## Local Contracts + +- Keep route formats, import guidance, extension layouts, toggle files, and settings resolution aligned with runtime behavior. +- Do not recommend destructive cleanup unless the user explicitly asks and the target is clear. +- Keep diagnostics safe around secrets and local user data. + +## Work Guidance + +- Add checks when new plugin surfaces or loader failure modes are introduced. +- Prefer targeted commands that identify the first failing layer. + +## Verification + +- Manually read `SKILL.md` for stale commands and plugin path assumptions. + +## Child DOX Index + +No child DOX files. diff --git a/skills/a0-development/AGENTS.md b/skills/a0-development/AGENTS.md new file mode 100644 index 000000000..b53fd4cc0 --- /dev/null +++ b/skills/a0-development/AGENTS.md @@ -0,0 +1,29 @@ +# Development Skill DOX + +## Purpose + +- Own the broad Agent Zero development guide used by agents extending the framework. +- Keep architecture, tools, extensions, API, agents, prompts, projects, and skills guidance in sync with the repository. + +## Ownership + +- `SKILL.md` owns the development overview, path conventions, and implementation references. + +## Local Contracts + +- Keep paths and examples current with source files and DOX contracts. +- Route plugin-specific tasks to the plugin router or specialist plugin skills. +- Do not duplicate long contracts that belong in narrower AGENTS.md files when a reference is enough. + +## Work Guidance + +- Update this skill after durable framework workflow, extension, tool, API, prompt, or profile changes. +- Keep examples operational and compatible with the current helper classes. + +## Verification + +- Manually read `SKILL.md` for stale architecture references and broken related-skill links. + +## Child DOX Index + +No child DOX files. diff --git a/skills/a0-manage-plugin/AGENTS.md b/skills/a0-manage-plugin/AGENTS.md new file mode 100644 index 000000000..144b4636f --- /dev/null +++ b/skills/a0-manage-plugin/AGENTS.md @@ -0,0 +1,28 @@ +# Plugin Management Skill DOX + +## Purpose + +- Own the workflow for browsing, scanning, installing, updating, enabling, disabling, and uninstalling Agent Zero plugins. + +## Ownership + +- `SKILL.md` owns management routing, Plugin Hub usage, security scan guidance, and lifecycle commands. + +## Local Contracts + +- Keep Plugin Hub URLs, install API behavior, scan expectations, and activation semantics current. +- Warn about third-party plugin execution risk before install workflows. +- Do not recommend unmanaged deletion outside plugin-owned paths. + +## Work Guidance + +- Update this skill when installer, scanner, validator, Plugin Index, or toggle behavior changes. +- Keep diagnostics and install examples consistent with plugin helper APIs. + +## Verification + +- Manually read `SKILL.md` for stale endpoints, paths, and security guidance. + +## Child DOX Index + +No child DOX files. diff --git a/skills/a0-plugin-router/AGENTS.md b/skills/a0-plugin-router/AGENTS.md new file mode 100644 index 000000000..72d8f5331 --- /dev/null +++ b/skills/a0-plugin-router/AGENTS.md @@ -0,0 +1,29 @@ +# Plugin Router Skill DOX + +## Purpose + +- Own routing for Agent Zero plugin-related user requests. +- Keep handoffs to plugin creation, review, contribution, management, and debugging skills accurate. + +## Ownership + +- `SKILL.md` owns intent classification, routing table, and concise plugin system overview. + +## Local Contracts + +- Keep related skill names and responsibilities synchronized with the actual skill directories. +- Keep plugin root, discovery, manifest, and extension layout summaries aligned with `plugins/AGENTS.md`. +- Ask only when plugin intent is ambiguous. + +## Work Guidance + +- Update this skill when plugin lifecycle skills are renamed, added, or reorganized. +- Keep the overview brief enough to serve routing, not replace specialist skills. + +## Verification + +- Manually read `SKILL.md` for stale skill paths and routing gaps. + +## Child DOX Index + +No child DOX files. diff --git a/skills/a0-review-plugin/AGENTS.md b/skills/a0-review-plugin/AGENTS.md new file mode 100644 index 000000000..be2637ef0 --- /dev/null +++ b/skills/a0-review-plugin/AGENTS.md @@ -0,0 +1,30 @@ +# Plugin Review Skill DOX + +## Purpose + +- Own the full audit workflow for Agent Zero plugins. +- Keep manifest, structure, code-pattern, security, and duplicate-detection checks current. + +## Ownership + +- `SKILL.md` owns the review workflow and phase order. +- `checklists.md` owns detailed review criteria loaded when needed. + +## Local Contracts + +- Keep review checks aligned with current plugin contracts, WebUI patterns, and Plugin Index expectations. +- Treat user plugins as `usr/plugins/` artifacts unless explicitly reviewing bundled core plugins. +- Do not expose secrets or private plugin data in review output. + +## Work Guidance + +- Update both `SKILL.md` and `checklists.md` when plugin conventions or security expectations change. +- Keep findings actionable and grouped by review phase. + +## Verification + +- Manually read changed skill files for stale paths, duplicated checks, and broken references. + +## Child DOX Index + +No child DOX files. diff --git a/skills/build-skill/AGENTS.md b/skills/build-skill/AGENTS.md new file mode 100644 index 000000000..c591f6511 --- /dev/null +++ b/skills/build-skill/AGENTS.md @@ -0,0 +1,30 @@ +# Build Skill DOX + +## Purpose + +- Own the workflow for creating, improving, auditing, and refactoring Agent Zero skills. +- Keep skill format guidance aligned with runtime discovery and loading. + +## Ownership + +- `SKILL.md` owns standard skill shape, writing rules, placement rules, and validation guidance. + +## Local Contracts + +- Every skill folder must contain `SKILL.md`. +- Keep frontmatter and directory-shape guidance synchronized with skill loader behavior. +- Prefer plugin-scoped skills when the workflow is owned by a plugin. + +## Work Guidance + +- Update this skill when skill metadata, discovery, or validation behavior changes. +- Keep examples concise and avoid duplicating long reference material in the skill body. + +## Verification + +- Manually read `SKILL.md` for stale test commands and format assumptions. +- Run skill runtime tests when changing skill loader contracts. + +## Child DOX Index + +No child DOX files. diff --git a/skills/scheduled-tasks/AGENTS.md b/skills/scheduled-tasks/AGENTS.md new file mode 100644 index 000000000..2902a7c93 --- /dev/null +++ b/skills/scheduled-tasks/AGENTS.md @@ -0,0 +1,29 @@ +# Scheduled Tasks Skill DOX + +## Purpose + +- Own the workflow for managing Agent Zero scheduled, planned, and adhoc tasks. +- Keep scheduler tool usage and date/time guidance accurate. + +## Ownership + +- `SKILL.md` owns scheduler action descriptions, schedule field guidance, safety rules, and examples. + +## Local Contracts + +- Inspect existing tasks before create, update, delete, or run operations. +- Use cron-like `schedule` fields for recurring tasks and ISO datetimes in `plan` for planned tasks. +- Do not create recursive scheduling prompts or run scheduled tasks unless the user asks. + +## Work Guidance + +- Update this skill when scheduler tool actions, field names, or timezone behavior changes. +- Keep examples valid JSON tool arguments. + +## Verification + +- Manually read `SKILL.md` for stale scheduler action names and date guidance. + +## Child DOX Index + +No child DOX files. diff --git a/tests/test_dirty_json.py b/tests/test_dirty_json.py index 011b23d5f..2715366e9 100644 --- a/tests/test_dirty_json.py +++ b/tests/test_dirty_json.py @@ -54,3 +54,42 @@ def test_completed_remains_true_after_trailing_content() -> None: } assert parser.completed is True + + +def test_value_keeps_unescaped_markdown_quotes_until_structural_delimiter() -> None: + payload = ( + "{\n" + ' "tool_name": "response",\n' + ' "tool_args": {\n' + ' "text": "The rule:\\n\\n> *"' + 'Create a child AGENTS.md when a folder becomes a boundary."' + '*\\n\\nAdding `css/AGENTS.md` that says *"' + 'this folder contains CSS"' + '* is duplication."\n' + " }\n" + "}" + ) + + parsed = DirtyJson.parse_string(payload) + + assert parsed["tool_args"] == { + "text": ( + "The rule:\n\n" + '> *"Create a child AGENTS.md when a folder becomes a boundary."*\n\n' + 'Adding `css/AGENTS.md` that says *"this folder contains CSS"* is duplication.' + ) + } + + +def test_value_keeps_unescaped_quotes_on_single_line() -> None: + parsed = DirtyJson.parse_string( + '{"text":"He said "hello" before closing","ok":true}' + ) + + assert parsed == {"text": 'He said "hello" before closing', "ok": True} + + +def test_value_can_still_end_before_quoted_key_when_comma_is_missing() -> None: + parsed = DirtyJson.parse_string('{"first":"one" "second":"two"}') + + assert parsed == {"first": "one", "second": "two"} diff --git a/tools/AGENTS.md b/tools/AGENTS.md index ed3cc8a37..0218740e0 100644 --- a/tools/AGENTS.md +++ b/tools/AGENTS.md @@ -18,17 +18,23 @@ - Use `await self.agent.handle_intervention(...)` when a long-running or external result should respect pause/intervention flow. - Sanitize or mask secrets before logging, returning, or storing tool outputs. - Do not perform destructive filesystem or network actions without the tool contract making that behavior explicit. +- This directory is a file-documented DOX profile: every direct `*.py` tool module must have a same-directory `*.py.dox.md` file named by appending `.dox.md` to the full Python filename. +- The `*.py.dox.md` file owns tool purpose, tool arguments/concepts, output and `break_loop` behavior, side effects, important helper dependencies, prompt-contract notes, and verification guidance. +- When a tool module is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change. +- Do not leave stale file-level DOX after tool deletion or rename. ## Work Guidance - Keep tool output concise enough for message history while preserving actionable detail. - Put reusable parsing, provider, filesystem, or network logic in `helpers/`. - Update prompt tool instructions when changing tool names, arguments, or behavior. +- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed tool behavior is described there. ## Verification - Run targeted tool tests after changing a tool or its prompt contract. - Run prompt/snapshot tests when tool instructions or output shape changes. +- Check file-level documentation coverage with a script or shell loop that verifies each `tools/*.py` has a matching `tools/*.py.dox.md`. ## Child DOX Index diff --git a/tools/a2a_chat.py.dox.md b/tools/a2a_chat.py.dox.md new file mode 100644 index 000000000..78d6ae143 --- /dev/null +++ b/tools/a2a_chat.py.dox.md @@ -0,0 +1,51 @@ +# a2a_chat.py DOX + +## Purpose + +- Own the `a2a_chat.py` agent tool. +- This module lets the agent message an external A2A agent and extract the assistant reply. +- Keep this file-level DOX profile synchronized with `a2a_chat.py` because this directory is intentionally flat. + +## Ownership + +- `a2a_chat.py` owns the runtime implementation. +- `a2a_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `A2AChatTool` (`Tool`) + - `async execute(self, **kwargs)` +- Top-level functions: +- `_session_key(agent_url: str) -> str`: Keep root and explicit /a2a URLs in the same conversation cache. +- `_text_from_part(part: Any) -> str` +- `_text_from_message(message: Any) -> str` +- `_extract_latest_assistant_text(task_response: Any) -> str` +- Notable constants/configuration names: `A2A_EMPTY_RESPONSE_ERROR`. + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `A2AChatTool` is a `Tool`. +- `A2AChatTool` defines `execute(...)`. +- Observed side-effect areas: filesystem writes, scheduler state. +- Imported dependency areas include: `helpers.fasta2a_client`, `helpers.print_style`, `helpers.tool`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `agent_url.rstrip`, `normalized.endswith`, `_text_from_message`, `normalized.rstrip`, `message.strip`, `join`, `_session_key`, `value.strip`, `_text_from_part`, `is_client_available`, `Response`, `self.agent.get_data`, `sessions.pop`, `_extract_latest_assistant_text`, `PrintStyle.error`, `connect_to_agent`, `conn.send_message`, `conn.wait_for_completion`, `self.agent.set_data`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/test_tool_action_contracts.py` + +## Child DOX Index + +No child DOX files. diff --git a/tools/call_subordinate.py.dox.md b/tools/call_subordinate.py.dox.md new file mode 100644 index 000000000..544873f0b --- /dev/null +++ b/tools/call_subordinate.py.dox.md @@ -0,0 +1,46 @@ +# call_subordinate.py DOX + +## Purpose + +- Own the `call_subordinate.py` agent tool. +- This module delegates work to a subordinate Agent Zero profile and returns its result. +- Keep this file-level DOX profile synchronized with `call_subordinate.py` because this directory is intentionally flat. + +## Ownership + +- `call_subordinate.py` owns the runtime implementation. +- `call_subordinate.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Delegation` (`Tool`) + - `async execute(self, message=..., reset=..., **kwargs)` + - `get_log_object(self)` + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `Delegation` is a `Tool`. +- `Delegation` defines `execute(...)`. +- Observed side-effect areas: filesystem writes, settings/state persistence. +- Imported dependency areas include: `agent`, `extensions.python.hist_add_tool_result`, `helpers.tool`, `initialize`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self.agent.get_data`, `subordinate.hist_add_user_message`, `subordinate.history.new_topic`, `Response`, `self.agent.context.log.log`, `initialize_agent`, `Agent`, `sub.set_data`, `self.agent.set_data`, `UserMessage`, `subordinate.monologue`, `self.agent.read_prompt`, `str.lower.strip`, `str.lower`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/test_default_prompt_budget.py` + +## Child DOX Index + +No child DOX files. diff --git a/tools/document_query.py.dox.md b/tools/document_query.py.dox.md new file mode 100644 index 000000000..dea7310d7 --- /dev/null +++ b/tools/document_query.py.dox.md @@ -0,0 +1,41 @@ +# document_query.py DOX + +## Purpose + +- Own the `document_query.py` agent tool. +- This module loads and queries documents through the document query plugin compatibility path. +- Keep this file-level DOX profile synchronized with `document_query.py` because this directory is intentionally flat. + +## Ownership + +- `document_query.py` owns the runtime implementation. +- `document_query.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- Observed side-effect areas: plugin state. +- Imported dependency areas include: `plugins._document_query.tools.document_query`. + +## Key Concepts + +- This module is primarily declarative or delegates behavior through classes/imported objects. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/test_document_query_fallback.py` + - `tests/test_document_query_plugin.py` + +## Child DOX Index + +No child DOX files. diff --git a/tools/notify_user.py.dox.md b/tools/notify_user.py.dox.md new file mode 100644 index 000000000..17cc9a44f --- /dev/null +++ b/tools/notify_user.py.dox.md @@ -0,0 +1,44 @@ +# notify_user.py DOX + +## Purpose + +- Own the `notify_user.py` agent tool. +- This module sends a user-facing notification from the agent. +- Keep this file-level DOX profile synchronized with `notify_user.py` because this directory is intentionally flat. + +## Ownership + +- `notify_user.py` owns the runtime implementation. +- `notify_user.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `NotifyUserTool` (`Tool`) + - `async execute(self, **kwargs)` + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `NotifyUserTool` is a `Tool`. +- `NotifyUserTool` defines `execute(...)`. +- Imported dependency areas include: `agent`, `helpers.notification`, `helpers.tool`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager.add_notification`, `Response`, `NotificationType`, `NotificationPriority`, `AgentContext.get_notification_manager`, `self.agent.read_prompt`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/test_tool_action_contracts.py` + +## Child DOX Index + +No child DOX files. diff --git a/tools/response.py.dox.md b/tools/response.py.dox.md new file mode 100644 index 000000000..a2d18ac0d --- /dev/null +++ b/tools/response.py.dox.md @@ -0,0 +1,53 @@ +# response.py DOX + +## Purpose + +- Own the `response.py` agent tool. +- This module emits the final or intermediate agent response to the user. +- Keep this file-level DOX profile synchronized with `response.py` because this directory is intentionally flat. + +## Ownership + +- `response.py` owns the runtime implementation. +- `response.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `ResponseTool` (`Tool`) + - `async execute(self, **kwargs)` + - `async before_execution(self, **kwargs)` + - `async after_execution(self, response, **kwargs)` + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `ResponseTool` is a `Tool`. +- `ResponseTool` defines `execute(...)`. +- Imported dependency areas include: `helpers.tool`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Response`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/chunk_parser_test.py` + - `tests/rate_limiter_test.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_chat_compaction.py` + - `tests/test_dirty_json.py` + - `tests/test_download_toast_regressions.py` + - `tests/test_fasta2a_client.py` + - `tests/test_fastmcp_openapi_security.py` + +## Child DOX Index + +No child DOX files. diff --git a/tools/scheduler.py.dox.md b/tools/scheduler.py.dox.md new file mode 100644 index 000000000..a36f2bc07 --- /dev/null +++ b/tools/scheduler.py.dox.md @@ -0,0 +1,63 @@ +# scheduler.py DOX + +## Purpose + +- Own the `scheduler.py` agent tool. +- This module creates, updates, lists, runs, waits for, and deletes scheduled/planned/adhoc tasks. +- Keep this file-level DOX profile synchronized with `scheduler.py` because this directory is intentionally flat. + +## Ownership + +- `scheduler.py` owns the runtime implementation. +- `scheduler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SchedulerTool` (`Tool`) + - `async execute(self, **kwargs)` + - `async list_tasks(self, **kwargs) -> Response` + - `async find_task_by_name(self, **kwargs) -> Response` + - `async show_task(self, **kwargs) -> Response` + - `async run_task(self, **kwargs) -> Response` + - `async delete_task(self, **kwargs) -> Response` + - `async update_task(self, **kwargs) -> Response` + - `async create_scheduled_task(self, **kwargs) -> Response` +- Top-level functions: +- `_current_action(tool: Tool, kwargs: dict) -> str` +- `_normalize_timezone(value: Any) -> str | None` +- `_schedule_timezone(kwargs: dict) -> str | None` +- `_task_schedule_from_input(schedule: Any, timezone: str | None=...) -> TaskSchedule` +- `_validate_task_schedule(task_schedule: TaskSchedule) -> str` +- `_task_plan_from_input(plan: Any) -> tuple[TaskPlan | None, str]` +- Notable constants/configuration names: `DEFAULT_WAIT_TIMEOUT`, `LOCAL_TIMEZONE_ALIASES`. + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `SchedulerTool` is a `Tool`. +- `SchedulerTool` defines `execute(...)`. +- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state. +- Imported dependency areas include: `agent`, `asyncio`, `datetime`, `helpers`, `helpers.localization`, `helpers.projects`, `helpers.task_scheduler`, `helpers.tool`, `json`, `pytz`, `random`, `re`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `str.strip.lower.replace`, `str.strip`, `_normalize_timezone`, `TaskSchedule`, `task_schedule.to_crontab`, `timezone_name.lower`, `Localization.get.get_timezone`, `pytz.timezone`, `schedule.split`, `re.match`, `parse_datetime`, `TaskPlan.create`, `_current_action`, `get_context_project_name`, `TaskScheduler.get.get_tasks`, `Response`, `TaskScheduler.get.find_task_by_name`, `TaskScheduler.get.get_task_by_uuid`, `scheduler.get_task_by_uuid`, `self._resolve_project_metadata`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/test_task_scheduler_timezone.py` + - `tests/test_timezone_regressions.py` + - `tests/test_tool_action_contracts.py` + - `tests/test_tool_request_normalization.py` + +## Child DOX Index + +No child DOX files. diff --git a/tools/search_engine.py.dox.md b/tools/search_engine.py.dox.md new file mode 100644 index 000000000..102ee68c4 --- /dev/null +++ b/tools/search_engine.py.dox.md @@ -0,0 +1,46 @@ +# search_engine.py DOX + +## Purpose + +- Own the `search_engine.py` agent tool. +- This module runs web search through the configured search helper. +- Keep this file-level DOX profile synchronized with `search_engine.py` because this directory is intentionally flat. + +## Ownership + +- `search_engine.py` owns the runtime implementation. +- `search_engine.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SearchEngine` (`Tool`) + - `async execute(self, query=..., **kwargs)` + - `async searxng_search(self, question)` + - `format_result_searxng(self, result, source)` +- Notable constants/configuration names: `SEARCH_ENGINE_RESULTS`. + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `SearchEngine` is a `Tool`. +- `SearchEngine` defines `execute(...)`. +- Imported dependency areas include: `asyncio`, `helpers`, `helpers.errors`, `helpers.print_style`, `helpers.searxng`, `helpers.tool`, `os`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Response`, `self.format_result_searxng`, `join.strip`, `self.searxng_search`, `self.agent.handle_intervention`, `searxng`, `handle_error`, `join`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. + +## Child DOX Index + +No child DOX files. diff --git a/tools/skills_tool.py.dox.md b/tools/skills_tool.py.dox.md new file mode 100644 index 000000000..e93b91e50 --- /dev/null +++ b/tools/skills_tool.py.dox.md @@ -0,0 +1,51 @@ +# skills_tool.py DOX + +## Purpose + +- Own the `skills_tool.py` agent tool. +- This module searches, loads, and lists Agent Zero skills for the agent. +- Keep this file-level DOX profile synchronized with `skills_tool.py` because this directory is intentionally flat. + +## Ownership + +- `skills_tool.py` owns the runtime implementation. +- `skills_tool.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `SkillsTool` (`Tool`) + - `get_log_object(self)` + - `async before_execution(self, **kwargs)` + - `async execute(self, **kwargs) -> Response` +- Top-level functions: +- `max_loaded_skills() -> int` +- Notable constants/configuration names: `DATA_NAME_LOADED_SKILLS`. + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `SkillsTool` is a `Tool`. +- `SkillsTool` defines `execute(...)`. +- Observed side-effect areas: filesystem reads, filesystem deletion, settings/state persistence. +- Imported dependency areas include: `__future__`, `helpers`, `helpers.print_style`, `helpers.tool`, `pathlib`, `typing`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `str.strip.lower.replace`, `skill_name.strip`, `super.get_log_object`, `self._normalize_skill_name`, `self.get_log_object`, `skills_helper.list_skills`, `join`, `skills_helper.search_skills`, `skills_helper.find_skill`, `skill.path.resolve`, `Path`, `resolved.read_text`, `skill_name.startswith`, `skill_name.endswith`, `self._current_action`, `self.agent.context.log.log`, `Response`, `strip`, `loaded.remove`, `target.is_absolute`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/test_document_query_plugin.py` + - `tests/test_tool_action_contracts.py` + +## Child DOX Index + +No child DOX files. diff --git a/tools/unknown.py.dox.md b/tools/unknown.py.dox.md new file mode 100644 index 000000000..1264ab30f --- /dev/null +++ b/tools/unknown.py.dox.md @@ -0,0 +1,48 @@ +# unknown.py DOX + +## Purpose + +- Own the `unknown.py` agent tool. +- This module handles unknown or malformed tool-call requests. +- Keep this file-level DOX profile synchronized with `unknown.py` because this directory is intentionally flat. + +## Ownership + +- `unknown.py` owns the runtime implementation. +- `unknown.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `Unknown` (`Tool`) + - `async execute(self, **kwargs)` + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `Unknown` is a `Tool`. +- `Unknown` defines `execute(...)`. +- Imported dependency areas include: `extensions.python.system_prompt._11_tools_prompt`, `helpers.tool`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Response`, `build_tools_prompt`, `self.agent.read_prompt`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/test_file_tree_visualize.py` + - `tests/test_oauth_providers.py` + - `tests/test_socketio_unknown_namespace.py` + - `tests/test_tunnel_remote_link.py` + - `tests/test_ws_manager.py` + +## Child DOX Index + +No child DOX files. diff --git a/tools/vision_load.py.dox.md b/tools/vision_load.py.dox.md new file mode 100644 index 000000000..da9531242 --- /dev/null +++ b/tools/vision_load.py.dox.md @@ -0,0 +1,50 @@ +# vision_load.py DOX + +## Purpose + +- Own the `vision_load.py` agent tool. +- This module loads images into model-visible content for vision-capable models. +- Keep this file-level DOX profile synchronized with `vision_load.py` because this directory is intentionally flat. + +## Ownership + +- `vision_load.py` owns the runtime implementation. +- `vision_load.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `VisionLoad` (`Tool`) + - `async execute(self, paths: list[str]=..., **kwargs) -> Response` + - `async after_execution(self, response: Response, **kwargs)` +- Notable constants/configuration names: `TOKENS_ESTIMATE`. + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `VisionLoad` is a `Tool`. +- `VisionLoad` defines `execute(...)`. +- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence, secret handling. +- Imported dependency areas include: `helpers`, `helpers.print_style`, `helpers.tool`, `mimetypes`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `self._get_max_embeds`, `Response`, `str.strip`, `self._context_id`, `chat_media.infer_source`, `chat_media.category_for_source`, `chat_media.save_image_base64`, `chat_media.save_image_data_url`, `chat_media.materialize_image_ref`, `str.strip.lower`, `ephemeral_images.is_ref`, `cls._is_data_image_url`, `self._is_data_image_url`, `plugins.get_plugin_config`, `images.to_data_url`, `normalized.startswith`, `ephemeral_images.display_ref`, `join`, `self.agent.hist_add_tool_result`, `history.RawMessage`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/test_browser_agent_regressions.py` + - `tests/test_host_browser_connector.py` + - `tests/test_office_desktop_state.py` + - `tests/test_vision_load_image_refs.py` + +## Child DOX Index + +No child DOX files. diff --git a/tools/wait.py.dox.md b/tools/wait.py.dox.md new file mode 100644 index 000000000..1f2a461f8 --- /dev/null +++ b/tools/wait.py.dox.md @@ -0,0 +1,54 @@ +# wait.py DOX + +## Purpose + +- Own the `wait.py` agent tool. +- This module lets the agent wait for a managed duration while respecting intervention flow. +- Keep this file-level DOX profile synchronized with `wait.py` because this directory is intentionally flat. + +## Ownership + +- `wait.py` owns the runtime implementation. +- `wait.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. +- Classes: +- `WaitTool` (`Tool`) + - `async execute(self, **kwargs) -> Response` + - `get_log_object(self)` + - `get_heading(self, text: str=..., done: bool=...)` + +## Runtime Contracts + +- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. +- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change. +- `WaitTool` is a `Tool`. +- `WaitTool` defines `execute(...)`. +- Observed side-effect areas: settings/state persistence. +- Imported dependency areas include: `asyncio`, `datetime`, `helpers.localization`, `helpers.print_style`, `helpers.tool`, `helpers.wait`. + +## Key Concepts + +- Important called helpers/classes observed in the source: `Localization.get.now`, `PrintStyle.info`, `self.agent.read_prompt`, `Response`, `self.agent.context.log.log`, `self.agent.handle_intervention`, `timedelta`, `managed_wait`, `Localization.get.localtime_str_to_utc_dt`, `wait_duration.total_seconds`, `Localization.get.serialize_datetime`, `self.get_heading`, `ValueError`. +- Keep request/response, tool, or helper semantics documented here at the same time as source changes. + +## Work Guidance + +- Keep tool output concise, model-readable, and safe for history persistence. +- Coordinate argument or behavior changes with prompt tool instructions and skill guidance. +- Respect intervention flow for long-running, external, or user-visible operations. + +## Verification + +- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists. +- Related tests observed by source search: + - `tests/email_parser_test.py` + - `tests/rate_limiter_test.py` + - `tests/test_api_chat_lifetime.py` + - `tests/test_browser_agent_regressions.py` + - `tests/test_chat_compaction.py` + - `tests/test_default_prompt_budget.py` + - `tests/test_document_query_plugin.py` + - `tests/test_download_toast_regressions.py` + +## Child DOX Index + +No child DOX files. diff --git a/webui/AGENTS.md b/webui/AGENTS.md index cb0d16344..27cce4b4f 100644 --- a/webui/AGENTS.md +++ b/webui/AGENTS.md @@ -48,3 +48,5 @@ Direct child DOX files: | [components/AGENTS.md](components/AGENTS.md) | Alpine component HTML, component stores, and component-local styles. | | [css/AGENTS.md](css/AGENTS.md) | Shared WebUI stylesheet modules. | | [js/AGENTS.md](js/AGENTS.md) | Shared frontend JavaScript modules and client-side infrastructure. | +| [public/AGENTS.md](public/AGENTS.md) | First-party static WebUI images, icons, splash art, and PWA assets. | +| [vendor/AGENTS.md](vendor/AGENTS.md) | Vendored third-party browser libraries. | diff --git a/webui/components/AGENTS.md b/webui/components/AGENTS.md index 5390fb3bc..606f4ab65 100644 --- a/webui/components/AGENTS.md +++ b/webui/components/AGENTS.md @@ -56,4 +56,21 @@ ## Child DOX Index -No child DOX files. +Direct child DOX files: + +| Child | Scope | +| --- | --- | +| [_examples/AGENTS.md](_examples/AGENTS.md) | Reference component and store examples. | +| [canvas/AGENTS.md](canvas/AGENTS.md) | Right-canvas component surface and store. | +| [chat/AGENTS.md](chat/AGENTS.md) | Chat composer, attachments, queue, navigation, and top-section components. | +| [dropdown/AGENTS.md](dropdown/AGENTS.md) | Shared dropdown component. | +| [messages/AGENTS.md](messages/AGENTS.md) | Message rendering helpers, action buttons, process groups, and resize behavior. | +| [modals/AGENTS.md](modals/AGENTS.md) | Modal component workflows loaded through the shared modal stack. | +| [notifications/AGENTS.md](notifications/AGENTS.md) | Toasts, notification modal, icons, and notification store. | +| [plugins/AGENTS.md](plugins/AGENTS.md) | Plugin settings, info, list, execution, and toggle components. | +| [projects/AGENTS.md](projects/AGENTS.md) | Project creation, selection, edit, secrets, model, skill, and file-structure components. | +| [settings/AGENTS.md](settings/AGENTS.md) | Settings shell and built-in settings subsections. | +| [sidebar/AGENTS.md](sidebar/AGENTS.md) | Left sidebar layout, chat/task lists, top actions, and preferences. | +| [sync/AGENTS.md](sync/AGENTS.md) | WebUI sync status component and store. | +| [tooltips/AGENTS.md](tooltips/AGENTS.md) | Shared tooltip store and behavior. | +| [welcome/AGENTS.md](welcome/AGENTS.md) | Welcome screen, discovery cards, banners, and welcome state. | diff --git a/webui/components/_examples/AGENTS.md b/webui/components/_examples/AGENTS.md new file mode 100644 index 000000000..882ae3eea --- /dev/null +++ b/webui/components/_examples/AGENTS.md @@ -0,0 +1,27 @@ +# Component Examples DOX + +## Purpose + +- Own reference component and store examples for WebUI component authors. + +## Ownership + +- `_example-component.html` owns the component markup example. +- `_example-store.js` owns the store pattern example. + +## Local Contracts + +- Keep examples aligned with current component loader, Store Gating, and `createStore` patterns. +- Do not add product behavior or dependencies here. + +## Work Guidance + +- Prefer small examples that demonstrate current conventions clearly. + +## Verification + +- Manually inspect examples after component contract changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/canvas/AGENTS.md b/webui/components/canvas/AGENTS.md new file mode 100644 index 000000000..3ec1d5006 --- /dev/null +++ b/webui/components/canvas/AGENTS.md @@ -0,0 +1,28 @@ +# Canvas Components DOX + +## Purpose + +- Own the right-canvas component surface and its state. + +## Ownership + +- `right-canvas.html` owns canvas markup. +- `right-canvas-store.js` owns canvas state, surface registration, and actions. +- `right-canvas.css` owns canvas-specific styling. + +## Local Contracts + +- Keep registered surfaces compatible with WebUI extension hooks. +- Preserve responsive layout and avoid overlapping the chat/sidebar shells. + +## Work Guidance + +- Use existing surface and extension helpers before adding new canvas infrastructure. + +## Verification + +- Smoke-test right-canvas open, close, resize, and registered surfaces after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/chat/AGENTS.md b/webui/components/chat/AGENTS.md new file mode 100644 index 000000000..220667ecb --- /dev/null +++ b/webui/components/chat/AGENTS.md @@ -0,0 +1,32 @@ +# Chat Components DOX + +## Purpose + +- Own chat composer, attachments, message queue, navigation, and top-section component groups. + +## Ownership + +- `input/` owns composer input, progress, banners, and bottom action bars. +- `attachments/` owns drag/drop and attachment preview UI. +- `message-queue/` owns queued message display and store state. +- `navigation/` owns chat navigation state. +- `top-section/` owns chat header/top area. + +## Local Contracts + +- Preserve Store Gating for all store-backed chat components. +- Use shared API, WebSocket, notification, and attachment helpers where available. +- Do not bypass CSRF or WebSocket state-sync expectations. + +## Work Guidance + +- Keep composer and attachment changes responsive across desktop and mobile. +- Coordinate payload changes with backend chat, upload, and WebSocket handlers. + +## Verification + +- Smoke-test sending, queued messages, attachments, drag/drop, and navigation after visible changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/dropdown/AGENTS.md b/webui/components/dropdown/AGENTS.md new file mode 100644 index 000000000..a6e9f284e --- /dev/null +++ b/webui/components/dropdown/AGENTS.md @@ -0,0 +1,26 @@ +# Dropdown Component DOX + +## Purpose + +- Own the shared dropdown component used by WebUI controls. + +## Ownership + +- `dropdown.html` owns dropdown markup, behavior hooks, and component-local styling. + +## Local Contracts + +- Keep keyboard, focus, and click-outside behavior compatible with existing callers. +- Avoid caller-specific assumptions in the shared dropdown. + +## Work Guidance + +- Prefer component attributes and slots over hardcoded option sets. + +## Verification + +- Smoke-test each caller that uses the dropdown after behavior changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/messages/AGENTS.md b/webui/components/messages/AGENTS.md new file mode 100644 index 000000000..78c340802 --- /dev/null +++ b/webui/components/messages/AGENTS.md @@ -0,0 +1,29 @@ +# Message Components DOX + +## Purpose + +- Own message rendering helpers, action buttons, process groups, and resize behavior. + +## Ownership + +- `action-buttons/` owns simple message action controls. +- `process-group/` owns grouped process-step DOM and styling helpers. +- `resize/` owns message resize state. + +## Local Contracts + +- Keep message DOM helpers compatible with extension points that modify rendered messages. +- Sanitize or safely render model/user-provided content through shared rendering paths. +- Avoid layout shifts that break long-running message streaming. + +## Work Guidance + +- Coordinate changes with `webui/js/messages.js` and frontend extension hooks. + +## Verification + +- Smoke-test message rendering, action buttons, process groups, and resizing after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/modals/AGENTS.md b/webui/components/modals/AGENTS.md new file mode 100644 index 000000000..45783107e --- /dev/null +++ b/webui/components/modals/AGENTS.md @@ -0,0 +1,30 @@ +# Modal Components DOX + +## Purpose + +- Own WebUI modal component content loaded through the shared modal stack. + +## Ownership + +- Each direct child folder owns one modal workflow and its store. +- Modal HTML files own body content, titles, scoped styles, and `data-modal-footer` content. +- Modal store files own modal-local state and cleanup. + +## Local Contracts + +- Use `openModal(path)` and `closeModal()` from `/js/modals.js`. +- Keep footer content marked with `data-modal-footer` when using pinned modal actions. +- Do not introduce a parallel overlay, backdrop, or teleport modal system. + +## Work Guidance + +- Keep modal state cleanup explicit because stores may outlive DOM nodes. +- Preserve stacked modal, Escape, click-outside, scroll, and footer behavior. + +## Verification + +- Smoke-test open, close, Escape, click-outside, scrolling, stacked modals, and pinned footers after modal changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/notifications/AGENTS.md b/webui/components/notifications/AGENTS.md new file mode 100644 index 000000000..071bf076f --- /dev/null +++ b/webui/components/notifications/AGENTS.md @@ -0,0 +1,30 @@ +# Notification Components DOX + +## Purpose + +- Own WebUI toast, modal, icon, and notification store behavior. + +## Ownership + +- `notification-store.js` owns notification state and public helper actions. +- `notification-toast-stack.html` owns toast rendering. +- `notification-modal.html` owns notification detail modal UI. +- `notification-icons.html` owns shared notification icon markup. + +## Local Contracts + +- Use the notification system for user-facing success, warning, info, and error feedback. +- Keep public helper names stable for core and plugin callers. +- Avoid exposing secrets or raw auth payloads in notification text. + +## Work Guidance + +- Coordinate helper changes with plugin UI contracts and existing frontend imports. + +## Verification + +- Smoke-test toast display, dismiss, modal details, and notification severity styling. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/plugins/AGENTS.md b/webui/components/plugins/AGENTS.md new file mode 100644 index 000000000..219c01176 --- /dev/null +++ b/webui/components/plugins/AGENTS.md @@ -0,0 +1,30 @@ +# Plugin Components DOX + +## Purpose + +- Own core WebUI plugin settings, info, list, execution, and toggle components. + +## Ownership + +- Root plugin component files own shared plugin settings and info screens. +- `list/` owns plugin list and execute modal components. +- `toggle/` owns scoped plugin activation UI. +- Store files own plugin modal and settings state. + +## Local Contracts + +- Keep plugin settings modals bound through `$store.pluginSettingsPrototype` conventions. +- Preserve global and scoped toggle semantics using `.toggle-1` and `.toggle-0`. +- Use notification helpers for plugin UI feedback. + +## Work Guidance + +- Coordinate plugin API payload changes with `helpers/plugins.py` and plugin API handlers. + +## Verification + +- Smoke-test plugin list, settings, scoped toggles, plugin info, and execute modal after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/projects/AGENTS.md b/webui/components/projects/AGENTS.md new file mode 100644 index 000000000..d5a9855c9 --- /dev/null +++ b/webui/components/projects/AGENTS.md @@ -0,0 +1,30 @@ +# Project Components DOX + +## Purpose + +- Own WebUI project creation, selection, editing, secrets, model, skill, and file-structure components. + +## Ownership + +- `projects-store.js` owns project state and actions. +- `project-create.html`, `project-list.html`, and `project-selector.html` own project creation and navigation UI. +- `project-edit*.html` files own project editing subsections. +- `project-file-structure-test.html` owns file-structure test UI. + +## Local Contracts + +- Keep project API payloads synchronized with backend project handlers. +- Do not expose project secrets in logs, URLs, or long-lived frontend state unnecessarily. +- Preserve scoped settings interactions with plugins, models, and skills. + +## Work Guidance + +- Verify project edit flows when changing shared project store state. + +## Verification + +- Smoke-test create, select, edit, secrets, LLM, skills, and file-structure flows after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/settings/AGENTS.md b/webui/components/settings/AGENTS.md new file mode 100644 index 000000000..f44e4a596 --- /dev/null +++ b/webui/components/settings/AGENTS.md @@ -0,0 +1,29 @@ +# Settings Components DOX + +## Purpose + +- Own WebUI settings shell and built-in settings subsections. + +## Ownership + +- `settings.html` and `settings-store.js` own the settings shell and state. +- Subdirectories own settings areas such as agent, external, developer, MCP, backup, plugins, secrets, skills, tunnel, and A2A. + +## Local Contracts + +- Keep settings payloads synchronized with backend APIs and plugin settings contracts. +- Do not store secrets in localStorage, URLs, or console output. +- Preserve Store Gating and modal footer conventions in settings components. + +## Work Guidance + +- Prefer subsection-local stores for complex settings areas. +- Coordinate plugin settings UI changes with `webui/components/plugins/` and `plugins/AGENTS.md`. + +## Verification + +- Smoke-test changed settings tabs and save/reload behavior after visible or API changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/sidebar/AGENTS.md b/webui/components/sidebar/AGENTS.md new file mode 100644 index 000000000..5cacb10d9 --- /dev/null +++ b/webui/components/sidebar/AGENTS.md @@ -0,0 +1,31 @@ +# Sidebar Components DOX + +## Purpose + +- Own left sidebar layout, chat/task lists, top actions, and bottom preferences components. + +## Ownership + +- `left-sidebar.html` and `sidebar-store.js` own sidebar shell and shared state. +- `top-section/` owns header and quick actions. +- `chats/` owns chat list UI and state. +- `tasks/` owns task list UI and state. +- `bottom/` owns lower sidebar controls and preferences panel. + +## Local Contracts + +- Preserve responsive sidebar behavior and collapsed/expanded state. +- Keep chat and task list updates compatible with WebSocket state sync. +- Avoid text or controls overflowing fixed sidebar widths. + +## Work Guidance + +- Coordinate navigation and state changes with WebSocket sync and chat/project stores. + +## Verification + +- Smoke-test sidebar collapse, chat list, task list, quick actions, and preferences after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/sync/AGENTS.md b/webui/components/sync/AGENTS.md new file mode 100644 index 000000000..d47d46b80 --- /dev/null +++ b/webui/components/sync/AGENTS.md @@ -0,0 +1,27 @@ +# Sync Components DOX + +## Purpose + +- Own WebUI state synchronization status UI and store. + +## Ownership + +- `sync-store.js` owns sync status state. +- `sync-status.html` owns sync indicator markup. + +## Local Contracts + +- Keep sync state compatible with WebSocket state-sync events. +- Avoid noisy user-facing alerts for transient sync state unless existing UX expects them. + +## Work Guidance + +- Coordinate sync changes with WebSocket client and backend WebSocket extensions. + +## Verification + +- Smoke-test connection, reconnect, and state refresh indicators after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/tooltips/AGENTS.md b/webui/components/tooltips/AGENTS.md new file mode 100644 index 000000000..6fb50e7fe --- /dev/null +++ b/webui/components/tooltips/AGENTS.md @@ -0,0 +1,26 @@ +# Tooltip Components DOX + +## Purpose + +- Own shared tooltip state and behavior for WebUI controls. + +## Ownership + +- `tooltip-store.js` owns tooltip state, positioning, and actions. + +## Local Contracts + +- Keep tooltip positioning compatible with desktop and mobile layouts. +- Do not make tooltips required for completing a workflow. + +## Work Guidance + +- Prefer concise tooltip text and stable positioning around icon-only controls. + +## Verification + +- Smoke-test hover/focus tooltip behavior after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/components/welcome/AGENTS.md b/webui/components/welcome/AGENTS.md new file mode 100644 index 000000000..4237418aa --- /dev/null +++ b/webui/components/welcome/AGENTS.md @@ -0,0 +1,28 @@ +# Welcome Components DOX + +## Purpose + +- Own the WebUI welcome screen, discovery cards, banners, and related state. + +## Ownership + +- `welcome-screen.html` owns welcome screen markup and layout. +- `welcome-store.js` owns welcome state, banners, cards, and actions. + +## Local Contracts + +- Keep banner and discovery card behavior compatible with Python `banners` extensions. +- Supported banner/card CTA actions must stay synchronized with plugin discovery contracts. +- Do not show setup prompts for already configured plugins when backend status can prevent it. + +## Work Guidance + +- Coordinate visual card or CTA changes with plugin discovery and onboarding surfaces. + +## Verification + +- Smoke-test alert banners, feature cards, dismissal, priority ordering, and CTA actions after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/public/AGENTS.md b/webui/public/AGENTS.md new file mode 100644 index 000000000..cdf8bfddc --- /dev/null +++ b/webui/public/AGENTS.md @@ -0,0 +1,32 @@ +# WebUI Public Assets DOX + +## Purpose + +- Own first-party static images, icons, splash art, and PWA assets served by the WebUI. +- Keep visual assets stable for core UI surfaces and settings sections. + +## Ownership + +- SVG files own first-party icons and settings/category symbols. +- Raster files own splash, thumbnail, and app-icon imagery. +- Asset filenames are part of the frontend reference contract when used by HTML, CSS, JS, or plugins. + +## Local Contracts + +- Do not add secrets, user uploads, generated runtime files, or private branding assets here. +- Keep asset paths stable or update every frontend reference in the same change. +- Prefer optimized web formats and reasonable file sizes for assets loaded during startup. + +## Work Guidance + +- Use this folder for shared first-party assets, not component-specific images that belong with a plugin or component. +- Check contrast and legibility for icon changes in both light and dark UI contexts when relevant. + +## Verification + +- Manually smoke-test pages that reference changed assets. +- Run frontend checks when asset references are covered by tests. + +## Child DOX Index + +No child DOX files. diff --git a/webui/vendor/AGENTS.md b/webui/vendor/AGENTS.md new file mode 100644 index 000000000..28ad931ce --- /dev/null +++ b/webui/vendor/AGENTS.md @@ -0,0 +1,42 @@ +# WebUI Vendor Assets DOX + +## Purpose + +- Own vendored third-party browser libraries served by the WebUI. +- Keep external library updates intentional, isolated, and reviewable. + +## Ownership + +- Each direct child directory owns one vendored library or library bundle. +- Vendored files should be treated as upstream artifacts, with local edits avoided unless clearly documented. + +## Local Contracts + +- Do not edit vendored files for application behavior when a wrapper or caller can own the change. +- Preserve license, version, and distribution assumptions for third-party assets. +- Do not add package-manager caches, build outputs, or unrelated downloaded artifacts. + +## Work Guidance + +- Prefer replacing a vendor bundle with a clean upstream build over hand-editing minified files. +- Coordinate library path changes with all HTML, CSS, and JS imports. + +## Verification + +- Manually smoke-test UI paths that load an updated vendor library. +- Run frontend checks when imports or wrappers are covered. + +## Child DOX Index + +Direct child DOX files: + +| Child | Scope | +| --- | --- | +| [_ace/AGENTS.md](_ace/AGENTS.md) | Minimal Ace editor subset used by core editor surfaces. | +| [ace-min/AGENTS.md](ace-min/AGENTS.md) | Full minified Ace distribution and supporting assets. | +| [alpine/AGENTS.md](alpine/AGENTS.md) | Vendored Alpine.js core and collapse plugin. | +| [dompurify/AGENTS.md](dompurify/AGENTS.md) | Vendored DOMPurify sanitizer module. | +| [flatpickr/AGENTS.md](flatpickr/AGENTS.md) | Vendored Flatpickr date/time picker assets. | +| [google/AGENTS.md](google/AGENTS.md) | Vendored Google Material Symbols font and stylesheet. | +| [katex/AGENTS.md](katex/AGENTS.md) | Vendored KaTeX rendering assets. | +| [marked/AGENTS.md](marked/AGENTS.md) | Vendored Marked markdown parser module. | diff --git a/webui/vendor/_ace/AGENTS.md b/webui/vendor/_ace/AGENTS.md new file mode 100644 index 000000000..716d83274 --- /dev/null +++ b/webui/vendor/_ace/AGENTS.md @@ -0,0 +1,27 @@ +# Ace Minimal Vendor DOX + +## Purpose + +- Own the minimal Ace editor files used by focused WebUI editor flows. + +## Ownership + +- JavaScript mode, theme, worker, and loader files are vendored Ace artifacts. +- `ace.min.css` owns local Ace styling required by the bundled files. + +## Local Contracts + +- Avoid hand-editing Ace source files; replace from a known upstream build when updating. +- Keep filenames stable for existing WebUI imports. + +## Work Guidance + +- Prefer adding only the modes and themes actually needed by core UI surfaces. + +## Verification + +- Smoke-test editor surfaces that load this subset after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/vendor/ace-min/AGENTS.md b/webui/vendor/ace-min/AGENTS.md new file mode 100644 index 000000000..ec6faa949 --- /dev/null +++ b/webui/vendor/ace-min/AGENTS.md @@ -0,0 +1,28 @@ +# Ace Min Vendor DOX + +## Purpose + +- Own the full minified Ace editor distribution and static assets. + +## Ownership + +- `ace.js`, extensions, modes, themes, workers, keybindings, and image assets are vendored Ace artifacts. + +## Local Contracts + +- Treat files as upstream-generated assets. +- Do not hand-edit minified or generated files for product behavior. +- Preserve referenced asset filenames unless all imports are updated. + +## Work Guidance + +- Replace this directory with a clean upstream distribution when updating Ace. +- Keep unrelated generated files and local caches out of this vendor bundle. + +## Verification + +- Smoke-test editor and code-input surfaces after vendor updates. + +## Child DOX Index + +No child DOX files. diff --git a/webui/vendor/alpine/AGENTS.md b/webui/vendor/alpine/AGENTS.md new file mode 100644 index 000000000..64cb52cb2 --- /dev/null +++ b/webui/vendor/alpine/AGENTS.md @@ -0,0 +1,27 @@ +# Alpine Vendor DOX + +## Purpose + +- Own vendored Alpine.js browser runtime files used by the WebUI. + +## Ownership + +- `alpine.min.js` owns the Alpine core runtime. +- `alpine.collapse.min.js` owns the collapse plugin runtime. + +## Local Contracts + +- Do not modify vendored Alpine runtime files directly. +- Keep load order compatible with `webui/js/initFw.js` and component initialization. + +## Work Guidance + +- Update Alpine as a deliberate vendor bump and smoke-test component lifecycle directives. + +## Verification + +- Smoke-test WebUI startup, component loading, and store initialization after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/vendor/dompurify/AGENTS.md b/webui/vendor/dompurify/AGENTS.md new file mode 100644 index 000000000..693d2ad0f --- /dev/null +++ b/webui/vendor/dompurify/AGENTS.md @@ -0,0 +1,27 @@ +# DOMPurify Vendor DOX + +## Purpose + +- Own the vendored DOMPurify sanitizer module used for safe HTML rendering. + +## Ownership + +- `purify.es.mjs` owns the browser module imported by WebUI sanitization paths. + +## Local Contracts + +- Do not weaken sanitizer behavior through local edits. +- Keep import paths synchronized with markdown and message rendering code. + +## Work Guidance + +- Replace with a clean upstream module when updating. +- Coordinate sanitizer updates with security-sensitive rendering tests. + +## Verification + +- Run or manually exercise HTML/markdown rendering paths after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/vendor/flatpickr/AGENTS.md b/webui/vendor/flatpickr/AGENTS.md new file mode 100644 index 000000000..5e94ab2e8 --- /dev/null +++ b/webui/vendor/flatpickr/AGENTS.md @@ -0,0 +1,27 @@ +# Flatpickr Vendor DOX + +## Purpose + +- Own vendored Flatpickr date and time picker assets. + +## Ownership + +- `flatpickr.min.js` owns picker runtime behavior. +- `flatpickr.min.css` owns picker vendor styling. + +## Local Contracts + +- Do not hand-edit minified vendor files for application behavior. +- Keep scheduler and date-input imports synchronized with file paths. + +## Work Guidance + +- Replace from a clean upstream release when updating. + +## Verification + +- Smoke-test scheduler or date/time inputs after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/vendor/google/AGENTS.md b/webui/vendor/google/AGENTS.md new file mode 100644 index 000000000..effd8c15b --- /dev/null +++ b/webui/vendor/google/AGENTS.md @@ -0,0 +1,27 @@ +# Google Icons Vendor DOX + +## Purpose + +- Own vendored Google Material Symbols font and stylesheet assets. + +## Ownership + +- `google-icons.css` owns the font-face and icon class definitions. +- `google-icons.ttf` owns the font binary used by the WebUI. + +## Local Contracts + +- Keep font filenames and CSS references synchronized. +- Do not add unrelated remote font assets or tracking references. + +## Work Guidance + +- Replace font and stylesheet together when updating icon coverage. + +## Verification + +- Smoke-test visible icon surfaces after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/vendor/katex/AGENTS.md b/webui/vendor/katex/AGENTS.md new file mode 100644 index 000000000..983d15276 --- /dev/null +++ b/webui/vendor/katex/AGENTS.md @@ -0,0 +1,28 @@ +# KaTeX Vendor DOX + +## Purpose + +- Own vendored KaTeX assets used for math rendering. + +## Ownership + +- `katex.min.js` owns core rendering behavior. +- `katex.auto-render.min.js` owns auto-render support. +- `katex.min.css` owns KaTeX styling. + +## Local Contracts + +- Do not hand-edit minified vendor files. +- Keep markdown/message rendering imports synchronized with asset paths. + +## Work Guidance + +- Replace from a clean upstream release when updating KaTeX. + +## Verification + +- Smoke-test markdown or message content containing math after changes. + +## Child DOX Index + +No child DOX files. diff --git a/webui/vendor/marked/AGENTS.md b/webui/vendor/marked/AGENTS.md new file mode 100644 index 000000000..e171735ba --- /dev/null +++ b/webui/vendor/marked/AGENTS.md @@ -0,0 +1,26 @@ +# Marked Vendor DOX + +## Purpose + +- Own the vendored Marked markdown parser module. + +## Ownership + +- `marked.esm.js` owns markdown parsing behavior imported by WebUI rendering code. + +## Local Contracts + +- Do not hand-edit the vendored parser for application behavior. +- Keep parser updates coordinated with sanitization and message rendering expectations. + +## Work Guidance + +- Replace with a clean upstream module when updating. + +## Verification + +- Smoke-test markdown rendering after changes. + +## Child DOX Index + +No child DOX files.