machinaos 0.0.78 → 0.0.80

package/server/services/temporal/__init__.py

@@ -17,7 +17,28 @@ When TEMPORAL_ENABLED=false:
 - Falls back to the existing parallel/sequential executor
 """
 
-__all__ = ["TemporalExecutor", "TemporalClientWrapper"]
+__all__ = [
+    "TemporalExecutor",
+    "TemporalClientWrapper",
+    "TemporalServerRuntime",
+    "get_temporal_server_runtime",
+]
 
 from .executor import TemporalExecutor
 from .client import TemporalClientWrapper
+from ._runtime import (
+    TemporalServerRuntime,
+    get_temporal_server_runtime,
+)
+
+# ---- self-registration (Wave 11 plugin-folder pattern) -------------------
+# WS handlers (temporal_status / _start / _stop) + WS-connect refresh
+# (broadcasts current Temporal snapshot). Registries are idempotent on
+# re-import; same callable for same key is a no-op.
+from ._handlers import WS_HANDLERS as _WS_HANDLERS
+from ._refresh import refresh_temporal_status as _refresh_temporal_status
+from services.ws_handler_registry import register_ws_handlers
+from services.status_broadcaster import register_service_refresh
+
+register_ws_handlers(_WS_HANDLERS)
+register_service_refresh(_refresh_temporal_status)

package/server/services/temporal/_handlers.py

@@ -0,0 +1,65 @@
+"""WebSocket handlers for the Temporal lifecycle commands.
+
+Wire keys registered in :mod:`services.ws_handler_registry`:
+
+  - ``temporal_status``  → status snapshot of the runtime
+  - ``temporal_start``   → idempotent start
+  - ``temporal_stop``    → idempotent stop
+
+All three share the snapshot shape from
+:func:`services.temporal._refresh.temporal_status_snapshot` — the
+single source of truth for the ``{temporal}`` payload that the
+WS-connect refresh callback also emits.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import WebSocket
+
+from core.logging import get_logger
+from services.temporal._refresh import temporal_status_snapshot
+
+logger = get_logger(__name__)
+
+
+async def handle_temporal_status(
+    data: dict[str, Any],
+    websocket: WebSocket,
+) -> dict[str, Any]:
+    """Return the status snapshot for the Temporal runtime."""
+    return temporal_status_snapshot()
+
+
+async def handle_temporal_start(
+    data: dict[str, Any],
+    websocket: WebSocket,
+) -> dict[str, Any]:
+    """Start Temporal. Idempotent — ``.start()`` returns immediately if
+    the runtime is already running."""
+    from services.temporal._runtime import get_temporal_server_runtime
+
+    await get_temporal_server_runtime().start()
+    return {"ok": True, **temporal_status_snapshot()}
+
+
+async def handle_temporal_stop(
+    data: dict[str, Any],
+    websocket: WebSocket,
+) -> dict[str, Any]:
+    """Stop Temporal. Idempotent."""
+    from services.temporal._runtime import get_temporal_server_runtime
+
+    await get_temporal_server_runtime().stop()
+    return {"ok": True, **temporal_status_snapshot()}
+
+
+WS_HANDLERS: dict[str, Any] = {
+    "temporal_status": handle_temporal_status,
+    "temporal_start": handle_temporal_start,
+    "temporal_stop": handle_temporal_stop,
+}
+
+
+__all__ = ["WS_HANDLERS"]

package/server/services/temporal/_install.py

