BIG PYTHON REFACTOR

Python scripts moved out of python/ folder to root to be unified with plugins

+ frontend extension around api calls

AGENTS.md

@@ -105,8 +105,8 @@ Key Files:
 ## Development Patterns & Conventions
 
 ### Backend (Python)
-- Context Access: Use from agent import AgentContext, AgentContextType (not python.helpers.context).
+- Context Access: Use from agent import AgentContext, AgentContextType (not helpers.context).
-- Communication: Use mq from python.helpers.messages to log proactive UI messages:
+- 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 python/helpers/api.py.
 - Extensions: Use the extension framework in python/helpers/extension.py for lifecycle hooks.
@@ -164,7 +164,7 @@ Key Files:
 
 ### API Handler (Good)
 ```python
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
 class MyHandler(ApiHandler):
     async def process(self, input: dict, request: Request) -> dict | Response:
@@ -186,7 +186,7 @@ export const store = createStore("myStore", {
 
 ### Tool Definition (Good)
 ```python
-from python.helpers.tool import Tool, ToolResult
+from helpers.tool import Tool, ToolResult
 
 class MyTool(Tool):
     async def execute(self, arg1: str):

agent.py

@@ -7,7 +7,7 @@ from typing import Any, Awaitable, Coroutine, Dict, Literal
 from enum import Enum
 import models
 
