refactor(automations): bind action handlers via ActionContext factory

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

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 from .store import all_actions, get_action, register_action
-from .types import ActionDefinition, ActionHandler
+from .types import ActionContext, ActionDefinition, ActionHandler, ActionHandlerFactory
 
 __all__ = [
+    "ActionContext",
     "ActionDefinition",
     "ActionHandler",
+    "ActionHandlerFactory",
     "all_actions",
     "get_action",
     "register_action",

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

@@ -7,13 +7,18 @@ from typing import Any
 from app.automations.schemas.actions import AgentTaskActionParams
 
 from .store import register_action
-from .types import ActionDefinition
+from .types import ActionContext, ActionDefinition, ActionHandler
 
 
-async def _handle_agent_task(args: dict[str, Any]) -> dict[str, Any]:
-    """Stub. Validates params; real wiring lands with the executor."""
-    AgentTaskActionParams.model_validate(args)
-    return {"status": "stubbed"}
+def _build_handler(ctx: ActionContext) -> ActionHandler:
+    """Bind run/session context to the agent_task handler. Real wiring lands in Phase 4b."""
+    del ctx  # ignored by the stub; real handler will consume it
+
+    async def handle(params: dict[str, Any]) -> dict[str, Any]:
+        AgentTaskActionParams.model_validate(params)
+        return {"status": "stubbed"}
+
+    return handle
 
 
 AGENT_TASK_ACTION = ActionDefinition(
@@ -21,7 +26,7 @@ AGENT_TASK_ACTION = ActionDefinition(
     name="Agent task",
     description="Run an agent task with a scoped tool allowlist.",
     params_schema=AgentTaskActionParams.model_json_schema(),
-    handler=_handle_agent_task,
+    build_handler=_build_handler,
 )
 
 register_action(AGENT_TASK_ACTION)

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

@@ -1,12 +1,28 @@
-"""``ActionDefinition`` dataclass and handler signature."""
+"""``ActionDefinition``, ``ActionContext``, and handler/factory signatures."""
 
 from __future__ import annotations
 
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from typing import Any
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+@dataclass(frozen=True, slots=True)
+class ActionContext:
+    """Per-invocation dependencies bound to an action handler at execute time."""
+
+    session: AsyncSession
+    run_id: int
+    step_id: str
+    search_space_id: int
+    creator_user_id: UUID | None
+
 
 ActionHandler = Callable[[dict[str, Any]], Awaitable[Any]]
+ActionHandlerFactory = Callable[[ActionContext], ActionHandler]
 
 
 @dataclass(frozen=True, slots=True)
@@ -15,4 +31,4 @@ class ActionDefinition:
     name: str
     description: str
     params_schema: dict[str, Any]
-    handler: ActionHandler
+    build_handler: ActionHandlerFactory