agent-zero/plugins/_agent_editor/AGENTS.md

Agent Editor Plugin DOX

Purpose

• Own the deterministic Easy and Advanced Agent Editor API and WebUI workflow.

Ownership

• helpers/editor.py composes existing profile, prompt, model, tool, and skill owners into editor state and sparse change plans.
• api/ owns authenticated/CSRF-protected state, save, and avatar routes.
• webui/ owns the Alpine store, modal surface, styling, and client-side draft.
• extensions/webui/ owns lifecycle registration on the shared modal stack and the global entry points used by existing WebUI surfaces.

Local Contracts

• The editor performs zero model calls.
• Profile list requests stay lightweight: summary rows inspect only sparse editor-owned keys and files and never construct full save or removal plans.
• Writes are limited to the selected profile layer — global usr/agents/<profile-id> or project usr/projects/<project>/.a0proj/agents/<profile-id> — and only to paths or config keys listed in the validated change plan. The availability toggle reuses the existing project .a0proj/agents.json load/save owner; the WebUI permits one availability save at a time. Global availability remains a sparse enabled profile override.
• Every profile, including Default, can be made unavailable. The backend rejects only the change that would leave the selected scope with no available profile, then reconciles loaded chats through the shared project owner.
• Destructive cleanup and custom-profile deletion require an explicit confirmed apply request. Profile creation and availability invariants are rechecked at the existing editor mutation boundary; project availability refuses malformed agents.json and changes only the requested profile entry through the existing project storage owner.
• Never call helpers.subagents.save_agent_data.
• Fast creation from slash commands and connector clients calls helpers/editor.py:save_easy_profile, so profile IDs, validation, sparse writes, and the mutation boundary stay identical to Easy mode.
• Authored profile definitions remain YAML; editor-written plugin configs remain JSON.
• Profile config paths use helpers.plugins.determine_plugin_asset_path for the selected Global or project scope and remain rooted in that exact validated profile boundary.
• Project profiles inherit the existing global, plugin, and bundled layers. Removing or deleting in project scope never mutates those inherited layers; only agents created in the selected scope are deletable.
• Bundled agents/ files are read-only.
• Advanced prompt text is edited with a full-height bundled ACE editor in Markdown mode. The selected file's customization path sits below its name; per-file close/check actions discard or accept the current edit checkpoint, while the editor's global save remains the only persistence boundary.
• New profiles require a display name and non-empty agent instructions in both Easy and Advanced; existing Advanced prompt edits retain per-file semantics.
• Easy and Advanced share the same segmented capability controls: Default removes the item from allowed and blocked, On stores it in allowed, and Off stores it in blocked. Tools, canonical MCP entries, and Skills expose independent default switches; explicit choices remain pinned when a default changes, and opening then undoing an inherited policy produces no write. Easy places each initially closed native accordion directly below its default switch. Advanced gives Tools, MCPs, and Skills separate sections while keeping unavailable retained IDs reviewable. Framework-required tools remain absent.
• Model selection in both modes reuses _model_config's compact preset dropdown and preset editor; Agent Editor persists only the scoped preset reference.
• The exact default profile is an internal baseline and is omitted only from selectable and editable UI rows. Runtime discovery remains unchanged, and an existing chat using it may still report it as current status.
• Manage agents reuses the plugin-settings project vocabulary: Global or one existing project. The active chat profile appears once above the list; each row exposes scoped availability, duplication, restore for inherited profiles, icon-only Edit, and Delete for profiles owned by that scope. Duplicate materializes the effective source profile into the selected writable layer with a collision-free ID and title. Restore visibility follows the sparse removal plan, ignores unrelated profile files, and reports successful reset. Availability changes quietly refresh the adjacent profile switcher catalog without a success toast.
• The same project selector is available inside Create and Edit. Create keeps the in-progress draft when its destination changes; Edit reloads the selected profile from the new scope after guarding unsaved changes.
• Save & test activates the saved profile in a fresh chat using that same scope.
• The WebUI uses the shared modal stack, labeled prompt scroll regions, and 24px-or-larger policy and text-action targets.

Verification

• Run Agent Editor, profile merge, tool policy, skill policy, API security, and WebUI tests, then verify the explicitly named bind-mounted runtime.

Child DOX Index

No child DOX files.