@@ -0,0 +1,158 @@
+"""Cross-platform Temporal CLI binary downloader using pooch.
+
+Downloads the official ``temporal`` CLI from the URL documented at
+https://docs.temporal.io/develop/python/set-up-your-local-python
+(``temporal.download/cli/archive/latest?platform=<os>&arch=<arch>``).
+
+Pooch handles XDG-aware cross-platform caching and archive extraction
+(zip on Windows, tar.gz elsewhere). The ``latest`` URL rotates as new
+CLI versions ship, so the download is unverified (TLS gives transport
+integrity); pooch caches by local filename, not URL contents, so
+re-runs after the first fetch are instant cache hits.
+
+The downloaded ``temporal`` CLI powers ``temporal server start-dev``
+(the SQLite/in-memory dev server) and ad-hoc workflow / operator
+commands.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import platform
+import stat
+from pathlib import Path
+
+import pooch
+
+from core.config import Settings
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+# Official Temporal CLI download URL. Per the docs at
+# https://docs.temporal.io/develop/python/set-up-your-local-python the
+# CLI archive lives at ``temporal.download/cli/archive/latest`` with
+# ``platform`` and ``arch`` query parameters. Contains a single
+# ``temporal`` binary.
+_CLI_BASE_URL = "https://temporal.download/cli/archive/latest"
+_CLI_PLATFORM_MAP: dict[tuple[str, str], tuple[str, str]] = {
+    # platform.system, platform.machine -> (URL platform, URL arch)
+    ("Linux", "x86_64"): ("linux", "amd64"),
+    ("Linux", "aarch64"): ("linux", "arm64"),
+    ("Darwin", "x86_64"): ("darwin", "amd64"),
+    ("Darwin", "arm64"): ("darwin", "arm64"),
+    ("Windows", "AMD64"): ("windows", "amd64"),
+    ("Windows", "ARM64"): ("windows", "arm64"),
+}
+
+# pooch cache namespace. Pooch's own cache layout includes the asset
+# URL so versions don't collide.
+_CACHE_NAMESPACE = "machinaos-temporal"
+
+
+_cached: dict[str, Path] | None = None
+_lock = asyncio.Lock()
+
+
+async def ensure_temporal_binaries(
+    settings: Settings | None = None,
+) -> dict[str, Path]:
+    """Return ``{"temporal": Path}`` — the official ``temporal`` CLI binary.
+
+    Idempotent — first call downloads, subsequent calls hit the pooch
+    cache (XDG / OS-conventional dir). Async-locked so concurrent
+    callers don't double-download.
+
+    The ``settings`` argument is accepted for API symmetry but currently
+    unused — the official ``latest`` URL has no version slot to override.
+    """
+    global _cached
+    # settings accepted for API symmetry; no fields consulted (the
+    # ``latest`` URL has no version slot).
+    _ = settings
+
+    async with _lock:
+        if _cached is not None:
+            return _cached
+        cli_path = await asyncio.to_thread(_fetch_cli_sync)
+        _cached = {"temporal": cli_path}
+        logger.info(
+            "[Temporal install] binary ready: %s",
+            {k: str(v) for k, v in _cached.items()},
+        )
+        return _cached
+
+
+def _fetch_cli_sync() -> Path:
+    """Download the official ``temporal`` CLI archive and return the binary path.
+
+    Uses ``pooch.retrieve`` with ``known_hash=None`` because the
+    ``temporal.download/cli/archive/latest`` URL rotates as new CLI
+    versions ship — pinning a SHA would defeat the "latest" semantics
+    the official docs document. TLS gives us transport integrity.
+    """
+    key = (platform.system(), platform.machine())
+    if key not in _CLI_PLATFORM_MAP:
+        raise RuntimeError(f"[Temporal install] Unsupported platform for CLI: {key}. " f"Supported: {sorted(_CLI_PLATFORM_MAP.keys())}")
+    url_platform, url_arch = _CLI_PLATFORM_MAP[key]
+    url = f"{_CLI_BASE_URL}?platform={url_platform}&arch={url_arch}"
+
+    is_windows = platform.system() == "Windows"
+    fname = f"temporal_cli_latest_{url_platform}_{url_arch}.{'zip' if is_windows else 'tar.gz'}"
+    processor = pooch.Unzip() if is_windows else pooch.Untar()
+
+    extracted = pooch.retrieve(
+        url=url,
+        known_hash=None,
+        path=pooch.os_cache(_CACHE_NAMESPACE),
+        fname=fname,
+        processor=processor,
+        progressbar=True,
+    )
+
+    target = "temporal.exe" if is_windows else "temporal"
+    match = next((Path(p) for p in extracted if Path(p).name == target), None)
+    if match is None:
+        raise RuntimeError(
+            f"[Temporal install] CLI binary {target!r} not found in archive. " f"Extracted files: {[Path(p).name for p in extracted]}"
+        )
+    if not is_windows:
+        mode = match.stat().st_mode
+        match.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return match
+
+
+__all__ = ["ensure_temporal_binaries"]
+
+
+def _main() -> int:
+    """Standalone entry: ``python -m services.temporal._install``.
+
+    Used by ``machina build`` step [6/6] to materialise the Temporal
+    CLI at build time instead of paying the download cost on first
+    ``machina start``. Fetches, verifies the binary exists on disk,
+    prints the resolved location. Non-zero exit on any failure.
+    """
+    import sys as _sys
+
+    try:
+        paths = asyncio.run(ensure_temporal_binaries())
+    except Exception as exc:  # noqa: BLE001 — propagate to non-zero exit
+        print(f"[Temporal install] {exc}", file=_sys.stderr)
+        return 1
+
+    missing = [name for name, path in paths.items() if not path.exists()]
+    if missing:
+        print(
+            f"[Temporal install] binaries missing after fetch: {missing}",
+            file=_sys.stderr,
+        )
+        return 1
+
+    for name, path in paths.items():
+        print(f"  {name}: {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

package/server/services/temporal/_refresh.py

@@ -0,0 +1,57 @@
+"""WS-connect status broadcast for the Temporal stack.
+
+Registered via ``status_broadcaster.register_service_refresh`` so the
+frontend health indicator stays current — every WebSocket client
+connect triggers ``_refresh_all_services()`` which fans out to every
+registered callback. Same idiom :mod:`nodes.telegram._refresh` uses.
+
+Also exposes :func:`temporal_status_snapshot` — the single source of
+truth for the ``{temporal}`` status shape consumed by both this refresh
+callback and ``_handlers.py``'s WS commands.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from core.logging import get_logger
+
+if TYPE_CHECKING:
+    from services.status_broadcaster import StatusBroadcaster
+
+logger = get_logger(__name__)
+
+
+def temporal_status_snapshot() -> dict[str, Any]:
+    """Return ``{"temporal": {...}}`` snapshot.
+
+    Exposes the uniform ``{name, running, started_at, last_error,
+    ...extras}`` shape every ``BaseSupervisor`` subclass returns.
+    Shared by the WS-refresh callback below and the
+    ``temporal_status`` / ``_start`` / ``_stop`` handlers in
+    :mod:`services.temporal._handlers`.
+    """
+    from services.temporal._runtime import get_temporal_server_runtime
+
+    return {"temporal": get_temporal_server_runtime().status_snapshot()}
+
+
+async def refresh_temporal_status(broadcaster: "StatusBroadcaster") -> None:
+    """Broadcast the Temporal status snapshot on WS connect.
+
+    Signature matches the ``register_service_refresh`` callback contract
+    — :meth:`StatusBroadcaster._refresh_all_services` invokes every
+    registered callback as ``callback(self)`` (passes the broadcaster
+    as the sole positional argument). Without the parameter the
+    framework's ``TaskGroup`` swallows a ``TypeError: takes 0 positional
+    arguments but 1 was given`` on every server boot.
+    """
+    await broadcaster.broadcast(
+        {
+            "type": "temporal_status",
+            "data": temporal_status_snapshot(),
+        }
+    )
+
+
+__all__ = ["refresh_temporal_status", "temporal_status_snapshot"]