-from python.helpers import (
+from helpers import (
     extract_tools,
     files,
     errors,
@@ -17,22 +17,21 @@ from python.helpers import (
     dirty_json,
     subagents,
 )
-from python.helpers import extension
+from helpers import extension
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
 
 from langchain_core.prompts import (
     ChatPromptTemplate,
 )
 from langchain_core.messages import SystemMessage, BaseMessage
 
-import python.helpers.log as Log
+import helpers.log as Log
-from python.helpers.dirty_json import DirtyJson
+from helpers.dirty_json import DirtyJson
-from python.helpers.defer import DeferredTask
+from helpers.defer import DeferredTask
 from typing import Callable
-from python.helpers.localization import Localization
+from helpers.localization import Localization
-from python.helpers.extension import call_extensions, extensible
+from helpers.extension import call_extensions, extensible
-from python.helpers.errors import RepairableException, InterventionException, HandledException
+from helpers.errors import RepairableException, InterventionException, HandledException
-
 
 class AgentContextType(Enum):
     USER = "user"
@@ -147,7 +146,7 @@ class AgentContext:
     @classmethod
     def get_notification_manager(cls):
         if cls._notification_manager is None:
-            from python.helpers.notification import NotificationManager  # type: ignore
+            from helpers.notification import NotificationManager  # type: ignore
 
             cls._notification_manager = NotificationManager()
         return cls._notification_manager
@@ -177,7 +176,7 @@ class AgentContext:
         # recursive is not used now, prepared for context hierarchy
         self.output_data[key] = value
 
-    @extensible
+    # @extensible
     def output(self):
         return {
             "id": self.id,
@@ -859,7 +858,7 @@ class Agent:
 
             # Try getting tool from MCP first
             try:
-                import python.helpers.mcp_handler as mcp_helper
+                import helpers.mcp_handler as mcp_helper
 
                 mcp_tool_candidate = mcp_helper.MCPConfig.get_instance().get_tool(
                     self, tool_name
@@ -969,13 +968,13 @@ class Agent:
         loop_data: LoopData | None,
         **kwargs,
     ):
-        from python.tools.unknown import Unknown
+        from tools.unknown import Unknown
-        from python.helpers.tool import Tool
+        from helpers.tool import Tool
 
         classes = []
 
         # search for tools in agent's folder hierarchy
-        paths = subagents.get_paths(self, "tools", name + ".py", default_root="python")
+        paths = subagents.get_paths(self, "tools", name + ".py")
 
         for path in paths:
             try:

agents/_example/extensions/agent_init/_10_example_extension.py

@@ -1,4 +1,4 @@
-from python.helpers.extension import Extension
+from helpers.extension import Extension
 
 # this is an example extension that renames the current agent when initialized
 # see /extensions folder for all available extension points

agents/_example/tools/example_tool.py

@@ -1,4 +1,4 @@
-from python.helpers.tool import Tool, Response
+from helpers.tool import Tool, Response
 
 # this is an example tool class
 # don't forget to include instructions in the system prompt by creating 

agents/_example/tools/response.py

@@ -1,4 +1,4 @@
-from python.helpers.tool import Tool, Response
+from helpers.tool import Tool, Response
 
 # example of a tool redefinition
 # the original response tool is in python/tools/response.py

api/agents.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers import subagents
+from helpers import subagents
 
 
 class Agents(ApiHandler):

api/api_files_get.py

@@ -1,8 +1,8 @@
 import base64
 import os
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import files
+from helpers import files
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
 import json
 
 

api/api_log_get.py

@@ -1,5 +1,5 @@
 from agent import AgentContext
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
 
 class ApiLogGet(ApiHandler):

api/api_message.py

@@ -2,11 +2,11 @@ import base64
 import os
 from datetime import datetime, timedelta
 from agent import AgentContext, UserMessage, AgentContextType
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import files, projects
+from helpers import files, projects
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
-from python.helpers.projects import activate_project
+from helpers.projects import activate_project
-from python.helpers.security import safe_filename
+from helpers.security import safe_filename
 from initialize import initialize_agent
 import threading
 

api/api_reset_chat.py

@@ -1,7 +1,7 @@
 from agent import AgentContext
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
-from python.helpers import persist_chat
+from helpers import persist_chat
 import json
 
 

api/api_terminate_chat.py

@@ -1,7 +1,7 @@
 from agent import AgentContext
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers.persist_chat import remove_chat
+from helpers.persist_chat import remove_chat
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
 import json
 
 

api/backup_create.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response, send_file
+from helpers.api import ApiHandler, Request, Response, send_file
-from python.helpers.backup import BackupService
+from helpers.backup import BackupService
-from python.helpers.persist_chat import save_tmp_chats
+from helpers.persist_chat import save_tmp_chats
 
 
 class BackupCreate(ApiHandler):

api/backup_get_defaults.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers.backup import BackupService
+from helpers.backup import BackupService
 
 
 class BackupGetDefaults(ApiHandler):

api/backup_inspect.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers.backup import BackupService
+from helpers.backup import BackupService
 from werkzeug.datastructures import FileStorage
 
 

api/backup_preview_grouped.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers.backup import BackupService
+from helpers.backup import BackupService
 from typing import Dict, Any
 
 

api/backup_restore.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 from werkzeug.datastructures import FileStorage
-from python.helpers.backup import BackupService
+from helpers.backup import BackupService
-from python.helpers.persist_chat import load_tmp_chats
+from helpers.persist_chat import load_tmp_chats
 import json
 
 

api/backup_restore_preview.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 from werkzeug.datastructures import FileStorage
-from python.helpers.backup import BackupService
+from helpers.backup import BackupService
 import json
 
 

api/backup_test.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers.backup import BackupService
+from helpers.backup import BackupService
 
 
 class BackupTest(ApiHandler):

api/banners.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers.extension import call_extensions
+from helpers.extension import call_extensions
 
 
 class GetBanners(ApiHandler):

api/cache_reset.py

@@ -0,0 +1,35 @@
+from helpers.api import ApiHandler, Request, Response
+from helpers import cache
+
+
+class CacheReset(ApiHandler):
+    @classmethod
+    def requires_auth(cls) -> bool:
+        return False
+
+    @classmethod
+    def requires_csrf(cls) -> bool:
+        return False
+
+    @classmethod
+    def requires_api_key(cls) -> bool:
+        return False
+
+    @classmethod
+    def requires_loopback(cls) -> bool:
+        return True
+
+    @classmethod
+    def get_methods(cls) -> list[str]:
+        return ["GET", "POST"]
+
+    async def process(self, input: dict, request: Request) -> dict | Response:
+        areas = input.get("areas", [])
+
+        if not areas:
+            cache.clear_all()
+        else:
+            for area in areas:
+                cache.clear(area)
+
+        return {"ok": True}

api/chat_create.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
 
 
-from python.helpers import settings, projects, guids
+from helpers import settings, projects, guids
 from agent import AgentContext
 
 
@@ -26,7 +26,7 @@ class CreateChat(ApiHandler):
                 new_context.set_output_data(projects.CONTEXT_DATA_KEY_PROJECT, current_data_2)
 
         # New context should appear in other tabs' chat lists via state_push.
-        from python.helpers.state_monitor_integration import mark_dirty_all
+        from helpers.state_monitor_integration import mark_dirty_all
         mark_dirty_all(reason="api.chat_create.CreateChat")
 
         return {

api/chat_export.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
 
-from python.helpers import persist_chat
+from helpers import persist_chat
 
 class ExportChat(ApiHandler):
     async def process(self, input: Input, request: Request) -> Output:

api/chat_files_path_get.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import files, projects, settings
+from helpers import files, projects, settings
 
 
 class GetChatFilesPath(ApiHandler):

api/chat_load.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
 
 
-from python.helpers import persist_chat
+from helpers import persist_chat
 
 class LoadChats(ApiHandler):
     async def process(self, input: Input, request: Request) -> Output:

api/chat_remove.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
 from agent import AgentContext
-from python.helpers import persist_chat
+from helpers import persist_chat
-from python.helpers.task_scheduler import TaskScheduler
+from helpers.task_scheduler import TaskScheduler
 
 
 class RemoveChat(ApiHandler):
@@ -26,7 +26,7 @@ class RemoveChat(ApiHandler):
             await scheduler.remove_task_by_uuid(task.uuid)
 
         # Context removal affects global chat/task lists in all tabs.
-        from python.helpers.state_monitor_integration import mark_dirty_all
+        from helpers.state_monitor_integration import mark_dirty_all
         mark_dirty_all(reason="api.chat_remove.RemoveChat")
 
         return {

api/chat_reset.py

@@ -1,8 +1,8 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
 
 
-from python.helpers import persist_chat
+from helpers import persist_chat
-from python.helpers.task_scheduler import TaskScheduler
+from helpers.task_scheduler import TaskScheduler
 
 
 class Reset(ApiHandler):
@@ -19,7 +19,7 @@ class Reset(ApiHandler):
         persist_chat.remove_msg_files(ctxid)
 
         # Reset updates context metadata (log guid/version) and must refresh other tabs' lists.
-        from python.helpers.state_monitor_integration import mark_dirty_all
+        from helpers.state_monitor_integration import mark_dirty_all
         mark_dirty_all(reason="api.chat_reset.Reset")
 
         return {

api/csrf_token.py

@@ -1,6 +1,6 @@
 import secrets
 from urllib.parse import urlparse
-from python.helpers.api import (
+from helpers.api import (
     ApiHandler,
     Input,
     Output,
@@ -8,7 +8,7 @@ from python.helpers.api import (
     Response,
     session,
 )
-from python.helpers import runtime, dotenv, login
+from helpers import runtime, dotenv, login
 import fnmatch
 
 ALLOWED_ORIGINS_KEY = "ALLOWED_ORIGINS"
@@ -104,7 +104,7 @@ class GetCsrfToken(ApiHandler):
 
         # always allow tunnel url if running
         try:
-            from python.api.tunnel_proxy import process as tunnel_api_process
+            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["success"]:

api/ctx_window_get.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
 
-from python.helpers import tokens
+from helpers import tokens
 
 
 class GetCtxWindow(ApiHandler):

api/delete_work_dir_file.py

@@ -1,9 +1,9 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
 
 
-from python.helpers.file_browser import FileBrowser
+from helpers.file_browser import FileBrowser
-from python.helpers import files, runtime
+from helpers import files, runtime
-from python.api import get_work_dir_files
+from api import get_work_dir_files
 
 
 class DeleteWorkDirFile(ApiHandler):

api/download_work_dir_file.py

@@ -4,9 +4,9 @@ import mimetypes
 import os
 
 from flask import Response
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers import files, runtime
+from helpers import files, runtime
-from python.api import file_info
+from api import file_info
 from urllib.parse import quote
 
 

api/edit_work_dir_file.py

@@ -1,9 +1,9 @@
 import mimetypes
 import os
 
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers.file_browser import FileBrowser
+from helpers.file_browser import FileBrowser
-from python.helpers import runtime, files
+from helpers import runtime, files
 
 MAX_EDIT_FILE_SIZE = 1024 * 1024
 BINARY_SAMPLE_SIZE = 10 * 1024

api/file_info.py

@@ -1,6 +1,6 @@
 import os
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
-from python.helpers import files, runtime
+from helpers import files, runtime
 from typing import TypedDict
 
 class FileInfoApi(ApiHandler):

api/get_work_dir_files.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers.file_browser import FileBrowser
+from helpers.file_browser import FileBrowser
-from python.helpers import runtime, files
+from helpers import runtime, files
 
 class GetWorkDirFiles(ApiHandler):
 

api/health.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import errors, git
+from helpers import errors, git
 
 class HealthCheck(ApiHandler):
 

api/history_get.py

@@ -1,4 +1,4 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
 
 class GetHistory(ApiHandler):

api/image_get.py

@@ -1,7 +1,7 @@
 import base64
 import os
-from python.helpers.api import ApiHandler, Request, Response, send_file
+from helpers.api import ApiHandler, Request, Response, send_file
-from python.helpers import files, runtime
+from helpers import files, runtime
 import io
 from mimetypes import guess_type
 

api/load_webui_extensions.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import plugins
+from helpers import extension
 
 
 class LoadWebuiExtensions(ApiHandler):
@@ -15,6 +15,6 @@ class LoadWebuiExtensions(ApiHandler):
         if not extension_point:
             return Response(status=400, response="Missing extension_point")
         
-        exts = plugins.get_webui_extensions(agent=None, extension_point=extension_point, filters=filters)
+        exts = extension.get_webui_extensions(agent=None, extension_point=extension_point, filters=filters)
         
         return {"extensions": exts or []}

api/logout.py

@@ -1,4 +1,4 @@
-from python.helpers.api import ApiHandler, Request, session
+from helpers.api import ApiHandler, Request, session
 
 
 class ApiLogout(ApiHandler):

api/mcp_server_get_detail.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 from typing import Any
 
-from python.helpers.mcp_handler import MCPConfig
+from helpers.mcp_handler import MCPConfig
 
 
 class McpServerGetDetail(ApiHandler):

api/mcp_server_get_log.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 from typing import Any
 
-from python.helpers.mcp_handler import MCPConfig
+from helpers.mcp_handler import MCPConfig
 
 
 class McpServerGetLog(ApiHandler):

api/mcp_servers_apply.py

@@ -1,10 +1,10 @@
 import time
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
 from typing import Any
 
-from python.helpers.mcp_handler import MCPConfig
+from helpers.mcp_handler import MCPConfig
-from python.helpers.settings import set_settings_delta
+from helpers.settings import set_settings_delta
 
 
 class McpServersApply(ApiHandler):

api/mcp_servers_status.py

@@ -1,8 +1,8 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
 from typing import Any
 
-from python.helpers.mcp_handler import MCPConfig
+from helpers.mcp_handler import MCPConfig
 
 
 class McpServersStatuss(ApiHandler):

api/message.py

@@ -1,10 +1,10 @@
 from agent import AgentContext, UserMessage
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
-from python.helpers import files, extension, message_queue as mq
+from helpers import files, extension, message_queue as mq
 import os
-from python.helpers.security import safe_filename
+from helpers.security import safe_filename
-from python.helpers.defer import DeferredTask
+from helpers.defer import DeferredTask
 
 
 class Message(ApiHandler):

api/message_async.py

@@ -1,6 +1,6 @@
 from agent import AgentContext
-from python.helpers.defer import DeferredTask
+from helpers.defer import DeferredTask
-from python.api.message import Message
+from api.message import Message
 
 
 class MessageAsync(Message):

api/message_queue_add.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import message_queue as mq
+from helpers import message_queue as mq
 from agent import AgentContext
-from python.helpers.state_monitor_integration import mark_dirty_for_context
+from helpers.state_monitor_integration import mark_dirty_for_context
 
 
 class MessageQueueAdd(ApiHandler):

api/message_queue_remove.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import message_queue as mq
+from helpers import message_queue as mq
 from agent import AgentContext
-from python.helpers.state_monitor_integration import mark_dirty_for_context
+from helpers.state_monitor_integration import mark_dirty_for_context
 
 class MessageQueueRemove(ApiHandler):
     """Remove message(s) from queue."""

api/message_queue_send.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import message_queue as mq
+from helpers import message_queue as mq
 from agent import AgentContext
-from python.helpers.state_monitor_integration import mark_dirty_for_context
+from helpers.state_monitor_integration import mark_dirty_for_context
 
 class MessageQueueSend(ApiHandler):
     """Send queued message(s) immediately."""

api/notification_create.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler
+from helpers.api import ApiHandler
 from flask import Request, Response
-from python.helpers.notification import NotificationManager, NotificationPriority, NotificationType
+from helpers.notification import NotificationManager, NotificationPriority, NotificationType
 
 
 class NotificationCreate(ApiHandler):

api/notifications_clear.py

@@ -1,4 +1,4 @@
-from python.helpers.api import ApiHandler
+from helpers.api import ApiHandler
 from flask import Request, Response
 from agent import AgentContext
 

api/notifications_history.py

@@ -1,4 +1,4 @@
-from python.helpers.api import ApiHandler
+from helpers.api import ApiHandler
 from flask import Request, Response
 from agent import AgentContext
 

api/notifications_mark_read.py

@@ -1,4 +1,4 @@
-from python.helpers.api import ApiHandler
+from helpers.api import ApiHandler
 from flask import Request, Response
 from agent import AgentContext
 

api/nudge.py

@@ -1,4 +1,4 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
 class Nudge(ApiHandler):
     async def process(self, input: dict, request: Request) -> dict | Response:

api/pause.py

@@ -1,4 +1,4 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
 
 class Pause(ApiHandler):

api/plugins.py

@@ -4,8 +4,8 @@ import subprocess
 import sys
 from datetime import datetime, timezone
 
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import plugins, files
+from helpers import plugins, files
 
 
 class Plugins(ApiHandler):

api/plugins_list.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers import plugins
+from helpers import plugins
 
 class PluginsList(ApiHandler):
     async def process(self, input: Input, request: Request) -> Output:

api/poll.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
-from python.helpers.state_snapshot import build_snapshot
+from helpers.state_snapshot import build_snapshot
 
 
 class Poll(ApiHandler):

api/projects.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
-from python.helpers import projects
+from helpers import projects
-from python.helpers.notification import NotificationManager, NotificationType, NotificationPriority
+from helpers.notification import NotificationManager, NotificationType, NotificationPriority
 
 
 class Projects(ApiHandler):

api/rename_work_dir_file.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers.file_browser import FileBrowser
+from helpers.file_browser import FileBrowser
-from python.helpers import runtime
+from helpers import runtime
-from python.api import get_work_dir_files
+from api import get_work_dir_files
 
 
 class RenameWorkDirFile(ApiHandler):

api/restart.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
-from python.helpers import process
+from helpers import process
 
 class Restart(ApiHandler):
     async def process(self, input: dict, request: Request) -> dict | Response:

api/rfc.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
-from python.helpers import runtime
+from helpers import runtime
 
 class RFC(ApiHandler):
 

api/scheduler_task_create.py

@@ -1,11 +1,11 @@
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers.task_scheduler import (
+from helpers.task_scheduler import (
     TaskScheduler, ScheduledTask, AdHocTask, PlannedTask, TaskSchedule,
     serialize_task, parse_task_schedule, parse_task_plan, TaskType
 )
-from python.helpers.projects import load_basic_project_data
+from helpers.projects import load_basic_project_data
-from python.helpers.localization import Localization
+from helpers.localization import Localization
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
 import random
 
 

api/scheduler_task_delete.py

@@ -1,8 +1,8 @@
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers.task_scheduler import TaskScheduler, TaskState
+from helpers.task_scheduler import TaskScheduler, TaskState
-from python.helpers.localization import Localization
+from helpers.localization import Localization
 from agent import AgentContext
-from python.helpers import persist_chat
+from helpers import persist_chat
 
 
 class SchedulerTaskDelete(ApiHandler):

api/scheduler_task_run.py

@@ -1,7 +1,7 @@
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers.task_scheduler import TaskScheduler, TaskState
+from helpers.task_scheduler import TaskScheduler, TaskState
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
-from python.helpers.localization import Localization
+from helpers.localization import Localization
 
 
 class SchedulerTaskRun(ApiHandler):

api/scheduler_task_update.py

@@ -1,9 +1,9 @@
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers.task_scheduler import (
+from helpers.task_scheduler import (
     TaskScheduler, ScheduledTask, AdHocTask, PlannedTask, TaskState,
     serialize_task, parse_task_schedule, parse_task_plan
 )
-from python.helpers.localization import Localization
+from helpers.localization import Localization
 
 
 class SchedulerTaskUpdate(ApiHandler):

api/scheduler_tasks_list.py

@@ -1,8 +1,8 @@
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers.task_scheduler import TaskScheduler
+from helpers.task_scheduler import TaskScheduler
 import traceback
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
-from python.helpers.localization import Localization
+from helpers.localization import Localization
 
 
 class SchedulerTasksList(ApiHandler):

api/scheduler_tick.py

@@ -1,9 +1,9 @@
 from datetime import datetime
 
-from python.helpers.api import ApiHandler, Input, Output, Request
+from helpers.api import ApiHandler, Input, Output, Request
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
-from python.helpers.task_scheduler import TaskScheduler
+from helpers.task_scheduler import TaskScheduler
-from python.helpers.localization import Localization
+from helpers.localization import Localization
 
 
 class SchedulerTick(ApiHandler):

api/settings_get.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
-from python.helpers import settings
+from helpers import settings
 
 class GetSettings(ApiHandler):
     async def process(self, input: dict, request: Request) -> dict | Response:

api/settings_set.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
-from python.helpers import settings
+from helpers import settings
 
 from typing import Any
 

api/settings_workdir_file_structure.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
-from python.helpers import file_tree, files
+from helpers import file_tree, files
 
 
 class SettingsWorkdirFileStructure(ApiHandler):

api/skills.py

@@ -1,5 +1,5 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
-from python.helpers import runtime, skills, projects, files
+from helpers import runtime, skills, projects, files
 
 
 class Skills(ApiHandler):

api/skills_import.py

@@ -5,9 +5,9 @@ import time
 import uuid
 from pathlib import Path
 
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import files
+from helpers import files
-from python.helpers.skills_import import import_skills
+from helpers.skills_import import import_skills
 from werkzeug.datastructures import FileStorage
 from werkzeug.utils import secure_filename
 

api/skills_import_preview.py

@@ -5,9 +5,9 @@ import time
 import uuid
 from pathlib import Path
 
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import files
+from helpers import files
-from python.helpers.skills_import import import_skills
+from helpers.skills_import import import_skills
 from werkzeug.datastructures import FileStorage
 from werkzeug.utils import secure_filename
 

api/subagents.py

@@ -1,9 +1,9 @@
-from python.helpers.api import ApiHandler, Input, Output, Request, Response
+from helpers.api import ApiHandler, Input, Output, Request, Response
-from python.helpers import subagents
+from helpers import subagents
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from python.helpers import projects
+    from helpers import projects
 
 class Subagents(ApiHandler):
     async def process(self, input: Input, request: Request) -> Output:

api/synthesize.py

@@ -1,8 +1,8 @@
 # api/synthesize.py
 
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
-from python.helpers import runtime, settings, kokoro_tts
+from helpers import runtime, settings, kokoro_tts
 
 class Synthesize(ApiHandler):
     async def process(self, input: dict, request: Request) -> dict | Response:

api/transcribe.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
 
-from python.helpers import runtime, settings, whisper
+from helpers import runtime, settings, whisper
 
 class Transcribe(ApiHandler):
     async def process(self, input: dict, request: Request) -> dict | Response:

api/tunnel.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import runtime
+from helpers import runtime
-from python.helpers.tunnel_manager import TunnelManager
+from helpers.tunnel_manager import TunnelManager
 
 class Tunnel(ApiHandler):
     async def process(self, input: dict, request: Request) -> dict | Response:

api/tunnel_proxy.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import dotenv, runtime
+from helpers import dotenv, runtime
-from python.helpers.tunnel_manager import TunnelManager
+from helpers.tunnel_manager import TunnelManager
 import requests
 
 
@@ -34,5 +34,5 @@ async def process(input: dict) -> dict | Response:
             return {"error": str(e)}
     else:
         # forward to API handler directly
-        from python.api.tunnel import process as local_process
+        from api.tunnel import process as local_process
         return await local_process(input)

api/upload.py

@@ -1,6 +1,6 @@
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers import files
+from helpers import files
-from python.helpers.security import safe_filename
+from helpers.security import safe_filename
 
 
 class UploadFile(ApiHandler):

api/upload_work_dir_files.py

@@ -1,9 +1,9 @@
 import base64
 from werkzeug.datastructures import FileStorage
-from python.helpers.api import ApiHandler, Request, Response
+from helpers.api import ApiHandler, Request, Response
-from python.helpers.file_browser import FileBrowser
+from helpers.file_browser import FileBrowser
-from python.helpers import files, runtime
+from helpers import files, runtime
-from python.api import get_work_dir_files
+from api import get_work_dir_files
 import os
 
 

docs/developer/contributing-skills.md

@@ -37,16 +37,16 @@ Skills you create here can be used in any of these platforms!
 
 ```bash
 # Create a new skill interactively
-python -m python.helpers.skills_cli create my-skill-name
+python -m helpers.skills_cli create my-skill-name
 
 # List all available skills
-python -m python.helpers.skills_cli list
+python -m helpers.skills_cli list
 
 # Validate a skill
-python -m python.helpers.skills_cli validate my-skill-name
+python -m helpers.skills_cli validate my-skill-name
 
 # Search skills
-python -m python.helpers.skills_cli search "keyword"
+python -m helpers.skills_cli search "keyword"
 ```
 
 ### Manual Creation
@@ -161,7 +161,7 @@ Ask yourself:
 
 ```bash
 # Using CLI
-python -m python.helpers.skills_cli create my-awesome-skill
+python -m helpers.skills_cli create my-awesome-skill
 
 # Or manually
 mkdir -p usr/skills/my-awesome-skill
@@ -225,7 +225,7 @@ This skill includes helper scripts:
 
 ```bash
 # Validate the skill
-python -m python.helpers.skills_cli validate my-awesome-skill
+python -m helpers.skills_cli validate my-awesome-skill
 
 # Test in Agent Zero
 # Start the agent and ask it to perform the task your skill handles
@@ -281,7 +281,7 @@ One skill = one expertise area. If your skill is getting too long, split it:
 
 1. **Validate Structure:**
    ```bash
-   python -m python.helpers.skills_cli validate my-skill
+   python -m helpers.skills_cli validate my-skill
    ```
 
 2. **Test Semantic Recall:**
@@ -304,7 +304,7 @@ One skill = one expertise area. If your skill is getting too long, split it:
 
 2. **Create Your Skill:**
    ```bash
-   python -m python.helpers.skills_cli create my-skill
+   python -m helpers.skills_cli create my-skill
    # Edit usr/skills/my-skill/SKILL.md
    ```
 

docs/developer/extensions.md

@@ -48,7 +48,7 @@ To create a custom extension:
 
 ```python
 # File: /agents/_example/extensions/agent_init/_10_example_extension.py
-from python.helpers.extension import Extension
+from helpers.extension import Extension
 
 class ExampleExtension(Extension):
     async def execute(self, **kwargs):
@@ -80,7 +80,7 @@ When a tool with the same name is requested, Agent Zero first checks for its exi
 
 ```python
 # File: /agents/_example/tools/response.py
-from python.helpers.tool import Tool, Response
+from helpers.tool import Tool, Response
 
 # example of a tool redefinition
 # the original response tool is in python/tools/response.py
@@ -145,8 +145,8 @@ When a prompt file is processed, Agent Zero automatically looks for a correspond
 If you have a prompt file `agent.system.tools.md`, you can create `agent.system.tools.py` alongside it:
 
 ```python
-from python.helpers.files import VariablesPlugin
+from helpers.files import VariablesPlugin
-from python.helpers import files
+from helpers import files
 
 class Tools(VariablesPlugin):
     def get_variables(self, file: str, backup_dirs: list[str] | None = None) -> dict[str, Any]:

docs/developer/notifications.md

@@ -10,7 +10,7 @@ Quick guide for using the notification system in Agent Zero.
 Use `AgentNotification` helper methods anywhere in your Python code:
 
 ```python
-from python.helpers.notification import AgentNotification
+from helpers.notification import AgentNotification
 
 # Basic notifications
 AgentNotification.info("Operation completed")

docs/developer/websockets.md

@@ -146,7 +146,7 @@ Handlers are discovered deterministically from `python/websocket_handlers/`:
 Create handler modules under the appropriate namespace entry and inherit from `WebSocketHandler`.
 
 ```python
-from python.helpers.websocket import WebSocketHandler
+from helpers.websocket import WebSocketHandler
 
 class DashboardHandler(WebSocketHandler):
     @classmethod

extensions/python/agent_Agent_handle_exception_end/_40_handle_intervention_exception.py

@@ -1,10 +1,10 @@
 from datetime import datetime, timezone
-from python.helpers.extension import Extension
+from helpers.extension import Extension
 from agent import LoopData
-from python.helpers.localization import Localization
+from helpers.localization import Localization
-from python.helpers.errors import InterventionException
+from helpers.errors import InterventionException
-from python.helpers import errors
+from helpers import errors
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
 
 
 class HandleInterventionException(Extension):

extensions/python/agent_Agent_handle_exception_end/_50_handle_repairable_exception.py

@@ -1,10 +1,10 @@
 from datetime import datetime, timezone
-from python.helpers.extension import Extension
+from helpers.extension import Extension
 from agent import LoopData
-from python.helpers.localization import Localization
+from helpers.localization import Localization
-from python.helpers.errors import RepairableException
+from helpers.errors import RepairableException
-from python.helpers import errors
+from helpers import errors
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
 
 
 class HandleRepairableException(Extension):

extensions/python/agent_Agent_handle_exception_end/_90_handle_critical_exception.py

@@ -1,10 +1,10 @@
 import asyncio
 
-from python.helpers.extension import Extension
+from helpers.extension import Extension
-from python.helpers.print_style import PrintStyle
+from helpers.print_style import PrintStyle
-from python.helpers import errors
+from helpers import errors
 
-from python.helpers.errors import HandledException
+from helpers.errors import HandledException
 
 
 class HandleCriticalException(Extension):

extensions/python/agent_init/_10_initial_message.py

@@ -1,6 +1,6 @@
 import json
 from agent import LoopData
-from python.helpers.extension import Extension
+from helpers.extension import Extension
 
 
 class InitialMessage(Extension):
@@ -10,6 +10,8 @@ class InitialMessage(Extension):
         Add an initial greeting message when first user message is processed.
         Called only once per session via _process_chain method.
         """
+        if not self.agent:
+            return
 
         # Only add initial message for main agent (A0), not subordinate agents
         if self.agent.number != 0:

extensions/python/agent_init/_15_load_profile_settings.py

@@ -1,6 +1,6 @@
 from initialize import initialize_agent
-from python.helpers import dirty_json, files, subagents, projects
+from helpers import dirty_json, files, subagents, projects
-from python.helpers.extension import Extension
+from helpers.extension import Extension
 
 
 class LoadProfileSettings(Extension):

extensions/python/banners/_10_unsecured_connection.py

@@ -1,5 +1,5 @@
-from python.helpers.extension import Extension
+from helpers.extension import Extension
-from python.helpers import dotenv
+from helpers import dotenv
 import re
 
 

extensions/python/banners/_20_missing_api_key.py

@@ -1,5 +1,5 @@
-from python.helpers.extension import Extension
+from helpers.extension import Extension
-from python.helpers import settings as settings_helper
+from helpers import settings as settings_helper
 import models
 
 

extensions/python/banners/_30_system_resources.py

@@ -1,4 +1,4 @@
-from python.helpers.extension import Extension
+from helpers.extension import Extension
 import os
 import psutil
 

extensions/python/before_main_llm_call/_10_log_for_stream.py

@@ -1,15 +1,18 @@
-from python.helpers import persist_chat, tokens
+from helpers import persist_chat, tokens
-from python.helpers.extension import Extension
+from helpers.extension import Extension
 from agent import LoopData
 import asyncio
-from python.helpers.log import LogItem
+from helpers.log import LogItem
-from python.helpers import log
+from helpers import log
 import math
 
 
 class LogForStream(Extension):
 
     async def execute(self, loop_data: LoopData = LoopData(), text: str = "", **kwargs):
+        if not self.agent:
+            return
+        
         # create log message and store it in loop data temporary params
         if "log_item_generating" not in loop_data.params_temporary:
             loop_data.params_temporary["log_item_generating"] = (

extensions/python/error_format/_10_mask_errors.py

@@ -1,10 +1,13 @@
-from python.helpers.extension import Extension
+from helpers.extension import Extension
-from python.helpers.secrets import get_secrets_manager
+from helpers.secrets import get_secrets_manager
 
 
 class MaskErrorSecrets(Extension):
 
     async def execute(self, **kwargs):
+        if not self.agent:
+            return
+        
         # Get error data from kwargs
         msg = kwargs.get("msg")
         if not msg:

extensions/python/hist_add_before/_10_mask_content.py

@@ -1,10 +1,13 @@
-from python.helpers.extension import Extension
+from helpers.extension import Extension
-from python.helpers.secrets import get_secrets_manager
+from helpers.secrets import get_secrets_manager
 
 
 class MaskHistoryContent(Extension):
 
     async def execute(self, **kwargs):
+        if not self.agent:
+            return
+
         # Get content data from kwargs
         content_data = kwargs.get("content_data")
         if not content_data: