/a0/                              # Framework root
├── agent.py                      # Core Agent + AgentContext + AgentConfig classes
├── initialize.py                 # Agent initialization logic
├── models.py                     # Model definitions
├── run_ui.py                     # Web UI entry point
│
├── tools/                        # Core tools (search, response, browser, etc.)
├── extensions/
│   ├── python/                   # Python lifecycle extensions
│   │   ├── <hook_point>/         # e.g., agent_init/, system_prompt/, etc.
│   │   │   └── _NN_name.py       # Numbered extension files
│   │   └── _functions/           # Implicit @extensible decorator extensions
│   └── webui/                    # JavaScript WebUI extensions
│       └── <hook_point>/         # e.g., json_api_call_before/
│           └── name.js
├── api/                          # Flask API endpoint handlers
├── helpers/                      # Framework utilities and base classes
│   ├── tool.py                   # Tool + Response base classes
│   ├── extension.py              # Extension base class + @extensible decorator
│   ├── api.py                    # ApiHandler base class
│   ├── files.py                  # File operations + prompt reading
│   ├── plugins.py                # Plugin system manager
│   ├── print_style.py            # Console output formatting
│   └── ...                       # Many more utility modules
│
├── prompts/                      # Core prompt fragments (system, tools, framework)
├── agents/                       # Agent profiles (subordinate specializations)
│   ├── default/                  # Base profile (inherited by others)
│   ├── agent0/                   # Main user-facing agent
│   ├── developer/                # Developer subordinate
│   ├── hacker/                   # Security subordinate
│   ├── researcher/               # Research subordinate
│   └── _example/                 # Example profile with tool + extension samples
│
├── plugins/                      # Core plugins (tools, extensions, prompts)
│   ├── _code_execution/          # Terminal/Python/Node.js execution
│   ├── _memory/                  # Persistent memory system
│   ├── _text_editor/             # File read/write/patch
│   ├── _model_config/            # LLM model selection
│   ├── _infection_check/         # Prompt injection safety
│   └── ...                       # More core plugins
│
├── skills/                       # Core skills (SKILL.md bundles)
├── knowledge/                    # Knowledge base files
├── webui/                        # Web UI frontend
├── docs/                         # Documentation
│
└── usr/                          # User-space (survives updates)
    ├── agents/                   # User-created agent profiles
    ├── plugins/                  # User-installed plugins
    ├── skills/                   # User-created skills
    ├── knowledge/                # User knowledge base files
    ├── extensions/               # Standalone user extensions (created on demand; prefer plugins instead)
    ├── projects/                 # Project workspaces (created on demand when user adds projects via UI)
    └── workdir/                  # Default working directory

from helpers.tool import Tool, Response

# /a0/helpers/tool.py

@dataclass
class Response:
    message: str              # Text response shown to agent
    break_loop: bool          # True = stop agent message loop
    additional: dict[str, Any] | None = None  # Extra metadata for history

class Tool:
    def __init__(self, agent: Agent, name: str, method: str | None,
                 args: dict[str,str], message: str,
                 loop_data: LoopData | None, **kwargs) -> None:
        self.agent = agent
        self.name = name
        self.method = method   # For tools with sub-methods (e.g., "skills_tool:load")
        self.args = args
        self.loop_data = loop_data
        self.message = message

    async def execute(self, **kwargs) -> Response:
        pass  # Override this

    # Lifecycle hooks (called automatically):
    async def before_execution(self, **kwargs): ...
    async def after_execution(self, response: Response, **kwargs): ...

# my_tool.py
from helpers.tool import Tool, Response

class MyTool(Tool):
    async def execute(self, **kwargs):
        # Get arguments — kwargs contains the tool_args from the agent's JSON
        input_data = kwargs.get("input", "")

        # Do something
        result = f"Processed: {input_data}"

        # Return response
        return Response(
            message=result,        # Shown to the agent
            break_loop=False,      # Don't stop the agent loop
        )

from helpers.extension import Extension

class Extension:
    def __init__(self, agent: "Agent | None", **kwargs):
        self.agent: "Agent | None" = agent
        self.kwargs = kwargs

    def execute(self, **kwargs) -> None | Awaitable[None]:
        pass  # Override this — kwargs are hook-point-specific

extensions/python/<hook_point>/_NN_name.py

_functions/<module_path>/<qualname_path>/start
_functions/<module_path>/<qualname_path>/end

# extensions/python/agent_init/_15_my_extension.py
from helpers.extension import Extension

class MyExtension(Extension):
    async def execute(self, **kwargs):
        # Access the agent
        agent = self.agent
        context = agent.context

        # Extension logic — kwargs content depends on the hook point
        agent.agent_name = "CustomAgent" + str(agent.number)

_10_first.py      # Runs first
_20_second.py     # Runs second
_50_third.py      # Runs third

from helpers.api import ApiHandler
from flask import Request, Response

