mirror of
https://github.com/agent0ai/agent-zero.git
synced 2026-07-12 02:18:28 +00:00
Compare commits
No commits in common. "main" and "v1.16" have entirely different histories.
972 changed files with 8686 additions and 76692 deletions
38
.github/AGENTS.md
vendored
38
.github/AGENTS.md
vendored
|
|
@ -1,38 +0,0 @@
|
|||
# GitHub Automation DOX
|
||||
|
||||
## Purpose
|
||||
|
||||
- Own repository automation that runs on GitHub, including workflows and release-planning scripts.
|
||||
- Keep CI, Docker publishing, stale issue handling, and release-note generation aligned with repository release rules.
|
||||
|
||||
## Ownership
|
||||
|
||||
- `workflows/` contains GitHub Actions workflow definitions.
|
||||
- `scripts/` contains Python helpers called by workflows.
|
||||
- This file owns release automation rules; user-facing release documentation belongs under `docs/`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Docker publishing lives in `workflows/docker-publish.yml` and delegates planning to `scripts/docker_release_plan.py`.
|
||||
- Releasable tags are `vX.Y` tags at or above `v1.0`, matching the workflow environment.
|
||||
- On `main`, the newest eligible tag publishes both the version tag and `latest`, then creates or updates its GitHub release after the image push succeeds; other allowed branches publish only their branch tag.
|
||||
- Manual dispatch without a tag backfills missing Docker Hub tags. Manual dispatch with a tag rebuilds that target and refreshes `latest` and the GitHub release only when it remains the newest eligible tag on `main`.
|
||||
- Release-note generation reads `scripts/openrouter_release_notes_system_prompt.md` from the repository root and requires OpenRouter credentials from workflow environment variables.
|
||||
- Release notes compare against the previous published GitHub release tag and fall back to `No release notes.` when no meaningful summary is generated.
|
||||
- Keep workflow secrets in GitHub Actions secrets or environment variables. Do not commit credentials, tokens, or generated release bodies containing private data.
|
||||
- Workflow scripts must fail loudly with actionable messages when required environment variables or git refs are missing.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Prefer deterministic, testable Python for workflow planning logic instead of complex inline shell in YAML.
|
||||
- Preserve manual dispatch behavior when changing Docker publishing.
|
||||
- Keep branch, tag, and release behavior synchronized between workflow YAML, release scripts, tests, and user-facing release documentation.
|
||||
|
||||
## Verification
|
||||
|
||||
- Run `pytest tests/test_docker_release_plan.py` after changing Docker publish planning or release workflow behavior.
|
||||
- Run targeted tests for any changed script that already has coverage.
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child DOX files.
|
||||
307
AGENTS.md
307
AGENTS.md
|
|
@ -1,92 +1,253 @@
|
|||
# Agent Zero DOX
|
||||
# Agent Zero - AGENTS.md
|
||||
|
||||
## Purpose
|
||||
[Generated using reconnaissance on 2026-02-22]
|
||||
|
||||
- Own project-wide engineering rules and the top-level DOX index.
|
||||
- Keep detailed contracts in the closest applicable child `AGENTS.md`.
|
||||
## Quick Reference
|
||||
Tech Stack: Python 3.12+ | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)
|
||||
Dev Server: python run_ui.py (runs on http://localhost:50001 by default)
|
||||
Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)
|
||||
Documentation: README.md | docs/
|
||||
Frontend Deep Dives: [Component System](docs/agents/AGENTS.components.md) | [Modal System](docs/agents/AGENTS.modals.md) | [Plugin Architecture](docs/agents/AGENTS.plugins.md) | [Banners & Discovery](docs/agents/AGENTS.banners.md)
|
||||
|
||||
## Project
|
||||
---
|
||||
|
||||
- Stack: Python 3.12+ framework, Python 3.13 agent execution runtime, Flask, Alpine.js, LiteLLM, and Socket.IO.
|
||||
- Start the WebUI with `python run_ui.py`; discover its URL from startup output, Docker mappings, or explicit configuration rather than assuming a port.
|
||||
- Run the full test suite with `pytest` or a focused file with `pytest tests/test_name.py`.
|
||||
- Human-facing documentation lives in `README.md` and `docs/`.
|
||||
## Table of Contents
|
||||
1. [Project Overview](#project-overview)
|
||||
2. [Core Commands](#core-commands)
|
||||
3. [Docker Environment](#docker-environment)
|
||||
4. [Project Structure](#project-structure)
|
||||
5. [Development Patterns & Conventions](#development-patterns--conventions)
|
||||
6. [Safety and Permissions](#safety-and-permissions)
|
||||
7. [Code Examples](#code-examples)
|
||||
8. [Git Workflow](#git-workflow)
|
||||
9. [Release Notes](#release-notes)
|
||||
10. [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Root Ownership
|
||||
---
|
||||
|
||||
- `agent.py` owns `Agent`, `AgentContext`, and loop data.
|
||||
- `initialize.py` owns framework initialization.
|
||||
- `models.py` owns model-provider configuration and LiteLLM integration.
|
||||
- `run_ui.py` is the WebUI entry point.
|
||||
- `DockerfileLocal` must remain compatible with the contracts under `docker/`.
|
||||
- Runtime or user state under `usr/` and `tmp/` is intentionally outside tracked DOX unless the user explicitly asks otherwise.
|
||||
## Project Overview
|
||||
|
||||
## Project-Wide Contracts
|
||||
Agent Zero is a dynamic, organic agentic framework designed to grow and learn. It uses the operating system as a tool, featuring a multi-agent cooperation model where every agent can create subordinates to break down tasks.
|
||||
|
||||
- Import `AgentContext` and `AgentContextType` from `agent`, not `helpers.context`.
|
||||
- Never commit secrets, `.env` files, API keys, tokens, or private user data.
|
||||
- Preserve authentication and CSRF protections.
|
||||
- Use Linux paths and commands in examples.
|
||||
- Treat the Docker container exposed at `localhost:32080` as the live plugin/backend runtime when that target is named.
|
||||
- Copy live core-plugin changes back into tracked source under `plugins/`.
|
||||
- Develop new custom plugins under ignored `usr/plugins/`; tracked bundled plugins live under `plugins/`.
|
||||
- Use the framework runtime for backend and plugin-hook verification, not the separate agent execution runtime.
|
||||
Type: Full-Stack Agentic Framework (Python Backend + Alpine.js Frontend)
|
||||
Status: Active Development
|
||||
Primary Language(s): Python, JavaScript (ES Modules)
|
||||
|
||||
## Permissions
|
||||
---
|
||||
|
||||
Allowed without asking:
|
||||
## Core Commands
|
||||
|
||||
- Read repository files.
|
||||
- Update files under `usr/`.
|
||||
### Setup
|
||||
Do not combine these commands; run them individually:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
pip install -r requirements2.txt
|
||||
```
|
||||
- Start WebUI: python run_ui.py
|
||||
|
||||
Ask before:
|
||||
---
|
||||
|
||||
- Installing dependencies.
|
||||
- Deleting core files outside `usr/` or `tmp/`.
|
||||
- Modifying `agent.py` or `initialize.py`.
|
||||
- Creating commits or pushing branches.
|
||||
## Docker Environment
|
||||
|
||||
## DOX Workflow
|
||||
When running in Docker, Agent Zero uses two distinct Python runtimes to isolate the framework from the code being executed:
|
||||
|
||||
- `AGENTS.md` files are binding contracts for their subtrees.
|
||||
- Before editing, read this file and every `AGENTS.md` on the path to each target; the closest contract controls local details without weakening parent rules.
|
||||
- Keep work understandable from the applicable DOX chain. Put project-wide rules here and concrete ownership, workflows, inputs, outputs, side effects, and verification in child docs.
|
||||
- Create a child `AGENTS.md` only for a durable boundary with distinct ownership or workflow.
|
||||
- Child docs should use: Purpose, Ownership, Local Contracts, Work Guidance, Verification, and Child DOX Index.
|
||||
- After every meaningful change, re-check the affected paths, update the closest owning docs and indexes, remove stale guidance, and run relevant verification.
|
||||
- Do not document ignored `usr/` or `tmp/` changes unless explicitly requested.
|
||||
- Keep DOX concise, current, operational, and free of diary entries or duplicated parent guidance.
|
||||
### 1. Framework Runtime (/opt/venv-a0)
|
||||
- Version: Python 3.12.4
|
||||
- Purpose: Runs the Agent Zero backend, API, and core logic.
|
||||
- Packages: Contains all dependencies from requirements.txt.
|
||||
|
||||
## Child DOX Index
|
||||
### 2. Execution Runtime (/opt/venv)
|
||||
- Version: Python 3.13
|
||||
- Purpose: Default environment for the interactive terminal and the agent's code execution tool.
|
||||
- Behavior: This is the environment active when you docker exec into the container. Packages installed by the agent via pip install during a task are stored here.
|
||||
|
||||
| Child | Scope |
|
||||
| --- | --- |
|
||||
| [.github/AGENTS.md](.github/AGENTS.md) | GitHub Actions workflows and release automation scripts. |
|
||||
| [agents/AGENTS.md](agents/AGENTS.md) | Bundled agent profiles, profile-local prompts, and tools. |
|
||||
| [api/AGENTS.md](api/AGENTS.md) | HTTP API and WebSocket handler entry points. |
|
||||
| [conf/AGENTS.md](conf/AGENTS.md) | Repository-shipped configuration defaults and templates. |
|
||||
| [docker/AGENTS.md](docker/AGENTS.md) | Docker build contexts, images, compose files, and runtime layout. |
|
||||
| [docs/AGENTS.md](docs/AGENTS.md) | Human-facing documentation and screenshots. |
|
||||
| [extensions/AGENTS.md](extensions/AGENTS.md) | Backend and WebUI lifecycle extensions. |
|
||||
| [helpers/AGENTS.md](helpers/AGENTS.md) | Shared backend utilities and runtime services. |
|
||||
| [knowledge/AGENTS.md](knowledge/AGENTS.md) | Built-in agent self-knowledge. |
|
||||
| [lib/AGENTS.md](lib/AGENTS.md) | Lightweight browser-side helpers outside the WebUI bundle. |
|
||||
| [plugins/AGENTS.md](plugins/AGENTS.md) | Bundled system plugins and custom-plugin architecture. |
|
||||
| [prompts/AGENTS.md](prompts/AGENTS.md) | Core prompt templates. |
|
||||
| [scripts/AGENTS.md](scripts/AGENTS.md) | Repository maintenance scripts and automation inputs. |
|
||||
| [skills/AGENTS.md](skills/AGENTS.md) | Bundled Agent Zero skills. |
|
||||
| [tests/AGENTS.md](tests/AGENTS.md) | Pytest regression and contract tests. |
|
||||
| [tools/AGENTS.md](tools/AGENTS.md) | Core agent tool implementations. |
|
||||
| [webui/AGENTS.md](webui/AGENTS.md) | Alpine.js WebUI shell, components, JavaScript, CSS, and assets. |
|
||||
---
|
||||
|
||||
Intentionally unindexed local or generated roots:
|
||||
## Project Structure
|
||||
|
||||
| Path | Reason |
|
||||
| --- | --- |
|
||||
| `.conda/`, `.venv/` | Local Python environments. |
|
||||
| `.pytest_cache/`, `__pycache__/` | Generated test and bytecode caches. |
|
||||
| `.vscode/`, `.windsurf/` | Editor-local configuration and assistant metadata. |
|
||||
| `logs/` | Runtime output. |
|
||||
| `tmp/` | Ignored runtime caches, uploads, and generated work. |
|
||||
| `usr/` | Ignored local user data, settings, plugins, chats, and workdirs. |
|
||||
| `python/` | Generated or legacy runtime mirror; current source is in root modules and tracked source directories. |
|
||||
```
|
||||
/
|
||||
├── agent.py # Core Agent and AgentContext definitions
|
||||
├── initialize.py # Framework initialization logic
|
||||
├── models.py # LLM provider configurations
|
||||
├── run_ui.py # WebUI server entry point
|
||||
├── api/ # API Handlers (ApiHandler subclasses) + WsHandler subclasses (ws_*.py)
|
||||
├── extensions/ # Backend lifecycle extensions
|
||||
├── helpers/ # Shared Python utilities (plugins, files, etc.)
|
||||
├── tools/ # Agent tools (Tool subclasses)
|
||||
├── webui/
|
||||
│ ├── components/ # Alpine.js components
|
||||
│ ├── js/ # Core frontend logic (modals, stores, etc.)
|
||||
│ └── index.html # Main UI shell
|
||||
├── usr/ # User data directory (isolated from core)
|
||||
│ ├── plugins/ # Custom user plugins
|
||||
│ ├── settings.json # User-specific configuration
|
||||
│ └── workdir/ # Default agent workspace
|
||||
├── plugins/ # Core system plugins
|
||||
├── agents/ # Agent profiles (prompts and config)
|
||||
├── prompts/ # System and message prompt templates
|
||||
├── knowledge/
|
||||
│ └── main/about/ # Agent self-knowledge (indexed into vector DB for runtime recall)
|
||||
│ ├── identity.md # Philosophy, principles, project context
|
||||
│ ├── architecture.md # Agent loop, memory pipeline, multi-agent, extensions
|
||||
│ ├── capabilities.md # Detailed capabilities and limitations
|
||||
│ ├── configuration.md # LLM roles, providers, profiles, plugins, settings
|
||||
│ └── setup-and-deployment.md # Docker deployment, updates, troubleshooting
|
||||
└── tests/ # Pytest suite
|
||||
```
|
||||
|
||||
Key Files:
|
||||
- agent.py: Defines AgentContext and the main Agent class.
|
||||
- helpers/plugins.py: Plugin discovery and configuration logic.
|
||||
- webui/js/AlpineStore.js: Store factory for reactive frontend state.
|
||||
- helpers/api.py: Base class for all API endpoints.
|
||||
- scripts/openrouter_release_notes_system_prompt.md: Editable system prompt used to generate GitHub release notes during Docker publishing.
|
||||
- knowledge/main/about/: Agent self-knowledge files, indexed into the vector DB for runtime recall. Not user-facing docs - written for the agent's internal reference.
|
||||
- docs/agents/AGENTS.components.md: Deep dive into the frontend component architecture.
|
||||
- docs/agents/AGENTS.modals.md: Guide to the stacked modal system.
|
||||
- docs/agents/AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.
|
||||
|
||||
---
|
||||
|
||||
## Development Patterns & Conventions
|
||||
|
||||
### Backend (Python)
|
||||
- Context Access: Use from agent import AgentContext, AgentContextType (not helpers.context).
|
||||
- Communication: Use mq from helpers.messages to log proactive UI messages:
|
||||
mq.log_user_message(context.id, "Message", source="Plugin")
|
||||
- API Handlers: Derive from ApiHandler in helpers/api.py.
|
||||
- Extensions: Use the extension framework in helpers/extension.py for lifecycle hooks.
|
||||
- Error Handling: Use RepairableException for errors the LLM might be able to fix.
|
||||
|
||||
### Frontend (Alpine.js)
|
||||
- Store Gating: Always wrap store-dependent content in a template:
|
||||
```html
|
||||
<div x-data>
|
||||
<template x-if="$store.myStore">
|
||||
<div x-init="$store.myStore.onOpen()">...</div>
|
||||
</template>
|
||||
</div>
|
||||
```
|
||||
- Store Registration: Use createStore from /js/AlpineStore.js.
|
||||
- Modals: Use openModal(path) and closeModal() from /js/modals.js.
|
||||
|
||||
### Plugin Architecture
|
||||
- Location: Always develop new plugins in usr/plugins/.
|
||||
- Manifest: Every plugin requires a plugin.yaml with name, description, version, and optionally settings_sections, per_project_config, per_agent_config, and always_enabled.
|
||||
- Discovery: Conventions based on folder names (api/, tools/, webui/, extensions/).
|
||||
- Plugin-local Python imports: Prefer `usr.plugins.<plugin_name>...` for code that lives under `usr/plugins/`. Avoid `sys.path` hacks and avoid symlink-dependent `plugins.<plugin_name>...` imports for community plugins.
|
||||
- Runtime hooks: Plugins may also expose hooks in hooks.py, callable by the framework through helpers.plugins.call_plugin_hook(...).
|
||||
- Hook runtime: hooks.py executes inside the Agent Zero framework Python environment, so sys.executable -m pip installs dependencies into that same framework runtime.
|
||||
- Environment targeting: If a plugin needs packages or binaries for the separate agent execution runtime or system environment, it must explicitly switch environments in a subprocess by targeting the correct interpreter, virtualenv, or package manager.
|
||||
- Settings: Use get_plugin_config(plugin_name, agent=agent) to retrieve settings. Plugins can expose a UI for settings via webui/config.html. Plugin settings modals instantiate a local context from $store.pluginSettingsPrototype; bind plugin fields to config.* and use context.* for modal-level state and actions.
|
||||
- Activation: Global and scoped activation rules are stored as .toggle-1 (ON) and .toggle-0 (OFF). Scoped rules are handled via the plugin "Switch" modal.
|
||||
- Cleanup rule: Plugins should not permanently modify the system in ways that outlive the plugin. Deleting a plugin should not leave behind symlinks, unmanaged services, or stray files outside plugin-owned paths unless the user explicitly requested that behavior.
|
||||
|
||||
### Releases
|
||||
- Docker publishing automation lives in `.github/workflows/docker-publish.yml`.
|
||||
- Releasable tags follow `v{X}.{Y}` and only tags `>= v1.0` are considered by the workflow.
|
||||
- The latest eligible tag on `main` also creates or updates a GitHub release after the Docker image push succeeds.
|
||||
- GitHub release notes are generated on the fly in `.github/scripts/docker_release_plan.py` by comparing the new tag against the previous published GitHub release tag, collecting commit subjects and descriptions in that range, and sending them to OpenRouter.
|
||||
- The OpenRouter call uses `OPENROUTER_API_KEY` and `OPENROUTER_MODEL_NAME` from the workflow environment, with the system prompt stored in `scripts/openrouter_release_notes_system_prompt.md`.
|
||||
- Prioritize user-visible features, important fixes, infra or packaging changes, and breaking notes. Skip low-signal churn.
|
||||
- If the generated summary has no meaningful content, the release body falls back to `No release notes.`
|
||||
|
||||
### Lifecycle Synchronization
|
||||
| Action | Backend Extension | Frontend Lifecycle |
|
||||
|---|---|---|
|
||||
| Initialization | agent_init | init() in Store |
|
||||
| Mounting | N/A | x-create directive |
|
||||
| Processing | monologue_start/end | UI loading state |
|
||||
| Cleanup | context_deleted | x-destroy directive |
|
||||
|
||||
---
|
||||
|
||||
## Safety and Permissions
|
||||
|
||||
### Allowed Without Asking
|
||||
- Read any file in the repository.
|
||||
- Update code files in usr/.
|
||||
|
||||
### Ask Before Executing
|
||||
- pip install (new dependencies).
|
||||
- Deleting core files outside of usr/ or tmp/.
|
||||
- Modifying agent.py or initialize.py.
|
||||
- Making git commits or pushes.
|
||||
|
||||
### Never Do
|
||||
- Commit, hardcode or leak secrets or .env files.
|
||||
- Bypass CSRF or authentication checks.
|
||||
- Hardcode API keys.
|
||||
|
||||
---
|
||||
|
||||
## Code Examples
|
||||
|
||||
### API Handler (Good)
|
||||
```python
|
||||
from helpers.api import ApiHandler, Request, Response
|
||||
|
||||
class MyHandler(ApiHandler):
|
||||
async def process(self, input: dict, request: Request) -> dict | Response:
|
||||
# Business logic here
|
||||
return {"ok": True, "data": "result"}
|
||||
```
|
||||
|
||||
### Alpine Store (Good)
|
||||
```javascript
|
||||
import { createStore } from "/js/AlpineStore.js";
|
||||
|
||||
export const store = createStore("myStore", {
|
||||
items: [],
|
||||
init() { /* global setup */ },
|
||||
onOpen() { /* mount setup */ },
|
||||
cleanup() { /* unmount cleanup */ }
|
||||
});
|
||||
```
|
||||
|
||||
### Tool Definition (Good)
|
||||
```python
|
||||
from helpers.tool import Tool, Response
|
||||
|
||||
class MyTool(Tool):
|
||||
async def execute(self, **kwargs):
|
||||
# Tool logic
|
||||
return Response(message="Success", break_loop=False)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git Workflow
|
||||
|
||||
- Docker publish automation lives in `.github/workflows/docker-publish.yml`.
|
||||
- Release tags handled by automation must match `vX.Y` and be `>= v1.0`.
|
||||
- Allowed release branches are configured at the top of the workflow. `main` publishes `<tag>` and `latest`; other allowed branches publish only the branch tag.
|
||||
- Manual dispatch accepts an optional tag. Without a tag it backfills missing Docker Hub tags. With a tag it rebuilds that exact target and only refreshes `latest` and the GitHub release when that tag is still the newest eligible tag on `main`.
|
||||
|
||||
---
|
||||
|
||||
## Release Notes
|
||||
|
||||
- The latest eligible `main` tag generates its GitHub release notes during Docker publish instead of reading committed Markdown files.
|
||||
- The release-note prompt is editable in `scripts/openrouter_release_notes_system_prompt.md`.
|
||||
- The commit range starts at the previous published GitHub release tag, not merely the previous semantic tag in the repository.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Dependency Conflicts
|
||||
If pip install fails, try running in a clean virtual environment:
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
pip install -r requirements2.txt
|
||||
```
|
||||
|
||||
### WebSocket Connection Failures
|
||||
- Check if X-CSRF-Token is being sent.
|
||||
- Ensure the runtime ID in the session matches the current server instance.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-03-25*
|
||||
*Maintained by: Agent Zero Core Team*
|
||||
|
|
|
|||
287
README.md
287
README.md
|
|
@ -3,62 +3,48 @@
|
|||
<img src="docs/res/a0-vector-graphics/horizontal_banner.svg" alt="Agent Zero Banner" width="100%"/>
|
||||
|
||||
# Agent Zero
|
||||
### Give your agent a full Linux computer.
|
||||
### AI agents with a full Linux system at their fingertips.
|
||||
|
||||
Agent Zero is an open agent framework for work that needs more than chat: a Dockerized Linux desktop, a browser with DOM annotation, live document cowork, projects, skills, plugins, and a bridge back to your host machine.
|
||||
Agent Zero is a dynamic, organic agentic framework for running AI agents that can create tools, write code, browse the web, cooperate with other agents, and keep learning from your goals and projects.
|
||||
|
||||
[](https://agent-zero.ai)
|
||||
[](./docs/)
|
||||
[](https://discord.gg/B8KZKNsPpj)
|
||||
[](https://github.com/sponsors/agent0ai)
|
||||
[](https://deepwiki.com/agent0ai/agent-zero)
|
||||
|
||||
[Quick Start](#quick-start) |
|
||||
[Why Agent Zero](#why-agent-zero) |
|
||||
[Try These First](#try-these-first) |
|
||||
[Deep Dives](#deep-dives) |
|
||||
[Introduction](#what-is-agent-zero) |
|
||||
[Space Agent](#agent-zero-and-space-agent) |
|
||||
[Quick Start](#how-to-install) |
|
||||
[LLM Plans](#use-your-openai-codex-plan) |
|
||||
[CLI Connector](#a0-cli-connector-use-agent-zero-on-your-host-machine) |
|
||||
[Browser](#native-browser-with-annotations-and-extensions) |
|
||||
[Desktop](#linux-desktop-and-libreoffice-cowork) |
|
||||
[Features](#what-makes-agent-zero-different) |
|
||||
[Examples](#try-these-first) |
|
||||
[Docs](#documentation)
|
||||
|
||||
[](https://deepwiki.com/agent0ai/agent-zero)
|
||||
[Ask ChatGPT](https://chatgpt.com/?q=Analyze%20this%3A%20https%3A%2F%2Fgithub.com%2Fagent0ai%2Fagent-zero) |
|
||||
[Ask Claude](https://claude.ai/new?q=Analyze%20this%3A%20https%3A%2F%2Fgithub.com%2Fagent0ai%2Fagent-zero)
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<div align="center">
|
||||
<img alt="Agent Zero driving Blender in its built-in XFCE desktop" src="docs/res/usage/webui/agentzero-xfce-computer.gif" width="100%" />
|
||||
<a href="https://www.youtube.com/watch?v=k78HX_RA9Q0&t=19s">
|
||||
<img src="docs/res/thumbnail-install.webp" alt="Agent Zero Installation Guide" width="100%"/>
|
||||
</a>
|
||||
</div>
|
||||
|
||||
# Why Agent Zero
|
||||
# What Is Agent Zero
|
||||
|
||||
| Feature | Why it matters |
|
||||
| --- | --- |
|
||||
| **Full Linux desktop** | The agent can use real GUI software, terminals, files, and desktop apps inside the Canvas. |
|
||||
| **Browser DOM annotation** | Click page elements and turn them into inspect, change, lift, or review instructions. |
|
||||
| **Live document cowork** | Edit Markdown, Writer, Spreadsheet, and Presentation files together instead of losing work in chat. |
|
||||
| **Plugin Hub** | Install 100+ community plugins or publish your own extension points. |
|
||||
| **Projects and memory** | Keep files, instructions, secrets, memories, repositories, and model presets isolated per project. |
|
||||
| **Host-machine bridge** | Connect with the A0 CLI so the same agent can work in your real local repositories. |
|
||||
| **Multi-agent cooperation** | Let agents delegate research, coding, analysis, or review tasks to focused subagents. |
|
||||
| **Transparent internals** | Prompts, tools, plugins, skills, and settings are inspectable and editable. |
|
||||
Agent Zero is not a predefined one-purpose agent.
|
||||
|
||||
# Quick Start
|
||||
It is a transparent, extensible framework where the agent can use the operating system as a tool: a real Linux environment, terminal, code execution, files, memory, browser automation, plugins, and tools it learns to create along the way.
|
||||
|
||||
## Recommended: A0 Launcher
|
||||
The goal is simple: give an AI agent enough environment, memory, communication, and freedom to solve real tasks while keeping the work inspectable and steerable by you.
|
||||
|
||||
The desktop **A0 Launcher** is the fastest guided path on a personal machine. Download it, open it, and let it check Docker, create Instances, manage ports, and connect to local or remote Agent Zero installs.
|
||||
|
||||
Agent Zero runs wherever Docker runs, from a $6 VPS or Raspberry Pi to a local workstation or GPU server.
|
||||
|
||||
| Architecture | macOS | Linux | Windows |
|
||||
| --- | --- | --- | --- |
|
||||
| x86 | [Mac Intel](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-macos-x64.dmg) | [Linux x86](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-linux-x64.AppImage) | [Windows x86](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-windows-x64.exe) |
|
||||
| ARM64 | [Mac Apple Silicon](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-macos-arm64.dmg) | [Linux ARM64](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-linux-arm64.AppImage) | [Windows ARM64](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-windows-arm64.exe) |
|
||||
|
||||
See the [A0 Launcher v1.2 release](https://github.com/agent0ai/a0-launcher/releases/tag/v1.2) for release notes and updater metadata. See the [Launcher guide](./docs/guides/launcher.md) for the first-run walkthrough.
|
||||
|
||||
<details>
|
||||
<summary><strong>Other install paths</strong></summary>
|
||||
|
||||
## A0 Install
|
||||
|
||||
Use **A0 Install** when you want the terminal path: SSH sessions, servers, recovery shells, or a scriptable setup. It creates Dockerized Agent Zero instances, mounts each instance's data into `/a0/usr` inside the container, and uses a reuse-before-setup policy: it tries your current Docker CLI configuration, `DOCKER_HOST`, Docker contexts, and known local Docker-compatible endpoints before setting up a runtime.
|
||||
## How To Install
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
|
|
@ -72,131 +58,89 @@ curl -fsSL https://bash.agent-zero.ai | bash
|
|||
irm https://ps.agent-zero.ai | iex
|
||||
```
|
||||
|
||||
### Headless / scripted
|
||||
|
||||
For servers and automation, run the installer in Quick Start mode so it creates one instance and exits without opening menus:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://bash.agent-zero.ai | bash -s -- --quick-start --name agent-zero --port 5080
|
||||
```
|
||||
|
||||
```powershell
|
||||
& ([scriptblock]::Create((irm https://ps.agent-zero.ai))) -QuickStart -Name agent-zero -Port 5080
|
||||
```
|
||||
|
||||
Use `--skip-runtime-setup` / `-SkipRuntimeSetup` when Docker must already be working and the installer should not try to set up a runtime. See the [A0 Install repository](https://github.com/agent0ai/a0-install) for all installer flags.
|
||||
|
||||
## Docker already installed? Run this directly
|
||||
### Docker Desktop already installed? Use this command directly
|
||||
|
||||
```bash
|
||||
docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero
|
||||
```
|
||||
|
||||
Open the Web UI, configure your LLM provider, and start with a concrete task. For the full setup and onboarding experience, see the [Installation guide](./docs/setup/installation.md).
|
||||
Then open the Web UI, configure your LLM provider, and start with a concrete task. For the full setup path, including updates and platform notes, see the [Installation guide](./docs/setup/installation.md).
|
||||
|
||||
</details>
|
||||
# What Makes Agent Zero Different
|
||||
|
||||
## Troubleshooting
|
||||
## Computer as a Tool
|
||||
|
||||
- **Docker is not running:** start Docker Desktop or your Docker service, then reopen the Launcher or rerun the install command.
|
||||
- **Port 80 is already in use:** use the Launcher to pick another port, or run Docker directly with `-p 5080:80` and open `http://localhost:5080`.
|
||||
- **Installing on a server:** use the A0 Install Quick Start command with `--quick-start --name agent-zero --port 5080`.
|
||||
- **Still blocked:** see the [Troubleshooting guide](./docs/guides/troubleshooting.md).
|
||||
Agent Zero can use a Kali Linux system to accomplish your task. It can inspect files, run commands, write code, install and use tools, create scripts, search the web, and adapt its workflow as the task evolves.
|
||||
|
||||
# Try These First
|
||||
The important idea is not a fixed list of buttons. The important idea is that the agent can build and use the right tool when the work demands it.
|
||||
|
||||
- **Annotate a design you like:** "Open this template site in the Browser. I'll annotate the hero section - re-implement it in my project's React + Tailwind stack."
|
||||
- **Cowork on a spreadsheet:** "Create an editable ODS budget model with assumptions and monthly projections."
|
||||
- **Drive a desktop app:** "Use the Linux Desktop to open Blender and create a simple 3D logo for me."
|
||||
- **Review a web UI:** "Open my local app in the Browser. I will annotate the page with comments; then implement the requested UI fixes."
|
||||
- **Create a specialist:** "Create an Agent Profile for financial analysis with cautious reasoning, clear assumptions, and spreadsheet-first deliverables."
|
||||
- **Recover a workspace:** "Show me recent Time Travel snapshots and explain what changed before I revert anything."
|
||||
## Canvas
|
||||
|
||||
# Deep Dives
|
||||
Agent Zero is becoming more visual and shared. The right-side Canvas gives agents and humans working surfaces for browser sessions, documents, workspace history, and other plugin panels.
|
||||
|
||||
## A Real Linux Desktop in the Canvas
|
||||
The Canvas makes agent work visible. You can watch it browse, inspect what changed, open files, cowork on deliverables, and intervene before a small mistake becomes a large one.
|
||||
|
||||
Agent Zero opens its own Linux desktop inside the right-side Canvas. Not a remote VM, not a shared clipboard, but a real XFCE desktop session running in the container.
|
||||
## Linux Desktop and LibreOffice Cowork
|
||||
|
||||
That means the agent can drive *real desktop software*: open Blender to model a 3D object, jump into a terminal window, manage files visually, run a GUI tool that has no API.
|
||||
|
||||
You watch every action, and you can intervene at any moment because your mouse and keyboard share the same desktop.
|
||||
|
||||
See the [Desktop guide](./docs/guides/desktop.md) for the walkthrough, prompt examples, and how Desktop differs from Browser.
|
||||
|
||||
## Native Browser With DOM Annotations
|
||||
|
||||
<img alt="Annotating a webpage element in the Agent Zero browser" src="docs/res/usage/browser/annotation.gif" />
|
||||
<img alt="Agent Zero Desktop Canvas" src="docs/res/usage/webui/desktop-canvas.png" />
|
||||
<br>
|
||||
|
||||
Agent Zero ships a built-in Browser with an optional live surface in the Canvas. The agent can open pages, read them, click, type, upload files, and take screenshots - the usual. The unusual part is **Annotate mode**.
|
||||
The Desktop surface opens Agent Zero's own Linux desktop in the Canvas. It is useful when the work needs a real GUI: Linux desktop apps, a terminal window, visual file management, or LibreOffice running where you and the agent can both see it.
|
||||
|
||||
Annotate mode turns any webpage into an interactive directive surface. Click an element to:
|
||||
|
||||
- **Change it** - "make this button blue and round the corners" runs as a JS instruction the agent applies and verifies.
|
||||
- **Inspect it** - pull the DOM, the styles, the parent chain, the framework hints into the conversation.
|
||||
- **Lift it** - see a card, hero, or component on someone else's site that you like? Capture it and have the agent re-implement it in your own project's stack.
|
||||
- **Comment it** - leave actionable notes pinned to elements during a UI review; the agent reads the comments and ships the fixes.
|
||||
|
||||
The Docker browser is the default live Browser surface. Browser history keeps screenshots of important steps, so older chats can still show what the agent saw. The Browser also supports Chrome extensions inside the Docker browser, and **Bring Your Own Browser** through the A0 CLI Connector lets the agent drive Chrome, Edge, Brave, Opera, Vivaldi, or Chromium on your own machine.
|
||||
|
||||
See the [Browser guide](./docs/guides/browser.md) for screenshots, settings, host-browser setup, and troubleshooting.
|
||||
|
||||
## Cowork on Documents
|
||||
|
||||
### Markdown Editor With Live Cowork
|
||||
|
||||
<img alt="Agent Zero writing a TODO plan in the Canvas markdown editor" src="docs/res/usage/webui/markdown-editor.gif" />
|
||||
<img alt="Cowork on Documents" width="1406" height="720" src="https://github.com/user-attachments/assets/4ad71888-4f0d-484a-b68b-631ad99187d7" />
|
||||
<br>
|
||||
|
||||
The Canvas includes a rich Markdown editor designed for genuine cowork. Ask the agent to "write a plan to do X in a TODO.md in the open doc" and you'll see the file appear in the editor, character by character, while you keep typing in another section.
|
||||
Create, open, and cowork with the AI on documents, spreadsheets, and presentation decks with the LibreOffice stack.
|
||||
|
||||
It's not a preview pane. It's a real editor with toolbar, formatting buttons, tables, and an editable source view - built so that the agent's edits and yours are equal first-class operations on the same document.
|
||||
The Desktop toolbar can create Markdown, Writer, Spreadsheet, and Presentation files. LibreOffice Writer, Calc, and Impress run inside the Desktop, so you can type by hand while Agent Zero creates, updates, saves, and verifies the same files.
|
||||
|
||||
Use it for plans, TODOs, meeting notes, RFCs, project handoffs, or any artifact where the deliverable should *live as text* rather than be trapped inside chat scrollback.
|
||||
The document Canvas supports Markdown by default, with LibreOffice-native ODT, ODS, and ODP workflows when binary office artifacts are needed. Microsoft Office compatibility imports and exports remain available when explicitly requested.
|
||||
|
||||
### LibreOffice Integration
|
||||
Markdown, Writer, Spreadsheet, and Presentation files share a compact active-file header with save, rename, close, and creation controls in both Canvas and modal views.
|
||||
|
||||
LibreOffice Writer, Calc, and Impress are wired up so you can type by hand while Agent Zero creates, updates, saves, and verifies the same files in real time.
|
||||
See the [Desktop guide](./docs/guides/desktop.md) for the screenshot walkthrough, prompt examples, and how Desktop differs from Browser.
|
||||
|
||||
ODT, ODS, and ODP binary formats are first-class citizens in the Agent Zero Desktop environment to align with the Open Document Format (ODF).
|
||||
## Native Browser With Annotations and Extensions
|
||||
|
||||
Use the Desktop toolbar to create and edit Writer, Spreadsheet, and Presentation LibreOffice files.
|
||||
|
||||
## Plugin Hub - 100+ Community Plugins
|
||||
|
||||
<img alt="Agent Zero Plugin Hub showing community plugins" src="docs/res/usage/plugins/plugin-hub-browse.png" />
|
||||
<img alt="Agent Zero Browser Canvas and tool history" src="docs/res/usage/browser/browser-canvas-wide.png" />
|
||||
<br>
|
||||
|
||||
Agent Zero is built for extension, not just configuration. The built-in **Plugin Hub** browses a growing catalog of community plugins - currently more than 100, covering:
|
||||
Agent Zero includes a built-in Browser with an optional live surface in the Canvas. The agent can open pages, read them, click, type, upload files, and take screenshots.
|
||||
|
||||
- **Development frameworks** like the [BMAD Method](https://github.com/bmad-code-org/bmad-method) (full software development lifecycle with 20 specialist agents) and [Agent Skills](https://github.com/addyosmani/agent-skills).
|
||||
- **Memory systems** - alternative memory backends, intelligent consolidation strategies, vector recall plugins.
|
||||
- **Tools and integrations** - embedded terminals, custom browsers, deployment helpers, API clients.
|
||||
- **UI extensions** - chat rename controls, sidebar tweaks, theme packs, custom Canvas panels.
|
||||
- **Workflow plugins** - schedulers, multi-agent orchestration, project automations.
|
||||
The Docker browser is the default live Browser surface. With A0 CLI, Agent Zero can also use **Bring Your Own Browser** to work with Chrome, Edge, or Chromium on your own computer. Open the Browser surface when you want to watch the Docker browser, or ask Agent Zero to show it in the Canvas.
|
||||
|
||||
Install with a click from the Web UI, or publish your own to the index repository. Combined with custom prompts in `prompts/`, custom tools in `tools/`, MCP servers, A2A connectors, and project-scoped configuration, Agent Zero gives you a real surface area to shape the agent into whatever you need.
|
||||
Browser history keeps screenshots of important steps, so older chats can still show what the agent saw.
|
||||
|
||||
See the [Skills guide](./docs/guides/skills.md), the [Create a Small Plugin](./docs/guides/create-plugin.md) tutorial, and the [MCP setup](./docs/guides/mcp-setup.md) guide.
|
||||
For web and mobile development, Annotate mode lets you click page elements or regions and leave actionable comments for the agent targeted at the page itself. You can review a UI visually, mark what needs to change, and send those notes straight back into the conversation.
|
||||
|
||||
The Browser also supports Chrome extensions inside the Docker browser. See the [Browser guide](./docs/guides/browser.md) for screenshots, settings, host-browser setup, and troubleshooting.
|
||||
|
||||
## Use Your OpenAI Codex Plan
|
||||
|
||||
Agent Zero can now connect to your OpenAI Codex plan through the new OAuth flow. Sign in with your account, pick the Codex-backed provider, and let Agent Zero use the plan you already have.
|
||||
|
||||
<img alt="OAuth LLM plans in Agent Zero" src="docs/res/codex-screenshot.png" />
|
||||
<br>
|
||||
|
||||
Agent Zero connects to your OpenAI Codex plan through the new OAuth flow. Sign in with your account, pick the Codex-backed provider, and let Agent Zero use the plan you already have. Click "Connect", enter the device code in the OpenAI page, choose your model, and you're set.
|
||||
Click "Connect", enter the device code in the OpenAI page. Choose your model after checking the list, and you're all set.
|
||||
|
||||
This is the first step toward account-backed LLM plans in Agent Zero. More integrations are coming, including Gemini CLI and Claude Code through extra-usage.
|
||||
This is the first step toward account-backed LLM plans in Agent Zero. More integrations are coming, including Gemini CLI, Claude Code based on extra-usage, and more.
|
||||
|
||||
## A0 CLI Connector: Extend Onto Your Host Machine
|
||||
# A0 CLI Connector: Use Agent Zero on Your Host Machine
|
||||
|
||||
<img alt="A0 CLI driving the host browser through a Google Cloud VM creation flow" src="docs/res/usage/a0-cli/host-browser.gif" />
|
||||
The **A0 CLI Connector** is not a separate CLI agent. It connects to a running
|
||||
Agent Zero instance and gives that instance a terminal-native bridge to your
|
||||
host machine.
|
||||
|
||||
Agent Zero stays responsible for the reasoning loop, memory, projects, profiles,
|
||||
model choices, and tools. The CLI is how you intentionally let that Agent
|
||||
Zero instance work beyond the Docker container: on your host machine, in a
|
||||
terminal-first workflow, or against a server where you do not want a GUI at all.
|
||||
|
||||
<img alt="A0 CLI Connector connected shell" src="docs/res/usage/a0-cli/a0-cli-start.png" />
|
||||
<br>
|
||||
|
||||
The **A0 CLI Connector** is not a separate CLI agent. It connects to a running Agent Zero instance and gives that instance a terminal-native bridge to your host machine - so the same agent (with all its memory, projects, and skills) can also work on real files outside the Docker container.
|
||||
|
||||
Install the connector on the machine you want Agent Zero to work on, **not** inside the Agent Zero container.
|
||||
Install the connector on the machine you want Agent Zero to work on, not inside the Agent Zero container.
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
|
|
@ -210,42 +154,83 @@ curl -LsSf https://cli.agent-zero.ai/install.sh | sh
|
|||
irm https://cli.agent-zero.ai/install.ps1 | iex
|
||||
```
|
||||
|
||||
Then run `a0` to connect your terminal to an existing Agent Zero instance. It can usually discover a local instance automatically, or you can point it at a remote URL hosted somewhere else, such as a VPS or tunnel.
|
||||
Then run:
|
||||
|
||||
```bash
|
||||
a0
|
||||
```
|
||||
|
||||
`a0` connects your terminal to an existing Agent Zero instance. It can usually discover a local instance automatically, or you can point it at a remote Agent Zero URL hosted somewhere else, such as a VPS or tunnel.
|
||||
|
||||
Inside the shell, use `Ctrl+P` for the command palette, `/chats` to switch work, `/models` or `/presets` to adjust models, and `/browser status` to check Browser mode.
|
||||
|
||||
When you activate **Read+Write** access and the **Remote Code Execution Tool** in the CLI, Agent Zero can operate on the filesystem and shell of the machine where `a0` is running. That means it can work on your real local project files, not only files inside the Docker sandbox.
|
||||
|
||||
This is especially useful if you:
|
||||
|
||||
- prefer CLI workflows;
|
||||
- want Agent Zero to work in an existing local repository;
|
||||
- are running Agent Zero on a remote server;
|
||||
- want Docker isolation for Agent Zero while still granting explicit, controlled access to host-side work.
|
||||
- need code execution on a headless machine without using the Web UI;
|
||||
- want Docker isolation for Agent Zero while still granting explicit, controlled access to selected host-side work.
|
||||
|
||||
For full setup, see the [A0 CLI Connector guide](https://www.agent-zero.ai/p/docs/a0-cli-connector/) (or the [in-repo guide](./docs/guides/a0-cli-connector.md)).
|
||||
For full setup details, manual fallback installation, and remote-host tips, see the [A0 CLI Connector guide](./docs/guides/a0-cli-connector.md).
|
||||
|
||||
## Projects, Skills, Agent Profiles, and Model Presets
|
||||
|
||||
**Projects** isolate workspaces, instructions, memory, secrets, knowledge, repositories, and model presets. Clone a public or private Git repo into a project and give the agent context that belongs to that work alone.
|
||||
### Projects, Skills, Agent Profiles, and Model Presets
|
||||
|
||||
**Skills** can be loaded on demand by Agent Zero, or pinned from the chat input when you want a specific procedure to stay active.
|
||||
Projects isolate workspaces, instructions, memory, secrets, knowledge, repositories, and model presets. Clone a public or private Git repo into an isolated project and give the agent context that belongs to that work alone.
|
||||
|
||||
**Agent Profiles** change the broader working style of the current chat.
|
||||
Skills can be loaded on demand by Agent Zero, or pinned from the chat input when
|
||||
you want a specific procedure to stay active. Agent Profiles change the broader
|
||||
working style of the current chat. Model Presets are named shortcuts for model
|
||||
setups, so users can quickly switch between fast, balanced, cheap, local, or
|
||||
high-power model choices.
|
||||
|
||||
**Model Presets** are named shortcuts for model setups, so you can quickly switch between fast, balanced, cheap, local, or high-power model choices.
|
||||
|
||||
## Multi-Agent Cooperation
|
||||
### Multi-Agent Cooperation
|
||||
|
||||
Every agent can create subordinate agents to break down work. The superior gives tasks and receives reports; subagents keep their own contexts focused and return their findings when done.
|
||||
|
||||
This makes Agent Zero useful for research, software engineering, data analysis, plugin development, and tasks where several specialized perspectives are better than one overloaded context.
|
||||
|
||||
## Transparent and Extensible by Design
|
||||
### Transparent and Extensible by Design
|
||||
|
||||
Almost nothing is hidden. Prompts live in `prompts/`, tools live in `tools/` or plugins, and built-in behavior can be inspected, changed, replaced, or extended.
|
||||
|
||||
Agent Zero supports plugins, MCP, A2A, custom tools, custom prompts, project-scoped configuration, environment-based deployment settings, and a Web UI designed to keep the agent's work readable in real time.
|
||||
|
||||
## Time Travel
|
||||
### Also Included
|
||||
|
||||
Time Travel gives Agent Zero-owned `/a0/usr` workspaces snapshot history, diff inspection, travel, and revert. It is designed for recoverable agent work: see what changed, compare files, inspect a past state, and roll back when needed.
|
||||
- Fully Dockerized runtime with a clean Web UI.
|
||||
- Real-time streamed output so you can interrupt, redirect, or refine the work as it happens.
|
||||
- Speech-to-text and text-to-speech support through the built-in `_kokoro_tts` and `_whisper_stt` plugins, with browser-native speech synthesis as the fallback output path.
|
||||
- Chat load/save, generated HTML logs, file browser, settings UI, and deployment-friendly `A0_SET_` configuration.
|
||||
|
||||
## Try These First
|
||||
|
||||
- **Research with the Browser tool:** "Use the Browser tool to compare three project management tools for a small AI team, and summarize the tradeoffs with source links."
|
||||
- **Cowork on a spreadsheet:** "Create an editable ODS budget model with assumptions and monthly projections."
|
||||
- **Review a web UI:** "Open my local app in the Browser. I will annotate the page with comments; then implement the requested UI fixes."
|
||||
- **Work inside a Git project:** "Clone this repository into a new project, understand the layout, and propose the safest first improvement."
|
||||
- **Create a specialist:** "Create an Agent Profile for financial analysis with cautious reasoning, clear assumptions, and spreadsheet-first deliverables."
|
||||
- **Recover a workspace:** "Show me recent Time Travel snapshots and explain what changed before I revert anything."
|
||||
|
||||
## Agent Zero and Space Agent
|
||||
|
||||
Agent Zero is the open framework and Linux-powered agent workbench.
|
||||
|
||||
[Space Agent](https://github.com/agent0ai/space-agent) is our newer product direction for the agent-shaped workspace: a Space the agent can reshape from inside your browser, with live demos, a desktop app, and a path to running a real server for yourself or your team.
|
||||
|
||||
<p align="left">
|
||||
<a href="https://www.youtube.com/watch?v=CNRHxEZ8yqs"><img src="https://github.com/agent0ai/space-agent/raw/main/.github/thumbnail.webp" alt="Watch Space Agent on YouTube" width="560" /></a>
|
||||
</p>
|
||||
|
||||
If you want the raw power and deep customizability of an agent with a full Linux system, start here with Agent Zero. If you want the polished Space experience for easier personal, team, desktop, or self-hosted use, explore [Space Agent](https://github.com/agent0ai/space-agent).
|
||||
|
||||
|
||||
## Time Travel (powered by Space Agent)
|
||||
|
||||
Time Travel gives Agent Zero-owned `/a0/usr` workspaces snapshot history, diff inspection, travel, and revert. It is designed for recoverable agent work: see what changed, compare files, inspect a past state, and roll back when needed. Try it in Space Agent as well (link above).
|
||||
|
||||
<img alt="Time Travel" src="docs/res/time-travel.png" />
|
||||
|
||||
|
|
@ -254,8 +239,7 @@ It is not a replacement for Git or backups. It is a practical safety layer for t
|
|||
## Real-World Use Cases
|
||||
|
||||
- **Software engineering:** inspect a codebase, make scoped edits, run tests, explain tradeoffs, and keep a recoverable history of file changes.
|
||||
- **Host-machine development:** connect with `a0` and let Agent Zero work in your real local repositories, or clone them through Git Projects feature in the Web UI.
|
||||
- **Design inspiration and UI iteration:** browse the web, annotate elements you like, and pull components into your own stack.
|
||||
- **Host-machine development:** connect with `a0`, grant Read+Write and remote execution when needed, and let Agent Zero work in your real local repositories.
|
||||
- **Financial analysis and charting:** collect data, correlate events, create spreadsheets, and generate editable charts.
|
||||
- **Office deliverables:** cowork on documents, spreadsheets, and presentation decks instead of trapping the result in chat text.
|
||||
- **Web and mobile QA:** browse an app, annotate UI issues, install browser extensions, and turn visual comments into actionable fixes.
|
||||
|
|
@ -263,6 +247,18 @@ It is not a replacement for Git or backups. It is a practical safety layer for t
|
|||
- **Client/project isolation:** keep memory, secrets, instructions, files, and model choices separated by project.
|
||||
- **Scheduled operations:** run recurring checks and monitoring tasks with project-scoped context and credentials.
|
||||
|
||||
## Safety Model
|
||||
|
||||
Agent Zero is powerful because it can use a real environment. Treat it with the same respect you would give a capable developer with shell access.
|
||||
|
||||
- Keep it running inside Docker or another isolated environment.
|
||||
- Do not mount your entire home directory unless you understand the risk.
|
||||
- Grant A0 CLI Read+Write access and remote code execution only for machines and workspaces you trust.
|
||||
- Store credentials in project secrets or settings, not in prompts or public files.
|
||||
- Review actions that touch accounts, money, production systems, or private data.
|
||||
- Keep backups for important workspaces.
|
||||
- Install browser extensions and third-party plugins only from sources you trust.
|
||||
|
||||
## Documentation
|
||||
|
||||
| I want to... | Start here |
|
||||
|
|
@ -271,7 +267,7 @@ It is not a replacement for Git or backups. It is a practical safety layer for t
|
|||
| Learn the UI and basic workflow | [Quickstart](./docs/quickstart.md) |
|
||||
| Browse, annotate, and use Browser screenshots | [Browser guide](./docs/guides/browser.md) |
|
||||
| Use the Linux desktop and LibreOffice | [Desktop guide](./docs/guides/desktop.md) |
|
||||
| Connect Agent Zero to host-machine files and shell | [A0 CLI Connector](https://www.agent-zero.ai/p/docs/a0-cli-connector/) |
|
||||
| Connect Agent Zero to host-machine files and shell | [A0 CLI Connector](./docs/guides/a0-cli-connector.md) |
|
||||
| Use projects and Git workspaces | [Projects guide](./docs/guides/projects.md) |
|
||||
| Create a small plugin | [Create a Small Plugin](./docs/guides/create-plugin.md) |
|
||||
| Add or remove active skills | [Skills guide](./docs/guides/skills.md) |
|
||||
|
|
@ -289,7 +285,7 @@ It is not a replacement for Git or backups. It is a practical safety layer for t
|
|||
|
||||
Agent Zero is built for people who want to understand and shape their tools.
|
||||
|
||||
You can help by improving docs, creating skills, publishing plugins, testing model/provider setups, reporting bugs, sharing workflows, or contributing core improvements. Start with the [Contributing guide](./docs/guides/contribution.md), browse the [Plugin Hub](https://www.agent-zero.ai/p/docs/plugins/#plugin-hub), or bring ideas to Discord.
|
||||
You can help by improving docs, creating skills, publishing plugins, testing model/provider setups, reporting bugs, sharing workflows, or contributing core improvements. Start with the [Contributing guide](./docs/guides/contribution.md), browse the [Plugin Hub](./docs/guides/usage.md), or bring ideas to Discord.
|
||||
|
||||
## Community and Support
|
||||
|
||||
|
|
@ -298,16 +294,3 @@ You can help by improving docs, creating skills, publishing plugins, testing mod
|
|||
- [YouTube](https://www.youtube.com/@AgentZeroFW) for demos and tutorials.
|
||||
- [X](https://x.com/Agent0ai), [LinkedIn](https://www.linkedin.com/company/109758317), and [Warpcast](https://warpcast.com/agent-zero) for updates.
|
||||
- [GitHub Issues](https://github.com/agent0ai/agent-zero/issues) for bugs and feature requests.
|
||||
|
||||
[Space Agent](https://github.com/agent0ai/space-agent) is the related, more polished product direction for the agent-shaped workspace. Agent Zero remains the open framework and Linux-powered workbench.
|
||||
|
||||
## Safety Model
|
||||
|
||||
Agent Zero is powerful because it can use a real environment.
|
||||
|
||||
- Keep it running inside Docker or another isolated environment.
|
||||
- Do not mount your entire home directory unless you understand the risk.
|
||||
- Grant A0 CLI Read+Write access and remote code execution only for machines and workspaces you trust.
|
||||
- Store credentials in project secrets or settings, not in prompts or public files.
|
||||
- Review actions that touch accounts, money, production systems, or private data.
|
||||
- Keep backups for important workspaces.
|
||||
|
|
|
|||
595
agent.py
595
agent.py
|
|
@ -1,4 +1,4 @@
|
|||
import asyncio, json, random, re, string, threading
|
||||
import asyncio, random, string, threading
|
||||
|
||||
from collections import OrderedDict
|
||||
from dataclasses import dataclass, field
|
||||
|
|
@ -32,15 +32,6 @@ from typing import Callable
|
|||
from helpers.localization import Localization
|
||||
from helpers import extension
|
||||
from helpers.errors import RepairableException, InterventionException, HandledException
|
||||
from helpers.llm_result import (
|
||||
LLMResult,
|
||||
RESPONSE_METADATA_KEY,
|
||||
function_call_output_item,
|
||||
metadata_from_llm_result,
|
||||
result_from_metadata,
|
||||
)
|
||||
from helpers.litellm_transport import ResponsesTransport
|
||||
from helpers.responses_tools import build_responses_function_tools, original_tool_name
|
||||
|
||||
class AgentContextType(Enum):
|
||||
USER = "user"
|
||||
|
|
@ -338,8 +329,6 @@ class LoopData:
|
|||
self.system = []
|
||||
self.user_message: history.Message | None = None
|
||||
self.history_output: list[history.OutputMessage] = []
|
||||
self.protocol_temporary: OrderedDict[str, history.MessageContent] = OrderedDict()
|
||||
self.protocol_persistent: OrderedDict[str, history.MessageContent] = OrderedDict()
|
||||
self.extras_temporary: OrderedDict[str, history.MessageContent] = OrderedDict()
|
||||
self.extras_persistent: OrderedDict[str, history.MessageContent] = OrderedDict()
|
||||
self.last_response = ""
|
||||
|
|
@ -357,9 +346,6 @@ class Agent:
|
|||
DATA_NAME_SUPERIOR = "_superior"
|
||||
DATA_NAME_SUBORDINATE = "_subordinate"
|
||||
DATA_NAME_CTX_WINDOW = "ctx_window"
|
||||
DATA_NAME_RESPONSES_STATE = "responses_state"
|
||||
DATA_NAME_RESPONSES_TOOL_NAME_MAP = "responses_tool_name_map"
|
||||
DATA_NAME_RESPONSES_COMPUTER_SESSION = "responses_computer_session_id"
|
||||
|
||||
@extension.extensible
|
||||
def __init__(
|
||||
|
|
@ -482,12 +468,11 @@ class Agent:
|
|||
return stop_response
|
||||
|
||||
# call main LLM
|
||||
llm_result = await self.call_chat_model_turn(
|
||||
agent_response, _reasoning = await self.call_chat_model(
|
||||
messages=prompt,
|
||||
response_callback=stream_callback,
|
||||
reasoning_callback=reasoning_callback,
|
||||
)
|
||||
agent_response = llm_result.response
|
||||
await self.handle_intervention(agent_response)
|
||||
|
||||
# Notify extensions to finalize their stream filters
|
||||
|
|
@ -507,12 +492,7 @@ class Agent:
|
|||
): # if assistant_response is the same as last message in history, let him know
|
||||
# Append the assistant's response to the history
|
||||
log_item = self.loop_data.params_temporary.get("log_item_generating")
|
||||
assistant_message = self.hist_add_ai_response(
|
||||
agent_response,
|
||||
id=log_item.id if log_item else "",
|
||||
llm_result=llm_result,
|
||||
)
|
||||
self._remember_llm_result_state(llm_result, assistant_message)
|
||||
self.hist_add_ai_response(agent_response, id=log_item.id if log_item else "")
|
||||
# Append warning message to the history
|
||||
warning_msg = self.read_prompt("fw.msg_repeat.md")
|
||||
wmsg = self.hist_add_warning(message=warning_msg)
|
||||
|
|
@ -524,16 +504,9 @@ class Agent:
|
|||
else: # otherwise proceed with tool
|
||||
# Append the assistant's response to the history
|
||||
log_item = self.loop_data.params_temporary.get("log_item_generating")
|
||||
assistant_message = self.hist_add_ai_response(
|
||||
agent_response,
|
||||
id=log_item.id if log_item else "",
|
||||
llm_result=llm_result,
|
||||
)
|
||||
self._remember_llm_result_state(llm_result, assistant_message)
|
||||
self.hist_add_ai_response(agent_response, id=log_item.id if log_item else "")
|
||||
# process tools requested in agent message
|
||||
tools_result = await self.process_llm_result_tools(
|
||||
llm_result
|
||||
)
|
||||
tools_result = await self.process_tools(agent_response)
|
||||
if tools_result: # final response of message loop available
|
||||
return tools_result # break the execution if the task is done
|
||||
|
||||
|
|
@ -582,28 +555,24 @@ class Agent:
|
|||
# concatenate system prompt
|
||||
system_text = "\n\n".join(loop_data.system)
|
||||
|
||||
# join protocol and extras
|
||||
protocol = self._build_context_message(
|
||||
"agent.context.protocol.md",
|
||||
"protocol",
|
||||
{**loop_data.protocol_persistent, **loop_data.protocol_temporary},
|
||||
include_empty=False,
|
||||
)
|
||||
extras = self._build_context_message(
|
||||
"agent.context.extras.md",
|
||||
"extras",
|
||||
{**loop_data.extras_persistent, **loop_data.extras_temporary},
|
||||
include_empty=True,
|
||||
)
|
||||
loop_data.protocol_temporary.clear()
|
||||
# join extras
|
||||
extras = history.Message( # type: ignore[abstract]
|
||||
False,
|
||||
content=self.read_prompt(
|
||||
"agent.context.extras.md",
|
||||
extras=dirty_json.stringify(
|
||||
{**loop_data.extras_persistent, **loop_data.extras_temporary}
|
||||
),
|
||||
),
|
||||
).output()
|
||||
loop_data.extras_temporary.clear()
|
||||
|
||||
# convert protocol + history + extras to LLM format
|
||||
# convert history + extras to LLM format
|
||||
history_langchain: list[BaseMessage] = history.output_langchain(
|
||||
protocol + loop_data.history_output + extras
|
||||
loop_data.history_output + extras
|
||||
)
|
||||
|
||||
# build full prompt from system prompt, protocol, message history and extras
|
||||
# build full prompt from system prompt, message history and extrS
|
||||
full_prompt: list[BaseMessage] = [
|
||||
SystemMessage(content=system_text),
|
||||
*history_langchain,
|
||||
|
|
@ -615,30 +584,12 @@ class Agent:
|
|||
Agent.DATA_NAME_CTX_WINDOW,
|
||||
{
|
||||
"text": full_text,
|
||||
"tokens": tokens.approximate_prompt_tokens(full_text),
|
||||
"tokens": tokens.approximate_tokens(full_text),
|
||||
},
|
||||
)
|
||||
|
||||
return full_prompt
|
||||
|
||||
def _build_context_message(
|
||||
self,
|
||||
prompt_file: str,
|
||||
variable_name: str,
|
||||
values: dict[str, history.MessageContent],
|
||||
include_empty: bool,
|
||||
) -> list[history.OutputMessage]:
|
||||
if not include_empty and not values:
|
||||
return []
|
||||
|
||||
return history.Message( # type: ignore[abstract]
|
||||
False,
|
||||
content=self.read_prompt(
|
||||
prompt_file,
|
||||
**{variable_name: dirty_json.stringify(values)},
|
||||
),
|
||||
).output()
|
||||
|
||||
@extension.extensible
|
||||
async def handle_exception(self, location: str, exception: Exception):
|
||||
if exception:
|
||||
|
|
@ -713,12 +664,7 @@ class Agent:
|
|||
|
||||
@extension.extensible
|
||||
def hist_add_message(
|
||||
self,
|
||||
ai: bool,
|
||||
content: history.MessageContent,
|
||||
tokens: int = 0,
|
||||
id: str = "",
|
||||
metadata: dict[str, Any] | None = None,
|
||||
self, ai: bool, content: history.MessageContent, tokens: int = 0, id: str = ""
|
||||
):
|
||||
self.last_message = Localization.get().now()
|
||||
# Allow extensions to process content before adding to history
|
||||
|
|
@ -727,11 +673,7 @@ class Agent:
|
|||
"hist_add_before", self, content_data=content_data, ai=ai
|
||||
)
|
||||
return self.history.add_message(
|
||||
ai=ai,
|
||||
content=content_data["content"],
|
||||
tokens=tokens,
|
||||
id=id,
|
||||
metadata=metadata,
|
||||
ai=ai, content=content_data["content"], tokens=tokens, id=id
|
||||
)
|
||||
|
||||
@extension.extensible
|
||||
|
|
@ -764,17 +706,10 @@ class Agent:
|
|||
return msg
|
||||
|
||||
@extension.extensible
|
||||
def hist_add_ai_response(
|
||||
self, message: str, id: str = "", llm_result: LLMResult | None = None
|
||||
):
|
||||
def hist_add_ai_response(self, message: str, id: str = ""):
|
||||
self.loop_data.last_response = message
|
||||
content = self.parse_prompt("fw.ai_response.md", message=message)
|
||||
return self.hist_add_message(
|
||||
True,
|
||||
content=content,
|
||||
id=id,
|
||||
metadata=metadata_from_llm_result(llm_result),
|
||||
)
|
||||
return self.hist_add_message(True, content=content, id=id)
|
||||
|
||||
@extension.extensible
|
||||
def hist_add_warning(self, message: history.MessageContent, id: str = ""):
|
||||
|
|
@ -784,28 +719,13 @@ class Agent:
|
|||
@extension.extensible
|
||||
def hist_add_tool_result(self, tool_name: str, tool_result: str, **kwargs):
|
||||
msg_id = kwargs.pop("id", "")
|
||||
responses_item = kwargs.pop("_responses_output_item", None) or kwargs.pop(
|
||||
"responses_item", None
|
||||
)
|
||||
metadata = (
|
||||
{
|
||||
RESPONSE_METADATA_KEY: {
|
||||
"input_items": [responses_item],
|
||||
"output_items": [],
|
||||
"mode": "responses",
|
||||
"state": "provider",
|
||||
}
|
||||
}
|
||||
if isinstance(responses_item, dict)
|
||||
else None
|
||||
)
|
||||
data = {
|
||||
"tool_name": tool_name,
|
||||
"tool_result": tool_result,
|
||||
**kwargs,
|
||||
}
|
||||
extension.call_extensions_sync("hist_add_tool_result", self, data=data)
|
||||
return self.hist_add_message(False, content=data, id=msg_id, metadata=metadata)
|
||||
return self.hist_add_message(False, content=data, id=msg_id)
|
||||
|
||||
def concat_messages(
|
||||
self, messages
|
||||
|
|
@ -910,164 +830,6 @@ class Agent:
|
|||
|
||||
return response, reasoning
|
||||
|
||||
@extension.extensible
|
||||
async def call_chat_model_turn(
|
||||
self,
|
||||
messages: list[BaseMessage],
|
||||
response_callback: Callable[[str, str], Awaitable[str | None]] | None = None,
|
||||
reasoning_callback: Callable[[str, str], Awaitable[None]] | None = None,
|
||||
background: bool = False,
|
||||
explicit_caching: bool = True,
|
||||
) -> LLMResult:
|
||||
model = self.get_chat_model()
|
||||
model_kwargs = getattr(model, "kwargs", {}) if model else {}
|
||||
if isinstance(model_kwargs, dict) and model_kwargs.get("responses_delete_on_chat_delete") is False:
|
||||
self.set_data("responses_delete_on_chat_delete", False)
|
||||
response_tools, name_map = build_responses_function_tools(self)
|
||||
self.set_data(Agent.DATA_NAME_RESPONSES_TOOL_NAME_MAP, name_map)
|
||||
|
||||
call_data = {
|
||||
"model": model,
|
||||
"messages": messages,
|
||||
"response_callback": response_callback,
|
||||
"reasoning_callback": reasoning_callback,
|
||||
"background": background,
|
||||
"explicit_caching": explicit_caching,
|
||||
"a0_responses_function_tools": response_tools,
|
||||
}
|
||||
|
||||
previous_state = self._responses_state_for_model(model)
|
||||
if previous_state:
|
||||
history_counter = int(previous_state.get("history_counter", 0) or 0)
|
||||
call_data["previous_response_id"] = previous_state.get("response_id", "")
|
||||
call_data["responses_input_items"] = self._responses_input_items_since(
|
||||
model,
|
||||
history_counter,
|
||||
)
|
||||
call_data["responses_local_input_items"] = self._responses_prompt_input_items(
|
||||
model,
|
||||
messages,
|
||||
)
|
||||
|
||||
await extension.call_extensions_async(
|
||||
"chat_model_call_before", self, call_data=call_data
|
||||
)
|
||||
|
||||
turn_kwargs = {
|
||||
"a0_responses_function_tools": call_data.get(
|
||||
"a0_responses_function_tools"
|
||||
),
|
||||
"responses_local_input_items": call_data.get(
|
||||
"responses_local_input_items"
|
||||
),
|
||||
}
|
||||
for key in (
|
||||
"responses_builtin_tools",
|
||||
"responses_state",
|
||||
"previous_response_id",
|
||||
"responses_input_items",
|
||||
):
|
||||
if call_data.get(key) is not None:
|
||||
turn_kwargs[key] = call_data.get(key)
|
||||
|
||||
llm_result = await call_data["model"].unified_turn(
|
||||
messages=call_data["messages"],
|
||||
reasoning_callback=call_data["reasoning_callback"],
|
||||
response_callback=call_data["response_callback"],
|
||||
rate_limiter_callback=(
|
||||
self.rate_limiter_callback if not call_data["background"] else None
|
||||
),
|
||||
explicit_caching=call_data["explicit_caching"],
|
||||
**turn_kwargs,
|
||||
)
|
||||
|
||||
downgraded = llm_result.capability.get("builtin_tool_downgrades")
|
||||
if downgraded:
|
||||
self.context.log.log(
|
||||
type="info",
|
||||
heading="Responses capability downgrade",
|
||||
content=(
|
||||
"Provider rejected Responses built-in tool(s); omitted: "
|
||||
+ ", ".join(str(item) for item in downgraded)
|
||||
),
|
||||
)
|
||||
|
||||
await extension.call_extensions_async(
|
||||
"chat_model_call_after",
|
||||
self,
|
||||
call_data=call_data,
|
||||
response=llm_result.response,
|
||||
reasoning=llm_result.reasoning,
|
||||
)
|
||||
|
||||
return llm_result
|
||||
|
||||
def _responses_state_for_model(self, model: Any) -> dict[str, Any]:
|
||||
state = self.get_data(Agent.DATA_NAME_RESPONSES_STATE)
|
||||
if not isinstance(state, dict):
|
||||
return {}
|
||||
provider_model_key = str(getattr(model, "model_name", "") or "")
|
||||
if state.get("provider_model_key") != provider_model_key:
|
||||
return {}
|
||||
if not state.get("response_id"):
|
||||
return {}
|
||||
return state
|
||||
|
||||
def _responses_input_items_since(
|
||||
self, model: Any, sequence: int
|
||||
) -> list[dict[str, Any]]:
|
||||
items: list[dict[str, Any]] = []
|
||||
for message in self.history.messages_since(sequence):
|
||||
items.extend(self._responses_input_items_for_message(model, message))
|
||||
return items
|
||||
|
||||
def _responses_input_items_for_message(
|
||||
self, model: Any, message: history.Message
|
||||
) -> list[dict[str, Any]]:
|
||||
result = result_from_metadata(message.metadata)
|
||||
if result:
|
||||
if message.ai and result.output_items:
|
||||
return [item.to_dict() for item in result.output_items]
|
||||
if not message.ai and result.input_items:
|
||||
return [dict(item) for item in result.input_items]
|
||||
|
||||
output = message.output()
|
||||
langchain_messages = history.output_langchain(output)
|
||||
if hasattr(model, "_convert_messages"):
|
||||
converted = model._convert_messages(langchain_messages)
|
||||
return ResponsesTransport.input_from_messages(converted)
|
||||
return []
|
||||
|
||||
def _responses_prompt_input_items(
|
||||
self, model: Any, messages: list[BaseMessage]
|
||||
) -> list[dict[str, Any]]:
|
||||
if not hasattr(model, "_convert_messages"):
|
||||
return []
|
||||
converted = model._convert_messages(messages)
|
||||
return ResponsesTransport.input_from_messages(converted)
|
||||
|
||||
def _remember_llm_result_state(
|
||||
self, llm_result: LLMResult, history_message: history.Message
|
||||
) -> None:
|
||||
if not llm_result.response_id:
|
||||
return
|
||||
current = self.get_data(Agent.DATA_NAME_RESPONSES_STATE)
|
||||
response_ids = []
|
||||
if isinstance(current, dict) and isinstance(current.get("response_ids"), list):
|
||||
response_ids = [str(item) for item in current["response_ids"] if item]
|
||||
if llm_result.response_id not in response_ids:
|
||||
response_ids.append(llm_result.response_id)
|
||||
self.set_data(
|
||||
Agent.DATA_NAME_RESPONSES_STATE,
|
||||
{
|
||||
"response_id": llm_result.response_id,
|
||||
"previous_response_id": llm_result.previous_response_id,
|
||||
"provider_model_key": llm_result.provider_model_key,
|
||||
"history_counter": history_message.sequence,
|
||||
"response_ids": response_ids,
|
||||
},
|
||||
)
|
||||
|
||||
@extension.extensible
|
||||
async def rate_limiter_callback(
|
||||
self, message: str, key: str, total: int, limit: int
|
||||
|
|
@ -1101,310 +863,6 @@ class Agent:
|
|||
while self.context.paused:
|
||||
await asyncio.sleep(0.1)
|
||||
|
||||
async def process_llm_result_tools(self, llm_result: LLMResult):
|
||||
await self._log_response_builtin_items(llm_result)
|
||||
if llm_result.function_calls:
|
||||
for function_call in llm_result.function_calls:
|
||||
name_map = self.get_data(Agent.DATA_NAME_RESPONSES_TOOL_NAME_MAP)
|
||||
tool_name = original_tool_name(function_call.name, name_map)
|
||||
response_item_factory = lambda response, call=function_call: function_call_output_item(
|
||||
call.call_id,
|
||||
response.message,
|
||||
)
|
||||
result = await self._execute_tool_request(
|
||||
tool_name=tool_name,
|
||||
tool_args=function_call.arguments,
|
||||
message=llm_result.response,
|
||||
raw_tool_name=tool_name,
|
||||
responses_item_factory=response_item_factory,
|
||||
)
|
||||
if result:
|
||||
return result
|
||||
return None
|
||||
if llm_result.builtin_items and not llm_result.response:
|
||||
return None
|
||||
if (
|
||||
llm_result.mode == "responses"
|
||||
and llm_result.response
|
||||
and extract_tools.json_parse_dirty(llm_result.response) is None
|
||||
):
|
||||
return llm_result.response
|
||||
return await self.process_tools(llm_result.response)
|
||||
|
||||
async def _execute_tool_request(
|
||||
self,
|
||||
tool_name: str,
|
||||
tool_args: dict,
|
||||
message: str,
|
||||
raw_tool_name: str = "",
|
||||
responses_item_factory: Callable[[Any], dict[str, Any]] | None = None,
|
||||
):
|
||||
raw_tool_name = raw_tool_name or tool_name
|
||||
tool_method = None
|
||||
tool = None
|
||||
|
||||
try:
|
||||
import helpers.mcp_handler as mcp_helper
|
||||
|
||||
mcp_tool_candidate = mcp_helper.MCPConfig.get_instance().get_tool(
|
||||
self, tool_name
|
||||
)
|
||||
if mcp_tool_candidate:
|
||||
tool = mcp_tool_candidate
|
||||
except ImportError:
|
||||
PrintStyle(
|
||||
background_color="black", font_color="yellow", padding=True
|
||||
).print("MCP helper module not found. Skipping MCP tool lookup.")
|
||||
except Exception as e:
|
||||
PrintStyle(background_color="black", font_color="red", padding=True).print(
|
||||
f"Failed to get MCP tool '{tool_name}': {e}"
|
||||
)
|
||||
|
||||
if not tool:
|
||||
tool = self.get_tool(
|
||||
name=tool_name,
|
||||
method=tool_method,
|
||||
args=tool_args,
|
||||
message=message,
|
||||
loop_data=self.loop_data,
|
||||
)
|
||||
|
||||
if not tool:
|
||||
error_detail = (
|
||||
f"Tool '{raw_tool_name}' not found or could not be initialized."
|
||||
)
|
||||
wmsg = self.hist_add_warning(error_detail)
|
||||
PrintStyle(font_color="red", padding=True).print(error_detail)
|
||||
self.context.log.log(
|
||||
type="warning",
|
||||
content=f"{self.agent_name}: {error_detail}",
|
||||
id=wmsg.id,
|
||||
)
|
||||
return None
|
||||
|
||||
self.loop_data.current_tool = tool # type: ignore
|
||||
try:
|
||||
await self.handle_intervention()
|
||||
|
||||
await tool.before_execution(**tool_args)
|
||||
await self.handle_intervention()
|
||||
|
||||
await extension.call_extensions_async(
|
||||
"tool_execute_before",
|
||||
self,
|
||||
tool_args=tool_args or {},
|
||||
tool_name=tool_name,
|
||||
)
|
||||
|
||||
response = await tool.execute(**tool_args)
|
||||
await self.handle_intervention()
|
||||
|
||||
await extension.call_extensions_async(
|
||||
"tool_execute_after",
|
||||
self,
|
||||
response=response,
|
||||
tool_name=tool_name,
|
||||
)
|
||||
|
||||
if responses_item_factory:
|
||||
response.additional = {
|
||||
**(response.additional or {}),
|
||||
"_responses_output_item": responses_item_factory(response),
|
||||
}
|
||||
|
||||
await tool.after_execution(response)
|
||||
await self.handle_intervention()
|
||||
|
||||
if response.break_loop:
|
||||
self._clear_responses_pending_state()
|
||||
return response.message
|
||||
finally:
|
||||
self.loop_data.current_tool = None
|
||||
return None
|
||||
|
||||
async def _log_response_builtin_items(self, llm_result: LLMResult) -> None:
|
||||
for item in llm_result.builtin_items:
|
||||
if item.type == "computer_call":
|
||||
await self._handle_responses_computer_call(item.data)
|
||||
continue
|
||||
if item.type == "mcp_approval_request":
|
||||
self._handle_responses_mcp_approval_request(item.data)
|
||||
continue
|
||||
self.context.log.log(
|
||||
type="info",
|
||||
heading=f"Responses tool item: {item.type}",
|
||||
content=json.dumps(item.data, ensure_ascii=False, default=str),
|
||||
)
|
||||
|
||||
async def _handle_responses_computer_call(self, item: dict[str, Any]) -> None:
|
||||
safety_checks = item.get("pending_safety_checks") or item.get("safety_checks")
|
||||
if safety_checks:
|
||||
message = (
|
||||
"Responses computer_call requested safety-check acknowledgement. "
|
||||
"Agent Zero requires explicit user acknowledgement before executing it."
|
||||
)
|
||||
output_item = {
|
||||
"type": "computer_call_output",
|
||||
"call_id": str(item.get("call_id") or item.get("id") or ""),
|
||||
"output": {"type": "input_text", "text": message},
|
||||
}
|
||||
self.hist_add_tool_result(
|
||||
"computer_call",
|
||||
message,
|
||||
responses_item=output_item,
|
||||
)
|
||||
self.context.log.log(type="warning", content=message)
|
||||
return
|
||||
|
||||
args = self._computer_call_args(item)
|
||||
if not args:
|
||||
message = "Responses computer_call action is unsupported by Agent Zero."
|
||||
output_item = {
|
||||
"type": "computer_call_output",
|
||||
"call_id": str(item.get("call_id") or item.get("id") or ""),
|
||||
"output": {"type": "input_text", "text": message},
|
||||
}
|
||||
self.hist_add_tool_result(
|
||||
"computer_call",
|
||||
message,
|
||||
responses_item=output_item,
|
||||
)
|
||||
self.context.log.log(type="warning", content=message)
|
||||
return
|
||||
|
||||
if args.get("action") != "start_session" and not args.get("session_id"):
|
||||
session_id = str(
|
||||
self.get_data(Agent.DATA_NAME_RESPONSES_COMPUTER_SESSION) or ""
|
||||
)
|
||||
if session_id:
|
||||
args["session_id"] = session_id
|
||||
|
||||
response_item_factory = lambda response: self._computer_call_output_item(
|
||||
item,
|
||||
response,
|
||||
)
|
||||
result = await self._execute_tool_request(
|
||||
tool_name="computer_use_remote",
|
||||
tool_args=args,
|
||||
message=json.dumps(item, ensure_ascii=False, default=str),
|
||||
raw_tool_name="computer_call",
|
||||
responses_item_factory=response_item_factory,
|
||||
)
|
||||
_ = result
|
||||
|
||||
def _handle_responses_mcp_approval_request(self, item: dict[str, Any]) -> None:
|
||||
request_id = str(
|
||||
item.get("approval_request_id") or item.get("id") or item.get("call_id") or ""
|
||||
)
|
||||
message = (
|
||||
"Responses MCP approval request received. Agent Zero denied it because "
|
||||
"provider-hosted MCP approval requires explicit user approval."
|
||||
)
|
||||
output_item = {
|
||||
"type": "mcp_approval_response",
|
||||
"approval_request_id": request_id,
|
||||
"approve": False,
|
||||
}
|
||||
self.hist_add_tool_result(
|
||||
"mcp_approval_request",
|
||||
message,
|
||||
responses_item=output_item,
|
||||
)
|
||||
self.context.log.log(
|
||||
type="warning",
|
||||
heading="Responses MCP approval required",
|
||||
content=message,
|
||||
)
|
||||
|
||||
def _computer_call_args(self, item: dict[str, Any]) -> dict[str, Any]:
|
||||
action = item.get("action")
|
||||
action_data = dict(action) if isinstance(action, dict) else {}
|
||||
action_type = str(
|
||||
action_data.get("type")
|
||||
or action_data.get("action")
|
||||
or item.get("action_type")
|
||||
or ""
|
||||
).strip().lower()
|
||||
args: dict[str, Any] = {}
|
||||
|
||||
if action_type in {"screenshot", "capture"}:
|
||||
args["action"] = "capture"
|
||||
elif action_type in {"move", "mousemove"}:
|
||||
args.update({"action": "move", "x": action_data.get("x"), "y": action_data.get("y")})
|
||||
elif action_type in {"click", "double_click"}:
|
||||
args.update(
|
||||
{
|
||||
"action": "click",
|
||||
"x": action_data.get("x"),
|
||||
"y": action_data.get("y"),
|
||||
"button": action_data.get("button", "left"),
|
||||
"count": 2 if action_type == "double_click" else action_data.get("count", 1),
|
||||
}
|
||||
)
|
||||
elif action_type == "scroll":
|
||||
args.update(
|
||||
{
|
||||
"action": "scroll",
|
||||
"dx": action_data.get("dx", action_data.get("scroll_x", 0)),
|
||||
"dy": action_data.get("dy", action_data.get("scroll_y", 0)),
|
||||
}
|
||||
)
|
||||
elif action_type in {"keypress", "key"}:
|
||||
args.update(
|
||||
{
|
||||
"action": "key",
|
||||
"keys": action_data.get("keys") or action_data.get("key"),
|
||||
}
|
||||
)
|
||||
elif action_type in {"type", "input_text"}:
|
||||
args.update({"action": "type", "text": action_data.get("text", "")})
|
||||
else:
|
||||
return {}
|
||||
|
||||
session_id = item.get("session_id") or action_data.get("session_id")
|
||||
if session_id:
|
||||
args["session_id"] = session_id
|
||||
return args
|
||||
|
||||
def _computer_call_output_item(
|
||||
self, source_item: dict[str, Any], response: Any
|
||||
) -> dict[str, Any]:
|
||||
output: dict[str, Any] = {
|
||||
"type": "input_text",
|
||||
"text": str(getattr(response, "message", "") or ""),
|
||||
}
|
||||
additional = getattr(response, "additional", None)
|
||||
raw_content = additional.get("raw_content") if isinstance(additional, dict) else None
|
||||
if isinstance(raw_content, list):
|
||||
for content in raw_content:
|
||||
if not isinstance(content, dict):
|
||||
continue
|
||||
if content.get("type") != "image_url":
|
||||
continue
|
||||
image_url = content.get("image_url")
|
||||
url = image_url.get("url") if isinstance(image_url, dict) else image_url
|
||||
if url:
|
||||
output = {"type": "input_image", "image_url": url}
|
||||
break
|
||||
|
||||
session_id_match = re_search_session_id(str(getattr(response, "message", "") or ""))
|
||||
if session_id_match:
|
||||
self.set_data(Agent.DATA_NAME_RESPONSES_COMPUTER_SESSION, session_id_match)
|
||||
|
||||
return {
|
||||
"type": "computer_call_output",
|
||||
"call_id": str(source_item.get("call_id") or source_item.get("id") or ""),
|
||||
"output": output,
|
||||
}
|
||||
|
||||
def _clear_responses_pending_state(self) -> None:
|
||||
state = self.get_data(Agent.DATA_NAME_RESPONSES_STATE)
|
||||
if isinstance(state, dict):
|
||||
state = dict(state)
|
||||
state.pop("response_id", None)
|
||||
state.pop("previous_response_id", None)
|
||||
self.set_data(Agent.DATA_NAME_RESPONSES_STATE, state)
|
||||
|
||||
@extension.extensible
|
||||
async def process_tools(self, msg: str):
|
||||
# search for tool usage requests in agent message
|
||||
|
|
@ -1579,8 +1037,3 @@ class Agent:
|
|||
loop_data=loop_data,
|
||||
**kwargs,
|
||||
)
|
||||
|
||||
|
||||
def re_search_session_id(text: str) -> str:
|
||||
match = re.search(r"session_id=([A-Za-z0-9_.:-]+)", text or "")
|
||||
return match.group(1) if match else ""
|
||||
|
|
|
|||
|
|
@ -1,44 +0,0 @@
|
|||
# Agent Profiles DOX
|
||||
|
||||
## Purpose
|
||||
|
||||
- Own bundled agent profiles, profile-specific prompts, and profile-local tools.
|
||||
- Keep profile behavior understandable without requiring edits to core framework prompts.
|
||||
|
||||
## Ownership
|
||||
|
||||
- Each direct profile directory owns its `agent.yaml`, optional `prompts/`, optional `tools/`, and optional `extensions/`.
|
||||
- `_example/` demonstrates profile layout and should stay suitable as a reference.
|
||||
- User-created local profiles belong under `usr/agents/`, not here, unless they are intended to ship with the product.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- `agent.yaml` is the profile entry point and must stay valid YAML.
|
||||
- Profile prompt overrides should be narrow and named to match the core prompt they extend or replace.
|
||||
- Profile-local tools must follow the same `Tool` contract as root `tools/`.
|
||||
- Do not put secrets, provider API keys, local paths, or user-specific settings in bundled profiles.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Prefer small profile-specific prompt files over duplicating large core prompts.
|
||||
- Keep examples generic and runnable in a clean checkout.
|
||||
- When changing profile behavior, check how the WebUI profile picker and backend profile loader discover profiles.
|
||||
|
||||
## Verification
|
||||
|
||||
- Run `pytest` or targeted tests covering profile loading when changing `agent.yaml` structure or profile discovery.
|
||||
- Manually inspect YAML validity for changed profiles if no targeted test exists.
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
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. |
|
||||
| [tiny-local/AGENTS.md](tiny-local/AGENTS.md) | Small/local model profile with an action-first communication prompt. |
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
### Initial Interview
|
||||
|
||||
When 'Master Developer' agent receives a development task, first decide whether the request is already actionable. For clear, bounded coding tasks, infer reasonable defaults from the repository, inspect local specs/tests, implement, and verify. Ask the user only when ambiguity blocks safe progress, would change the deliverable materially, or risks destructive/unwanted work.
|
||||
When 'Master Developer' agent receives a development task, it must execute a comprehensive requirements elicitation protocol to ensure complete specification of all parameters, constraints, and success criteria before initiating autonomous development operations.
|
||||
|
||||
For broad or underspecified development mandates, conduct a structured interview process to establish:
|
||||
The agent SHALL conduct a structured interview process to establish:
|
||||
- **Scope Boundaries**: Precise delineation of features, modules, and integrations included/excluded from the development mandate
|
||||
- **Technical Requirements**: Expected performance benchmarks, scalability needs, from prototype to production-grade implementations
|
||||
- **Output Specifications**: Deliverable preferences (source code, containers, documentation), deployment targets, testing requirements
|
||||
|
|
@ -13,7 +13,7 @@ For broad or underspecified development mandates, conduct a structured interview
|
|||
- **Timeline Parameters**: Sprint cycles, release deadlines, milestone deliverables, continuous deployment schedules
|
||||
- **Success Metrics**: Explicit criteria for determining code quality, system performance, and feature completeness
|
||||
|
||||
Use the 'response' tool iteratively only for blocking questions. Do not ask an interview when the user asked for a small script, bug fix, refactor, test addition, or inspection task that can be handled from local context. For these tasks, move quickly through inspect -> implement -> test -> cleanup -> concise final report.
|
||||
The agent must utilize the 'response' tool iteratively until achieving complete clarity on all dimensions. Only when the agent can execute the entire development lifecycle without further clarification should autonomous work commence. This front-loaded investment in requirements understanding prevents costly refactoring and ensures alignment with user expectations.
|
||||
|
||||
### Thinking (thoughts)
|
||||
|
||||
|
|
@ -80,4 +80,4 @@ Exactly one JSON object per response cycle.
|
|||
}
|
||||
~~~
|
||||
|
||||
{{ include "agent.system.main.communication_additions.md" }}
|
||||
{{ include "agent.system.main.communication_additions.md" }}
|
||||
|
|
@ -40,10 +40,6 @@ You are Agent Zero 'Master Developer' - an autonomous intelligence system engine
|
|||
4. **Innovation Focus**: Leverage cutting-edge technologies while maintaining pragmatic stability requirements
|
||||
5. **Practical Delivery**: Ship working software that solves real problems with elegant, maintainable solutions
|
||||
|
||||
### Delivery Discipline
|
||||
|
||||
For coding-agent and terminal-heavy tasks, scale the core coding discipline rather than replacing it. Read repository facts first, keep edits scoped, delegate only bounded components with testable outputs, verify integration points and exact artifacts, clean generated work, and report only what was checked.
|
||||
|
||||
Your expertise enables transformation of complex technical challenges into elegant, scalable solutions that power mission-critical systems at the highest performance levels.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,31 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
# 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 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.
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
# Tiny Local Agent Profile DOX
|
||||
|
||||
## Purpose
|
||||
|
||||
- Own the bundled Tiny Local profile for small/local chat models.
|
||||
- Keep local-model behavior prompt-only and isolated from core framework execution.
|
||||
|
||||
## Ownership
|
||||
|
||||
- `agent.yaml` owns profile metadata for discovery and profile switching.
|
||||
- `prompts/agent.system.main.communication.md` owns the local-model communication contract.
|
||||
- `prompts/agent.system.main.solving.md` owns the local-model problem-solving contract and suppresses inherited visible reasoning requirements.
|
||||
- `prompts/fw.msg_repeat.md` owns Tiny Local's profile-specific recovery instructions when the framework rejects a duplicate assistant message.
|
||||
- `prompts/agent.system.tools.md` owns the Tiny Local tools wrapper and final output-shape reminder after tool listing.
|
||||
- `prompts/agent.system.tool.*.md` files own Tiny Local-specific tool examples that avoid inherited reasoning fields and repeated writes.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Preserve the normal Agent Zero tool-call shape: `tool_name` plus `tool_args`.
|
||||
- Do not add parser repair, duplicate suppression runtime, model transport, or text-editor runtime behavior here.
|
||||
- Duplicate-message handling may be tightened through profile prompts only.
|
||||
- Keep prompt text short enough for small local models to follow.
|
||||
- Treat continuation requests such as `proceed` or `continue` as commands to execute the next unfinished step, not as prompts for another status response.
|
||||
- Do not include user-specific provider names, API keys, local paths, or secrets.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Prefer prompt wording changes over new files when tightening this profile, except when replacing inherited tool examples for local-model compliance.
|
||||
- Keep this profile suitable for Ollama, LM Studio, Qwen, and comparable local models.
|
||||
|
||||
## Verification
|
||||
|
||||
- Render the `tiny-local` system prompt after communication prompt changes.
|
||||
- Run `pytest tests/test_default_prompt_budget.py` for prompt and profile regressions.
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child DOX files.
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
title: Tiny Local
|
||||
description: Action-first profile for small local models that need a minimal tool-call contract.
|
||||
context: Use this agent when running small local chat models through Ollama, LM Studio, or similar providers and the model tends to explain actions instead of calling tools.
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
## Communication
|
||||
|
||||
You are Agent Zero. Act on the user's behalf.
|
||||
|
||||
When the user asks you to do something, do it directly. Do not explain how the user could do it themselves.
|
||||
|
||||
Your visible assistant message must be exactly one valid JSON object.
|
||||
|
||||
Use exactly these top-level fields: `"tool_name"` and `"tool_args"`.
|
||||
|
||||
Do not include markdown fences, prose before the JSON, prose after the JSON, hidden reasoning, analysis, thoughts, or headlines.
|
||||
|
||||
Choose a tool from the tools listed in this system prompt. Do not invent tool names, action names, or generic names such as `read`, `write`, `terminal`, or `multi`.
|
||||
|
||||
For a final user-facing answer, use the `response` tool.
|
||||
|
||||
Use `response` only when the work is complete, blocked, or the user is only acknowledging completed work.
|
||||
|
||||
If the user says "proceed", "continue", "go ahead", "do it", "excellent proceed", or similar after you named a next step or there is unfinished work, do not answer with a promise or status update. Call the next appropriate tool.
|
||||
|
||||
Final-answer shape:
|
||||
|
||||
`{"tool_name":"response","tool_args":{"text":"Answer briefly."}}`
|
||||
|
||||
For work that requires a command, file action, browser action, or any other available tool, call the appropriate tool immediately. Do not explain what command the user could run manually.
|
||||
|
||||
If the framework warns that your prior message was malformed, repeated, or reasoning-only, output a corrected JSON tool request immediately without explaining the warning.
|
||||
|
||||
When the warning says you sent the same message again, do not resend the same JSON. Change the tool, action, arguments, or final answer so the next message is meaningfully different.
|
||||
|
||||
{{ include "agent.system.main.communication_additions.md" }}
|
||||
|
|
@ -1,18 +0,0 @@
|
|||
## Problem Solving
|
||||
|
||||
Act directly and keep hidden reasoning out of the visible JSON.
|
||||
|
||||
For simple questions, answer with the `response` tool.
|
||||
|
||||
Continuation words such as "proceed", "continue", "go ahead", "do it", and "excellent proceed" mean execute the next unfinished step. Do not respond by saying you will begin, continue, start, proceed, or investigate. Use a real tool call unless the task is already complete or blocked.
|
||||
|
||||
For tasks that need shell commands, files, browser actions, or other capabilities:
|
||||
- choose the appropriate listed tool immediately
|
||||
- keep one tool call per turn unless the `parallel` tool is listed and truly useful
|
||||
- inspect outputs before deciding the next tool call
|
||||
- never claim success from timeout output or a still-running command
|
||||
- after a successful tool result, do not repeat the same exact tool call
|
||||
- after a repeated-message warning, do not repeat the same status response or exact tool request; choose the next different executable action or report a blocker
|
||||
- when finished, use the `response` tool with a brief result
|
||||
|
||||
Do not include `thoughts`, `headline`, analysis, plans, or prose outside the JSON object.
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
### code_execution_tool
|
||||
Run terminal, Python, or Node.js commands.
|
||||
|
||||
Arguments in `tool_args`:
|
||||
- `runtime`: `terminal`, `python`, `nodejs`, or `output`
|
||||
- `code`: command or script code
|
||||
- `session`: terminal session id; default `0`
|
||||
- `reset`: kill a session before running; `true` or `false`
|
||||
|
||||
Rules:
|
||||
- Put the command or script in `code`.
|
||||
- Use `runtime=output` to poll running work.
|
||||
- Use `input` for interactive terminal prompts.
|
||||
- If a session is stuck, call this tool again with the same `session` and `reset=true`.
|
||||
- Do not claim success from timeout output or a still-running command.
|
||||
- When counting files, prefer `find` over `ls` so hidden files and type filters are handled.
|
||||
|
||||
Examples:
|
||||
|
||||
`{"tool_name":"code_execution_tool","tool_args":{"runtime":"terminal","session":0,"reset":false,"code":"ls -1 /tmp | wc -l"}}`
|
||||
|
||||
`{"tool_name":"code_execution_tool","tool_args":{"runtime":"python","session":0,"reset":false,"code":"import os\nprint(os.getcwd())"}}`
|
||||
|
||||
`{"tool_name":"code_execution_tool","tool_args":{"runtime":"output","session":0}}`
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
### response
|
||||
Final answer to the user.
|
||||
|
||||
Use this tool only when the task is done, blocked, or no tool is needed.
|
||||
|
||||
Do not use this tool for "proceed", "continue", "go ahead", or similar continuation requests when there is an unfinished next step. Call a real tool instead.
|
||||
|
||||
Arguments in `tool_args`:
|
||||
- `text`: concise final answer text
|
||||
|
||||
Example:
|
||||
|
||||
`{"tool_name":"response","tool_args":{"text":"There are 24 files in /tmp."}}`
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
### text_editor
|
||||
Read, write, or patch Markdown and plain text files.
|
||||
|
||||
Actions in `tool_args.action`:
|
||||
- `read`: read a file
|
||||
- `write`: create or overwrite a file
|
||||
- `patch`: edit an existing file
|
||||
|
||||
Common arguments:
|
||||
- `path`: absolute file path
|
||||
- `content`: full file content for `write`
|
||||
- `open_in_canvas`: set `true` when the user explicitly asks to open a Markdown file in the Canvas or Editor
|
||||
|
||||
Rules:
|
||||
- Use this tool for `.md` and plain text files.
|
||||
- Use `write` to create a new Markdown file.
|
||||
- If the user asks to open the file in the Canvas or Editor, include `"open_in_canvas": true` in the same `write` or `patch` call.
|
||||
- After a successful write or patch result, do not repeat the same tool call. Use the `response` tool unless a different action is needed.
|
||||
|
||||
Examples:
|
||||
|
||||
`{"tool_name":"text_editor","tool_args":{"action":"write","path":"/a0/usr/workdir/TODO.md","content":"# TODO\n- [ ] First item\n","open_in_canvas":true}}`
|
||||
|
||||
`{"tool_name":"text_editor","tool_args":{"action":"read","path":"/a0/usr/workdir/TODO.md"}}`
|
||||
|
||||
`{"tool_name":"text_editor","tool_args":{"action":"patch","path":"/a0/usr/workdir/TODO.md","old_text":"- [ ] First item","new_text":"- [x] First item"}}`
|
||||
|
|
@ -1,17 +0,0 @@
|
|||
## Available Tools
|
||||
|
||||
Use only the tools listed below. Match tool names exactly.
|
||||
|
||||
Every tool request must be exactly one JSON object with only these top-level fields:
|
||||
- `tool_name`
|
||||
- `tool_args`
|
||||
|
||||
Action names are not tool names. Do not invent top-level `multi`, `read`, `write`, `terminal`, or generic batch tools.
|
||||
|
||||
{{tools}}
|
||||
|
||||
## Tiny Local Output Rule
|
||||
|
||||
Some inherited tool examples may show `thoughts` or `headline`. Ignore that shape for this profile.
|
||||
|
||||
Do not include `thoughts`, `headline`, analysis, markdown fences, or prose outside the JSON object.
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
You have sent the same message again. You have to do something else.
|
||||
|
||||
Your repeated JSON was recorded, but it did not execute another tool. Do not send the same JSON object again.
|
||||
|
||||
Choose one different action now:
|
||||
- If work is unfinished, call a real tool for the next unfinished step.
|
||||
- If your previous JSON used `response` while work remains, replace it with the next real tool call.
|
||||
- If a file write or patch already succeeded, read that file or answer with the observed result.
|
||||
- If a command already ran, inspect its output or run a different next command.
|
||||
- If the user only said "proceed" or "continue", continue with the next real tool call.
|
||||
- If no different action is possible, use `response` with a brief blocker.
|
||||
|
||||
Output exactly one JSON object with `tool_name` and `tool_args`. No prose or markdown.
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
# API Handlers DOX
|
||||
|
||||
## Purpose
|
||||
|
||||
- Own backend HTTP API handlers and WebSocket handler entry points.
|
||||
- Keep route-level behavior, authentication, CSRF, input parsing, and response shapes explicit.
|
||||
|
||||
## Ownership
|
||||
|
||||
- Files in this directory are discovered by the route registration layer in `helpers/api.py` and WebSocket registration code.
|
||||
- `ws_*.py` files define WebSocket namespaces or handlers through `helpers.ws.WsHandler`.
|
||||
- Plugin-provided API handlers belong inside plugin `api/` folders and follow the same base contracts.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- HTTP handlers must derive from `helpers.api.ApiHandler`.
|
||||
- Implement `async def process(self, input: dict, request: Request) -> dict | Response`.
|
||||
- Override `get_methods()`, `requires_auth()`, `requires_csrf()`, `requires_api_key()`, or `requires_loopback()` only when the endpoint contract requires it.
|
||||
- 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
|
||||
|
||||
No child DOX files.
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
from agent import AgentContext
|
||||
from agent import Agent, AgentContext
|
||||
from helpers import subagents
|
||||
from helpers.api import ApiHandler, Request, Response
|
||||
from helpers.persist_chat import save_tmp_chat
|
||||
|
|
@ -39,7 +39,11 @@ class SetAgentProfile(ApiHandler):
|
|||
|
||||
config = initialize_agent(override_settings={"agent_profile": profile})
|
||||
context.config = config
|
||||
context.agent0.config = config
|
||||
|
||||
agent = context.agent0
|
||||
while agent:
|
||||
agent.config = config
|
||||
agent = agent.get_data(Agent.DATA_NAME_SUBORDINATE)
|
||||
|
||||
save_tmp_chat(context)
|
||||
mark_dirty_for_context(context.id, reason="agent_profile_change")
|
||||
|
|
|
|||
|
|
@ -1,48 +0,0 @@
|
|||
# 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.
|
||||
- Switching a chat profile updates the context and top-level agent profile only; existing subordinate agents keep their own profile configs.
|
||||
- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.persist_chat`, `helpers.state_monitor_integration`.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- Important called helpers/classes observed in the source: `str.strip`, `context.is_running`, `_agent_profile_labels`, `initialize_agent`, `context.agent0.config`, `save_tmp_chat`, `mark_dirty_for_context`, `subagents.get_all_agents_list`, `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_subagent_profiles.py`
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child DOX files.
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,51 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -47,13 +47,12 @@ class BackupTest(ApiHandler):
|
|||
|
||||
backup_service = BackupService()
|
||||
matched_files = await backup_service.test_patterns(metadata, max_files=max_files)
|
||||
truncated = max_files is not None and len(matched_files) >= max_files
|
||||
|
||||
return {
|
||||
"success": True,
|
||||
"files": matched_files,
|
||||
"total_count": len(matched_files),
|
||||
"truncated": truncated
|
||||
"truncated": len(matched_files) >= max_files
|
||||
}
|
||||
|
||||
except Exception as e:
|
||||
|
|
|
|||
|
|
@ -1,48 +0,0 @@
|
|||
# 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`.
|
||||
- The `truncated` response flag is true only when a finite `max_files` limit is supplied and the result reaches that limit.
|
||||
|
||||
## 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.
|
||||
|
|
@ -1,46 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
import secrets
|
||||
from urllib.parse import urlparse
|
||||
from helpers.api import (
|
||||
ApiHandler,
|
||||
Input,
|
||||
|
|
@ -8,7 +9,6 @@ from helpers.api import (
|
|||
session,
|
||||
)
|
||||
from helpers import runtime, dotenv, login
|
||||
from helpers.tunnel_origins import origin_from_url
|
||||
import fnmatch
|
||||
|
||||
ALLOWED_ORIGINS_KEY = "ALLOWED_ORIGINS"
|
||||
|
|
@ -82,7 +82,11 @@ class GetCsrfToken(ApiHandler):
|
|||
)
|
||||
if not r:
|
||||
return None
|
||||
return origin_from_url(r)
|
||||
# parse and normalize
|
||||
p = urlparse(r)
|
||||
if not p.scheme or not p.hostname:
|
||||
return None
|
||||
return f"{p.scheme}://{p.hostname}" + (f":{p.port}" if p.port else "")
|
||||
|
||||
async def get_allowed_origins(self) -> list[str]:
|
||||
# get the allowed origins from the environment
|
||||
|
|
@ -103,10 +107,8 @@ class GetCsrfToken(ApiHandler):
|
|||
from api.tunnel_proxy import process as tunnel_api_process
|
||||
|
||||
tunnel = await tunnel_api_process({"action": "get"})
|
||||
if tunnel and isinstance(tunnel, dict) and tunnel.get("success"):
|
||||
tunnel_origin = origin_from_url(tunnel.get("tunnel_url"))
|
||||
if tunnel_origin:
|
||||
allowed_origins.append(tunnel_origin)
|
||||
if tunnel and isinstance(tunnel, dict) and tunnel["success"]:
|
||||
allowed_origins.append(tunnel["tunnel_url"])
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
|
|
|||
|
|
@ -1,57 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,46 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -9,7 +9,7 @@ class GetWorkDirFiles(ApiHandler):
|
|||
return ["GET"]
|
||||
|
||||
async def process(self, input: dict, request: Request) -> dict | Response:
|
||||
current_path = request.args.get("path", "") or "$WORK_DIR"
|
||||
current_path = request.args.get("path", "")
|
||||
if current_path == "$WORK_DIR":
|
||||
# if runtime.is_development():
|
||||
# current_path = "work_dir"
|
||||
|
|
|
|||
|
|
@ -1,48 +0,0 @@
|
|||
# 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`.
|
||||
- Empty `path` requests and explicit `$WORK_DIR` requests resolve to the default workdir path before `FileBrowser` is called, so the WebUI never receives an empty startup path for the default file browser view.
|
||||
- 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.
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -9,11 +9,9 @@ class McpServerGetDetail(ApiHandler):
|
|||
|
||||
# try:
|
||||
server_name = input.get("server_name")
|
||||
project_name = str(input.get("project_name", "") or "").strip()
|
||||
if not server_name:
|
||||
return {"success": False, "error": "Missing server_name"}
|
||||
config = MCPConfig.get_project_instance(project_name) if project_name else MCPConfig.get_instance()
|
||||
detail = config.get_server_detail(server_name)
|
||||
detail = MCPConfig.get_instance().get_server_detail(server_name)
|
||||
return {"success": True, "detail": detail}
|
||||
# except Exception as e:
|
||||
# return {"success": False, "error": str(e)}
|
||||
|
|
|
|||
|
|
@ -1,45 +0,0 @@
|
|||
# mcp_server_get_detail.py DOX
|
||||
|
||||
## Purpose
|
||||
|
||||
- Own the `mcp_server_get_detail.py` API endpoint.
|
||||
- This module handles MCP server detail requests for global or project scope.
|
||||
- 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`.
|
||||
- The request accepts `server_name` and optional `project_name`; when `project_name` is present, detail resolves through the project-scoped MCP configuration.
|
||||
- Detail responses include the server tools visible to the manager UI. Tools disabled through a server `disabled_tools` config list remain present in this detail list with a `disabled` flag so the UI can re-enable them.
|
||||
- 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_project_instance`, `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.
|
||||
|
|
@ -9,11 +9,9 @@ class McpServerGetLog(ApiHandler):
|
|||
|
||||
# try:
|
||||
server_name = input.get("server_name")
|
||||
project_name = str(input.get("project_name", "") or "").strip()
|
||||
if not server_name:
|
||||
return {"success": False, "error": "Missing server_name"}
|
||||
config = MCPConfig.get_project_instance(project_name) if project_name else MCPConfig.get_instance()
|
||||
log = config.get_server_log(server_name)
|
||||
log = MCPConfig.get_instance().get_server_log(server_name)
|
||||
return {"success": True, "log": log}
|
||||
# except Exception as e:
|
||||
# return {"success": False, "error": str(e)}
|
||||
|
|
|
|||
|
|
@ -1,44 +0,0 @@
|
|||
# mcp_server_get_log.py DOX
|
||||
|
||||
## Purpose
|
||||
|
||||
- Own the `mcp_server_get_log.py` API endpoint.
|
||||
- This module handles MCP server log requests for global or project scope.
|
||||
- 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`.
|
||||
- The request accepts `server_name` and optional `project_name`; when `project_name` is present, logs resolve through the project-scoped MCP configuration.
|
||||
- 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_project_instance`, `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.
|
||||
|
|
@ -1,232 +0,0 @@
|
|||
import asyncio
|
||||
from shutil import which
|
||||
from typing import Any
|
||||
from urllib.parse import urlparse
|
||||
|
||||
from helpers.api import ApiHandler, Request, Response
|
||||
from helpers.mcp_handler import MCPConfig, normalize_name
|
||||
|
||||
|
||||
_PROMPT_INJECTION_MARKERS = (
|
||||
"ignore previous",
|
||||
"ignore all previous",
|
||||
"system prompt",
|
||||
"developer message",
|
||||
"hidden instruction",
|
||||
"exfiltrate",
|
||||
"leak secret",
|
||||
"credential",
|
||||
)
|
||||
|
||||
|
||||
class McpServerScan(ApiHandler):
|
||||
async def process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response:
|
||||
server = dict(input.get("server") or {})
|
||||
allow_local_execution = bool(input.get("allow_local_execution", False))
|
||||
allow_remote_network = bool(input.get("allow_remote_network", False))
|
||||
inspect_runtime = input.get("inspect_runtime", True) is not False
|
||||
|
||||
server = self._normalize_server(server)
|
||||
warnings = self._static_warnings(server)
|
||||
is_local = not (server.get("url") or server.get("serverUrl"))
|
||||
has_static_errors = any(warning.get("level") == "error" for warning in warnings)
|
||||
|
||||
runtime_status: list[dict[str, Any]] = []
|
||||
runtime_detail: dict[str, Any] = {}
|
||||
runtime_error = ""
|
||||
|
||||
should_inspect_runtime = (
|
||||
inspect_runtime
|
||||
and not has_static_errors
|
||||
and ((is_local and allow_local_execution) or (not is_local and allow_remote_network))
|
||||
)
|
||||
|
||||
if should_inspect_runtime:
|
||||
try:
|
||||
scan_config = await asyncio.to_thread(
|
||||
lambda: MCPConfig(servers_list=[server], config_scope="scan")
|
||||
)
|
||||
runtime_status = scan_config.get_servers_status()
|
||||
runtime_detail = scan_config.get_server_detail(server.get("name", ""))
|
||||
warnings.extend(self._tool_warnings(runtime_detail.get("tools", [])))
|
||||
except Exception as exc:
|
||||
runtime_error = str(exc)
|
||||
warnings.append(
|
||||
{
|
||||
"level": "error",
|
||||
"title": "Runtime inspection failed",
|
||||
"message": runtime_error,
|
||||
}
|
||||
)
|
||||
elif is_local and inspect_runtime:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "warning",
|
||||
"title": "Local command not executed",
|
||||
"message": "Local stdio MCP inspection requires explicit trust because it runs the configured command.",
|
||||
}
|
||||
)
|
||||
elif not is_local and inspect_runtime and has_static_errors:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "info",
|
||||
"title": "Runtime inspection skipped",
|
||||
"message": "Fix static scan errors before attempting runtime MCP inspection.",
|
||||
}
|
||||
)
|
||||
elif not is_local and inspect_runtime:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "info",
|
||||
"title": "Remote runtime inspection skipped",
|
||||
"message": "Enable trusted remote inspection to contact the MCP URL and list exposed tools.",
|
||||
}
|
||||
)
|
||||
|
||||
return {
|
||||
"success": True,
|
||||
"server": self._redact_server(server),
|
||||
"risk_level": self._risk_level(warnings),
|
||||
"warnings": warnings,
|
||||
"status": runtime_status,
|
||||
"detail": runtime_detail,
|
||||
"runtime_error": runtime_error,
|
||||
}
|
||||
|
||||
def _normalize_server(self, server: dict[str, Any]) -> dict[str, Any]:
|
||||
name = str(server.get("name") or "").strip()
|
||||
url = str(server.get("url") or server.get("serverUrl") or "").strip()
|
||||
command = str(server.get("command") or "").strip()
|
||||
|
||||
if not name:
|
||||
name = self._derive_name(url, command)
|
||||
server["name"] = normalize_name(name or "mcp_server")
|
||||
|
||||
if url:
|
||||
server["url"] = url
|
||||
server.setdefault("type", "streamable-http")
|
||||
elif command:
|
||||
server["command"] = command
|
||||
server["type"] = "stdio"
|
||||
|
||||
return server
|
||||
|
||||
def _derive_name(self, url: str, command: str) -> str:
|
||||
if url:
|
||||
parsed = urlparse(url)
|
||||
parts = [part for part in parsed.path.split("/") if part]
|
||||
return parts[-1] if parts else parsed.hostname or "remote_mcp"
|
||||
if command:
|
||||
return command.rsplit("/", 1)[-1]
|
||||
return "mcp_server"
|
||||
|
||||
def _static_warnings(self, server: dict[str, Any]) -> list[dict[str, str]]:
|
||||
warnings: list[dict[str, str]] = []
|
||||
url = str(server.get("url") or "").strip()
|
||||
command = str(server.get("command") or "").strip()
|
||||
|
||||
if url:
|
||||
parsed = urlparse(url)
|
||||
if parsed.scheme not in {"http", "https"}:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "error",
|
||||
"title": "Unsupported URL scheme",
|
||||
"message": "Remote MCP URLs should use http or https.",
|
||||
}
|
||||
)
|
||||
elif parsed.scheme == "http" and parsed.hostname not in {"localhost", "127.0.0.1", "::1"}:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "warning",
|
||||
"title": "Unencrypted remote URL",
|
||||
"message": "Prefer HTTPS for remote MCP servers outside localhost.",
|
||||
}
|
||||
)
|
||||
if not parsed.netloc:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "error",
|
||||
"title": "Invalid remote URL",
|
||||
"message": "The remote MCP URL is missing a host.",
|
||||
}
|
||||
)
|
||||
elif command:
|
||||
if which(command) is None:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "warning",
|
||||
"title": "Command not found",
|
||||
"message": f"'{command}' is not currently available on PATH.",
|
||||
}
|
||||
)
|
||||
if command in {"bash", "sh", "zsh", "fish", "python", "python3", "node"}:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "warning",
|
||||
"title": "General-purpose interpreter",
|
||||
"message": "Review the command and arguments carefully before running this local MCP server.",
|
||||
}
|
||||
)
|
||||
else:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "error",
|
||||
"title": "Missing connection target",
|
||||
"message": "Provide either a remote URL or a local command.",
|
||||
}
|
||||
)
|
||||
|
||||
if isinstance(server.get("headers"), dict) and server["headers"]:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "info",
|
||||
"title": "Headers configured",
|
||||
"message": "Header values are redacted in scan output. Keep tokens in trusted settings only.",
|
||||
}
|
||||
)
|
||||
|
||||
if isinstance(server.get("env"), dict) and server["env"]:
|
||||
warnings.append(
|
||||
{
|
||||
"level": "info",
|
||||
"title": "Environment configured",
|
||||
"message": "Environment values are redacted in scan output. Avoid hardcoding secrets in MCP configs.",
|
||||
}
|
||||
)
|
||||
|
||||
return warnings
|
||||
|
||||
def _tool_warnings(self, tools: Any) -> list[dict[str, str]]:
|
||||
warnings: list[dict[str, str]] = []
|
||||
if not isinstance(tools, list):
|
||||
return warnings
|
||||
|
||||
for tool in tools:
|
||||
if not isinstance(tool, dict):
|
||||
continue
|
||||
haystack = f"{tool.get('name', '')}\n{tool.get('description', '')}".lower()
|
||||
if any(marker in haystack for marker in _PROMPT_INJECTION_MARKERS):
|
||||
warnings.append(
|
||||
{
|
||||
"level": "warning",
|
||||
"title": "Suspicious tool description",
|
||||
"message": f"Review tool '{tool.get('name', 'unknown')}' for prompt-injection style language.",
|
||||
}
|
||||
)
|
||||
return warnings
|
||||
|
||||
def _redact_server(self, server: dict[str, Any]) -> dict[str, Any]:
|
||||
redacted = dict(server)
|
||||
for key in ("headers", "env"):
|
||||
if isinstance(redacted.get(key), dict):
|
||||
redacted[key] = {name: "***" for name in redacted[key]}
|
||||
return redacted
|
||||
|
||||
def _risk_level(self, warnings: list[dict[str, str]]) -> str:
|
||||
levels = {warning.get("level", "info") for warning in warnings}
|
||||
if "error" in levels:
|
||||
return "error"
|
||||
if "warning" in levels:
|
||||
return "warning"
|
||||
return "ok"
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# mcp_server_scan.py DOX
|
||||
|
||||
## Purpose
|
||||
|
||||
- Own the `mcp_server_scan.py` API endpoint.
|
||||
- Provide static and optional runtime inspection for a single MCP server draft before it is added to global or project MCP config.
|
||||
- Keep this file-level DOX profile synchronized with `mcp_server_scan.py` because this directory is intentionally flat.
|
||||
|
||||
## Ownership
|
||||
|
||||
- `mcp_server_scan.py` owns the runtime implementation.
|
||||
- `mcp_server_scan.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
|
||||
- Classes:
|
||||
- `McpServerScan` (`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`.
|
||||
- The request accepts a `server` draft object, `inspect_runtime`, `allow_remote_network`, and `allow_local_execution`.
|
||||
- Remote runtime inspection may contact the configured MCP URL to list tools only when `allow_remote_network` is true and static checks have no errors.
|
||||
- Local stdio runtime inspection must not execute unless `allow_local_execution` is true.
|
||||
- Response data redacts `headers` and `env` values.
|
||||
- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
|
||||
- Imported dependency areas include: `asyncio`, `helpers.api`, `helpers.mcp_handler`, `shutil`, `typing`, `urllib.parse`.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- Static checks report invalid URLs, non-HTTPS remote URLs, missing local commands, interpreter-style local commands, headers/env presence, and obvious prompt-injection markers in inspected tool descriptions.
|
||||
- Static errors skip runtime inspection; remote network inspection and local command execution both require explicit trust flags.
|
||||
- Runtime inspection creates a temporary `MCPConfig` in a worker thread so stdio/remote tool listing does not call `asyncio.run()` inside the request event loop.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
|
||||
- Do not return secret values, raw environment values, or private files.
|
||||
- Keep scanner warnings explicit about local command execution risk.
|
||||
|
||||
## Verification
|
||||
|
||||
- Run endpoint-specific or MCP helper tests for changed behavior; smoke-test remote URL and local-command scan paths when practical.
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child DOX files.
|
||||
|
|
@ -5,27 +5,20 @@ from typing import Any
|
|||
|
||||
from helpers.mcp_handler import MCPConfig
|
||||
from helpers.settings import set_settings_delta
|
||||
from helpers import projects
|
||||
|
||||
|
||||
class McpServersApply(ApiHandler):
|
||||
async def process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response:
|
||||
mcp_servers = input["mcp_servers"]
|
||||
project_name = str(input.get("project_name", "") or "").strip()
|
||||
try:
|
||||
if project_name:
|
||||
projects.save_project_mcp_servers(project_name, mcp_servers)
|
||||
config = MCPConfig.refresh_project(project_name)
|
||||
else:
|
||||
# MCPConfig.update(mcp_servers) # done in settings automatically
|
||||
set_settings_delta({"mcp_servers": "[]"}) # to force reinitialization
|
||||
set_settings_delta({"mcp_servers": mcp_servers})
|
||||
# MCPConfig.update(mcp_servers) # done in settings automatically
|
||||
set_settings_delta({"mcp_servers": "[]"}) # to force reinitialization
|
||||
set_settings_delta({"mcp_servers": mcp_servers})
|
||||
|
||||
time.sleep(1) # wait at least a second
|
||||
# MCPConfig.wait_for_lock() # wait until config lock is released
|
||||
config = MCPConfig.get_instance()
|
||||
status = config.get_servers_status()
|
||||
return {"success": True, "status": status, "mcp_servers": mcp_servers, "project_name": project_name}
|
||||
time.sleep(1) # wait at least a second
|
||||
# MCPConfig.wait_for_lock() # wait until config lock is released
|
||||
status = MCPConfig.get_instance().get_servers_status()
|
||||
return {"success": True, "status": status}
|
||||
|
||||
except Exception as e:
|
||||
return {"success": False, "error": str(e)}
|
||||
|
|
|
|||
|
|
@ -1,47 +0,0 @@
|
|||
# mcp_servers_apply.py DOX
|
||||
|
||||
## Purpose
|
||||
|
||||
- Own the `mcp_servers_apply.py` API endpoint.
|
||||
- This module handles MCP servers apply requests for global or project scope.
|
||||
- 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`.
|
||||
- The request accepts `config` and optional `project_name`.
|
||||
- Without `project_name`, the endpoint persists global `mcp_servers_config` through settings and refreshes the global `MCPConfig`.
|
||||
- With `project_name`, the endpoint saves `.a0proj/mcp_servers.json` through `helpers.projects.save_project_mcp_servers(...)` and refreshes that project's merged MCP config.
|
||||
- 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: filesystem writes, settings/state persistence.
|
||||
- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `helpers.projects`, `helpers.settings`, `time`, `typing`.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- Important called helpers/classes observed in the source: `set_settings_delta`, `projects.save_project_mcp_servers`, `MCPConfig.refresh_project`, `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.
|
||||
|
|
@ -9,9 +9,7 @@ class McpServersStatuss(ApiHandler):
|
|||
async def process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response:
|
||||
|
||||
# try:
|
||||
project_name = (input or {}).get("project_name") if isinstance(input, dict) else None
|
||||
config = MCPConfig.get_project_instance(project_name) if project_name else MCPConfig.get_instance()
|
||||
status = config.get_servers_status()
|
||||
status = MCPConfig.get_instance().get_servers_status()
|
||||
return {"success": True, "status": status}
|
||||
# except Exception as e:
|
||||
# return {"success": False, "error": str(e)}
|
||||
|
|
|
|||
|
|
@ -1,45 +0,0 @@
|
|||
# mcp_servers_status.py DOX
|
||||
|
||||
## Purpose
|
||||
|
||||
- Own the `mcp_servers_status.py` API endpoint.
|
||||
- This module handles MCP servers status requests for global or project scope.
|
||||
- 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`.
|
||||
- The request accepts optional `project_name`; when present, status resolves through the merged project-scoped MCP configuration.
|
||||
- `tool_count` reports enabled MCP tools only; tools disabled by a server `disabled_tools` list stay hidden from agent-facing status counts.
|
||||
- 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_project_instance`, `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.
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,46 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,46 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
# 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.
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue