| 1 | # Python Extensions DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own built-in backend lifecycle extensions under `extensions/python/`. |
| 6 | - Keep Python hook behavior compatible with `helpers.extension.call_extensions_async` and `call_extensions_sync`. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - Each direct subdirectory is one named extension point. |
| 11 | - Python files inside an extension point are loaded in deterministic filename order. |
| 12 | - Implicit `@extensible` hook implementations use `_functions/<module>/<qualname>/<start|end>/` layout when present. |
| 13 | |
| 14 | ## Local Contracts |
| 15 | |
| 16 | - Extension functions must match the arguments supplied by their hook point. |
| 17 | - Preserve numeric prefixes when ordering affects prompt construction, stream masking, persistence, or cleanup. |
| 18 | - Use `AgentContext` from `agent` when context access is needed. |
| 19 | - Do not log unmasked secrets, raw hidden prompt sections, or private user data. |
| 20 | |
| 21 | ## Work Guidance |
| 22 | |
| 23 | - Keep extension modules import-light; many hooks run during hot paths. |
| 24 | - Use mutable `ctx` or `data` dictionaries according to the hook contract when rewriting content. |
| 25 | - Add or update tests when a hook changes prompt content, message history, tool output, streaming, or persistence behavior. |
| 26 | |
| 27 | ## Verification |
| 28 | |
| 29 | - Run targeted tests for the affected lifecycle area. |
| 30 | - Run a startup smoke check for `agent_init`, `startup_migration`, or `system_prompt` changes when practical. |
| 31 | |
| 32 | ## Child DOX Index |
| 33 | |
| 34 | Direct child DOX files: |
| 35 | |
| 36 | | Child | Scope | |
| 37 | | --- | --- | |
| 38 | | [_functions/AGENTS.md](_functions/AGENTS.md) | Implicit `@extensible` backend hook implementations. | |
| 39 | | [agent_init/AGENTS.md](agent_init/AGENTS.md) | Agent context initialization hooks. | |
| 40 | | [banners/AGENTS.md](banners/AGENTS.md) | Backend banner and discovery-card contributions. | |
| 41 | | [before_main_llm_call/AGENTS.md](before_main_llm_call/AGENTS.md) | Pre-main-model-call behavior. | |
| 42 | | [error_format/AGENTS.md](error_format/AGENTS.md) | Error formatting and masking behavior. | |
| 43 | | [hist_add_before/AGENTS.md](hist_add_before/AGENTS.md) | Pre-history-insertion masking behavior. | |
| 44 | | [hist_add_tool_result/AGENTS.md](hist_add_tool_result/AGENTS.md) | Tool-result history side effects. | |
| 45 | | [job_loop/AGENTS.md](job_loop/AGENTS.md) | Periodic backend maintenance jobs. | |
| 46 | | [message_loop_end/AGENTS.md](message_loop_end/AGENTS.md) | End-of-message-loop history and persistence behavior. | |
| 47 | | [message_loop_result/AGENTS.md](message_loop_result/AGENTS.md) | Completed model-result normalization and default-processing interception. | |
| 48 | | [message_loop_prompts_after/AGENTS.md](message_loop_prompts_after/AGENTS.md) | Prompt protocol and extras assembled around message-loop prompt construction. | |
| 49 | | [message_loop_prompts_before/AGENTS.md](message_loop_prompts_before/AGENTS.md) | Pre-prompt-construction message-loop gates. | |
| 50 | | [message_loop_start/AGENTS.md](message_loop_start/AGENTS.md) | Start-of-message-loop iteration state. | |
| 51 | | [monologue_end/AGENTS.md](monologue_end/AGENTS.md) | End-of-monologue UI and cleanup behavior. | |
| 52 | | [monologue_start/AGENTS.md](monologue_start/AGENTS.md) | Core start-of-monologue lifecycle extensions. | |
| 53 | | [process_chain_end/AGENTS.md](process_chain_end/AGENTS.md) | Process-chain completion and queued-message handling. | |
| 54 | | [reasoning_stream/AGENTS.md](reasoning_stream/AGENTS.md) | Full reasoning stream handling. | |
| 55 | | [reasoning_stream_chunk/AGENTS.md](reasoning_stream_chunk/AGENTS.md) | Reasoning stream chunk masking. | |
| 56 | | [reasoning_stream_end/AGENTS.md](reasoning_stream_end/AGENTS.md) | Reasoning stream finalization. | |
| 57 | | [response_stream/AGENTS.md](response_stream/AGENTS.md) | Full assistant response stream handling. | |
| 58 | | [response_stream_chunk/AGENTS.md](response_stream_chunk/AGENTS.md) | Assistant response chunk masking. | |
| 59 | | [response_stream_end/AGENTS.md](response_stream_end/AGENTS.md) | Assistant response stream finalization. | |
| 60 | | [startup_migration/AGENTS.md](startup_migration/AGENTS.md) | Startup migrations. | |
| 61 | | [system_prompt/AGENTS.md](system_prompt/AGENTS.md) | Core system prompt section construction. | |
| 62 | | [tool_execute_after/AGENTS.md](tool_execute_after/AGENTS.md) | Post-tool-execution processing. | |
| 63 | | [tool_execute_before/AGENTS.md](tool_execute_before/AGENTS.md) | Pre-tool-execution processing. | |
| 64 | | [user_message_ui/AGENTS.md](user_message_ui/AGENTS.md) | User-visible UI message hooks. | |
| 65 | | [util_model_call_before/AGENTS.md](util_model_call_before/AGENTS.md) | Pre-utility-model-call masking. | |
| 66 | | [webui_ws_connect/AGENTS.md](webui_ws_connect/AGENTS.md) | WebUI WebSocket connect behavior. | |
| 67 | | [webui_ws_disconnect/AGENTS.md](webui_ws_disconnect/AGENTS.md) | WebUI WebSocket disconnect behavior. | |
| 68 | | [webui_ws_event/AGENTS.md](webui_ws_event/AGENTS.md) | Incoming WebUI WebSocket event behavior. | |