class ApiHandler:
    def __init__(self, app: Flask, thread_lock: ThreadLockType):
        self.app = app
        self.thread_lock = thread_lock

    # Override these class methods to configure behavior:
    @classmethod
    def requires_loopback(cls) -> bool: return False   # Restrict to localhost
    @classmethod
    def requires_api_key(cls) -> bool: return False     # Require API key
    @classmethod
    def requires_auth(cls) -> bool: return True         # Require auth session
    @classmethod
    def get_methods(cls) -> list[str]: return ["POST"]   # HTTP methods
    @classmethod
    def requires_csrf(cls) -> bool: return cls.requires_auth()  # CSRF protection

    # Implement this:
    async def process(self, input: dict, request: Request) -> dict | Response:
        pass

    # Utility: get or create an agent context
    def use_context(self, ctxid: str, create_if_not_exists: bool = True) -> AgentContext:
        ...

# api/my_endpoint.py
from helpers.api import ApiHandler
from flask import Request, Response
from agent import AgentContext

class MyEndpoint(ApiHandler):
    @classmethod
    def get_methods(cls) -> list[str]:
        return ["GET", "POST"]

    async def process(self, input: dict, request: Request) -> dict:
        param = input.get("param", "default")

        # Get or create agent context
        ctxid = input.get("context", "")
        context = self.use_context(ctxid)

        return {
            "result": f"processed {param}",
            "context": context.id,
        }

agents/<profile-name>/
+-- agent.yaml                    # Required: profile metadata
+-- prompts/                      # Optional: prompt overrides
|   +-- agent.system.main.role.md         # Role definition (most common override)
|   +-- agent.system.main.communication.md # Communication style
|   +-- agent.system.tool.<name>.md       # Tool-specific prompts
+-- tools/                        # Optional: profile-specific tools
|   +-- my_tool.py
+-- extensions/                   # Optional: profile-specific extensions
    +-- <hook_point>/
        +-- _NN_extension.py

title: Developer
description: Agent specialized in complex software development.
context: Use this agent for software development tasks, including writing code,
  debugging, refactoring, and architectural design.

# /a0/usr/agents/data-analyst/agent.yaml
title: Data Analyst
description: Agent specialized in data analysis, visualization, and statistical modeling.
context: Use this agent for data analysis tasks, creating visualizations, statistical
  analysis, and working with datasets in Python.

<!-- /a0/usr/agents/data-analyst/prompts/agent.system.main.role.md -->

## Your role
You are a specialized data analysis agent.
Your expertise includes:
- Python data analysis (pandas, numpy, scipy)
- Data visualization (matplotlib, seaborn, plotly)
- Statistical modeling and hypothesis testing
- SQL queries and database analysis
- Data cleaning and preprocessing

## Process
1. Understand the data and the question
2. Choose appropriate tools and methods
3. Execute analysis with code_execution_tool
4. Visualize results when applicable
5. Provide clear interpretation of findings

agent.system.main.md            # Main system prompt (entry point)
agent.system.main.role.md       # Role definition
agent.system.main.communication.md  # Communication style
agent.system.tool.<name>.md     # Tool usage instructions
agent.system.tools.md           # Tools overview
agent.system.projects.main.md   # Project system
agent.system.secrets.md         # Secret handling
agent.system.skills.md          # Skills listing
agent.system.datetime.md        # Current date/time
agent.context.extras.md         # Context extras
fw.*.md                         # Framework messages (errors, hints, etc.)

# From within an Agent method:
content = self.read_prompt("fw.some_message.md", variable1="value1")

# From helpers:
from helpers.files import read_prompt_file
content = read_prompt_file("template.md", _directories=[...], var="value")

{"tool_name": "skills_tool:list", "tool_args": {}}
{"tool_name": "skills_tool:load", "tool_args": {"skill_name": "my-skill"}}

/a0/usr/projects/<project-name>/
+-- .a0proj/
|   +-- project.json          # Project configuration
|   +-- agents.json           # Per-project agent overrides
|   +-- variables.env         # Non-sensitive variables
|   +-- secrets.env           # Encrypted secrets
|   +-- memory/               # Project-specific memory
|       +-- index.faiss
|       +-- index.pkl
|       +-- embedding.json
+-- <project-files>/          # Your project files (working directory)

{
    "title": "My Project",
    "description": "Project description",
    "instructions": "Markdown instructions for the agent when this project is active",
    "color": "#3a86ff",
    "git_url": "",
    "memory": "own",
    "file_structure": {
        "enabled": true,
        "max_depth": 5,
        "max_files": 20,
        "max_folders": 20,
        "max_lines": 250,
        "gitignore": ".a0proj/\nvenv/\n**/__pycache__/\n**/node_modules/\n**/.git/\n"
    }
}

# Shared across all agents in a conversation
context = self.agent.context
data = context.data  # dict-like shared state

# Store data
data["my_key"] = my_value

# Retrieve data
value = data.get("my_key", default)

from helpers import files

# File operations
content = files.read_file("path/to/file")
files.write_file("path/to/file", content)
exists = files.exists("path/to/file")

# Read and render a prompt file
content = files.read_prompt_file("template.md", _directories=[...], var="value")

from helpers.print_style import PrintStyle

PrintStyle.hint("Informational message")
PrintStyle.warning("Warning message")
PrintStyle.error("Error message")
PrintStyle(font_color="#85C1E9").print("Custom styled output")

from helpers.tool import Response

try:
    result = await risky_operation()
except Exception as e:
    PrintStyle.error(f"Operation failed: {e}")
    return Response(message=f"Error: {e}", break_loop=False)