refactor(automations): vertical-slice actions and triggers by domain

surfsense_backend/app/automations/actions/__init__.py

@@ -1 +1,24 @@
-"""Action implementations. One subpackage per built-in action type."""
+"""Actions domain: registry surface + built-in action packages.
+
+Each action lives in its own subpackage (``agent_task/``, ...) and self-registers
+at import time via its ``definition`` module. Side-effect imports below ensure
+the registry is populated whenever anyone touches the actions package.
+"""
+
+from __future__ import annotations
+
+from .store import all_actions, get_action, register_action
+from .types import ActionContext, ActionDefinition, ActionHandler, ActionHandlerFactory
+
+__all__ = [
+    "ActionContext",
+    "ActionDefinition",
+    "ActionHandler",
+    "ActionHandlerFactory",
+    "all_actions",
+    "get_action",
+    "register_action",
+]
+
+# Built-in actions self-register at import time.
+from . import agent_task  # noqa: E402, F401

surfsense_backend/app/automations/actions/agent_task/__init__.py

@@ -1,7 +1,15 @@
-"""``agent_task`` action: spin up multi_agent_chat for one rendered query."""
+"""``agent_task`` action: spin up multi_agent_chat for one rendered query.
+
+Imports ``definition`` for its side-effect (self-registration on the actions
+registry) and re-exports ``build_handler`` for direct consumers.
+"""
 
 from __future__ import annotations
 
 from .factory import build_handler
+from .params import AgentTaskActionParams
 
-__all__ = ["build_handler"]
+__all__ = ["AgentTaskActionParams", "build_handler"]
+
+# Side-effect: register on the actions store.
+from . import definition  # noqa: E402, F401

surfsense_backend/app/automations/actions/agent_task/definition.py

@@ -1,12 +1,11 @@
-"""Built-in ``agent_task`` action. Self-registers at import time."""
+"""``agent_task`` ``ActionDefinition`` registration."""
 
 from __future__ import annotations
 