package/server/services/temporal/_retry_policies.py

@@ -0,0 +1,85 @@
+"""Wave 12 D1: shared Temporal RetryPolicy constants.
+
+Replaces the duplicated inline ``RetryPolicy(1s, 30s, 3 attempts)``
+declarations that lived in ``services/temporal/workflow.py:246`` and
+``services/temporal/agent_workflow.py:76`` (identical knobs, hand-typed
+twice). Adds the missing ``non_retryable_error_types`` declaration so
+``NodeUserError`` (user-correctable failures: missing required field,
+unknown enum value, bad regex) fails fast instead of burning all three
+retry attempts.
+
+Why these specific error types are non-retryable
+------------------------------------------------
+
+- ``NodeUserError``: every plugin raises this for user-correctable
+  failures (see ``services/plugin/__init__.py``). Retrying just spends
+  retry budget — the input won't be different next time. The plugin
+  ``cls.retry_policy`` default already lists it as non-retryable
+  (Wave 12 A2, ``services/plugin/scaling.py``), but the WORKFLOW-side
+  ``workflow.execute_activity(..., retry_policy=...)`` override
+  silently lost that contract when the workflow author hand-typed a
+  fresh ``RetryPolicy(...)``. This module re-imposes it at the
+  workflow callsite.
+
+- ``InvalidEvent``: when ``services/events/dispatch.py:emit`` raises
+  on a malformed envelope (missing ``id``, bad ``source``), the
+  activity's input is structurally broken and retries can't fix it.
+
+Keep this list short. Adding error types here is a runtime contract
+change — every workflow that uses these policies inherits the
+non-retryability. Use ``cls.retry_policy.non_retryable_error_types``
+on a specific plugin class when only ONE plugin's failure should be
+non-retryable.
+
+Refs
+----
+- https://docs.temporal.io/encyclopedia/retry-policies
+- https://python.temporal.io/temporalio.common.RetryPolicy.html
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+from temporalio.common import RetryPolicy
+
+
+# Error types that surface user mistakes / structural payload bugs —
+# retrying makes no difference. Plugin classes that raise their own
+# domain-specific non-retryable errors should override
+# ``cls.retry_policy`` rather than expand this list.
+NON_RETRYABLE_ERROR_TYPES: tuple[str, ...] = (
+    "NodeUserError",
+    "InvalidEvent",
+)
+
+
+# Default activity policy for the orchestrator (MachinaWorkflow,
+# AgentWorkflow, PollingTriggerWorkflow). 3 attempts with 1s→30s
+# exponential backoff covers transient API blips (DNS, rate limits,
+# brief upstream outages) without holding the whole graph hostage to a
+# persistent failure.
+DEFAULT_ACTIVITY_RETRY: RetryPolicy = RetryPolicy(
+    initial_interval=timedelta(seconds=1),
+    maximum_interval=timedelta(seconds=30),
+    maximum_attempts=3,
+    non_retryable_error_types=list(NON_RETRYABLE_ERROR_TYPES),
+)
+
+
+# Tighter policy for activities that are themselves cheap operations
+# (e.g. ``emit_event_activity``, ``broadcast_progress``). Failing fast
+# here surfaces wiring bugs in tests + ops without retry-budget noise.
+QUICK_ACTIVITY_RETRY: RetryPolicy = RetryPolicy(
+    initial_interval=timedelta(milliseconds=250),
+    maximum_interval=timedelta(seconds=5),
+    maximum_attempts=2,
+    non_retryable_error_types=list(NON_RETRYABLE_ERROR_TYPES),
+)
+
+
+__all__ = [
+    "NON_RETRYABLE_ERROR_TYPES",
+    "DEFAULT_ACTIVITY_RETRY",
+    "QUICK_ACTIVITY_RETRY",
+]

package/server/services/temporal/_runtime.py

@@ -0,0 +1,181 @@
+"""Temporal server lifecycle.
+
+Single supervisor subclass: :class:`TemporalServerRuntime`. Spawns the
+official ``temporal`` CLI (downloaded by :mod:`services.temporal._install`
+from https://temporal.download/cli/archive/latest) with the
+``server start-dev`` subcommand against a SQLite db. Matches the local
+dev install method documented at
+https://docs.temporal.io/develop/python/set-up-your-local-python.
+
+Uses the singleton accessor pattern (``Class.get_instance()``) from
+``BaseSupervisor`` — same idiom :mod:`nodes.whatsapp._runtime` uses for
+``WhatsAppRuntime``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+from core.config import Settings
+from core.logging import get_logger
+from services._supervisor import BaseProcessSupervisor
+
+logger = get_logger(__name__)
+
+# How long each TCP-readiness probe waits per attempt. Sub-second so a
+# stalled subprocess fails health fast.
+_PROBE_TIMEOUT_SECONDS = 1.0
+
+
+async def _probe_tcp_port(port: int, host: str = "127.0.0.1") -> bool:
+    """Return ``True`` iff a TCP connection to ``host:port`` succeeds
+    within :data:`_PROBE_TIMEOUT_SECONDS`. Loopback-friendly readiness
+    check used by ``health_check``. Mirrors :func:`cli.tcp.probe_tcp_port`
+    but keeps server-side modules independent of the ``cli`` CLI package."""
+    try:
+        _, writer = await asyncio.wait_for(
+            asyncio.open_connection(host, port),
+            timeout=_PROBE_TIMEOUT_SECONDS,
+        )
+        writer.close()
+        try:
+            await writer.wait_closed()
+        except (ConnectionResetError, OSError):
+            pass
+        return True
+    except (asyncio.TimeoutError, ConnectionRefusedError, OSError):
+        return False
+
+
+class TemporalServerRuntime(BaseProcessSupervisor):
+    """Temporal dev server, supervised via BaseProcessSupervisor.
+
+    Spawns ``temporal server start-dev`` against a SQLite db at
+    ``settings.temporal_sqlite_path``. The ``temporal`` CLI binary is
+    downloaded by :func:`services.temporal._install.ensure_temporal_binaries`
+    from the official URL at
+    https://temporal.download/cli/archive/latest.
+
+    Path is env-driven via ``settings.temporal_sqlite_path``, resolved
+    relative to ``settings.data_dir`` unless already absolute.
+    """
+
+    name = "temporal"
+    pipe_streams = True
+    graceful_shutdown = sys.platform == "win32"
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        super().__init__()
+        if settings is None:
+            settings = Settings()
+        self.settings = settings
+        # SIGTERM grace = settings.temporal_graceful_shutdown_seconds —
+        # same knob already documented for the embedded Temporal worker.
+        self.terminate_grace_seconds = float(
+            settings.temporal_graceful_shutdown_seconds,
+        )
+        self._binaries: Optional[dict[str, Path]] = None
+
+    @property
+    def _sqlite_path(self) -> Path:
+        """Env-driven SQLite db path (``TEMPORAL_SQLITE_PATH``),
+        resolved relative to ``DATA_DIR`` unless absolute."""
+        return Path(self.settings._resolve_under_data(self.settings.temporal_sqlite_path))
+
+    # ---- BaseProcessSupervisor overrides ---------------------------------
+
+    async def _pre_spawn(self) -> None:
+        from services.temporal._install import ensure_temporal_binaries
+
+        self._binaries = await ensure_temporal_binaries(self.settings)
+        # Ensure the parent dir for the SQLite file exists before
+        # ``temporal server start-dev`` opens it.
+        self._sqlite_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def binary_path(self) -> Path:
+        # ``_pre_spawn`` (called by ``BaseProcessSupervisor._do_start``
+        # before this method) populates ``self._binaries`` via the
+        # pooch downloader. Loud failure if that contract regresses.
+        assert self._binaries is not None, f"[{self.label}] binary_path() called before _pre_spawn() " "populated self._binaries"
+        return self._binaries["temporal"]
+
+    def argv(self) -> list[str]:
+        # ``temporal server start-dev`` is the official subcommand for
+        # the SQLite-backed dev server. Flags documented at
+        # https://docs.temporal.io/cli/server (subset we use):
+        #   --port           frontend gRPC port (gates ready-probe)
+        #   --ui-port        Web UI port (default ``--port + 1000``)
+        #   --db-filename    SQLite file — preserves history across
+        #                    restarts. Running workflows are not
+        #                    auto-resumed; see ``TemporalClientWrapper.
+        #                    terminate_running_workflows`` (run from
+        #                    ``main.py`` lifespan) for the boot-time
+        #                    terminate-but-preserve-history behaviour.
+        #   --metrics-port   0 disables the Prometheus endpoint
+        #   --log-level      warn keeps the supervisor log readable
+        #   --namespace      default namespace bootstrapped at start
+        return [
+            str(self.binary_path()),
+            "server",
+            "start-dev",
+            "--port",
+            str(self.settings.temporal_frontend_grpc_port),
+            "--ui-port",
+            str(self.settings.temporal_ui_port),
+            "--db-filename",
+            str(self._sqlite_path),
+            "--metrics-port",
+            "0",
+            "--log-level",
+            "warn",
+            "--namespace",
+            self.settings.temporal_namespace,
+        ]
+
+    def cwd(self) -> Path:
+        # Land any incidental output / log files next to the SQLite
+        # file (when persisting) or under DATA_DIR (when in-memory) —
+        # either way, never the supervisor's own working directory.
+        return self._sqlite_path.parent
+
+    def env(self) -> dict[str, str]:
+        # ``temporal server start-dev`` reads everything from argv flags;
+        # inherit parent env only.
+        return {**os.environ}
+
+    async def health_check(self) -> bool:
+        if not self.is_running():
+            return False
+        # gRPC frontend port — configured via
+        # ``settings.temporal_frontend_grpc_port``. Same shared probe
+        # MachinaOS uses for every other supervised TCP service.
+        return await _probe_tcp_port(self.settings.temporal_frontend_grpc_port)
+
+    def _extra_status(self) -> dict[str, Any]:
+        base = super()._extra_status()
+        return {
+            **base,
+            "grpc_port": self.settings.temporal_frontend_grpc_port,
+            "ui_port": self.settings.temporal_ui_port,
+            "sqlite_path": str(self._sqlite_path),
+        }
+
+
+# ---- module-level singleton accessor ------------------------------------
+
+
+def get_temporal_server_runtime(
+    settings: Optional[Settings] = None,
+) -> TemporalServerRuntime:
+    """Return the Temporal server runtime singleton."""
+    return TemporalServerRuntime.get_instance(settings)
+
+
+__all__ = [
+    "TemporalServerRuntime",
+    "get_temporal_server_runtime",
+]

package/server/services/temporal/_supervised_runtime.py

@@ -0,0 +1,102 @@
+"""Generic bridge: run any ``BaseSupervisor`` singleton from a CLI.
+
+The CLI's ``Manager`` supervisor (``cli/supervisor.py``) schedules
+``ServiceSpec`` entries by spawning a subprocess and supervising it.
+``BaseSupervisor``-managed runtimes (e.g. the Temporal CLI dev server)
+don't ship a CLI of their own -- they're Python singletons started via
+``await runtime.start()``.
+
+This shim bridges the two: import a runtime factory by dotted path,
+call it, ``await singleton.start()``, then block on a shutdown signal.
+``Manager`` sends SIGTERM during graceful shutdown; we catch it,
+``await singleton.stop()``, then exit cleanly.
+
+Module location: this lives inside the ``server`` package because the
+factory targets it resolves
+(``services.temporal._runtime:get_temporal_server_runtime``) are
+server-side singletons. Hosting the shim here keeps the CLI free of
+server-side imports and lets a single ``uv run python -m
+services.temporal._supervised_runtime <factory>`` invocation work
+against the workspace ``.venv`` -- no PYTHONPATH composition, no
+cross-venv plumbing.
+
+Invocation (inside ``ServiceSpec.argv``, built via ``cli.run.uv_run``):
+
+    uv_run("python", "-m",
+           "services.temporal._supervised_runtime",
+           "services.temporal._runtime:get_temporal_server_runtime")
+
+Equivalent to (Python idiom):
+
+    from services.temporal._runtime import get_temporal_server_runtime
+    runtime = get_temporal_server_runtime()
+    await runtime.start()
+    await asyncio.Event().wait()  # block on signal
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import signal
+import sys
+from typing import Awaitable, Callable
+
+
+def _resolve(dotted: str) -> Callable[[], Awaitable[None]]:
+    """Resolve ``module.path:attr`` to a callable factory."""
+    if ":" not in dotted:
+        raise SystemExit(f"factory must be 'module.path:attr', got {dotted!r}")
+    mod_path, attr = dotted.split(":", 1)
+    mod = importlib.import_module(mod_path)
+    factory = getattr(mod, attr, None)
+    if factory is None:
+        raise SystemExit(f"{mod_path}.{attr} not found")
+    return factory
+
+
+async def _run(factory_dotted: str) -> int:
+    factory = _resolve(factory_dotted)
+    runtime = factory()
+    stop = asyncio.Event()
+
+    def _on_signal() -> None:
+        if not stop.is_set():
+            stop.set()
+
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, _on_signal)
+        except NotImplementedError:
+            # Windows: add_signal_handler raises for SIGTERM. The
+            # Manager supervisor's tree-kill semantics (psutil-based)
+            # work regardless -- we just lose the graceful path on Win.
+            pass
+
+    print(f"[supervised_runtime] starting {factory_dotted}", flush=True)
+    try:
+        await runtime.start()
+        print(f"[supervised_runtime] {factory_dotted} ready", flush=True)
+        await stop.wait()
+    finally:
+        print(f"[supervised_runtime] stopping {factory_dotted}", flush=True)
+        await runtime.stop()
+    return 0
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print(
+            "usage: python -m services.temporal._supervised_runtime " "<module.path:factory>",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        return asyncio.run(_run(sys.argv[1]))
+    except KeyboardInterrupt:
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())