voodoo-framework 2.5.1__tar.gz → 2.6.0__tar.gz

{voodoo_framework-2.5.1/src/voodoo_framework.egg-info → voodoo_framework-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 2.5.1
+Version: 2.6.0
 Summary: The programmable runtime for adaptive applications and operational systems — web, APIs, agents, workers, human workflows, distributed systems, and physical systems in one runtime.
 Author-email: Helder Perez <contact@helderperez.com>
 Maintainer-email: Helder Perez <contact@helderperez.com>
@@ -59,6 +59,8 @@ Requires-Dist: boto3>=1.34; extra == "s3"
 Requires-Dist: botocore>=1.34; extra == "s3"
 Provides-Extra: redis
 Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: edge
+Requires-Dist: paho-mqtt>=2.0; extra == "edge"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
@@ -232,6 +234,7 @@ if __name__ == "__main__":
 | **Observability everywhere** | Correlation IDs and telemetry built into every subsystem |
 | **Unified runtime engine** | Every operation (HTTP, Agent, Tool, MCP, Worker, Human, Event) produces an `Execution` record with full traceability |
 | **Human-in-the-Loop** | `ask_human()` + `approve()`/`deny()` — humans as compute participants, not afterthoughts |
+| **Physical devices as Entities** | `voodoo-edge/v1` protocol + Device Gateway over HTTP/MQTT — ESP32s, robots, and sensors join the same execution model as agents and workers |
 | **Adaptive execution** | Planner resolves capabilities to compute participants; supervisor steers with retry, fallback, budget control |
 | **Durable by default** | Tasks, executions, schedules, and events survive process restarts — backed by SQLite out of the box |
 | **Zero-config runtime** | `voodoo create` → `voodoo dev` → working app. No build step. Add `voodoo.toml` when you need configuration |
@@ -284,6 +287,7 @@ and [`ARCHITECTURE.md`](ARCHITECTURE.md) for the implementation model.
 - **Auth** — JWT tokens, API keys, session cookies, RBAC route guards
 - **Workers** — `@task` decorator with retries, timeout, and telemetry spans
 - **Voodoo Mesh** — Realtime event bus with local + remote boundaries
+- **Edge Devices** — Device Gateway (`voodoo-edge/v1` over HTTP & MQTT): devices emit events, trigger Executions, receive Effects — see [`docs/edge/overview.md`](docs/edge/overview.md)
 
 ### Runtime & Infrastructure
 - **Runtime Engine** — Unified `ExecutionEngine` producing `Execution` records for every operation
@@ -437,6 +441,14 @@ voodoo auth secret-key
 - [Mesh](docs/mesh.md)
 - [Workers](docs/workers.md)
 
+### Edge Devices
+- [Edge Overview](docs/edge/overview.md)
+- [Edge Protocol v1](docs/edge/protocol.md)
+- [HTTP Transport](docs/edge/http.md)
+- [MQTT Transport](docs/edge/mqtt.md)
+- [Device Security](docs/edge/security.md)
+- [Reliability](docs/edge/reliability.md)
+
 ### Runtime & Operations
 - [Runtime Engine](docs/runtime.md)
 - [Planner & Adaptive Runtime](docs/adaptive.md)

{voodoo_framework-2.5.1 → voodoo_framework-2.6.0}/README.md

@@ -165,6 +165,7 @@ if __name__ == "__main__":
 | **Observability everywhere** | Correlation IDs and telemetry built into every subsystem |
 | **Unified runtime engine** | Every operation (HTTP, Agent, Tool, MCP, Worker, Human, Event) produces an `Execution` record with full traceability |
 | **Human-in-the-Loop** | `ask_human()` + `approve()`/`deny()` — humans as compute participants, not afterthoughts |
+| **Physical devices as Entities** | `voodoo-edge/v1` protocol + Device Gateway over HTTP/MQTT — ESP32s, robots, and sensors join the same execution model as agents and workers |
 | **Adaptive execution** | Planner resolves capabilities to compute participants; supervisor steers with retry, fallback, budget control |
 | **Durable by default** | Tasks, executions, schedules, and events survive process restarts — backed by SQLite out of the box |
 | **Zero-config runtime** | `voodoo create` → `voodoo dev` → working app. No build step. Add `voodoo.toml` when you need configuration |
@@ -217,6 +218,7 @@ and [`ARCHITECTURE.md`](ARCHITECTURE.md) for the implementation model.
 - **Auth** — JWT tokens, API keys, session cookies, RBAC route guards
 - **Workers** — `@task` decorator with retries, timeout, and telemetry spans
 - **Voodoo Mesh** — Realtime event bus with local + remote boundaries
+- **Edge Devices** — Device Gateway (`voodoo-edge/v1` over HTTP & MQTT): devices emit events, trigger Executions, receive Effects — see [`docs/edge/overview.md`](docs/edge/overview.md)
 
 ### Runtime & Infrastructure
 - **Runtime Engine** — Unified `ExecutionEngine` producing `Execution` records for every operation
@@ -370,6 +372,14 @@ voodoo auth secret-key
 - [Mesh](docs/mesh.md)
 - [Workers](docs/workers.md)
 
+### Edge Devices
+- [Edge Overview](docs/edge/overview.md)
+- [Edge Protocol v1](docs/edge/protocol.md)
+- [HTTP Transport](docs/edge/http.md)
+- [MQTT Transport](docs/edge/mqtt.md)
+- [Device Security](docs/edge/security.md)
+- [Reliability](docs/edge/reliability.md)
+
 ### Runtime & Operations
 - [Runtime Engine](docs/runtime.md)
 - [Planner & Adaptive Runtime](docs/adaptive.md)

{voodoo_framework-2.5.1 → voodoo_framework-2.6.0}/pyproject.toml

@@ -93,6 +93,9 @@ s3 = [
 redis = [
     "redis>=5.0",
 ]
+edge = [
+    "paho-mqtt>=2.0",
+]
 otel = [
     "opentelemetry-api>=1.20",
     "opentelemetry-sdk>=1.20",

{voodoo_framework-2.5.1 → voodoo_framework-2.6.0}/src/voodoo/__init__.py

@@ -102,7 +102,7 @@ from .ui.styles import (
 from .ui.styles.theme import Theme, ThemeColors, create_theme
 from .workers import task
 
-__version__ = "2.5.1"
+__version__ = "2.6.0"
 
 __all__ = [
     # Core runtime

{voodoo_framework-2.5.1 → voodoo_framework-2.6.0}/src/voodoo/ai/agent.py

@@ -4,14 +4,22 @@ The Agent turns a prompt into a final answer by iterating:
 
     prompt → provider → tool calls (via registry) → final
 
-``run()`` returns a full :class:`AgentRun` record with token/cost accounting;
-``stream()`` yields normalized :class:`AgentEvent` objects so the UI can react
-to agent activity in real time. Lifecycle states (created → configured →
-running → tool_call ⇄ thinking → completed | error → retry/failed) are
-captured for telemetry and surfaced through mesh events (S7-2).
-
-The ``context`` parameter is an explicit, opaque dict passed to every tool
-call; it is neither memory nor a database — keep the concepts separate.
+The Agent is a *participant* in the runtime, not a parallel execution
+framework.  ``run()`` creates an :class:`~voodoo.runtime.execution.Execution`
+via the :class:`~voodoo.runtime.engine.ExecutionEngine` so that agent
+runs share the same lifecycle, persistence, recovery, authorization and
+observability as every other execution path (HTTP, Worker, Task, MCP, …).
+
+``run()`` returns a full :class:`AgentRun` record with token/cost
+accounting; ``stream()`` yields normalized :class:`AgentEvent` objects
+so the UI can react to agent activity in real time.  Lifecycle states
+(created → configured → running → tool_call ⇄ thinking → completed |
+error → retry/failed) are captured for telemetry and surfaced through
+mesh events (S7-2).
+
+The ``context`` parameter is an explicit, opaque dict passed to every
+tool call; it is neither memory nor a database — keep the concepts
+separate.
 """
 
 from __future__ import annotations
@@ -67,7 +75,15 @@ class AgentState(StrEnum):
 
 @dataclass
 class AgentRun:
-    """Full run record with token/cost accounting."""
+    """Full run record with token/cost accounting.
+
+    This is a *projection* of the underlying
+    :class:`~voodoo.runtime.execution.Execution` — it exists for
+    backward-compatible telemetry and agent-specific accounting, not as
+    a second source of truth.  The ``execution_id`` links this record
+    to the canonical Execution; ``trace_id`` is the correlation id
+    propagated through the entire stack.
+    """
 
     run_id: str
     model: str
@@ -84,6 +100,7 @@ class AgentRun:
     started_at: float = field(default_factory=time.time)
     completed_at: float | None = None
     trace_id: str | None = None
+    execution_id: str | None = None
 
 
 @dataclass
@@ -151,6 +168,7 @@ class Agent:
         agent_id: str | None = None,
         name: str = "",
         agent_registry: Any | None = None,
+        engine: Any | None = None,
         **provider_kwargs: Any,
     ) -> None:
         self.model = model or default_model()
@@ -171,6 +189,11 @@ class Agent:
         self._agent_registry: Any | None = agent_registry
         self._registered: bool = False
 
+        # Execution engine — when set, Agent.run() creates an Execution
+        # via the engine so the run shares lifecycle, persistence,
+        # recovery and observability with every other execution path.
+        self._engine: Any | None = engine
+
         # Resolve tool specs/names into a list of names for tool calling.
         self._tool_names: list[str] = []
         if tools:
@@ -336,9 +359,22 @@ class Agent:
         """Invoke a registered tool through the runtime authorization path.
 
         Flow: Agent → Intent → capability check → Tool → Effect → Mesh.
+
+        When running inside an
+        :class:`~voodoo.runtime.engine.ExecutionEngine` Execution, each
+        tool call creates a *child* Execution so the full agent activity
+        is visible in the execution graph:
+
+        ::
+
+            Agent Execution
+                  ├── Tool Execution #1
+                  ├── Tool Execution #2
+                  └── Tool Execution #3
+
         Tools that declare ``permissions`` require a matching capability,
         granted either to this agent or held by the active runtime
-        :class:`~voodoo.runtime.context.ExecutionContext`. Unauthorized
+        :class:`~voodoo.runtime.context.ExecutionContext`.  Unauthorized
         tool calls are denied before any side effect executes.
         """
         from voodoo.primitives.effect import Effect
@@ -371,6 +407,15 @@ class Agent:
                 f"{', '.join(missing)}"
             }
 
+        # When inside an engine Execution, create a child Execution for
+        # this tool call so it appears in the execution graph.
+        engine = ctx.engine if ctx else None
+        if engine is not None:
+            return await self._execute_tool_as_child_execution(
+                engine, name, arguments, spec, ctx
+            )
+
+        # Standalone path: record as an Effect on the current context.
         effect = Effect(
             name=f"tool.{name}", capability_name=required[0] if required else None
         )
@@ -391,6 +436,56 @@ class Agent:
         await self._broadcast("tool.completed", {"tool": name, "status": "succeeded"})
         return result
 
+    async def _execute_tool_as_child_execution(
+        self,
+        engine: Any,
+        name: str,
+        arguments: dict[str, Any],
+        spec: Any,
+        parent_ctx: Any,
+    ) -> Any:
+        """Execute a tool call as a child Execution on the engine.
+
+        Creates a child Execution with its own lifecycle, capability
+        context and effect record.  The parent agent Execution's
+        capabilities propagate to the child (Step 4: capability
+        propagation).
+        """
+        from voodoo.primitives.intent import Intent
+        from voodoo.runtime.context import ExecutionContext
+
+        intent = Intent(
+            name=f"tool.{name}",
+            description=f"Tool call: {name}",
+            params={"tool": name, "arguments": arguments},
+            requires=list(spec.permissions if spec else []),
+        )
+
+        async def _tool_compute(ctx: ExecutionContext) -> Any:
+            await self._broadcast("tool.called", {"tool": name, "arguments": arguments})
+            try:
+                result = await self.registry.call(name, **arguments)
+                await self._broadcast(
+                    "tool.completed",
+                    {"tool": name, "status": "succeeded"},
+                )
+                return result
+            except Exception as e:  # noqa: BLE001
+                await self._broadcast(
+                    "tool.completed",
+                    {"tool": name, "status": "failed", "error": str(e)},
+                )
+                return {"error": str(e)}
+
+        execution = await engine.execute(
+            intent,
+            _tool_compute,
+            actor=f"agent:{self.agent_id}",
+            capabilities=list(spec.permissions if spec else []),
+            parent=parent_ctx,
+        )
+        return execution.result
+
     # -- run ---------------------------------------------------------------
 
     async def run(
@@ -401,12 +496,126 @@ class Agent:
     ) -> AgentRun:
         """Execute prompt → provider → tool calls → final; return AgentRun.
 
+        When an :class:`~voodoo.runtime.engine.ExecutionEngine` is
+        available (either passed at construction or attached to the
+        active :class:`~voodoo.runtime.context.ExecutionContext`), the
+        run creates a first-class
+        :class:`~voodoo.runtime.execution.Execution` so it shares
+        lifecycle, persistence, recovery and observability with every
+        other execution path.
+
         ``history`` prepends prior conversation turns (a list of ``Message``
         dicts) before the new user prompt, enabling multi-turn chat.
         """
-        run_id = str(uuid.uuid4())
+        from voodoo.runtime.context import current_context
+
+        # Resolve the engine: explicit on the agent, or from the active
+        # context (set by ExecutionEngine._run_compute), or None.
+        ctx = current_context()
+        engine = self._engine or (ctx.engine if ctx else None)
+
+        if engine is not None:
+            return await self._run_via_engine(
+                engine, prompt, context=context, history=history, parent_ctx=ctx
+            )
+        return await self._run_standalone(prompt, context=context, history=history)
+
+    # -- engine-backed run -------------------------------------------------
+
+    async def _run_via_engine(
+        self,
+        engine: Any,
+        prompt: str,
+        *,
+        context: dict | None = None,
+        history: list[Message] | None = None,
+        parent_ctx: Any | None = None,
+    ) -> AgentRun:
+        """Run the agent loop inside an ExecutionEngine Execution.
+
+        The engine owns lifecycle, persistence, recovery and
+        observability.  The agent's provider loop is the *compute*
+        participant — it receives an
+        :class:`~voodoo.runtime.context.ExecutionContext` and returns a
+        :class:`~voodoo.runtime.engine.ComputeResult`.
+        """
+        from voodoo.primitives.intent import Intent
+        from voodoo.runtime.context import ExecutionContext
+
+        # Build the intent that represents this agent run.
+        intent = Intent(
+            name=f"agent.{self.name or self.agent_id}",
+            description=prompt[:200],
+            params={"prompt": prompt, "model": self.model},
+        )
+
+        # The compute function encapsulates the entire provider loop.
+        async def _agent_compute(ctx: ExecutionContext) -> Any:
+            return await self._provider_loop(
+                prompt, context=context, history=history, run_id=ctx.execution_id
+            )
+
+        # Execute through the engine — this creates the Execution,
+        # manages lifecycle, persists, and records telemetry.
+        execution = await engine.execute(
+            intent,
+            _agent_compute,
+            actor=f"agent:{self.agent_id}",
+            capabilities=self.capabilities or None,
+            parent=parent_ctx,
+        )
+
+        # Build the AgentRun projection from the Execution.
+        compute_result = execution.result
+        if isinstance(compute_result, AgentRun):
+            compute_result.execution_id = execution.id
+            return compute_result
+
+        # Fallback: wrap unexpected result types.
+        return AgentRun(
+            run_id=execution.id,
+            model=self.model,
+            provider=self.provider.name,
+            prompt=prompt,
+            output=str(compute_result) if compute_result is not None else "",
+            status=execution.status.value,
+            error=execution.error,
+            started_at=execution._started_ts or time.time(),
+            completed_at=execution._completed_ts,
+            trace_id=execution.trace_id,
+            execution_id=execution.id,
+        )
+
+    async def _run_standalone(
+        self,
+        prompt: str,
+        *,
+        context: dict | None = None,
+        history: list[Message] | None = None,
+    ) -> AgentRun:
+        """Run the agent loop without an engine (backward-compatible).
+
+        Used when no ExecutionEngine is available.  Still produces a
+        valid AgentRun with telemetry and memory writes.
+        """
+        return await self._provider_loop(prompt, context=context, history=history)
+
+    async def _provider_loop(
+        self,
+        prompt: str,
+        *,
+        context: dict | None = None,
+        history: list[Message] | None = None,
+        run_id: str | None = None,
+    ) -> AgentRun:
+        """The core provider loop shared by engine-backed and standalone runs.
+
+        When ``run_id`` is ``None``, a new UUID is generated.  When
+        called inside an engine Execution, ``run_id`` is the execution id.
+        """
         from voodoo.telemetry import telemetry_store
 
+        run_id = run_id or str(uuid.uuid4())
         trace_id = (
             telemetry_store.trace_id_var.get()
             if hasattr(telemetry_store, "trace_id_var")

{voodoo_framework-2.5.1 → voodoo_framework-2.6.0}/src/voodoo/config.py

@@ -255,6 +255,37 @@ class AIConfig(BaseModel):
     aliases: dict[str, str] = Field(default_factory=dict)
 
 
+class EdgeConfig(BaseModel):
+    """Edge device gateway configuration (``edge:`` block) — Sprint 23.
+
+    Edge is disabled by default: users who never enable it pay zero
+    overhead and need no MQTT broker, device tables, or gateway
+    (EDGE §68 — backwards compatibility).
+    """
+
+    enabled: bool = False
+    http_enabled: bool = True
+    mqtt_enabled: bool = False
+    # Optional separate listener for the edge gateway; when empty the
+    # edge routes mount onto the main app instead.
+    http_host: str = ""
+    http_port: int = 0
+    # MQTT broker connection (EDGE §35, §38).
+    mqtt_broker_url: str = ""
+    mqtt_port: int = 1883
+    mqtt_tls: bool = False
+    mqtt_username: str = ""
+    mqtt_password: str = ""
+    mqtt_client_id: str = "voodoo-runtime"
+    mqtt_keepalive: int = 60
+    mqtt_qos: int = 1
+    # Resource limits (EDGE §76).
+    max_message_size: int = 262144  # 256 KiB
+    max_state_size: int = 65536  # 64 KiB
+    max_pending_effects: int = 1000
+    heartbeat_interval: int = 30
+
+
 class VoodooConfig(BaseModel):
     """Core configuration for the Voodoo framework."""
 
@@ -276,6 +307,7 @@ class VoodooConfig(BaseModel):
     cache: CacheConfig = Field(default_factory=CacheConfig)
     models: ModelsConfig = Field(default_factory=ModelsConfig)
     ai: AIConfig = Field(default_factory=AIConfig)
+    edge: EdgeConfig = Field(default_factory=EdgeConfig)
 
     seo: SEOConfig = Field(default_factory=SEOConfig)
     auth: AuthConfig = Field(default_factory=AuthConfig)
@@ -458,6 +490,54 @@ def _build_ai_config(file_data: dict[str, Any]) -> AIConfig:
     )
 
 
+def _build_edge_config(file_data: dict[str, Any]) -> EdgeConfig:
+    """Merge file ``edge:`` block with ``VOODOO_EDGE_*``/``MQTT_*`` env vars."""
+    edge_data = file_data.get("edge") or {}
+    if not isinstance(edge_data, dict):
+        edge_data = {"enabled": bool(edge_data)}
+
+    def _flag(key: str, env: str) -> bool | None:
+        if key in edge_data:
+            return bool(edge_data[key])
+        val = _env_flag(env)
+        return val
+
+    enabled = _flag("enabled", "VOODOO_EDGE_ENABLED")
+    mqtt = edge_data.get("mqtt") or {}
+    if not isinstance(mqtt, dict):
+        mqtt = {}
+
+    kwargs: dict[str, Any] = {
+        "enabled": enabled if enabled is not None else False,
+        "http_enabled": (_flag("http_enabled", "VOODOO_EDGE_HTTP_ENABLED") or False)
+        if "http_enabled" in edge_data or "VOODOO_EDGE_HTTP_ENABLED" in os.environ
+        else True,
+        "mqtt_enabled": (_flag("mqtt_enabled", "VOODOO_EDGE_MQTT_ENABLED") or False)
+        if "mqtt_enabled" in edge_data or "VOODOO_EDGE_MQTT_ENABLED" in os.environ
+        else (bool(mqtt) or "MQTT_BROKER_URL" in os.environ),
+        "mqtt_broker_url": mqtt.get("broker_url") or os.getenv("MQTT_BROKER_URL", ""),
+        "mqtt_port": int(mqtt.get("port") or os.getenv("MQTT_PORT", "1883")),
+        "mqtt_tls": bool(mqtt.get("tls") or _env_flag("MQTT_TLS") or False),
+        "mqtt_username": mqtt.get("username") or os.getenv("MQTT_USERNAME", ""),
+        "mqtt_password": mqtt.get("password") or os.getenv("MQTT_PASSWORD", ""),
+        "mqtt_client_id": mqtt.get("client_id")
+        or os.getenv("MQTT_CLIENT_ID", "voodoo-runtime"),
+        "mqtt_keepalive": int(mqtt.get("keepalive", 60)),
+        "mqtt_qos": int(mqtt.get("qos", 1)),
+    }
+    for key in (
+        "max_message_size",
+        "max_state_size",
+        "max_pending_effects",
+        "heartbeat_interval",
+        "http_host",
+        "http_port",
+    ):
+        if key in edge_data:
+            kwargs[key] = edge_data[key]
+    return EdgeConfig(**kwargs)
+
+
 def _pick(
     file_data: dict[str, Any],
     key: str,
@@ -551,6 +631,7 @@ def get_config(
     config_args["cache"] = _build_cache_config(file_data)
     config_args["models"] = _build_models_config(file_data)
     config_args["ai"] = _build_ai_config(file_data)
+    config_args["edge"] = _build_edge_config(file_data)
 
     # Existing sub-configurations
     if "seo" in file_data and isinstance(file_data["seo"], dict):
@@ -578,6 +659,7 @@ def get_config(
         "cache",
         "models",
         "ai",
+        "edge",
         "seo",
         "auth",
         "security",

{voodoo_framework-2.5.1 → voodoo_framework-2.6.0}/src/voodoo/core/app.py

@@ -241,6 +241,22 @@ def create_app(app_dir: str = "app") -> Starlette:  # noqa: C901
 
     routes.extend(voodoo_api.routes)
 
+    # --- Edge device gateway (Sprint 23, EDGE §68) -------------------------
+    # Entirely optional: when ``edge.enabled`` is False, no store, gateway,
+    # routes, or MQTT client are created — regular apps pay zero overhead.
+    edge_gateway: list = []  # mutable holder so lifespan can share/replace the gateway
+    if config.edge.enabled and config.edge.http_enabled:
+        from voodoo.edge import DeviceGateway, SQLiteDeviceStore
+
+        edge_store = SQLiteDeviceStore(".voodoo/state/devices.db")
+        from voodoo.runtime.engine import engine as _runtime_engine
+
+        gateway = DeviceGateway(edge_store, _runtime_engine)
+        edge_gateway.append(gateway)
+        from voodoo.edge.http import build_edge_routes as _build_edge_routes
+
+        routes.extend(_build_edge_routes(gateway))
+
     from voodoo.auth import AuthMiddleware
     from voodoo.i18n import I18nMiddleware
     from voodoo.security import (
@@ -290,8 +306,39 @@ def create_app(app_dir: str = "app") -> Starlette:  # noqa: C901
 
         if _workers:
             worker_task = asyncio.create_task(start_workers())
+
+        # Edge MQTT transport (Sprint 23) — optional, only when configured.
+        mqtt_transport = None
+        if config.edge.enabled and config.edge.mqtt_enabled:
+            try:
+                from voodoo.edge import DeviceGateway as _DG
+                from voodoo.edge import SQLiteDeviceStore as _SDS
+                from voodoo.edge.mqtt import EdgeMQTTTransport
+                from voodoo.runtime.engine import engine as _rt_engine
+
+                gateway = (
+                    edge_gateway[0]
+                    if edge_gateway
+                    else _DG(_SDS(".voodoo/state/devices.db"), _rt_engine)
+                )
+                mqtt_transport = EdgeMQTTTransport(
+                    gateway,
+                    broker_url=config.edge.mqtt_broker_url or "localhost",
+                    port=config.edge.mqtt_port,
+                    tls=config.edge.mqtt_tls,
+                    username=config.edge.mqtt_username or None,
+                    password=config.edge.mqtt_password or None,
+                    client_id=config.edge.mqtt_client_id,
+                    qos=config.edge.mqtt_qos,
+                )
+                await mqtt_transport.start()
+            except ImportError:
+                # paho-mqtt not installed — edge stays HTTP-only.
+                pass
         yield
         # Shutdown
+        if mqtt_transport is not None:
+            await mqtt_transport.stop()
         await stop_workers()
         if worker_task:
             worker_task.cancel()