From e138e33ca998484c435ed87e9fc300ae9e1c5933 Mon Sep 17 00:00:00 2001 From: frdel <38891707+frdel@users.noreply.github.com> Date: Mon, 8 Jun 2026 12:41:53 +0200 Subject: [PATCH] Add file-level DOX docs & update AGENTS indexes Add comprehensive file-level DOX documentation across the repo and update directory AGENTS.md indexes. Many new `*.py.dox.md` files were added under api, helpers, tools, plugins, extensions, webui, and other dirs to document endpoint purpose, ownership, runtime contracts, work guidance, and verification. Several AGENTS.md files were created or updated (agents profiles, api, docker, extensions, helpers, plugins, skills, webui components, etc.) to list child DOX files and clarify documentation/work guidance. Also add example and bundled profile DOX files (agent0, default, developer, hacker, researcher) and minor updates to helpers/dirty_json.py and its tests. These changes improve on-disk documentation coverage and establish the convention that each direct runtime file should have a matching `*.dox.md` describing its contracts and verification steps. --- agents/AGENTS.md | 11 +- agents/_example/AGENTS.md | 33 ++++++ agents/agent0/AGENTS.md | 31 +++++ agents/default/AGENTS.md | 32 +++++ agents/developer/AGENTS.md | 32 +++++ agents/hacker/AGENTS.md | 31 +++++ agents/researcher/AGENTS.md | 31 +++++ api/AGENTS.md | 6 + api/agent_profile_set.py.dox.md | 46 +++++++ api/agents.py.dox.md | 48 ++++++++ api/api_files_get.py.dox.md | 52 ++++++++ api/api_log_get.py.dox.md | 52 ++++++++ api/api_message.py.dox.md | 51 ++++++++ api/api_reset_chat.py.dox.md | 52 ++++++++ api/api_terminate_chat.py.dox.md | 52 ++++++++ api/backup_create.py.dox.md | 49 ++++++++ api/backup_get_defaults.py.dox.md | 47 ++++++++ api/backup_inspect.py.dox.md | 47 ++++++++ api/backup_preview_grouped.py.dox.md | 47 ++++++++ api/backup_restore.py.dox.md | 49 ++++++++ api/backup_restore_preview.py.dox.md | 48 ++++++++ api/backup_test.py.dox.md | 47 ++++++++ api/banners.py.dox.md | 46 +++++++ api/cache_reset.py.dox.md | 53 +++++++++ api/chat_create.py.dox.md | 45 +++++++ api/chat_export.py.dox.md | 44 +++++++ api/chat_files_path_get.py.dox.md | 44 +++++++ api/chat_load.py.dox.md | 44 +++++++ api/chat_remove.py.dox.md | 44 +++++++ api/chat_reset.py.dox.md | 44 +++++++ api/csrf_token.py.dox.md | 57 +++++++++ api/ctx_window_get.py.dox.md | 44 +++++++ api/delete_work_dir_file.py.dox.md | 46 +++++++ api/delete_work_dir_files.py.dox.md | 47 ++++++++ api/download_work_dir_file.py.dox.md | 53 +++++++++ api/download_work_dir_files.py.dox.md | 54 +++++++++ api/edit_work_dir_file.py.dox.md | 50 ++++++++ api/file_info.py.dox.md | 47 ++++++++ api/get_work_dir_files.py.dox.md | 47 ++++++++ api/health.py.dox.md | 52 ++++++++ api/history_get.py.dox.md | 44 +++++++ api/image_get.py.dox.md | 53 +++++++++ api/load_webui_extensions.py.dox.md | 44 +++++++ api/logout.py.dox.md | 47 ++++++++ api/mcp_server_get_detail.py.dox.md | 43 +++++++ api/mcp_server_get_log.py.dox.md | 43 +++++++ api/mcp_servers_apply.py.dox.md | 44 +++++++ api/mcp_servers_status.py.dox.md | 43 +++++++ api/message.py.dox.md | 54 +++++++++ api/message_async.py.dox.md | 42 +++++++ api/message_queue_add.py.dox.md | 44 +++++++ api/message_queue_remove.py.dox.md | 44 +++++++ api/message_queue_send.py.dox.md | 44 +++++++ api/notification_create.py.dox.md | 46 +++++++ api/notifications_clear.py.dox.md | 45 +++++++ api/notifications_history.py.dox.md | 45 +++++++ api/notifications_mark_read.py.dox.md | 45 +++++++ api/nudge.py.dox.md | 44 +++++++ api/pause.py.dox.md | 45 +++++++ api/plugins.py.dox.md | 52 ++++++++ api/plugins_list.py.dox.md | 46 +++++++ api/poll.py.dox.md | 52 ++++++++ api/projects.py.dox.md | 59 +++++++++ api/rename_work_dir_file.py.dox.md | 47 ++++++++ api/restart.py.dox.md | 48 ++++++++ api/rfc.py.dox.md | 47 ++++++++ api/scheduler_task_create.py.dox.md | 44 +++++++ api/scheduler_task_delete.py.dox.md | 44 +++++++ api/scheduler_task_run.py.dox.md | 44 +++++++ api/scheduler_task_update.py.dox.md | 44 +++++++ api/scheduler_tasks_list.py.dox.md | 44 +++++++ api/scheduler_tick.py.dox.md | 50 ++++++++ api/self_update_get.py.dox.md | 45 +++++++ api/self_update_schedule.py.dox.md | 45 +++++++ api/self_update_tags.py.dox.md | 43 +++++++ api/settings_get.py.dox.md | 46 +++++++ api/settings_set.py.dox.md | 44 +++++++ api/settings_workdir_file_structure.py.dox.md | 46 +++++++ api/skills.py.dox.md | 54 +++++++++ api/skills_import.py.dox.md | 44 +++++++ api/skills_import_preview.py.dox.md | 44 +++++++ api/subagents.py.dox.md | 49 ++++++++ api/tunnel.py.dox.md | 48 ++++++++ api/tunnel_proxy.py.dox.md | 46 +++++++ api/upload.py.dox.md | 47 ++++++++ api/upload_work_dir_files.py.dox.md | 47 ++++++++ api/ws_dev_test.py.dox.md | 44 +++++++ api/ws_hello.py.dox.md | 44 +++++++ api/ws_webui.py.dox.md | 49 ++++++++ docker/AGENTS.md | 7 +- docker/base/AGENTS.md | 34 ++++++ docker/run/AGENTS.md | 36 ++++++ extensions/python/AGENTS.md | 35 +++++- extensions/python/_functions/AGENTS.md | 29 +++++ extensions/python/agent_init/AGENTS.md | 26 ++++ extensions/python/banners/AGENTS.md | 27 +++++ .../python/before_main_llm_call/AGENTS.md | 26 ++++ extensions/python/error_format/AGENTS.md | 26 ++++ extensions/python/hist_add_before/AGENTS.md | 26 ++++ .../python/hist_add_tool_result/AGENTS.md | 26 ++++ extensions/python/job_loop/AGENTS.md | 26 ++++ extensions/python/message_loop_end/AGENTS.md | 26 ++++ .../message_loop_prompts_after/AGENTS.md | 27 +++++ .../message_loop_prompts_before/AGENTS.md | 26 ++++ .../python/message_loop_start/AGENTS.md | 26 ++++ extensions/python/monologue_end/AGENTS.md | 26 ++++ extensions/python/monologue_start/AGENTS.md | 26 ++++ extensions/python/process_chain_end/AGENTS.md | 26 ++++ extensions/python/reasoning_stream/AGENTS.md | 26 ++++ .../python/reasoning_stream_chunk/AGENTS.md | 26 ++++ .../python/reasoning_stream_end/AGENTS.md | 26 ++++ extensions/python/response_stream/AGENTS.md | 27 +++++ .../python/response_stream_chunk/AGENTS.md | 26 ++++ .../python/response_stream_end/AGENTS.md | 26 ++++ extensions/python/startup_migration/AGENTS.md | 27 +++++ extensions/python/system_prompt/AGENTS.md | 27 +++++ .../python/tool_execute_after/AGENTS.md | 26 ++++ .../python/tool_execute_before/AGENTS.md | 27 +++++ extensions/python/user_message_ui/AGENTS.md | 26 ++++ .../python/util_model_call_before/AGENTS.md | 26 ++++ extensions/python/webui_ws_connect/AGENTS.md | 26 ++++ .../python/webui_ws_disconnect/AGENTS.md | 26 ++++ extensions/python/webui_ws_event/AGENTS.md | 26 ++++ extensions/webui/AGENTS.md | 15 ++- .../webui/fetch_api_call_after/AGENTS.md | 26 ++++ .../webui/fetch_api_call_before/AGENTS.md | 26 ++++ .../webui/get_message_handler/AGENTS.md | 27 +++++ extensions/webui/initFw_end/AGENTS.md | 27 +++++ .../webui/json_api_call_after/AGENTS.md | 26 ++++ .../webui/json_api_call_before/AGENTS.md | 26 ++++ .../right_canvas_register_surfaces/AGENTS.md | 27 +++++ .../webui/set_messages_after_loop/AGENTS.md | 26 ++++ .../webui/set_messages_before_loop/AGENTS.md | 26 ++++ extensions/webui/webui_ws_push/AGENTS.md | 27 +++++ helpers/AGENTS.md | 6 + helpers/api.py.dox.md | 71 +++++++++++ helpers/attachment_manager.py.dox.md | 47 ++++++++ helpers/backup.py.dox.md | 50 ++++++++ helpers/browser.py.dox.md | 46 +++++++ helpers/cache.py.dox.md | 64 ++++++++++ helpers/call_llm.py.dox.md | 43 +++++++ helpers/chat_media.py.dox.md | 60 ++++++++++ helpers/cli_tunnel.py.dox.md | 54 +++++++++ helpers/cloudflare_tunnel.py.dox.md | 43 +++++++ helpers/context.py.dox.md | 54 +++++++++ helpers/context_utils.py.dox.md | 41 +++++++ helpers/crypto.py.dox.md | 48 ++++++++ helpers/defer.py.dox.md | 55 +++++++++ helpers/dirty_json.py | 74 +++++++++++- helpers/dirty_json.py.dox.md | 51 ++++++++ helpers/docker.py.dox.md | 53 +++++++++ helpers/document_query.py.dox.md | 41 +++++++ helpers/dotenv.py.dox.md | 48 ++++++++ helpers/duckduckgo_search.py.dox.md | 40 +++++++ helpers/email_client.py.dox.md | 39 ++++++ helpers/ephemeral_images.py.dox.md | 58 +++++++++ helpers/errors.py.dox.md | 54 +++++++++ helpers/extension.py.dox.md | 63 ++++++++++ helpers/extract_tools.py.dox.md | 48 ++++++++ helpers/faiss_monkey_patch.py.dox.md | 38 ++++++ helpers/fasta2a_client.py.dox.md | 50 ++++++++ helpers/fasta2a_server.py.dox.md | 52 ++++++++ helpers/file_browser.py.dox.md | 51 ++++++++ helpers/file_tree.py.dox.md | 63 ++++++++++ helpers/files.py.dox.md | 82 +++++++++++++ helpers/functions.py.dox.md | 45 +++++++ helpers/git.py.dox.md | 70 +++++++++++ helpers/guids.py.dox.md | 40 +++++++ helpers/history.py.dox.md | 109 +++++++++++++++++ helpers/images.py.dox.md | 48 ++++++++ helpers/integration_commands.py.dox.md | 53 +++++++++ helpers/job_loop.py.dox.md | 46 +++++++ helpers/kvp.py.dox.md | 52 ++++++++ helpers/localization.py.dox.md | 50 ++++++++ helpers/log.py.dox.md | 68 +++++++++++ helpers/login.py.dox.md | 49 ++++++++ helpers/mcp_handler.py.dox.md | 90 ++++++++++++++ helpers/mcp_server.py.dox.md | 54 +++++++++ helpers/media_artifacts.py.dox.md | 60 ++++++++++ helpers/message_queue.py.dox.md | 53 +++++++++ helpers/messages.py.dox.md | 50 ++++++++ helpers/microsoft_tunnel.py.dox.md | 50 ++++++++ helpers/migration.py.dox.md | 52 ++++++++ helpers/modules.py.dox.md | 53 +++++++++ helpers/network.py.dox.md | 55 +++++++++ helpers/notification.py.dox.md | 62 ++++++++++ helpers/performance.py.dox.md | 42 +++++++ helpers/perplexity_search.py.dox.md | 41 +++++++ helpers/persist_chat.py.dox.md | 65 ++++++++++ helpers/plugins.py.dox.md | 81 +++++++++++++ helpers/print_catch.py.dox.md | 40 +++++++ helpers/print_style.py.dox.md | 54 +++++++++ helpers/process.py.dox.md | 54 +++++++++ helpers/projects.py.dox.md | 85 +++++++++++++ helpers/providers.py.dox.md | 61 ++++++++++ helpers/rate_limiter.py.dox.md | 45 +++++++ helpers/rfc.py.dox.md | 48 ++++++++ helpers/rfc_exchange.py.dox.md | 42 +++++++ helpers/rfc_files.py.dox.md | 70 +++++++++++ helpers/runtime.py.dox.md | 69 +++++++++++ helpers/searxng.py.dox.md | 43 +++++++ helpers/secrets.py.dox.md | 62 ++++++++++ helpers/security.py.dox.md | 45 +++++++ helpers/self_update.py.dox.md | 77 ++++++++++++ helpers/serveo_tunnel.py.dox.md | 43 +++++++ helpers/server_startup.py.dox.md | 62 ++++++++++ helpers/settings.py.dox.md | 88 ++++++++++++++ helpers/skills.py.dox.md | 83 +++++++++++++ helpers/skills_cli.py.dox.md | 51 ++++++++ helpers/skills_import.py.dox.md | 55 +++++++++ helpers/state_migration.py.dox.md | 45 +++++++ helpers/state_monitor.py.dox.md | 59 +++++++++ helpers/state_monitor_integration.py.dox.md | 43 +++++++ helpers/state_snapshot.py.dox.md | 63 ++++++++++ helpers/strings.py.dox.md | 49 ++++++++ helpers/subagents.py.dox.md | 61 ++++++++++ helpers/system_packages.py.dox.md | 44 +++++++ helpers/tailscale_tunnel.py.dox.md | 64 ++++++++++ helpers/task_scheduler.py.dox.md | 112 ++++++++++++++++++ helpers/timed_input.py.dox.md | 40 +++++++ helpers/tokens.py.dox.md | 54 +++++++++ helpers/tool.py.dox.md | 58 +++++++++ helpers/tunnel_common.py.dox.md | 51 ++++++++ helpers/tunnel_manager.py.dox.md | 51 ++++++++ helpers/ui_server.py.dox.md | 57 +++++++++ helpers/update_check.py.dox.md | 41 +++++++ helpers/vector_db.py.dox.md | 53 +++++++++ helpers/virtual_desktop.py.dox.md | 74 ++++++++++++ helpers/virtual_desktop_routes.py.dox.md | 55 +++++++++ helpers/wait.py.dox.md | 49 ++++++++ helpers/watchdog.py.dox.md | 72 +++++++++++ helpers/ws.py.dox.md | 75 ++++++++++++ helpers/ws_manager.py.dox.md | 70 +++++++++++ helpers/yaml.py.dox.md | 52 ++++++++ plugins/AGENTS.md | 33 +++++- plugins/_a0_connector/AGENTS.md | 31 +++++ plugins/_browser/AGENTS.md | 32 +++++ plugins/_chat_branching/AGENTS.md | 31 +++++ plugins/_chat_compaction/AGENTS.md | 32 +++++ plugins/_code_execution/AGENTS.md | 30 +++++ plugins/_desktop/AGENTS.md | 30 +++++ plugins/_discovery/AGENTS.md | 29 +++++ plugins/_document_query/AGENTS.md | 30 +++++ plugins/_editor/AGENTS.md | 30 +++++ plugins/_email_integration/AGENTS.md | 30 +++++ plugins/_error_retry/AGENTS.md | 30 +++++ plugins/_infection_check/AGENTS.md | 29 +++++ plugins/_kokoro_tts/AGENTS.md | 31 +++++ plugins/_memory/AGENTS.md | 31 +++++ plugins/_model_config/AGENTS.md | 30 +++++ plugins/_office/AGENTS.md | 30 +++++ plugins/_onboarding/AGENTS.md | 28 +++++ plugins/_plugin_installer/AGENTS.md | 30 +++++ plugins/_plugin_scan/AGENTS.md | 30 +++++ plugins/_plugin_validator/AGENTS.md | 30 +++++ plugins/_promptinclude/AGENTS.md | 30 +++++ plugins/_skills/AGENTS.md | 31 +++++ plugins/_telegram_integration/AGENTS.md | 30 +++++ plugins/_text_editor/AGENTS.md | 30 +++++ plugins/_time_travel/AGENTS.md | 30 +++++ plugins/_whatsapp_integration/AGENTS.md | 31 +++++ plugins/_whisper_stt/AGENTS.md | 31 +++++ skills/AGENTS.md | 15 ++- skills/a0-contribute-plugin/AGENTS.md | 29 +++++ skills/a0-create-agent/AGENTS.md | 29 +++++ skills/a0-create-plugin/AGENTS.md | 29 +++++ skills/a0-debug-plugin/AGENTS.md | 28 +++++ skills/a0-development/AGENTS.md | 29 +++++ skills/a0-manage-plugin/AGENTS.md | 28 +++++ skills/a0-plugin-router/AGENTS.md | 29 +++++ skills/a0-review-plugin/AGENTS.md | 30 +++++ skills/build-skill/AGENTS.md | 30 +++++ skills/scheduled-tasks/AGENTS.md | 29 +++++ tests/test_dirty_json.py | 39 ++++++ tools/AGENTS.md | 6 + tools/a2a_chat.py.dox.md | 51 ++++++++ tools/call_subordinate.py.dox.md | 46 +++++++ tools/document_query.py.dox.md | 41 +++++++ tools/notify_user.py.dox.md | 44 +++++++ tools/response.py.dox.md | 53 +++++++++ tools/scheduler.py.dox.md | 63 ++++++++++ tools/search_engine.py.dox.md | 46 +++++++ tools/skills_tool.py.dox.md | 51 ++++++++ tools/unknown.py.dox.md | 48 ++++++++ tools/vision_load.py.dox.md | 50 ++++++++ tools/wait.py.dox.md | 54 +++++++++ webui/AGENTS.md | 2 + webui/components/AGENTS.md | 19 ++- webui/components/_examples/AGENTS.md | 27 +++++ webui/components/canvas/AGENTS.md | 28 +++++ webui/components/chat/AGENTS.md | 32 +++++ webui/components/dropdown/AGENTS.md | 26 ++++ webui/components/messages/AGENTS.md | 29 +++++ webui/components/modals/AGENTS.md | 30 +++++ webui/components/notifications/AGENTS.md | 30 +++++ webui/components/plugins/AGENTS.md | 30 +++++ webui/components/projects/AGENTS.md | 30 +++++ webui/components/settings/AGENTS.md | 29 +++++ webui/components/sidebar/AGENTS.md | 31 +++++ webui/components/sync/AGENTS.md | 27 +++++ webui/components/tooltips/AGENTS.md | 26 ++++ webui/components/welcome/AGENTS.md | 28 +++++ webui/public/AGENTS.md | 32 +++++ webui/vendor/AGENTS.md | 42 +++++++ webui/vendor/_ace/AGENTS.md | 27 +++++ webui/vendor/ace-min/AGENTS.md | 28 +++++ webui/vendor/alpine/AGENTS.md | 27 +++++ webui/vendor/dompurify/AGENTS.md | 27 +++++ webui/vendor/flatpickr/AGENTS.md | 27 +++++ webui/vendor/google/AGENTS.md | 27 +++++ webui/vendor/katex/AGENTS.md | 28 +++++ webui/vendor/marked/AGENTS.md | 26 ++++ 312 files changed, 13246 insertions(+), 10 deletions(-) create mode 100644 agents/_example/AGENTS.md create mode 100644 agents/agent0/AGENTS.md create mode 100644 agents/default/AGENTS.md create mode 100644 agents/developer/AGENTS.md create mode 100644 agents/hacker/AGENTS.md create mode 100644 agents/researcher/AGENTS.md create mode 100644 api/agent_profile_set.py.dox.md create mode 100644 api/agents.py.dox.md create mode 100644 api/api_files_get.py.dox.md create mode 100644 api/api_log_get.py.dox.md create mode 100644 api/api_message.py.dox.md create mode 100644 api/api_reset_chat.py.dox.md create mode 100644 api/api_terminate_chat.py.dox.md create mode 100644 api/backup_create.py.dox.md create mode 100644 api/backup_get_defaults.py.dox.md create mode 100644 api/backup_inspect.py.dox.md create mode 100644 api/backup_preview_grouped.py.dox.md create mode 100644 api/backup_restore.py.dox.md create mode 100644 api/backup_restore_preview.py.dox.md create mode 100644 api/backup_test.py.dox.md create mode 100644 api/banners.py.dox.md create mode 100644 api/cache_reset.py.dox.md create mode 100644 api/chat_create.py.dox.md create mode 100644 api/chat_export.py.dox.md create mode 100644 api/chat_files_path_get.py.dox.md create mode 100644 api/chat_load.py.dox.md create mode 100644 api/chat_remove.py.dox.md create mode 100644 api/chat_reset.py.dox.md create mode 100644 api/csrf_token.py.dox.md create mode 100644 api/ctx_window_get.py.dox.md create mode 100644 api/delete_work_dir_file.py.dox.md create mode 100644 api/delete_work_dir_files.py.dox.md create mode 100644 api/download_work_dir_file.py.dox.md create mode 100644 api/download_work_dir_files.py.dox.md create mode 100644 api/edit_work_dir_file.py.dox.md create mode 100644 api/file_info.py.dox.md create mode 100644 api/get_work_dir_files.py.dox.md create mode 100644 api/health.py.dox.md create mode 100644 api/history_get.py.dox.md create mode 100644 api/image_get.py.dox.md create mode 100644 api/load_webui_extensions.py.dox.md create mode 100644 api/logout.py.dox.md create mode 100644 api/mcp_server_get_detail.py.dox.md create mode 100644 api/mcp_server_get_log.py.dox.md create mode 100644 api/mcp_servers_apply.py.dox.md create mode 100644 api/mcp_servers_status.py.dox.md create mode 100644 api/message.py.dox.md create mode 100644 api/message_async.py.dox.md create mode 100644 api/message_queue_add.py.dox.md create mode 100644 api/message_queue_remove.py.dox.md create mode 100644 api/message_queue_send.py.dox.md create mode 100644 api/notification_create.py.dox.md create mode 100644 api/notifications_clear.py.dox.md create mode 100644 api/notifications_history.py.dox.md create mode 100644 api/notifications_mark_read.py.dox.md create mode 100644 api/nudge.py.dox.md create mode 100644 api/pause.py.dox.md create mode 100644 api/plugins.py.dox.md create mode 100644 api/plugins_list.py.dox.md create mode 100644 api/poll.py.dox.md create mode 100644 api/projects.py.dox.md create mode 100644 api/rename_work_dir_file.py.dox.md create mode 100644 api/restart.py.dox.md create mode 100644 api/rfc.py.dox.md create mode 100644 api/scheduler_task_create.py.dox.md create mode 100644 api/scheduler_task_delete.py.dox.md create mode 100644 api/scheduler_task_run.py.dox.md create mode 100644 api/scheduler_task_update.py.dox.md create mode 100644 api/scheduler_tasks_list.py.dox.md create mode 100644 api/scheduler_tick.py.dox.md create mode 100644 api/self_update_get.py.dox.md create mode 100644 api/self_update_schedule.py.dox.md create mode 100644 api/self_update_tags.py.dox.md create mode 100644 api/settings_get.py.dox.md create mode 100644 api/settings_set.py.dox.md create mode 100644 api/settings_workdir_file_structure.py.dox.md create mode 100644 api/skills.py.dox.md create mode 100644 api/skills_import.py.dox.md create mode 100644 api/skills_import_preview.py.dox.md create mode 100644 api/subagents.py.dox.md create mode 100644 api/tunnel.py.dox.md create mode 100644 api/tunnel_proxy.py.dox.md create mode 100644 api/upload.py.dox.md create mode 100644 api/upload_work_dir_files.py.dox.md create mode 100644 api/ws_dev_test.py.dox.md create mode 100644 api/ws_hello.py.dox.md create mode 100644 api/ws_webui.py.dox.md create mode 100644 docker/base/AGENTS.md create mode 100644 docker/run/AGENTS.md create mode 100644 extensions/python/_functions/AGENTS.md create mode 100644 extensions/python/agent_init/AGENTS.md create mode 100644 extensions/python/banners/AGENTS.md create mode 100644 extensions/python/before_main_llm_call/AGENTS.md create mode 100644 extensions/python/error_format/AGENTS.md create mode 100644 extensions/python/hist_add_before/AGENTS.md create mode 100644 extensions/python/hist_add_tool_result/AGENTS.md create mode 100644 extensions/python/job_loop/AGENTS.md create mode 100644 extensions/python/message_loop_end/AGENTS.md create mode 100644 extensions/python/message_loop_prompts_after/AGENTS.md create mode 100644 extensions/python/message_loop_prompts_before/AGENTS.md create mode 100644 extensions/python/message_loop_start/AGENTS.md create mode 100644 extensions/python/monologue_end/AGENTS.md create mode 100644 extensions/python/monologue_start/AGENTS.md create mode 100644 extensions/python/process_chain_end/AGENTS.md create mode 100644 extensions/python/reasoning_stream/AGENTS.md create mode 100644 extensions/python/reasoning_stream_chunk/AGENTS.md create mode 100644 extensions/python/reasoning_stream_end/AGENTS.md create mode 100644 extensions/python/response_stream/AGENTS.md create mode 100644 extensions/python/response_stream_chunk/AGENTS.md create mode 100644 extensions/python/response_stream_end/AGENTS.md create mode 100644 extensions/python/startup_migration/AGENTS.md create mode 100644 extensions/python/system_prompt/AGENTS.md create mode 100644 extensions/python/tool_execute_after/AGENTS.md create mode 100644 extensions/python/tool_execute_before/AGENTS.md create mode 100644 extensions/python/user_message_ui/AGENTS.md create mode 100644 extensions/python/util_model_call_before/AGENTS.md create mode 100644 extensions/python/webui_ws_connect/AGENTS.md create mode 100644 extensions/python/webui_ws_disconnect/AGENTS.md create mode 100644 extensions/python/webui_ws_event/AGENTS.md create mode 100644 extensions/webui/fetch_api_call_after/AGENTS.md create mode 100644 extensions/webui/fetch_api_call_before/AGENTS.md create mode 100644 extensions/webui/get_message_handler/AGENTS.md create mode 100644 extensions/webui/initFw_end/AGENTS.md create mode 100644 extensions/webui/json_api_call_after/AGENTS.md create mode 100644 extensions/webui/json_api_call_before/AGENTS.md create mode 100644 extensions/webui/right_canvas_register_surfaces/AGENTS.md create mode 100644 extensions/webui/set_messages_after_loop/AGENTS.md create mode 100644 extensions/webui/set_messages_before_loop/AGENTS.md create mode 100644 extensions/webui/webui_ws_push/AGENTS.md create mode 100644 helpers/api.py.dox.md create mode 100644 helpers/attachment_manager.py.dox.md create mode 100644 helpers/backup.py.dox.md create mode 100644 helpers/browser.py.dox.md create mode 100644 helpers/cache.py.dox.md create mode 100644 helpers/call_llm.py.dox.md create mode 100644 helpers/chat_media.py.dox.md create mode 100644 helpers/cli_tunnel.py.dox.md create mode 100644 helpers/cloudflare_tunnel.py.dox.md create mode 100644 helpers/context.py.dox.md create mode 100644 helpers/context_utils.py.dox.md create mode 100644 helpers/crypto.py.dox.md create mode 100644 helpers/defer.py.dox.md create mode 100644 helpers/dirty_json.py.dox.md create mode 100644 helpers/docker.py.dox.md create mode 100644 helpers/document_query.py.dox.md create mode 100644 helpers/dotenv.py.dox.md create mode 100644 helpers/duckduckgo_search.py.dox.md create mode 100644 helpers/email_client.py.dox.md create mode 100644 helpers/ephemeral_images.py.dox.md create mode 100644 helpers/errors.py.dox.md create mode 100644 helpers/extension.py.dox.md create mode 100644 helpers/extract_tools.py.dox.md create mode 100644 helpers/faiss_monkey_patch.py.dox.md create mode 100644 helpers/fasta2a_client.py.dox.md create mode 100644 helpers/fasta2a_server.py.dox.md create mode 100644 helpers/file_browser.py.dox.md create mode 100644 helpers/file_tree.py.dox.md create mode 100644 helpers/files.py.dox.md create mode 100644 helpers/functions.py.dox.md create mode 100644 helpers/git.py.dox.md create mode 100644 helpers/guids.py.dox.md create mode 100644 helpers/history.py.dox.md create mode 100644 helpers/images.py.dox.md create mode 100644 helpers/integration_commands.py.dox.md create mode 100644 helpers/job_loop.py.dox.md create mode 100644 helpers/kvp.py.dox.md create mode 100644 helpers/localization.py.dox.md create mode 100644 helpers/log.py.dox.md create mode 100644 helpers/login.py.dox.md create mode 100644 helpers/mcp_handler.py.dox.md create mode 100644 helpers/mcp_server.py.dox.md create mode 100644 helpers/media_artifacts.py.dox.md create mode 100644 helpers/message_queue.py.dox.md create mode 100644 helpers/messages.py.dox.md create mode 100644 helpers/microsoft_tunnel.py.dox.md create mode 100644 helpers/migration.py.dox.md create mode 100644 helpers/modules.py.dox.md create mode 100644 helpers/network.py.dox.md create mode 100644 helpers/notification.py.dox.md create mode 100644 helpers/performance.py.dox.md create mode 100644 helpers/perplexity_search.py.dox.md create mode 100644 helpers/persist_chat.py.dox.md create mode 100644 helpers/plugins.py.dox.md create mode 100644 helpers/print_catch.py.dox.md create mode 100644 helpers/print_style.py.dox.md create mode 100644 helpers/process.py.dox.md create mode 100644 helpers/projects.py.dox.md create mode 100644 helpers/providers.py.dox.md create mode 100644 helpers/rate_limiter.py.dox.md create mode 100644 helpers/rfc.py.dox.md create mode 100644 helpers/rfc_exchange.py.dox.md create mode 100644 helpers/rfc_files.py.dox.md create mode 100644 helpers/runtime.py.dox.md create mode 100644 helpers/searxng.py.dox.md create mode 100644 helpers/secrets.py.dox.md create mode 100644 helpers/security.py.dox.md create mode 100644 helpers/self_update.py.dox.md create mode 100644 helpers/serveo_tunnel.py.dox.md create mode 100644 helpers/server_startup.py.dox.md create mode 100644 helpers/settings.py.dox.md create mode 100644 helpers/skills.py.dox.md create mode 100644 helpers/skills_cli.py.dox.md create mode 100644 helpers/skills_import.py.dox.md create mode 100644 helpers/state_migration.py.dox.md create mode 100644 helpers/state_monitor.py.dox.md create mode 100644 helpers/state_monitor_integration.py.dox.md create mode 100644 helpers/state_snapshot.py.dox.md create mode 100644 helpers/strings.py.dox.md create mode 100644 helpers/subagents.py.dox.md create mode 100644 helpers/system_packages.py.dox.md create mode 100644 helpers/tailscale_tunnel.py.dox.md create mode 100644 helpers/task_scheduler.py.dox.md create mode 100644 helpers/timed_input.py.dox.md create mode 100644 helpers/tokens.py.dox.md create mode 100644 helpers/tool.py.dox.md create mode 100644 helpers/tunnel_common.py.dox.md create mode 100644 helpers/tunnel_manager.py.dox.md create mode 100644 helpers/ui_server.py.dox.md create mode 100644 helpers/update_check.py.dox.md create mode 100644 helpers/vector_db.py.dox.md create mode 100644 helpers/virtual_desktop.py.dox.md create mode 100644 helpers/virtual_desktop_routes.py.dox.md create mode 100644 helpers/wait.py.dox.md create mode 100644 helpers/watchdog.py.dox.md create mode 100644 helpers/ws.py.dox.md create mode 100644 helpers/ws_manager.py.dox.md create mode 100644 helpers/yaml.py.dox.md create mode 100644 plugins/_a0_connector/AGENTS.md create mode 100644 plugins/_browser/AGENTS.md create mode 100644 plugins/_chat_branching/AGENTS.md create mode 100644 plugins/_chat_compaction/AGENTS.md create mode 100644 plugins/_code_execution/AGENTS.md create mode 100644 plugins/_desktop/AGENTS.md create mode 100644 plugins/_discovery/AGENTS.md create mode 100644 plugins/_document_query/AGENTS.md create mode 100644 plugins/_editor/AGENTS.md create mode 100644 plugins/_email_integration/AGENTS.md create mode 100644 plugins/_error_retry/AGENTS.md create mode 100644 plugins/_infection_check/AGENTS.md create mode 100644 plugins/_kokoro_tts/AGENTS.md create mode 100644 plugins/_memory/AGENTS.md create mode 100644 plugins/_model_config/AGENTS.md create mode 100644 plugins/_office/AGENTS.md create mode 100644 plugins/_onboarding/AGENTS.md create mode 100644 plugins/_plugin_installer/AGENTS.md create mode 100644 plugins/_plugin_scan/AGENTS.md create mode 100644 plugins/_plugin_validator/AGENTS.md create mode 100644 plugins/_promptinclude/AGENTS.md create mode 100644 plugins/_skills/AGENTS.md create mode 100644 plugins/_telegram_integration/AGENTS.md create mode 100644 plugins/_text_editor/AGENTS.md create mode 100644 plugins/_time_travel/AGENTS.md create mode 100644 plugins/_whatsapp_integration/AGENTS.md create mode 100644 plugins/_whisper_stt/AGENTS.md create mode 100644 skills/a0-contribute-plugin/AGENTS.md create mode 100644 skills/a0-create-agent/AGENTS.md create mode 100644 skills/a0-create-plugin/AGENTS.md create mode 100644 skills/a0-debug-plugin/AGENTS.md create mode 100644 skills/a0-development/AGENTS.md create mode 100644 skills/a0-manage-plugin/AGENTS.md create mode 100644 skills/a0-plugin-router/AGENTS.md create mode 100644 skills/a0-review-plugin/AGENTS.md create mode 100644 skills/build-skill/AGENTS.md create mode 100644 skills/scheduled-tasks/AGENTS.md create mode 100644 tools/a2a_chat.py.dox.md create mode 100644 tools/call_subordinate.py.dox.md create mode 100644 tools/document_query.py.dox.md create mode 100644 tools/notify_user.py.dox.md create mode 100644 tools/response.py.dox.md create mode 100644 tools/scheduler.py.dox.md create mode 100644 tools/search_engine.py.dox.md create mode 100644 tools/skills_tool.py.dox.md create mode 100644 tools/unknown.py.dox.md create mode 100644 tools/vision_load.py.dox.md create mode 100644 tools/wait.py.dox.md create mode 100644 webui/components/_examples/AGENTS.md create mode 100644 webui/components/canvas/AGENTS.md create mode 100644 webui/components/chat/AGENTS.md create mode 100644 webui/components/dropdown/AGENTS.md create mode 100644 webui/components/messages/AGENTS.md create mode 100644 webui/components/modals/AGENTS.md create mode 100644 webui/components/notifications/AGENTS.md create mode 100644 webui/components/plugins/AGENTS.md create mode 100644 webui/components/projects/AGENTS.md create mode 100644 webui/components/settings/AGENTS.md create mode 100644 webui/components/sidebar/AGENTS.md create mode 100644 webui/components/sync/AGENTS.md create mode 100644 webui/components/tooltips/AGENTS.md create mode 100644 webui/components/welcome/AGENTS.md create mode 100644 webui/public/AGENTS.md create mode 100644 webui/vendor/AGENTS.md create mode 100644 webui/vendor/_ace/AGENTS.md create mode 100644 webui/vendor/ace-min/AGENTS.md create mode 100644 webui/vendor/alpine/AGENTS.md create mode 100644 webui/vendor/dompurify/AGENTS.md create mode 100644 webui/vendor/flatpickr/AGENTS.md create mode 100644 webui/vendor/google/AGENTS.md create mode 100644 webui/vendor/katex/AGENTS.md create mode 100644 webui/vendor/marked/AGENTS.md 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.