-from app.automations.actions.agent_task import build_handler
+from ..store import register_action
-from app.automations.schemas.actions import AgentTaskActionParams
+from ..types import ActionDefinition
-
+from .factory import build_handler
-from .store import register_action
+from .params import AgentTaskActionParams
-from .types import ActionDefinition
 
 AGENT_TASK_ACTION = ActionDefinition(
     type="agent_task",

surfsense_backend/app/automations/actions/agent_task/factory.py

@@ -4,13 +4,9 @@ from __future__ import annotations
 
 from typing import Any
 
-from app.automations.registries.actions.types import (
+from ..types import ActionContext, ActionHandler
-    ActionContext,
-    ActionHandler,
-)
-from app.automations.schemas.actions import AgentTaskActionParams
-
 from .invoke import run_agent_task
+from .params import AgentTaskActionParams
 
 
 def build_handler(ctx: ActionContext) -> ActionHandler:

surfsense_backend/app/automations/actions/agent_task/invoke.py

@@ -10,9 +10,10 @@ from langchain_core.messages import HumanMessage
 from langgraph.types import Command
 
 from app.agents.multi_agent_chat import create_multi_agent_chat_deep_agent
-from app.automations.registries.actions.types import ActionContext
 from app.db import ChatVisibility, async_session_maker
 
+from ..types import ActionContext
+
 from .auto_decide import build_auto_decisions
 from .dependencies import build_dependencies
 from .finalize import extract_final_assistant_message

surfsense_backend/app/automations/registries/__init__.py

@@ -1,33 +0,0 @@
-"""Action and trigger registries — populated at process startup."""
-
-from __future__ import annotations
-
-from .actions import (
-    ActionContext,
-    ActionDefinition,
-    ActionHandler,
-    ActionHandlerFactory,
-    all_actions,
-    get_action,
-    register_action,
-)
-from .triggers import (
-    TriggerDefinition,
-    all_triggers,
-    get_trigger,
-    register_trigger,
-)
-
-__all__ = [
-    "ActionContext",
-    "ActionDefinition",
-    "ActionHandler",
-    "ActionHandlerFactory",
-    "TriggerDefinition",
-    "all_actions",
-    "all_triggers",
-    "get_action",
-    "get_trigger",
-    "register_action",
-    "register_trigger",
-]

surfsense_backend/app/automations/registries/actions/__init__.py

@@ -1,19 +0,0 @@
-"""Action registry."""
-
-from __future__ import annotations
-
-from .store import all_actions, get_action, register_action
-from .types import ActionContext, ActionDefinition, ActionHandler, ActionHandlerFactory
-
-__all__ = [
-    "ActionContext",
-    "ActionDefinition",
-    "ActionHandler",
-    "ActionHandlerFactory",
-    "all_actions",
-    "get_action",
-    "register_action",
-]
-
-# Built-in actions self-register at import time.
-from . import agent_task  # noqa: E402, F401

surfsense_backend/app/automations/runtime/executor.py

@@ -8,7 +8,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.automations.persistence.enums.run_status import RunStatus
 from app.automations.persistence.models.run import AutomationRun
-from app.automations.registries.actions.types import ActionContext
+from app.automations.actions.types import ActionContext
 from app.automations.schemas.definition.envelope import AutomationDefinition
 from app.automations.schemas.definition.plan_step import PlanStep
 from app.automations.templating import build_run_context

surfsense_backend/app/automations/runtime/step.py

@@ -6,8 +6,8 @@ from collections.abc import Mapping
 from datetime import UTC, datetime
 from typing import Any
 
-from app.automations.registries import get_action
+from app.automations.actions import get_action
-from app.automations.registries.actions.types import ActionContext
+from app.automations.actions.types import ActionContext
 from app.automations.schemas.definition.plan_step import PlanStep
 from app.automations.templating import evaluate_predicate, render_value
 

surfsense_backend/app/automations/schemas/__init__.py

@@ -1,8 +1,13 @@
-"""Schemas for the automation definition and per-type configs."""
+"""Schemas for the automation definition envelope.
+
+Per-action and per-trigger params schemas live with the action/trigger
+implementations (``app.automations.actions.<name>.params`` /
+``app.automations.triggers.<name>.params``); only the cross-cutting envelope
+lives here.
+"""
 
 from __future__ import annotations
 
-from .actions import AgentTaskActionParams
 from .definition import (
     AutomationDefinition,
     Execution,
@@ -11,16 +16,12 @@ from .definition import (
     PlanStep,
     TriggerSpec,
 )
-from .triggers import ManualTriggerParams, ScheduleTriggerParams
 
 __all__ = [
-    "AgentTaskActionParams",
     "AutomationDefinition",
     "Execution",
     "Inputs",
-    "ManualTriggerParams",
     "Metadata",
     "PlanStep",
-    "ScheduleTriggerParams",
     "TriggerSpec",
 ]

surfsense_backend/app/automations/schemas/actions/__init__.py

@@ -1,9 +0,0 @@
-"""Per-action params schemas, one per action type."""
-
-from __future__ import annotations
-
-from .agent_task import AgentTaskActionParams
-
-__all__ = [
-    "AgentTaskActionParams",
-]

surfsense_backend/app/automations/schemas/triggers/__init__.py

@@ -1,11 +0,0 @@
-"""Per-trigger params schemas, one per trigger type."""
-
-from __future__ import annotations
-
-from .manual import ManualTriggerParams
-from .schedule import ScheduleTriggerParams
-
-__all__ = [
-    "ManualTriggerParams",
-    "ScheduleTriggerParams",
-]

surfsense_backend/app/automations/triggers/__init__.py

@@ -1,4 +1,8 @@
-"""Trigger registry."""
+"""Triggers domain: registry surface + built-in trigger packages.
+
+Each trigger lives in its own subpackage (``manual/``, ``schedule/``, ...) and
+self-registers at import time via its ``definition`` module.
+"""
 
 from __future__ import annotations
 

surfsense_backend/app/automations/triggers/manual/__init__.py

@@ -0,0 +1,10 @@
+"""``manual`` trigger: fired by a user clicking ``Run now``."""
+
+from __future__ import annotations
+
+from .params import ManualTriggerParams
+
+__all__ = ["ManualTriggerParams"]
+
+# Side-effect: register on the triggers store.
+from . import definition  # noqa: E402, F401

surfsense_backend/app/automations/triggers/manual/definition.py

@@ -1,11 +1,10 @@
-"""Built-in ``manual`` trigger. Self-registers at import time."""
+"""``manual`` ``TriggerDefinition`` registration."""
 
 from __future__ import annotations
 
-from app.automations.schemas.triggers import ManualTriggerParams
+from ..store import register_trigger
-
+from ..types import TriggerDefinition
-from .store import register_trigger
+from .params import ManualTriggerParams
-from .types import TriggerDefinition
 
 MANUAL_TRIGGER = TriggerDefinition(
     type="manual",

surfsense_backend/app/automations/triggers/schedule/__init__.py

@@ -0,0 +1,10 @@
+"""``schedule`` trigger: fired on a cron schedule in a given timezone."""
+
+from __future__ import annotations
+
+from .params import ScheduleTriggerParams
+
+__all__ = ["ScheduleTriggerParams"]
+
+# Side-effect: register on the triggers store.
+from . import definition  # noqa: E402, F401

surfsense_backend/app/automations/triggers/schedule/definition.py

@@ -1,11 +1,10 @@
-"""Built-in ``schedule`` trigger. Self-registers at import time."""
+"""``schedule`` ``TriggerDefinition`` registration."""
 
 from __future__ import annotations
 
-from app.automations.schemas.triggers import ScheduleTriggerParams
+from ..store import register_trigger
-
+from ..types import TriggerDefinition
-from .store import register_trigger
+from .params import ScheduleTriggerParams
-from .types import TriggerDefinition
 
 SCHEDULE_TRIGGER = TriggerDefinition(
     type="schedule",