vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-07-09 17:08:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
agent-zero/helpers/AGENTS.md
frdel e138e33ca9 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.
2026-06-08 12:41:53 +02:00

2.6 KiB
Raw Blame History

Backend Helpers DOX

Purpose

  • Own shared Python framework utilities used by agents, APIs, tools, plugins, WebSockets, persistence, and runtime services.
  • Keep cross-cutting behavior stable and tested.

Ownership

  • Helper modules provide reusable services; feature-specific route handlers belong in api/, tool behavior in tools/, and plugin-local logic inside plugin directories.
  • Security, auth, settings, file access, plugin discovery, extension dispatch, notifications, state snapshots, scheduler, tunnel, and WebSocket primitives live here.

Local Contracts

  • Preserve public helper APIs used by core code and plugins unless all callers, docs, and tests are updated.
  • Use structured parsers and serializers for YAML, JSON, paths, and URLs instead of ad hoc string handling.
  • Keep path handling constrained to intended roots for user files, uploads, downloads, projects, and workdirs.
  • 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

No child DOX files.