Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(events): Wave 12 generalized event framework
trohitgc457303e43d8
diff --git a/server/routers/webhook.py b/server/routers/webhook.pyindex 2c0db035..187341d5 100644--- a/server/routers/webhook.py+++ b/server/routers/webhook.py@@ -1,14 +1,23 @@"""Dynamic webhook endpoint router for incoming HTTP requests.-Works like WhatsApp trigger - uses broadcaster.send_custom_event() to dispatch-to event_waiter which resolves waiting trigger nodes.+Two dispatch paths:++1. **Plugin-owned WebhookSource** (Wave 12 framework). Plugins register+ a :class:`services.events.WebhookSource` for their path; the router+ verifies the signature, shapes a :class:`WorkflowEvent`, and queues+ it onto the source. The source's owning plugin pulls events via+ ``source.emit()`` and dispatches into ``event_waiter``.+2. **Legacy generic webhook** (pre-framework). Falls through to+ ``broadcaster.send_custom_event("webhook_received", …)`` so existing+ ``webhookTrigger`` nodes keep working untouched."""-from fastapi import APIRouter, Request+from fastapi import APIRouter, HTTPException, Requestfrom fastapi.responses import JSONResponsefrom typing import Dictimport asyncioimport logging+from services.events import WEBHOOK_SOURCESfrom services.status_broadcaster import get_status_broadcasterlogger = logging.getLogger(__name__)@@ -38,10 +47,21 @@ def resolve_webhook_response(node_id: str, response_data: dict):async def handle_webhook(path: str, request: Request):"""Handle incoming webhook requests.- Dispatches webhook_received event to trigger waiting webhookTrigger nodes.- Similar to how WhatsApp events dispatch to whatsappReceive nodes.+ Path-handler dispatch (Wave 12) runs first; legacy generic+ dispatch is the fallback for paths nobody has claimed."""- # Build webhook request data+ source = WEBHOOK_SOURCES.get(path)+ if source is not None:+ try:+ await source.handle(request)+ except HTTPException:+ raise+ except Exception as e:+ logger.exception("[Webhook] %s handler crashed: %s", path, e)+ raise HTTPException(status_code=500, detail=str(e))+ logger.info("[Webhook] %s %s -> %s", request.method, path, type(source).__name__)+ return JSONResponse({"status": "received", "path": path}, status_code=200)+body = await request.body()json_body = Nonecontent_type = request.headers.get("content-type", "")@@ -63,12 +83,9 @@ async def handle_webhook(path: str, request: Request):logger.info(f"[Webhook] Received: {request.method} /webhook/{path}")- # Dispatch event using broadcaster (same pattern as WhatsApp)broadcaster = get_status_broadcaster()await broadcaster.send_custom_event("webhook_received", webhook_data)- # For now, always return immediate response- # TODO: Support responseNode mode by storing Future and waitingreturn JSONResponse(content={"status": "received",diff --git a/server/services/events/__init__.py b/server/services/events/__init__.pynew file mode 100644index 00000000..d9b2f0d5--- /dev/null+++ b/server/services/events/__init__.py@@ -0,0 +1,54 @@+"""Generalized event-source framework (Wave 12).++Three concrete EventSource subclasses cover all current MachinaOs+trigger integrations: ``PushEventSource`` (HTTP/RPC pushes),+``PollingEventSource`` (interval-based pull), ``DaemonEventSource``+(long-lived subprocess driver). Webhook flow is a thin specialisation+of PushEventSource via :class:`WebhookSource` + the path registry in+``server/routers/webhook.py``.++The unified payload type :class:`WorkflowEvent` mirrors CloudEvents+v1.0 verbatim — see ``envelope.py``. A back-compat shim in+``services.event_waiter`` auto-wraps legacy ``Dict`` dispatches so+existing plugins keep working untouched until they migrate.+"""++from __future__ import annotations++from .cli import run_cli_command+from .envelope import WorkflowEvent+from .lifecycle import make_lifecycle_handlers, make_status_refresh+from .source import EventSource+from .push import PushEventSource+from .polling import PollingEventSource+from .daemon import DaemonEventSource+from .triggers import BaseTriggerParams, WebhookTriggerNode+from .webhook import WebhookSource, WEBHOOK_SOURCES, register_webhook_source+from .verifiers import (+ WebhookVerifier,+ HmacVerifier,+ StripeVerifier,+ StandardWebhooksVerifier,+ GitHubVerifier,+)++__all__ = [+ "BaseTriggerParams",+ "DaemonEventSource",+ "EventSource",+ "GitHubVerifier",+ "HmacVerifier",+ "PollingEventSource",+ "PushEventSource",+ "StandardWebhooksVerifier",+ "StripeVerifier",+ "WEBHOOK_SOURCES",+ "WebhookSource",+ "WebhookTriggerNode",+ "WebhookVerifier",+ "WorkflowEvent",+ "make_lifecycle_handlers",+ "make_status_refresh",+ "register_webhook_source",+ "run_cli_command",+]diff --git a/server/services/events/cli.py b/server/services/events/cli.pynew file mode 100644index 00000000..b3c2c101--- /dev/null+++ b/server/services/events/cli.py@@ -0,0 +1,73 @@+"""Generic CLI invocation helper.++``run_cli_command`` resolves the binary on PATH, injects the+plugin's API key via the convention flag (``--api-key`` by default),+runs the subprocess with a timeout, captures stdout/stderr, and parses+stdout as JSON when possible. Used by any plugin that wraps a CLI+tool (Stripe, future GitHub-CLI / Cloudflare-Wrangler / etc.).+"""++from __future__ import annotations++import asyncio+import json+import shutil+from typing import Any, Dict, List, Optional, Type+++async def run_cli_command(+ *,+ binary: str,+ argv: List[str],+ credential: Optional[Type] = None,+ api_key_arg: str = "--api-key",+ timeout: float = 30.0,+) -> Dict[str, Any]:+ """Run ``<binary> <argv> [api_key_arg <key>]`` once, return parsed JSON.++ Returns a uniform envelope:+ {"success": bool, "result": parsed-JSON-or-None,+ "stdout": str, "stderr": str, "error": str or None}+ """+ api_key: Optional[str] = None+ if credential is not None:+ try:+ secrets = await credential.resolve()+ except PermissionError:+ return {"success": False, "error": f"{binary}: credential required"}+ api_key = secrets.get("api_key")+ if not api_key:+ return {"success": False, "error": f"{binary}: credential required"}++ resolved = shutil.which(binary)+ if resolved is None:+ return {"success": False, "error": f"{binary!r} not on PATH"}++ full_argv = [resolved, *argv]+ if api_key:+ full_argv.extend([api_key_arg, api_key])++ try:+ proc = await asyncio.create_subprocess_exec(+ *full_argv,+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,+ )+ stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)+ except asyncio.TimeoutError:+ return {"success": False, "error": f"{binary} timed out ({timeout}s)"}++ out = stdout.decode(errors="replace").strip()+ err = stderr.decode(errors="replace").strip()+ if proc.returncode != 0:+ return {+ "success": False,+ "stdout": out,+ "stderr": err,+ "error": err or f"exit {proc.returncode}",+ }+ try:+ parsed = json.loads(out) if out else None+ except json.JSONDecodeError:+ parsed = None+ return {"success": True, "result": parsed, "stdout": out, "stderr": err, "error": None}diff --git a/server/services/events/daemon.py b/server/services/events/daemon.pynew file mode 100644index 00000000..6c0c6df1--- /dev/null+++ b/server/services/events/daemon.py@@ -0,0 +1,178 @@+"""DaemonEventSource — long-lived subprocess (or SDK loop) that emits+events into the framework.++Used by stripe-listen, future telegram/whatsapp daemon migrations, and+any plugin that wraps a CLI tool. The class delegates lifecycle to+:class:`services.process_service.ProcessService` (already battle-tested:+PATHEXT-aware, ``kill_tree`` cleanup, log capture) and adds:++- typed event emission via :meth:`parse_line` (one event per stdout line,+ optionally per stderr line)+- declarative ``build_command(secrets) -> str`` so credential resolution+ is uniform across daemons+- pre-flight ``shutil.which`` check with a clear error if the binary+ isn't on PATH+"""++from __future__ import annotations++import asyncio+import shutil+from pathlib import Path+from typing import Any, AsyncIterator, ClassVar, Dict, Optional++from core.logging import get_logger+from services.process_service import get_process_service++from .envelope import WorkflowEvent+from .source import EventSource++logger = get_logger(__name__)+++class DaemonEventSource(EventSource):+ """Long-lived subprocess driver. Subclasses provide:++ * :attr:`process_name` — unique name for ProcessService key+ * :attr:`binary_name` — the executable to look up via PATH+ * :meth:`build_command(secrets)` — full command string+ * :meth:`parse_line(stream, line)` — turn output lines into events+ (return ``None`` to suppress; e.g. log-only lines)+ * :meth:`install_hint` (optional) — install URL surfaced in the+ "binary not on PATH" error+ """++ process_name: ClassVar[str] = ""+ binary_name: ClassVar[str] = ""+ workflow_namespace: ClassVar[str] = "_daemon"+ install_hint: ClassVar[str] = ""++ def __init__(self) -> None:+ super().__init__()+ self._pid: Optional[int] = None+ self._lock = asyncio.Lock()+ self._tail_task: Optional[asyncio.Task] = None+ self._queue: asyncio.Queue[WorkflowEvent] = asyncio.Queue()++ @property+ def pid(self) -> Optional[int]:+ return self._pid++ def build_command(self, secrets: Dict) -> str:+ raise NotImplementedError++ def parse_line(self, stream: str, line: str) -> Optional[WorkflowEvent]:+ """Override to emit events from output lines. ``stream`` is+ ``"stdout"`` or ``"stderr"``. Returning ``None`` swallows the line."""+ return None++ def workdir(self) -> Path:+ from core.config import Settings+ cwd = Path(Settings().workspace_base_resolved).resolve() / self.workflow_namespace+ cwd.mkdir(parents=True, exist_ok=True)+ return cwd++ async def _resolve_secrets(self) -> Dict[str, Any]:+ if self.credential is None:+ return {}+ try:+ return await self.credential.resolve()+ except PermissionError:+ return {}++ async def has_credential(self) -> bool:+ secrets = await self._resolve_secrets()+ return bool(secrets.get("api_key"))++ async def status(self) -> Dict[str, Any]:+ return {+ "type": self.type,+ "running": self._started,+ "pid": self._pid,+ }++ async def start(self) -> Dict[str, Any]:+ async with self._lock:+ if self._started:+ return {"success": True, "message": "already running", "status": await self.status()}++ secrets = await self._resolve_secrets()+ if self.credential is not None and not secrets.get("api_key"):+ return {"success": False, "error": f"{self.type}: credential required"}++ if self.binary_name and shutil.which(self.binary_name) is None:+ hint = f" Install: {self.install_hint}" if self.install_hint else ""+ return {"success": False, "error": f"{self.binary_name!r} not on PATH.{hint}"}++ cmd = self.build_command(secrets)+ cwd = self.workdir()+ result = await get_process_service().start(+ name=self.process_name,+ command=cmd,+ workflow_id=self.workflow_namespace,+ working_directory=str(cwd),+ )+ if not result.get("success"):+ return result++ self._pid = (result.get("result") or {}).get("pid")+ self._started = True+ self._stopped = False+ self._tail_task = asyncio.create_task(self._tail_logs(cwd))+ logger.info("[%s] daemon started pid=%s", self.type, self._pid)+ return {"success": True, "message": f"started (pid {self._pid})", "status": await self.status()}++ async def stop(self) -> Dict[str, Any]:+ async with self._lock:+ self._stopped = True+ if self._tail_task and not self._tail_task.done():+ self._tail_task.cancel()+ try:+ await self._tail_task+ except asyncio.CancelledError:+ pass+ self._tail_task = None+ await get_process_service().stop(+ name=self.process_name, workflow_id=self.workflow_namespace,+ )+ self._started = False+ self._pid = None+ return {"success": True, "message": "disconnected"}++ async def restart(self) -> Dict[str, Any]:+ await self.stop()+ return await self.start()++ async def _tail_logs(self, cwd: Path) -> None:+ """Tail both stdout.log and stderr.log; feed each new line to+ :meth:`parse_line` and queue any returned events."""+ await asyncio.gather(+ self._tail_one(cwd / ".processes" / self.process_name / "stdout.log", "stdout"),+ self._tail_one(cwd / ".processes" / self.process_name / "stderr.log", "stderr"),+ )++ async def _tail_one(self, path: Path, stream: str) -> None:+ offset = 0+ try:+ while not self._stopped:+ if path.exists():+ size = path.stat().st_size+ if size > offset:+ with path.open("r", encoding="utf-8", errors="replace") as f:+ f.seek(offset)+ for raw in f:+ if not raw.endswith("\n"):+ break+ line = raw.rstrip("\n")+ offset = f.tell()+ event = self.parse_line(stream, line)+ if event is not None:+ await self._queue.put(event)+ await asyncio.sleep(0.5)+ except asyncio.CancelledError:+ raise++ async def emit(self) -> AsyncIterator[WorkflowEvent]:+ while not self._stopped:+ event = await self._queue.get()+ yield eventdiff --git a/server/services/events/envelope.py b/server/services/events/envelope.pynew file mode 100644index 00000000..e4a42b56--- /dev/null+++ b/server/services/events/envelope.py@@ -0,0 +1,65 @@+"""WorkflowEvent — CloudEvents v1.0 envelope (in-house, no external dep).++Field set mirrors https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md+verbatim so future interop with EventBridge / Knative is a JSON-schema swap.+The MachinaOs extensions (workflow_id, trigger_node_id, correlation_id)+ride as CloudEvents extension attributes — fully compliant with the spec.+"""++from __future__ import annotations++from datetime import datetime, timezone+from typing import Any, Optional+from uuid import uuid4++from pydantic import BaseModel, ConfigDict, Field+++class WorkflowEvent(BaseModel):+ """Unified event envelope used by every EventSource."""++ specversion: str = "1.0"+ id: str = Field(default_factory=lambda: uuid4().hex)+ source: str+ type: str+ time: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))+ subject: Optional[str] = None+ datacontenttype: str = "application/json"+ dataschema: Optional[str] = None+ data: Any = None++ workflow_id: Optional[str] = None+ trigger_node_id: Optional[str] = None+ correlation_id: Optional[str] = None++ model_config = ConfigDict(extra="allow")++ @classmethod+ def from_legacy(cls, event_type: str, payload: dict) -> "WorkflowEvent":+ """Wrap a legacy Dict payload from the pre-framework dispatch path.++ Used by the back-compat shim in event_waiter.dispatch so existing+ plugins (telegram, whatsapp, gmail, etc.) keep working until they+ migrate to native WorkflowEvent emission.+ """+ return cls(+ source=f"legacy://{event_type}",+ type=event_type,+ data=payload,+ )++ def matches_type(self, pattern: str) -> bool:+ """Glob-style match on event type. ``"all"``/empty matches any.++ Examples:+ "stripe.charge.succeeded" matches itself+ "stripe.charge.*" matches "stripe.charge.succeeded"+ "stripe.*" matches "stripe.charge.succeeded"+ "all" or "" matches everything+ """+ if not pattern or pattern == "all":+ return True+ if pattern.endswith(".*"):+ prefix = pattern[:-2]+ return self.type.startswith(prefix + ".") or self.type == prefix+ return self.type == patterndiff --git a/server/services/events/lifecycle.py b/server/services/events/lifecycle.pynew file mode 100644index 00000000..04928fb4--- /dev/null+++ b/server/services/events/lifecycle.py@@ -0,0 +1,99 @@+"""Generic lifecycle wiring helpers.++:func:`make_lifecycle_handlers` returns the standard 4 WebSocket+handlers (``connect`` / ``disconnect`` / ``reconnect`` / ``status``) for+any :class:`EventSource`. Plugins call it once and register the dict —+no per-handler boilerplate.++:func:`make_status_refresh` returns a ``register_service_refresh``+callback that auto-reconnects the source when a credential is stored+and mirrors its status into the broadcaster cache.++Together these collapse ~50 LOC of identical boilerplate per plugin+into two function calls.+"""++from __future__ import annotations++from typing import Any, Awaitable, Callable, Dict, TYPE_CHECKING++from fastapi import WebSocket++from core.logging import get_logger++from .source import EventSource++if TYPE_CHECKING:+ from services.status_broadcaster import StatusBroadcaster++logger = get_logger(__name__)+++def make_lifecycle_handlers(+ prefix: str,+ source: EventSource,+ *,+ extra: Dict[str, Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]] | None = None,+) -> Dict[str, Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]]:+ """Return ``{prefix}_connect / _disconnect / _reconnect / _status`` handlers.++ Pass ``extra`` to merge additional plugin-specific handlers (e.g.+ ``{"stripe_trigger": handle_stripe_trigger}``).+ """++ async def _connect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:+ return await source.start()++ async def _disconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:+ return await source.stop()++ async def _reconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:+ restart = getattr(source, "restart", None)+ if restart is not None:+ return await restart()+ await source.stop()+ return await source.start()++ async def _status(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:+ status = await source.status()+ if hasattr(source, "has_credential"):+ status["has_stored_key"] = await source.has_credential() # type: ignore[attr-defined]+ return {"success": True, "status": status}++ handlers: Dict[str, Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]] = {+ f"{prefix}_connect": _connect,+ f"{prefix}_disconnect": _disconnect,+ f"{prefix}_reconnect": _reconnect,+ f"{prefix}_status": _status,+ }+ if extra:+ handlers.update(extra)+ return handlers+++def make_status_refresh(+ source: EventSource,+ *,+ status_key: str,+ broadcast_type: str,+) -> Callable[["StatusBroadcaster"], Awaitable[None]]:+ """Return a ``register_service_refresh`` callback.++ The callback auto-starts the source if it has stored credentials,+ mirrors its status into ``broadcaster._status[status_key]``, and+ emits a ``broadcast_type`` broadcast.+ """++ async def refresh(broadcaster: "StatusBroadcaster") -> None:+ try:+ if not getattr(source, "_started", False) and hasattr(source, "has_credential"):+ if await source.has_credential(): # type: ignore[attr-defined]+ logger.info("[StatusBroadcaster] auto-reconnecting %s", status_key)+ await source.start()+ status = await source.status()+ broadcaster._status[status_key] = status+ await broadcaster.broadcast({"type": broadcast_type, "data": status})+ except Exception as e:+ logger.debug("[StatusBroadcaster] %s refresh failed: %s", status_key, e)++ return refreshdiff --git a/server/services/events/polling.py b/server/services/events/polling.pynew file mode 100644index 00000000..1360a945--- /dev/null+++ b/server/services/events/polling.py@@ -0,0 +1,60 @@+"""PollingEventSource — periodic pull from an external API.++Replaces the duplicated loop frame in gmail_receive.py / email_receive.py /+twitter_receive.py. Subclasses implement :meth:`poll_once` and the+framework owns sleep timing, baseline-state persistence, and cancellation.+"""++from __future__ import annotations++import asyncio+from typing import AsyncIterator, ClassVar, Dict, Iterable++from core.logging import get_logger++from .envelope import WorkflowEvent+from .source import EventSource++logger = get_logger(__name__)+++class PollingEventSource(EventSource):+ """Polling-mode source. Subclasses provide :meth:`poll_once`."""++ poll_interval_default: ClassVar[int] = 60++ def __init__(self, poll_interval: int | None = None) -> None:+ super().__init__()+ self.poll_interval = poll_interval or self.poll_interval_default+ self._state: Dict = {}++ async def load_state(self) -> Dict:+ """Override to hydrate cursor / last-seen-id from disk or DB.+ Default keeps state in-memory only (lost on restart)."""+ return self._state++ async def save_state(self, state: Dict) -> None:+ """Override to persist cursor across restarts."""+ self._state = state++ async def poll_once(self, state: Dict) -> Iterable[WorkflowEvent]:+ """Return any new events since the last poll. Mutate ``state``+ in place to record what was seen."""+ raise NotImplementedError++ async def emit(self) -> AsyncIterator[WorkflowEvent]:+ state = await self.load_state()+ while not self._stopped:+ try:+ events = await self.poll_once(state) or []+ await self.save_state(state)+ for ev in events:+ yield ev+ except asyncio.CancelledError:+ raise+ except Exception as e:+ logger.warning("[%s] poll_once failed: %s", self.type, e)+ try:+ await asyncio.sleep(self.poll_interval)+ except asyncio.CancelledError:+ breakdiff --git a/server/services/events/push.py b/server/services/events/push.pynew file mode 100644index 00000000..51697f04--- /dev/null+++ b/server/services/events/push.py@@ -0,0 +1,36 @@+"""PushEventSource — events arrive via external write (HTTP webhook,+RPC callback, server-sent event). The source itself is passive: it+exposes a :meth:`receive` method that whoever owns the inbound channel+calls with each new payload, and an internal queue surfaces the events+through the standard :meth:`emit` async iterator.++Used directly by :class:`WebhookSource` (in webhook.py); future RPC /+SSE sources subclass this same base.+"""++from __future__ import annotations++import asyncio+from typing import AsyncIterator++from .envelope import WorkflowEvent+from .source import EventSource+++class PushEventSource(EventSource):+ """Push-mode source: external code calls :meth:`receive` with each+ event; :meth:`emit` yields them in order.+ """++ def __init__(self) -> None:+ super().__init__()+ self._queue: asyncio.Queue[WorkflowEvent] = asyncio.Queue()++ async def receive(self, event: WorkflowEvent) -> None:+ """Hand-off from the inbound channel into the framework queue."""+ await self._queue.put(event)++ async def emit(self) -> AsyncIterator[WorkflowEvent]:+ while not self._stopped:+ event = await self._queue.get()+ yield eventdiff --git a/server/services/events/source.py b/server/services/events/source.pynew file mode 100644index 00000000..70e6e98b--- /dev/null+++ b/server/services/events/source.py@@ -0,0 +1,63 @@+"""EventSource abstract base — every external event-producer plugs in here.++Three concrete subclasses cover the four execution modalities documented+in Apache Camel EIP and matched by n8n's trigger model:++ PushEventSource HTTP webhooks, server-sent events, RPC pushes+ PollingEventSource interval-based pull (Gmail/Twitter/IMAP polling)+ DaemonEventSource long-lived subprocess or SDK loop (Stripe CLI,+ Telegram bot, WhatsApp Go RPC)++Cron / scheduled events stay on APScheduler — they don't need this base.+Internal (in-process) events go through ``event_waiter.dispatch`` directly.+"""++from __future__ import annotations++from abc import ABC, abstractmethod+from typing import Any, AsyncIterator, ClassVar, Dict, Optional, Type++from core.logging import get_logger++logger = get_logger(__name__)+++class EventSource(ABC):+ """Base — subclasses declare ``type``, optionally ``credential``,+ and implement :meth:`emit` (or one of the convenience hooks on the+ concrete subclasses)."""++ type: ClassVar[str] = ""+ credential: ClassVar[Optional[Type]] = None++ def __init__(self) -> None:+ self._stopped = False+ self._started = False++ async def start(self) -> Dict[str, Any]:+ """Activate the source. Idempotent. Concrete subclasses override+ with their actual lifecycle (subprocess spawn, polling task launch,+ webhook registration)."""+ self._started = True+ self._stopped = False+ return {"success": True, "type": self.type}++ async def stop(self) -> Dict[str, Any]:+ """Deactivate. Idempotent."""+ self._stopped = True+ self._started = False+ return {"success": True, "type": self.type}++ async def status(self) -> Dict[str, Any]:+ """Snapshot for the credentials modal / status broadcaster."""+ return {"type": self.type, "running": self._started}++ @abstractmethod+ def emit(self) -> AsyncIterator:+ """Async iterator yielding ``WorkflowEvent`` instances.++ Returning an iterator (not awaiting it) lets the framework+ manage cancellation and back-pressure uniformly across push,+ polling, and daemon sources.+ """+ raise NotImplementedErrordiff --git a/server/services/events/triggers.py b/server/services/events/triggers.pynew file mode 100644index 00000000..6a5536ce--- /dev/null+++ b/server/services/events/triggers.py@@ -0,0 +1,118 @@+"""Generic TriggerNode base classes backed by EventSources.++Plugins subclass :class:`WebhookTriggerNode` and declare:++ type, display_name, group, ... (standard plugin metadata)+ webhook_source: ClassVar[Type[WebhookSource]]+ Params, Output (Pydantic models)+ shape_output(event) (optional) reshape WorkflowEvent -> Output dict+ _check_precondition() (optional) return error str if not ready+ _extra_filter(params) (optional) additional filter on top of event_type++The base provides:+ - event_type derived from webhook_source.type+ - build_filter combining CloudEvents type-glob + _extra_filter+ - execute() with precheck + shape passthrough+ - the standard Operation("wait") stub+"""++from __future__ import annotations++import time+from typing import Any, Callable, ClassVar, Dict, Optional, Type++from pydantic import BaseModel, ConfigDict, Field++from services.plugin import NodeContext, Operation, TaskQueue, TriggerNode++from .envelope import WorkflowEvent+from .webhook import WebhookSource+++class BaseTriggerParams(BaseModel):+ """Default Params for WebhookTriggerNode subclasses. Subclass and add+ provider-specific filters."""++ event_type_filter: str = Field(+ default="all",+ description=(+ "Event type to match. 'all' for every event, exact name, "+ "or wildcard prefix (e.g. 'foo.*')."+ ),+ )++ model_config = ConfigDict(extra="ignore")+++class WebhookTriggerNode(TriggerNode):+ """TriggerNode whose events arrive through a :class:`WebhookSource`.++ The framework owns the wait/dispatch flow; subclasses describe only+ the differences from the generic shape.+ """++ webhook_source: ClassVar[Optional[Type[WebhookSource]]] = None+ # Auto-prepended to ``event_type_filter`` so users can type "charge.*"+ # instead of "stripe.charge.*". Empty disables the convenience.+ event_type_prefix: ClassVar[str] = ""+ mode: ClassVar[str] = "event"+ task_queue: ClassVar[str] = TaskQueue.TRIGGERS_EVENT+ Params: ClassVar[Type[BaseModel]] = BaseTriggerParams++ def __init_subclass__(cls, **kwargs):+ super().__init_subclass__(**kwargs)+ if cls.webhook_source is not None and not getattr(cls, "event_type", ""):+ cls.event_type = cls.webhook_source.type++ def build_filter(self, params: BaseModel) -> Callable[[Any], bool]:+ type_filter = (getattr(params, "event_type_filter", "") or "all").strip()+ if (+ type_filter+ and type_filter != "all"+ and self.event_type_prefix+ and not type_filter.startswith(self.event_type_prefix)+ ):+ type_filter = self.event_type_prefix + type_filter+ extras = self._extra_filter(params)++ def matches(event: Any) -> bool:+ ev = event if isinstance(event, WorkflowEvent) else WorkflowEvent(**event)+ if not ev.matches_type(type_filter):+ return False+ return extras(ev) if extras else True++ return matches++ def _extra_filter(self, params: BaseModel) -> Optional[Callable[[WorkflowEvent], bool]]:+ """Override for filters beyond event-type matching (e.g. livemode)."""+ return None++ async def _check_precondition(self) -> Optional[str]:+ """Override to short-circuit. Return error string or None."""+ return None++ async def execute(+ self,+ node_id: str,+ parameters: Dict[str, Any],+ context,+ ) -> Dict[str, Any]:+ err = await self._check_precondition()+ if err:+ return self._wrap_error(start_time=time.time(), error=err)+ result = await super().execute(node_id, parameters, context)+ if result.get("success"):+ event = result.get("result") or {}+ ev = event if isinstance(event, WorkflowEvent) else WorkflowEvent(**event)+ result["result"] = self.shape_output(ev)+ return result++ def shape_output(self, event: WorkflowEvent) -> Dict[str, Any]:+ """Default: dump the CloudEvent. Override for provider-shaped output."""+ return event.model_dump(mode="json")++ @Operation("wait")+ async def wait(self, ctx: NodeContext, params: BaseModel):+ raise NotImplementedError(+ "Event triggers return via TriggerNode.execute, not the op body"+ )diff --git a/server/services/events/verifiers/__init__.py b/server/services/events/verifiers/__init__.pynew file mode 100644index 00000000..77f84faa--- /dev/null+++ b/server/services/events/verifiers/__init__.py@@ -0,0 +1,25 @@+"""Webhook signature verifiers — pluggable HMAC schemes per provider.++Each verifier is a stateless class with one method:++ verify(headers, body, secret) -> None # raises ValueError on mismatch++Plugins reference verifier classes directly; there's no string-keyed+registry to avoid (yet another) lookup table.+"""++from __future__ import annotations++from .base import WebhookVerifier+from .hmac_basic import HmacVerifier+from .stripe import StripeVerifier+from .standard_webhooks import StandardWebhooksVerifier+from .github import GitHubVerifier++__all__ = [+ "WebhookVerifier",+ "HmacVerifier",+ "StripeVerifier",+ "StandardWebhooksVerifier",+ "GitHubVerifier",+]diff --git a/server/services/events/verifiers/base.py b/server/services/events/verifiers/base.pynew file mode 100644index 00000000..4cd784f6--- /dev/null+++ b/server/services/events/verifiers/base.py@@ -0,0 +1,28 @@+"""Webhook verifier base — single-method contract."""++from __future__ import annotations++from typing import Mapping+++class WebhookVerifier:+ """Abstract base. Each provider's signature scheme is one subclass."""++ @classmethod+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:+ """Raise ``ValueError`` if the request is not authentic.++ ``headers`` is case-insensitive at the caller's discretion;+ verifiers handle the lookup themselves to stay defensive.+ ``body`` is the raw request bytes (signed payload).+ ``secret`` is the provider-issued signing secret.+ """+ raise NotImplementedError++ @staticmethod+ def _header(headers: Mapping[str, str], name: str) -> str:+ target = name.lower()+ for k, v in headers.items():+ if k.lower() == target:+ return v+ return ""diff --git a/server/services/events/verifiers/github.py b/server/services/events/verifiers/github.pynew file mode 100644index 00000000..674c2cca--- /dev/null+++ b/server/services/events/verifiers/github.py@@ -0,0 +1,25 @@+"""GitHub webhook signature verifier.++Header: ``X-Hub-Signature-256: sha256=<hex_hmac>``+Algorithm: HMAC-SHA256 of the secret over the raw body, hex-encoded.+Reference: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries+"""++from __future__ import annotations++import hashlib+import hmac+from typing import Mapping++from .base import WebhookVerifier+++class GitHubVerifier(WebhookVerifier):+ @classmethod+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:+ sig = cls._header(headers, "x-hub-signature-256")+ if not sig.startswith("sha256="):+ raise ValueError("X-Hub-Signature-256 missing or malformed")+ expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()+ if not hmac.compare_digest(expected, sig):+ raise ValueError("X-Hub-Signature-256 mismatch")diff --git a/server/services/events/verifiers/hmac_basic.py b/server/services/events/verifiers/hmac_basic.pynew file mode 100644index 00000000..e66ccbce--- /dev/null+++ b/server/services/events/verifiers/hmac_basic.py@@ -0,0 +1,32 @@+"""Generic HMAC-SHA256 verifier — fallback for providers whose scheme+is "single header carrying hex HMAC of the raw body".++Subclasses customise :attr:`header_name` and (optionally)+:attr:`signature_prefix`. The default reads ``X-Signature-256`` and+expects a bare hex digest.+"""++from __future__ import annotations++import hashlib+import hmac+from typing import ClassVar, Mapping++from .base import WebhookVerifier+++class HmacVerifier(WebhookVerifier):+ header_name: ClassVar[str] = "X-Signature-256"+ signature_prefix: ClassVar[str] = "" # e.g. "sha256=" for some providers++ @classmethod+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:+ sig = cls._header(headers, cls.header_name)+ if not sig:+ raise ValueError(f"{cls.header_name} header missing")+ if cls.signature_prefix and not sig.startswith(cls.signature_prefix):+ raise ValueError(f"{cls.header_name} missing prefix {cls.signature_prefix!r}")+ provided = sig[len(cls.signature_prefix):]+ expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()+ if not hmac.compare_digest(expected, provided):+ raise ValueError(f"{cls.header_name} mismatch")diff --git a/server/services/events/verifiers/standard_webhooks.py b/server/services/events/verifiers/standard_webhooks.pynew file mode 100644index 00000000..6b3b0931--- /dev/null+++ b/server/services/events/verifiers/standard_webhooks.py@@ -0,0 +1,47 @@+"""Standard Webhooks (Svix) signature verifier.++Spec: https://www.standardwebhooks.com/+Headers: ``webhook-id``, ``webhook-timestamp``, ``webhook-signature``+Signed payload: ``f"{webhook-id}.{webhook-timestamp}.{raw_body}"``+Algorithm: HMAC-SHA256 of the secret (b64-decoded after the ``whsec_`` prefix+is stripped) over the signed payload, base64-encoded.+``webhook-signature`` may carry multiple space-separated ``v1,<sig>`` entries+to support secret rotation.+"""++from __future__ import annotations++import base64+import hashlib+import hmac+from typing import Mapping++from .base import WebhookVerifier+++class StandardWebhooksVerifier(WebhookVerifier):+ @classmethod+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:+ msg_id = cls._header(headers, "webhook-id")+ timestamp = cls._header(headers, "webhook-timestamp")+ sig_header = cls._header(headers, "webhook-signature")+ if not (msg_id and timestamp and sig_header):+ raise ValueError("Standard Webhooks headers missing")++ if secret.startswith("whsec_"):+ key = base64.b64decode(secret[len("whsec_"):])+ else:+ key = secret.encode()++ signed = f"{msg_id}.{timestamp}.".encode() + body+ expected = base64.b64encode(+ hmac.new(key, signed, hashlib.sha256).digest()+ ).decode()++ candidates: list[str] = []+ for part in sig_header.split():+ if "," in part:+ _, value = part.split(",", 1)+ candidates.append(value)+ if not any(hmac.compare_digest(expected, c) for c in candidates):+ raise ValueError("Standard Webhooks signature mismatch")diff --git a/server/services/events/verifiers/stripe.py b/server/services/events/verifiers/stripe.pynew file mode 100644index 00000000..bc1c653a--- /dev/null+++ b/server/services/events/verifiers/stripe.py@@ -0,0 +1,42 @@+"""Stripe webhook signature verifier.++Header format: ``Stripe-Signature: t=<unix_ts>,v1=<hex_hmac>[,v1=<rotated>]``+Signed payload: ``f"{timestamp}.{raw_body}"`` (HMAC-SHA256, hex)+Reference: https://stripe.com/docs/webhooks/signatures+"""++from __future__ import annotations++import hashlib+import hmac+from typing import Mapping++from .base import WebhookVerifier+++class StripeVerifier(WebhookVerifier):+ @classmethod+ def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:+ sig_header = cls._header(headers, "stripe-signature")+ if not sig_header:+ raise ValueError("Stripe-Signature header missing")++ timestamp = ""+ candidates: list[str] = []+ for part in sig_header.split(","):+ if "=" not in part:+ continue+ k, v = part.split("=", 1)+ k = k.strip()+ v = v.strip()+ if k == "t":+ timestamp = v+ elif k == "v1":+ candidates.append(v)+ if not timestamp or not candidates:+ raise ValueError("Stripe-Signature missing t= or v1= component")++ signed = f"{timestamp}.".encode() + body+ expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()+ if not any(hmac.compare_digest(expected, c) for c in candidates):+ raise ValueError("Stripe-Signature mismatch")diff --git a/server/services/events/webhook.py b/server/services/events/webhook.pynew file mode 100644index 00000000..c06ae516--- /dev/null+++ b/server/services/events/webhook.py@@ -0,0 +1,105 @@+"""WebhookSource — push source backed by an HTTP POST to /webhook/{path}.++Plugins subclass and declare:++ class MyWebhook(WebhookSource):+ path = "myprovider"+ verifier = MyVerifier # WebhookVerifier subclass (optional)+ secret_field = "my_webhook_secret" # extra field on the credential++ async def shape(self, request, body, payload) -> WorkflowEvent: ...++A single edit to ``routers/webhook.py`` consults :data:`WEBHOOK_SOURCES`+before the legacy generic dispatch path. No plugin name is hardcoded+in the router.+"""++from __future__ import annotations++import json+from typing import ClassVar, Dict, Optional, Type++from fastapi import HTTPException, Request++from core.logging import get_logger++from .envelope import WorkflowEvent+from .push import PushEventSource+from .verifiers import WebhookVerifier++logger = get_logger(__name__)+++WEBHOOK_SOURCES: Dict[str, "WebhookSource"] = {}+++def register_webhook_source(source: "WebhookSource") -> None:+ """Idempotent: same instance for the same path is a no-op; conflicts raise."""+ existing = WEBHOOK_SOURCES.get(source.path)+ if existing is not None and existing is not source:+ raise ValueError(+ f"Webhook path {source.path!r} already registered to {type(existing).__name__}"+ )+ WEBHOOK_SOURCES[source.path] = source+++class WebhookSource(PushEventSource):+ """Base for HTTP-webhook event sources.++ Subclass contract:+ path: URL fragment under /webhook/+ verifier: WebhookVerifier subclass (or None to skip verification)+ secret_field: credential extra-field name holding the signing secret+ shape(): turn the verified request into a WorkflowEvent+ """++ path: ClassVar[str] = ""+ verifier: ClassVar[Optional[Type[WebhookVerifier]]] = None+ secret_field: ClassVar[Optional[str]] = None++ async def _resolve_secret(self) -> Optional[str]:+ if self.secret_field is None or self.credential is None:+ return None+ try:+ secrets = await self.credential.resolve()+ except PermissionError:+ return None+ return secrets.get(self.secret_field)++ async def shape(self, request: Request, body: bytes, payload: dict) -> WorkflowEvent:+ """Override to map the verified payload into a CloudEvent."""+ return WorkflowEvent(+ source=f"webhook://{self.path}",+ type=f"webhook.{self.path}",+ data=payload,+ )++ async def handle(self, request: Request) -> WorkflowEvent:+ """Called by the webhook router. Verifies signature, parses the+ body, shapes the event, dispatches into ``event_waiter``, and+ returns the event for logging / response shaping."""+ body = await request.body()+ if self.verifier is not None:+ secret = await self._resolve_secret()+ if not secret:+ logger.warning(+ "[%s] no signing secret available; accepting unverified event",+ self.type or self.path,+ )+ else:+ try:+ self.verifier.verify(dict(request.headers), body, secret)+ except ValueError as e:+ raise HTTPException(status_code=400, detail=str(e))++ try:+ payload = json.loads(body.decode() or "{}")+ except (json.JSONDecodeError, UnicodeDecodeError) as e:+ raise HTTPException(status_code=400, detail=f"invalid JSON body: {e}")++ event = await self.shape(request, body, payload)+ await self.receive(event)++ from services import event_waiter+ event_waiter.dispatch(self.type, event)+ return eventdiff --git a/server/tests/services/test_events.py b/server/tests/services/test_events.pynew file mode 100644index 00000000..f1f08808--- /dev/null+++ b/server/tests/services/test_events.py@@ -0,0 +1,333 @@+"""Contract tests for the generalized event-source framework."""++from __future__ import annotations++import asyncio+import base64+import hashlib+import hmac+import json+import time+from typing import Iterable+from unittest.mock import patch++import pytest++pytestmark = pytest.mark.node_contract+++def _run(coro):+ return asyncio.new_event_loop().run_until_complete(coro)+++# ============================================================================+# WorkflowEvent envelope+# ============================================================================+++class TestWorkflowEvent:+ def test_required_fields(self):+ from services.events import WorkflowEvent+ ev = WorkflowEvent(source="stripe://acct_1", type="stripe.charge.succeeded")+ assert ev.specversion == "1.0"+ assert ev.id # uuid default+ assert ev.datacontenttype == "application/json"++ def test_round_trip_json(self):+ from services.events import WorkflowEvent+ ev = WorkflowEvent(+ source="stripe://acct_1", type="stripe.charge.succeeded", data={"amount": 1000},+ )+ restored = WorkflowEvent.model_validate(json.loads(ev.model_dump_json()))+ assert restored.type == ev.type+ assert restored.data == {"amount": 1000}+ assert restored.id == ev.id++ def test_matches_type_glob(self):+ from services.events import WorkflowEvent+ ev = WorkflowEvent(source="stripe://x", type="stripe.charge.succeeded")+ assert ev.matches_type("all") is True+ assert ev.matches_type("") is True+ assert ev.matches_type("stripe.charge.succeeded") is True+ assert ev.matches_type("stripe.charge.*") is True+ assert ev.matches_type("stripe.*") is True+ assert ev.matches_type("payment_intent.*") is False++ def test_from_legacy(self):+ from services.events import WorkflowEvent+ ev = WorkflowEvent.from_legacy("whatsapp_message_received", {"text": "hi"})+ assert ev.type == "whatsapp_message_received"+ assert ev.data == {"text": "hi"}+ assert ev.source.startswith("legacy://")+++# ============================================================================+# Verifiers+# ============================================================================+++class TestStripeVerifier:+ SECRET = "whsec_test"++ def _sign(self, body: bytes, ts: int | None = None) -> dict:+ ts = ts if ts is not None else int(time.time())+ signed = f"{ts}.".encode() + body+ sig = hmac.new(self.SECRET.encode(), signed, hashlib.sha256).hexdigest()+ return {"Stripe-Signature": f"t={ts},v1={sig}"}++ def test_valid_signature_passes(self):+ from services.events import StripeVerifier+ body = b'{"id":"evt_1"}'+ StripeVerifier.verify(self._sign(body), body, self.SECRET)++ def test_tampered_body_rejected(self):+ from services.events import StripeVerifier+ body = b'{"id":"evt_1"}'+ headers = self._sign(body)+ with pytest.raises(ValueError):+ StripeVerifier.verify(headers, b'{"id":"evt_2"}', self.SECRET)++ def test_missing_header_rejected(self):+ from services.events import StripeVerifier+ with pytest.raises(ValueError, match="missing"):+ StripeVerifier.verify({}, b'{}', self.SECRET)++ def test_malformed_header_rejected(self):+ from services.events import StripeVerifier+ with pytest.raises(ValueError):+ StripeVerifier.verify({"Stripe-Signature": "garbage"}, b'{}', self.SECRET)+++class TestGitHubVerifier:+ def test_round_trip(self):+ from services.events import GitHubVerifier+ secret = "shh"+ body = b'{"action":"opened"}'+ sig = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()+ GitHubVerifier.verify({"X-Hub-Signature-256": sig}, body, secret)++ def test_tampered_rejected(self):+ from services.events import GitHubVerifier+ with pytest.raises(ValueError):+ GitHubVerifier.verify({"X-Hub-Signature-256": "sha256=deadbeef"}, b'{}', "shh")+++class TestStandardWebhooksVerifier:+ def test_round_trip(self):+ from services.events import StandardWebhooksVerifier+ secret_raw = b"super-secret-key-bytes"+ secret = "whsec_" + base64.b64encode(secret_raw).decode()+ body = b'{"foo":"bar"}'+ msg_id = "msg_abc"+ ts = "1700000000"+ signed = f"{msg_id}.{ts}.".encode() + body+ sig = base64.b64encode(hmac.new(secret_raw, signed, hashlib.sha256).digest()).decode()+ headers = {+ "webhook-id": msg_id,+ "webhook-timestamp": ts,+ "webhook-signature": f"v1,{sig}",+ }+ StandardWebhooksVerifier.verify(headers, body, secret)++ def test_tampered_rejected(self):+ from services.events import StandardWebhooksVerifier+ with pytest.raises(ValueError):+ StandardWebhooksVerifier.verify(+ {"webhook-id": "1", "webhook-timestamp": "1", "webhook-signature": "v1,bad"},+ b'{}', "whsec_AAAA",+ )+++class TestHmacVerifier:+ def test_round_trip(self):+ from services.events import HmacVerifier+ secret = "shh"+ body = b'{"x":1}'+ sig = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()+ HmacVerifier.verify({"X-Signature-256": sig}, body, secret)+++# ============================================================================+# PollingEventSource loop+# ============================================================================+++class TestPollingEventSource:+ def test_emits_what_poll_once_returns_then_sleeps(self):+ from services.events import PollingEventSource, WorkflowEvent++ class FakePolling(PollingEventSource):+ type = "fake.polling"+ poll_interval_default = 0 # tight loop for the test++ def __init__(self):+ super().__init__()+ self.calls = 0++ async def poll_once(self, state) -> Iterable[WorkflowEvent]:+ self.calls += 1+ if self.calls == 1:+ return [WorkflowEvent(source="x", type="fake.tick", data={"n": 1})]+ self._stopped = True+ return []++ async def drain():+ src = FakePolling()+ seen = []+ async for ev in src.emit():+ seen.append(ev)+ if len(seen) >= 1:+ src._stopped = True+ return seen++ events = _run(drain())+ assert len(events) == 1+ assert events[0].type == "fake.tick"+++# ============================================================================+# WebhookSource — handle() integration+# ============================================================================+++class TestWebhookSourceHandle:+ def _build_source(self, secret_value: str | None):+ from services.events import StripeVerifier, WebhookSource, WorkflowEvent++ class _Cred:+ @classmethod+ async def resolve(cls):+ if secret_value is None:+ raise PermissionError+ return {"api_key": "sk_test", "test_secret": secret_value}++ class FakeSource(WebhookSource):+ type = "fake.hook"+ path = "fake"+ verifier = StripeVerifier+ secret_field = "test_secret"+ credential = _Cred++ async def shape(self, request, body, payload):+ return WorkflowEvent(source="fake://x", type="fake.event", data=payload)++ return FakeSource()++ def _signed_request(self, body: bytes, secret: str):+ ts = int(time.time())+ signed = f"{ts}.".encode() + body+ sig = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()++ class FakeReq:+ headers = {"Stripe-Signature": f"t={ts},v1={sig}"}++ async def body(self):+ return body++ return FakeReq()++ def test_valid_signature_dispatches(self):+ src = self._build_source(secret_value="whsec_test")+ body = b'{"event":"payload"}'+ req = self._signed_request(body, "whsec_test")+ with patch("services.event_waiter.dispatch") as dispatch:+ ev = _run(src.handle(req))+ assert ev.type == "fake.event"+ dispatch.assert_called_once()+ called_type, called_event = dispatch.call_args[0]+ assert called_type == "fake.hook"+ assert called_event is ev++ def test_tampered_signature_raises_400(self):+ from fastapi import HTTPException+ src = self._build_source(secret_value="whsec_test")+ body = b'{"event":"payload"}'+ req = self._signed_request(body, "whsec_other") # signed with different secret+ with pytest.raises(HTTPException) as exc:+ _run(src.handle(req))+ assert exc.value.status_code == 400++ def test_missing_secret_accepts_unverified(self):+ """No secret captured yet -> log warning, accept event."""+ src = self._build_source(secret_value=None)+ body = b'{"event":"payload"}'++ class FakeReq:+ headers = {}++ async def body(self):+ return body++ with patch("services.event_waiter.dispatch") as dispatch:+ ev = _run(src.handle(FakeReq()))+ assert ev.type == "fake.event"+ dispatch.assert_called_once()+++# ============================================================================+# DaemonEventSource lifecycle (mocked ProcessService)+# ============================================================================+++class TestDaemonEventSource:+ def test_start_calls_process_service_start(self):+ from services.events import DaemonEventSource++ class FakeDaemon(DaemonEventSource):+ type = "fake.daemon"+ process_name = "fake-daemon"+ binary_name = "echo" # always on PATH++ def build_command(self, secrets):+ return "echo hello"++ def parse_line(self, stream, line):+ return None++ async def go():+ with patch("services.events.daemon.shutil.which", return_value="/usr/bin/echo"), \+ patch("services.events.daemon.get_process_service") as get_ps:+ ps = get_ps.return_value++ async def fake_start(**kwargs):+ return {"success": True, "result": {"pid": 4242}}++ ps.start.side_effect = fake_start++ async def fake_stop(**kwargs):+ return {"success": True}++ ps.stop.side_effect = fake_stop++ src = FakeDaemon()+ result = await src.start()+ assert result["success"] is True+ assert src.pid == 4242+ ps.start.assert_called_once()+ # Cancel the tail task so the test exits cleanly.+ await src.stop()+ assert src.pid is None++ _run(go())++ def test_start_fails_when_binary_missing(self):+ from services.events import DaemonEventSource++ class FakeDaemon(DaemonEventSource):+ type = "fake.daemon"+ process_name = "fake-daemon"+ binary_name = "definitely-not-on-path-zzzzz"+ install_hint = "see docs"++ def build_command(self, secrets):+ return "x"++ async def go():+ with patch("services.events.daemon.shutil.which", return_value=None):+ src = FakeDaemon()+ result = await src.start()+ assert result["success"] is False+ assert "PATH" in result["error"]+ assert "see docs" in result["error"]++ _run(go())