Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(temporal): plugin-folder pattern + pooch + pgserver — replaces temporal-server npm package
trohitg6c8fc9ea88d6
diff --git a/.env.template b/.env.templateindex 94be0351..390e558c 100644--- a/.env.template+++ b/.env.template@@ -47,6 +47,7 @@ TEMPORAL_NAMESPACE=defaultTEMPORAL_TASK_QUEUE=machina-tasksTEMPORAL_PER_TYPE_DISPATCH=trueTEMPORAL_AGENT_WORKFLOW_ENABLED=true+TEMPORAL_BACKEND=sqlite# Data directory (base for all persistent storage: DBs, workspaces, logs)DATA_DIR=datadiff --git a/CLAUDE.md b/CLAUDE.mdindex 71b56d52..cca720b5 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1583,8 +1583,16 @@ TEMPORAL_PER_TYPE_DISPATCH=true # F4.A flag — per-type activity dispatTEMPORAL_AGENT_WORKFLOW_ENABLED=true # F4.B flag — agent-as-child-workflow```-**Temporal Server** (`temporal-server` global CLI):-The `temporal-server` npm package bundles the official Temporal CLI binary for local dev server with SQLite persistence. It is a **global CLI tool** (not a project dependency) — installed automatically by `scripts/install.js` and `scripts/build.js`, or manually via `npm install -g temporal-server`. The package manages its own binary download, data directory, and lifecycle.+**Temporal binary + persistence** are managed in-process by the plugin-folder pattern under [`server/services/temporal/`](./server/services/temporal/) — the `temporal-server` npm package is no longer used. Binary distribution + lifecycle = standard libs, zero custom code:++- **`_install.py`** — [`pooch`](https://pypi.org/project/pooch/) downloads `temporal-server` + `temporal-sql-tool` from `temporalio/temporal` GitHub releases (SHA-256 verified, XDG-cached cross-platform). Falls back to `shutil.which("temporal-server")` when a system install is on PATH (brew / scoop / cargo).+- **`_runtime.py`** — `PostgresRuntime` (subclasses `BaseSupervisor`; wraps [`pgserver`](https://pypi.org/project/pgserver/) which bundles PostgreSQL 16.2 binaries cross-platform) + `TemporalServerRuntime` (subclasses `BaseProcessSupervisor`; runs the binary with a Python-rendered YAML config). Same singleton + lifecycle surface every other supervised service uses ([`nodes/whatsapp/_runtime.py`](./server/nodes/whatsapp/_runtime.py) is the template).+- **`_config.py`** — `pyyaml.safe_dump` of the Temporal cluster config; `temporal-sql-tool create-database` + `setup-schema` + `update-schema` for both `temporal` and `temporal_visibility` Postgres databases (idempotent).+- **`_handlers.py` + `_refresh.py`** — `temporal_status` / `_start` / `_stop` WS commands and the WS-connect status snapshot, registered through `services.ws_handler_registry` and `services.status_broadcaster.register_service_refresh`.++**Backend selection** via `TEMPORAL_BACKEND` env var:+- `sqlite` (dev default) — single ServiceSpec runs `temporal api` against an in-memory / file-based SQLite. Same dev experience as before.+- `postgres` (prod) — two ServiceSpecs run via the `_supervised_runtime.py` shim: `temporal-postgres` (pgserver) then `temporal-server` (Temporal binary). The supervisor's TCP readiness probe orders postgres → temporal automatically.**Ports:**| Service | Port | URL |@@ -1593,23 +1601,18 @@ The `temporal-server` npm package bundles the official Temporal CLI binary for l| HTTP API | 8233 | http://localhost:8233 || Web UI | 8080 | http://localhost:8080 || Metrics | 9090 | http://localhost:9090 |+| Postgres | dyn | postgresql://...:NNNNN (`postgres` backend; pgserver picks a free port — read via `get_postgres_runtime().uri`) |-**CLI commands**:+**CLI commands** (still available when `temporal` is on PATH or pooch-installed):```bash-temporal-server start # Start in background (daemon mode)-temporal-server api # Start in foreground (blocks)-temporal-server stop # Stop server-temporal-server status # Show status (all 4 ports)-temporal-server restart # Restart server-temporal-server clean # Stop + remove bin/, data/+temporal-server start --config <yaml> # what TemporalServerRuntime invokes+temporal api # what the sqlite ServiceSpec invokes+temporal --version```-**Start script integration** (`scripts/start.js`):-The start script checks `temporal-server status` via CLI before building the concurrently service list. If Temporal is already running, it skips adding it to concurrently (prevents `--kill-others` cascade when `temporal-server api` exits immediately with "Already running"). If not running, adds `npm:temporal:start` (`temporal-server api` in foreground mode) to the service list.--**Port management**: Temporal manages its own ports (7233, 8233, 8080, 9090). These ports are NOT included in MachinaOS `allPorts` and are NOT killed during port-freeing. Temporal lifecycle is managed exclusively through its own CLI (`temporal-server start/stop/status`).+**Start script integration** ([`machina/commands/start.py`](./machina/commands/start.py) + [`machina/commands/dev.py`](./machina/commands/dev.py)): both call `temporal_specs(root, cfg)` ([`machina/commands/_temporal_specs.py`](./machina/commands/_temporal_specs.py)) which returns the right ServiceSpec set for the chosen backend. The supervisor's `_temporal_running()` probe still short-circuits if Temporal is already running on 7233 (lets you run `temporal-server start` standalone for debugging).-**Docker**: Uses official `temporalio/temporal:latest` image as a separate container — the npm package is not needed in Docker.+**Docker**: Optional. The Python supervisor handles cross-platform lifecycle without Docker; production-scale Temporal+Postgres runs identically on Linux / macOS / Windows via pip-installed binaries.**Execution Routing** (`workflow.py`):1. If `TEMPORAL_ENABLED=true` and Temporal configured → `_execute_temporal()`diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.mdindex 54ceb5a8..67c436a0 100644--- a/docs-internal/TEMPORAL_ARCHITECTURE.md+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md@@ -434,20 +434,52 @@ client = await Client.connect(server_address, namespace=namespace, runtime=runti## Server Management-`temporal-server` is installed globally (`npm install -g temporal-server`) and managed via CLI:+The Temporal binary + persistence layer are managed in-process by the plugin-folder pattern at [`server/services/temporal/`](../server/services/temporal/) — the `temporal-server` npm package has been retired. Six sibling files (`_install.py`, `_runtime.py`, `_config.py`, `_handlers.py`, `_refresh.py`, plus `__init__.py` for registry wiring) match the [Wave 11 plugin-folder pattern](./plugin_system.md#self-contained-plugin-folders) that `server/nodes/whatsapp/` uses for its Go binary.-```bash-temporal-server start # Start in background (daemon)-temporal-server stop # Stop server-temporal-server status # Show status (all 4 ports)-temporal-server api # Start in foreground (blocks)-temporal-server restart # Restart server-temporal-server clean # Stop + remove bin/, data/-```+**Persistence backends** (selected by `TEMPORAL_BACKEND` env var):++| Backend | When | What runs |+|---|---|---|+| `sqlite` (dev default) | `TEMPORAL_BACKEND=sqlite` | Single supervised process running `temporal api` (the binary's built-in `start-dev` mode). In-memory or file-based SQLite. Zero deps beyond the Temporal binary. |+| `postgres` (prod) | `TEMPORAL_BACKEND=postgres` | Two supervised processes: `temporal-postgres` (pgserver-managed PostgreSQL 16.2) then `temporal-server` (binary with YAML config pointing at the Postgres). Ordered automatically by the supervisor's TCP readiness probe. |++**Modern libs doing the heavy lifting** (zero custom infrastructure code):+- **[`pooch`](https://pypi.org/project/pooch/)** — `services/temporal/_install.py` downloads `temporal-server` + `temporal-sql-tool` from `temporalio/temporal` GitHub releases. SHA-256 verified (digests pinned in `_install.py:_CHECKSUMS`); XDG-cached via `pooch.os_cache()`; tar.gz / zip extraction handled by `pooch.Untar()` / `pooch.Unzip()`. Falls back to `shutil.which("temporal-server")` for system installs. ~30 LOC total.+- **[`pgserver`](https://pypi.org/project/pgserver/)** — bundles PostgreSQL 16.2 binaries cross-platform (Linux / macOS / Windows, x86_64 + ARM64) via pip. Single API: `pgserver.get_server(data_dir)` returns a managed instance. `PostgresRuntime` wraps its lifecycle in `BaseSupervisor.start()` / `.stop()`.+- **`BaseProcessSupervisor` + `BaseSupervisor`** (`server/services/_supervisor/`) — the existing in-house supervisor base classes that `server/nodes/whatsapp/_runtime.py` already uses. Provides cross-platform signal handling (POSIX setsid + Windows Job Objects + psutil tree-kill), restart policy via tenacity, log draining, status snapshots. We subclass both — zero custom supervisor logic.++**ServiceSpec wiring**: [`machina/commands/_temporal_specs.py`](../machina/commands/_temporal_specs.py) returns the right ServiceSpec set for the selected backend. Both `start.py` and `dev.py` call it. The generic [`_supervised_runtime.py`](../machina/commands/_supervised_runtime.py) shim (~50 LOC) lets the `Manager` supervisor schedule any `BaseSupervisor` singleton as a regular subprocess — `python -m machina.commands._supervised_runtime services.temporal._runtime:get_postgres_runtime`.-**Port management**: Temporal owns its ports (7233, 8233, 8080, 9090). They are NOT in MachinaOS `allPorts` and NOT killed during port-freeing. Use `temporal-server stop` to stop Temporal.+**WS surface**: `_handlers.py` registers `temporal_status` / `temporal_start` / `temporal_stop` via `services.ws_handler_registry.register_ws_handlers`. `_refresh.py` registers a WS-connect callback via `services.status_broadcaster.register_service_refresh` so the FE health indicator stays current.-**Start script integration**: `scripts/start.js` checks `temporal-server status` before building the concurrently service list. If already running, skips adding Temporal (prevents `--kill-others` cascade kill). `scripts/dev.js` always includes Temporal (no `--kill-others`, so early exit is harmless).+**Port management**: Temporal owns ports 7233 / 8233 / 8080 / 9090. Postgres picks a dynamic free port (read via `get_postgres_runtime().uri`). Both are excluded from MachinaOS `allPorts` and from port-freeing in `scripts/start.js`.++**Direct CLI access** is still possible — the `temporal` binary on PATH (or under `pooch.os_cache("machinaos-temporal")`) supports `temporal server start --config <yaml>`, `temporal-sql-tool` subcommands, and `tctl`. The supervisor invokes these binaries; you can too.++**Cluster tunables** (all live in [`core/config.py:Settings`](../server/core/config.py); zero magic numbers in the runtime / config / supervisor wiring):++| Setting | Env var | Default | Purpose |+|---|---|---|---|+| `temporal_backend` | `TEMPORAL_BACKEND` | `sqlite` | Backend selector — `sqlite` (dev) / `postgres` (prod). |+| `temporal_frontend_grpc_port` | `TEMPORAL_FRONTEND_GRPC_PORT` | `7233` | gRPC port the SDK client connects to. Drives the readiness probe + cluster `rpcAddress`. |+| `temporal_matching_grpc_port` | `TEMPORAL_MATCHING_GRPC_PORT` | `7235` | Internal matching service. |+| `temporal_history_grpc_port` | `TEMPORAL_HISTORY_GRPC_PORT` | `7234` | Internal history service. |+| `temporal_worker_grpc_port` | `TEMPORAL_WORKER_GRPC_PORT` | `7239` | Internal worker service. |+| `temporal_bind_local_only` | `TEMPORAL_BIND_LOCAL_ONLY` | `true` | When `true`, all gRPC ports bind `127.0.0.1`. Flip to `false` for multi-host deployments (`0.0.0.0`). |+| `temporal_num_history_shards` | `TEMPORAL_NUM_HISTORY_SHARDS` | `4` | History-shard count. Bump for higher write throughput; not online-resizable. |+| `temporal_default_max_conns` | `TEMPORAL_DEFAULT_MAX_CONNS` | `20` | Postgres pool size for the `temporal` (history) datastore. |+| `temporal_visibility_max_conns` | `TEMPORAL_VISIBILITY_MAX_CONNS` | `4` | Postgres pool size for the `temporal_visibility` datastore. |+| `temporal_max_conn_lifetime` | `TEMPORAL_MAX_CONN_LIFETIME` | `1h` | Postgres connection rotation interval. Accepts Go-duration strings (`30m`, `2h`, etc.). |+| `temporal_binary_version` | `TEMPORAL_BINARY_VERSION` | `1.31.0` | Pinned `temporalio/temporal` release tag. Bumping requires a matching entry in `_install.py:_CHECKSUMS_BY_VERSION`. |+| `temporal_graceful_shutdown_seconds` | `TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS` | `30` | SIGTERM → SIGKILL grace window for the Temporal binary supervisor. Shared with the embedded worker shutdown. |+| `temporal_postgres_dsn` | `TEMPORAL_POSTGRES_DSN` | (unset) | Reserved for multi-host deployments — when set, bypasses pgserver and points Temporal at an external Postgres. Out of scope for current sprint. |++Two supervisor-build-time env vars (read inside `_temporal_specs.py`, not in `Settings`):++| Env var | Default | Purpose |+|---|---|---|+| `TEMPORAL_PG_READY_TIMEOUT_SECONDS` | `60` | How long the supervisor waits for pgserver to be ready before marking the spec failed. |+| `TEMPORAL_SERVER_READY_TIMEOUT_SECONDS` | `120` | How long the supervisor waits for Temporal's gRPC port to come up. Includes the first-run binary download (~90 MB). |## Debuggingdiff --git a/machina/commands/_supervised_runtime.py b/machina/commands/_supervised_runtime.pynew file mode 100644index 00000000..65d3cd72--- /dev/null+++ b/machina/commands/_supervised_runtime.py@@ -0,0 +1,94 @@+"""Generic bridge: run any ``BaseSupervisor`` singleton from a CLI.++The Manager supervisor in ``machina/supervisor.py`` schedules+``ServiceSpec`` entries by spawning a subprocess and supervising it.+``BaseSupervisor``-managed runtimes (pgserver, Temporal binary) 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.++Usage (inside ``ServiceSpec.argv``):++ [+ "python", "-m", "machina.commands._supervised_runtime",+ "services.temporal._runtime:get_postgres_runtime",+ ]++Equivalent to (Python idiom):++ from services.temporal._runtime import get_postgres_runtime+ runtime = get_postgres_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 machina.commands._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())diff --git a/machina/commands/_temporal_specs.py b/machina/commands/_temporal_specs.pynew file mode 100644index 00000000..cc7894b8--- /dev/null+++ b/machina/commands/_temporal_specs.py@@ -0,0 +1,116 @@+"""ServiceSpecs for the Temporal stack — shared by ``start`` and ``dev``.++Returns the right Temporal ``ServiceSpec`` set based on the+``TEMPORAL_BACKEND`` env var:++ - ``sqlite`` (default, dev) — single spec running ``temporal start-dev``+ against a SQLite file. Same behaviour as before this sprint, but the+ binary now comes from a pooch-managed cache (downloaded on first+ run by the Python backend's ``services.temporal._install``) rather+ than the deprecated ``temporal-server`` npm package.++ - ``postgres`` (prod) — two specs running the supervised runtimes:+ ``temporal-postgres`` (pgserver) then ``temporal-server`` (Temporal+ binary with YAML config). Both wrap ``BaseSupervisor`` singletons+ via ``machina.commands._supervised_runtime``.++The supervisor's TCP readiness probes (``ready_port``) order the+postgres → temporal startup automatically — Temporal won't start until+Postgres is accepting connections.+"""+from __future__ import annotations++import os+from pathlib import Path++from machina.supervisor import RestartPolicy, ServiceSpec++# Backend names — must match ``core.config.Settings.temporal_backend``+# enum (``"sqlite" | "postgres"``). Read from ``TEMPORAL_BACKEND`` env+# var at supervisor-build time; the matching Settings field flows+# through to the runtimes via :class:`core.config.Settings`.+_BACKEND_SQLITE = "sqlite"+_BACKEND_POSTGRES = "postgres"+_BACKEND_ENV_VAR = "TEMPORAL_BACKEND"++# Readiness-probe windows. ``temporal-server`` may need to download+# its binary on first run (~90 MB tarball); the Postgres init step+# runs schema migrations once. Override via env if your environment+# needs different headroom.+_PG_READY_TIMEOUT_SECONDS = float(+ os.environ.get("TEMPORAL_PG_READY_TIMEOUT_SECONDS", "60"),+)+_SERVER_READY_TIMEOUT_SECONDS = float(+ os.environ.get("TEMPORAL_SERVER_READY_TIMEOUT_SECONDS", "120"),+)++# Graceful-shutdown grace. Read directly from the same setting the+# runtime uses (``TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS``) so the+# supervisor and the Python runtime stay in lockstep.+_GRACE_SECONDS = float(+ os.environ.get("TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS", "30"),+)+++def _runtime_argv(factory_path: str) -> list[str]:+ """Build the argv for one BaseSupervisor singleton, invoked via the+ generic supervised-runtime shim. ``factory_path`` is the dotted+ ``module:attr`` accessor."""+ return [+ "uv", "run", "python", "-m",+ "machina.commands._supervised_runtime",+ factory_path,+ ]+++def temporal_specs(root: Path, cfg) -> list[ServiceSpec]:+ """Return the Temporal ServiceSpec list for the current backend.++ ``cfg`` is ``machina.config.Config``; ``cfg.temporal_port`` drives+ the gRPC readiness probe regardless of backend (same port for+ both ``sqlite`` and ``postgres`` paths).+ """+ backend = os.environ.get(_BACKEND_ENV_VAR, _BACKEND_SQLITE).strip().lower()+ server_dir = root / "server"++ if backend == _BACKEND_POSTGRES:+ return [+ ServiceSpec(+ name="temporal-postgres",+ argv=_runtime_argv("services.temporal._runtime:get_postgres_runtime"),+ cwd=server_dir,+ # pgserver picks a dynamic port; skip the TCP probe here+ # and rely on the temporal-server spec to gate readiness+ # via gRPC (it can't connect until Postgres accepts).+ ready_port=None,+ ready_timeout=_PG_READY_TIMEOUT_SECONDS,+ restart=RestartPolicy.ON_CRASH,+ terminate_grace_seconds=_GRACE_SECONDS,+ ),+ ServiceSpec(+ name="temporal-server",+ argv=_runtime_argv(+ "services.temporal._runtime:get_temporal_server_runtime",+ ),+ cwd=server_dir,+ ready_port=cfg.temporal_port,+ ready_timeout=_SERVER_READY_TIMEOUT_SECONDS,+ restart=RestartPolicy.ON_CRASH,+ terminate_grace_seconds=_GRACE_SECONDS,+ ),+ ]++ # sqlite (default) — single spec wrapping the binary in+ # ``temporal api`` (the bundled SQLite dev server).+ return [+ ServiceSpec(+ name="temporal",+ argv=["temporal", "api"],+ cwd=root,+ ready_port=cfg.temporal_port,+ restart=RestartPolicy.ON_CRASH,+ ),+ ]+++__all__ = ["temporal_specs"]diff --git a/machina/commands/dev.py b/machina/commands/dev.pyindex 90c4fcb8..e04e7379 100644--- a/machina/commands/dev.py+++ b/machina/commands/dev.py@@ -25,6 +25,7 @@ from machina.platform_ import platform_name, project_rootfrom machina.buildenv import validate_buildfrom machina.ports import kill_portfrom machina.supervisor import Manager, ServiceSpec+from machina.commands._temporal_specs import temporal_specsdef _has_vite(root: Path) -> bool:@@ -78,16 +79,7 @@ def _build_specs(root: Path, cfg, *, daemon: bool, use_vite: bool) -> list[Serviready_port=cfg.backend_port,)- return [- client_spec,- server_spec,- ServiceSpec(- name="temporal",- argv=["temporal", "api"],- cwd=root,- ready_port=cfg.temporal_port,- ),- ]+ return [client_spec, server_spec, *temporal_specs(root, cfg)]def dev_command(diff --git a/machina/commands/start.py b/machina/commands/start.pyindex 81bb69ab..6afdf1ef 100644--- a/machina/commands/start.py+++ b/machina/commands/start.py@@ -28,6 +28,7 @@ from machina.buildenv import validate_build, venv_pythonfrom machina.ports import kill_portfrom machina.run import which_argvfrom machina.supervisor import Manager, RestartPolicy, ServiceSpec+from machina.commands._temporal_specs import temporal_specsdef _sqlalchemy_preflight(root: Path) -> None:@@ -121,14 +122,7 @@ def _build_specs(root: Path, cfg, *, temporal_running: bool) -> list[ServiceSpec),]if not temporal_running:- specs.append(- ServiceSpec(- name="temporal",- argv=["temporal", "api"],- cwd=root,- ready_port=cfg.temporal_port,- )- )+ specs.extend(temporal_specs(root, cfg))return specsdiff --git a/package.json b/package.jsonindex b0683196..7854f6b4 100644--- a/package.json+++ b/package.json@@ -96,7 +96,6 @@},"dependencies": {"cross-env": "^7.0.3",- "temporal-server": "^0.0.10","agent-browser": "latest","edgymeow": "0.0.20"},diff --git a/scripts/install.js b/scripts/install.jsindex 5fc531eb..d6637eae 100755--- a/scripts/install.js+++ b/scripts/install.js@@ -118,20 +118,17 @@ if (uvVersion) {}}-// Check/Install temporal-server (global CLI, binary name: temporal)+// Temporal binary: downloaded on first backend boot by+// server/services/temporal/_install.py via pooch (~90 MB tarball+// cached under platformdirs.user_cache). No global npm install.+// User-installed `temporal` on PATH (brew / scoop / cargo) is still+// honoured by the Python supervisor's shutil.which fallback.let temporalVersion = getVersion('temporal --version');-if (temporalVersion) {- console.log(` temporal-server: ${temporalVersion}`);-} else {- console.log(' temporal-server: not found, installing...');- run('npm install -g temporal-server');- temporalVersion = getVersion('temporal --version');- if (temporalVersion) {- console.log(` temporal-server: ${temporalVersion}`);- } else {- console.log(' Warning: temporal-server install failed. Distributed execution unavailable.');- }-}+console.log(+ temporalVersion+ ? ` temporal: ${temporalVersion} (system install, will be reused)`+ : ' temporal: managed by Python backend (pooch download on first boot)',+);// agent-browser is a project dependency (see package.json); pnpm/npm// already placed it in node_modules/.pnpm/ before this postinstall ran.diff --git a/server/pyproject.toml b/server/pyproject.tomlindex 12ca569c..3307b302 100644--- a/server/pyproject.toml+++ b/server/pyproject.toml@@ -31,9 +31,15 @@ dependencies = ["opentelemetry-api>=1.27.0","opentelemetry-sdk>=1.27.0",- # YAML parsing (for SKILL.md files)+ # YAML parsing (for SKILL.md files + Temporal config rendering)"pyyaml>=6.0",+ # Temporal Postgres backend (services/temporal/)+ # - pooch: cross-platform GitHub-release binary download + checksum + cache+ # - pgserver: bundles PostgreSQL 16.2 binaries per platform (no Docker)+ "pooch>=1.8.2",+ "pgserver>=0.1.4",+# Auth"bcrypt>=4.2.0","python-jose[cryptography]>=3.3.0",diff --git a/server/services/temporal/__init__.py b/server/services/temporal/__init__.pyindex c3d517af..e3b3fa5f 100644--- a/server/services/temporal/__init__.py+++ b/server/services/temporal/__init__.py@@ -17,7 +17,32 @@ When TEMPORAL_ENABLED=false:- Falls back to the existing parallel/sequential executor"""-__all__ = ["TemporalExecutor", "TemporalClientWrapper"]+__all__ = [+ "TemporalExecutor",+ "TemporalClientWrapper",+ "PostgresRuntime",+ "TemporalServerRuntime",+ "get_postgres_runtime",+ "get_temporal_server_runtime",+]from .executor import TemporalExecutorfrom .client import TemporalClientWrapper+from ._runtime import (+ PostgresRuntime,+ TemporalServerRuntime,+ get_postgres_runtime,+ get_temporal_server_runtime,+)++# ---- self-registration (Wave 11 plugin-folder pattern) -------------------+# WS handlers (temporal_status / _start / _stop) + WS-connect refresh+# (broadcasts current Postgres+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)diff --git a/server/services/temporal/_config.py b/server/services/temporal/_config.pynew file mode 100644index 00000000..a9f64cf8--- /dev/null+++ b/server/services/temporal/_config.py@@ -0,0 +1,252 @@+"""Temporal YAML config rendering + Postgres schema bootstrap.++Renders a minimal ``services``/``persistence``/``global`` YAML config+pointing at the pgserver-managed Postgres. Runs ``temporal-sql-tool``+to create + version-init the ``temporal`` + ``temporal_visibility``+databases — idempotent, safe to call on every supervisor start.++Reference for the YAML shape:+https://github.com/temporalio/temporal/tree/main/config+"""+from __future__ import annotations++import asyncio+from pathlib import Path+from typing import Any+from urllib.parse import urlparse++import yaml++from core.config import Settings+from core.logging import get_logger++logger = get_logger(__name__)+++def parse_postgres_uri(uri: str) -> dict[str, Any]:+ """Parse a pgserver-style ``postgresql://user@host:port/db`` URI.++ Single source of truth for URI decomposition — reused by+ :mod:`services.temporal._runtime` (port property, status snapshot)+ and the SQL-tool subprocess invocations below.+ """+ parsed = urlparse(uri)+ return {+ "host": parsed.hostname or "127.0.0.1",+ "port": parsed.port or 5432,+ "user": parsed.username or "postgres",+ "password": parsed.password or "",+ }+++# Membership ports = gRPC port + this offset. Mirrors the convention+# Temporal's reference config uses (frontend 7233/6933, history+# 7234/6934, matching 7235/6935, worker 7239/6939) so subtraction+# rather than another tunable settings group keeps the surface small.+# https://docs.temporal.io/references/configuration#services+_MEMBERSHIP_PORT_OFFSET = -300++# DB names. Required by temporal-sql-tool's `--database` and the+# YAML `datastores` block; not tunable because the schema files+# bundled with the binary hard-reference them.+_HISTORY_DB_NAME = "temporal"+_VISIBILITY_DB_NAME = "temporal_visibility"+++def _sql_datastore(+ pg: dict[str, Any], db_name: str, *,+ max_conns: int, max_conn_lifetime: str,+) -> dict[str, Any]:+ return {+ "sql": {+ "pluginName": "postgres12",+ "databaseName": db_name,+ "connectAddr": f"{pg['host']}:{pg['port']}",+ "connectProtocol": "tcp",+ "user": pg["user"],+ "password": pg["password"],+ "maxConns": max_conns,+ "maxIdleConns": max(2, max_conns // 4),+ "maxConnLifetime": max_conn_lifetime,+ },+ }+++def _service_rpc(*, grpc_port: int, bind_local: bool) -> dict[str, Any]:+ return {+ "rpc": {+ "grpcPort": grpc_port,+ "membershipPort": grpc_port + _MEMBERSHIP_PORT_OFFSET,+ "bindOnLocalHost": bind_local,+ },+ }+++def render_temporal_config(*, settings: Settings, postgres_uri: str) -> Path:+ """Render Temporal YAML config to ``data/_temporal/config.yaml``.++ Every tunable — ports, pool sizes, history shards, bind scope —+ lives in :class:`core.config.Settings`. Single-node cluster+ (frontend / matching / history / worker on separate gRPC ports+ of one process); multi-node scaling is a separate sprint.+ """+ pg = parse_postgres_uri(postgres_uri)+ bind_local = bool(settings.temporal_bind_local_only)+ rpc_host = "127.0.0.1" if bind_local else "0.0.0.0"+ frontend_port = settings.temporal_frontend_grpc_port+ conn_lifetime = settings.temporal_max_conn_lifetime++ config: dict[str, Any] = {+ "log": {"stdout": True, "level": "info"},+ "persistence": {+ "defaultStore": "default",+ "visibilityStore": "visibility",+ "numHistoryShards": settings.temporal_num_history_shards,+ "datastores": {+ "default": _sql_datastore(+ pg, _HISTORY_DB_NAME,+ max_conns=settings.temporal_default_max_conns,+ max_conn_lifetime=conn_lifetime,+ ),+ "visibility": _sql_datastore(+ pg, _VISIBILITY_DB_NAME,+ max_conns=settings.temporal_visibility_max_conns,+ max_conn_lifetime=conn_lifetime,+ ),+ },+ },+ "global": {+ "membership": {+ "name": "temporal",+ "broadcastAddress": rpc_host,+ "maxJoinDuration": "30s",+ },+ "pprof": {"port": 0}, # disable pprof; eliminates rand-port noise+ },+ "services": {+ "frontend": _service_rpc(grpc_port=frontend_port, bind_local=bind_local),+ "matching": _service_rpc(+ grpc_port=settings.temporal_matching_grpc_port, bind_local=bind_local,+ ),+ "history": _service_rpc(+ grpc_port=settings.temporal_history_grpc_port, bind_local=bind_local,+ ),+ "worker": _service_rpc(+ grpc_port=settings.temporal_worker_grpc_port, bind_local=bind_local,+ ),+ },+ "clusterMetadata": {+ "enableGlobalNamespace": False,+ "failoverVersionIncrement": 10,+ "masterClusterName": "active",+ "currentClusterName": "active",+ "clusterInformation": {+ "active": {+ "enabled": True,+ "initialFailoverVersion": 1,+ "rpcName": "frontend",+ "rpcAddress": f"{rpc_host}:{frontend_port}",+ },+ },+ },+ "dcRedirectionPolicy": {"policy": "noop"},+ "archival": {+ "history": {"state": "disabled"},+ "visibility": {"state": "disabled"},+ },+ "namespaceDefaults": {+ "archival": {+ "history": {"state": "disabled"},+ "visibility": {"state": "disabled"},+ },+ },+ }++ out_dir = Path(settings.data_dir) / "_temporal"+ out_dir.mkdir(parents=True, exist_ok=True)+ config_path = out_dir / "config.yaml"+ config_path.write_text(yaml.safe_dump(config, sort_keys=False), encoding="utf-8")+ logger.info("[Temporal config] rendered %s", config_path)+ return config_path+++async def bootstrap_temporal_schemas(+ *,+ sql_tool: Path,+ postgres_uri: str,+ binary_path: Path,+) -> None:+ """Create + version-init both Temporal databases.++ Idempotent. ``create-database`` is a no-op when the DB exists;+ ``setup-schema`` / ``update-schema`` apply schema-version+ migrations bundled with the Temporal binary.++ Schema versioned-DDL directory lives next to the binary in the+ extracted archive at ``schema/postgresql/v12/{temporal,visibility}/versioned``.+ """+ pg = parse_postgres_uri(postgres_uri)+ schema_root = binary_path.parent / "schema" / "postgresql" / "v12"++ common = [+ str(sql_tool),+ "--plugin", "postgres12",+ "--ep", pg["host"],+ "--port", str(pg["port"]),+ "--user", pg["user"],+ "--password", pg["password"],+ ]++ for db_name, schema_dir in (+ ("temporal", "temporal/versioned"),+ ("temporal_visibility", "visibility/versioned"),+ ):+ # create-database — idempotent (treats "already exists" as success)+ await _run_sql_tool(+ [*common, "--database", db_name, "create-database", "--database", db_name],+ ok_if_substring="already exists",+ )+ # setup-schema — v0.0 baseline; idempotent (no-op when schema_version table exists)+ await _run_sql_tool(+ [*common, "--database", db_name, "setup-schema", "-v", "0.0"],+ ok_if_substring="already exists",+ )+ # update-schema — apply versioned DDL files; idempotent+ schema_path = schema_root / schema_dir+ if not schema_path.exists():+ raise FileNotFoundError(+ f"[Temporal config] schema dir missing: {schema_path}. "+ f"Expected to ship with temporal-server binary at "+ f"{binary_path.parent}/schema/postgresql/v12/"+ )+ await _run_sql_tool(+ [*common, "--database", db_name, "update-schema", "-d", str(schema_path)],+ )+ logger.info("[Temporal config] schemas bootstrapped: temporal + temporal_visibility")+++async def _run_sql_tool(argv: list[str], *, ok_if_substring: str | None = None) -> None:+ """Run a temporal-sql-tool subcommand. Tolerates idempotency+ failures (e.g. "database already exists") when ``ok_if_substring``+ matches stderr."""+ proc = await asyncio.create_subprocess_exec(+ *argv,+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,+ )+ stdout, stderr = await proc.communicate()+ if proc.returncode == 0:+ return+ err = (stderr or b"").decode(errors="replace")+ if ok_if_substring and ok_if_substring in err:+ return+ raise RuntimeError(+ f"[Temporal config] {' '.join(argv[:4])}... failed (rc={proc.returncode}): {err}"+ )+++__all__ = [+ "render_temporal_config",+ "bootstrap_temporal_schemas",+ "parse_postgres_uri",+]diff --git a/server/services/temporal/_handlers.py b/server/services/temporal/_handlers.pynew file mode 100644index 00000000..eb5ac80c--- /dev/null+++ b/server/services/temporal/_handlers.py@@ -0,0 +1,69 @@+"""WebSocket handlers for Temporal + Postgres lifecycle commands.++Wire keys registered in :mod:`services.ws_handler_registry`:++ - ``temporal_status`` → status snapshot of both runtimes+ - ``temporal_start`` → idempotent start (postgres → temporal)+ - ``temporal_stop`` → idempotent stop (temporal → postgres)++All three share the snapshot shape from+:func:`services.temporal._refresh.temporal_status_snapshot` — the+single source of truth for the ``{postgres, 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 both Postgres + Temporal runtimes."""+ return temporal_status_snapshot()+++async def handle_temporal_start(+ data: dict[str, Any], websocket: WebSocket,+) -> dict[str, Any]:+ """Start Postgres then Temporal. Idempotent — each ``.start()``+ returns immediately if the runtime is already running."""+ from services.temporal._runtime import (+ get_postgres_runtime,+ get_temporal_server_runtime,+ )++ await get_postgres_runtime().start()+ 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 then Postgres. Idempotent."""+ from services.temporal._runtime import (+ get_postgres_runtime,+ get_temporal_server_runtime,+ )++ await get_temporal_server_runtime().stop()+ await get_postgres_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"]diff --git a/server/services/temporal/_install.py b/server/services/temporal/_install.pynew file mode 100644index 00000000..de7eb75d--- /dev/null+++ b/server/services/temporal/_install.py@@ -0,0 +1,178 @@+"""Cross-platform Temporal server binary downloader using pooch.++Downloads ``temporal-server`` + ``temporal-sql-tool`` from the+``temporalio/temporal`` GitHub releases. Pooch (https://www.fatiando.org/pooch/)+handles platform-asset resolution, SHA-256 verification, XDG-aware+cross-platform caching, archive extraction (tar.gz / zip), and+idempotent retrieval — replacing what would otherwise be ~150 LOC of+custom GitHub-release fetching with ~30 lines.++Checksums come from the release's ``checksums.txt``, queried once via+``gh release view --repo temporalio/temporal --json assets`` and pinned+below. Bump ``_VERSION`` → re-fetch checksums; pooch refuses any asset+whose SHA-256 doesn't match.+"""+from __future__ import annotations++import asyncio+import platform+import stat+import tarfile+import zipfile+from pathlib import Path++import pooch++from core.config import Settings+from core.logging import get_logger++logger = get_logger(__name__)++# Default version. Override via ``TEMPORAL_BINARY_VERSION`` env var+# (read at the start of ``_fetch_sync``). Bump together with the+# matching entry in ``_CHECKSUMS`` — pooch refuses any asset whose+# SHA-256 doesn't match the registry. Schema files bundled with the+# binary feed ``temporal-sql-tool update-schema`` so binary + schema+# versions stay in lockstep automatically.+_DEFAULT_VERSION = "1.31.0"+_BASE_URL = "https://github.com/temporalio/temporal/releases/download"+++# Asset-name template — Temporal's release naming convention. The+# version slot is substituted from settings (or _DEFAULT_VERSION).+# Verified against https://github.com/temporalio/temporal/releases+_ASSET_TEMPLATES: dict[tuple[str, str], str] = {+ ("Linux", "x86_64"): "temporal_{v}_linux_amd64.tar.gz",+ ("Linux", "aarch64"): "temporal_{v}_linux_arm64.tar.gz",+ ("Darwin", "x86_64"): "temporal_{v}_darwin_amd64.tar.gz",+ ("Darwin", "arm64"): "temporal_{v}_darwin_arm64.tar.gz",+ ("Windows", "AMD64"): "temporal_{v}_windows_amd64.zip",+ ("Windows", "ARM64"): "temporal_{v}_windows_arm64.zip",+}+++# SHA-256 digests per release. Keyed by version → asset filename →+# digest. Bumping ``temporal_binary_version`` in Settings to a version+# not in this map raises a clear error at install time. Regenerate+# via ``gh release view --repo temporalio/temporal --json assets``.+_CHECKSUMS_BY_VERSION: dict[str, dict[str, str]] = {+ "1.31.0": {+ "temporal_1.31.0_linux_amd64.tar.gz":+ "sha256:2e1fe709f7794929691dbf7044fea8935a5af5b4686758ae6477bebdc208012b",+ "temporal_1.31.0_linux_arm64.tar.gz":+ "sha256:d02e574e2e1ee5b888b4a57d02d8438bb92d6d5eec47fcf18bf190ac594c8ed3",+ "temporal_1.31.0_darwin_amd64.tar.gz":+ "sha256:c1174e1f3ad82489bb84ab6f4fd00b82ab13cb31ca81ddf8bf449e7f5ecafdb8",+ "temporal_1.31.0_darwin_arm64.tar.gz":+ "sha256:9023d04591eb3285f31735d9298cbd6214a0627c9e71f5c7b47991c2ffd91d05",+ "temporal_1.31.0_windows_amd64.zip":+ "sha256:f4b41b3d195803a2a16bc137c2fa81af3f5bbe8044c3b033411bb19af4fdc8b8",+ "temporal_1.31.0_windows_arm64.zip":+ "sha256:a7b39728ee2d1db51877745ffda450ad0d92034f5cd429223c42438156d6af9a",+ },+}++# Names of the binaries we extract from each release tarball. The+# Temporal release ships several; these are the two MachinaOS actually+# invokes (server + schema migrator). Adding ``tctl`` here would also+# extract it.+_BINARY_NAMES: tuple[str, ...] = ("temporal-server", "temporal-sql-tool")++# pooch cache namespace. Re-used across versions; 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()+++def _platform_key() -> tuple[str, str]:+ key = (platform.system(), platform.machine())+ if key not in _ASSET_TEMPLATES:+ raise RuntimeError(+ f"[Temporal install] Unsupported platform: {key}. "+ f"Supported: {sorted(_ASSET_TEMPLATES.keys())}"+ )+ return key+++def _asset_name(version: str) -> str:+ return _ASSET_TEMPLATES[_platform_key()].format(v=version)+++def _resolver(version: str) -> pooch.Pooch:+ checksums = _CHECKSUMS_BY_VERSION.get(version)+ if checksums is None:+ raise RuntimeError(+ f"[Temporal install] No SHA-256 digests pinned for version "+ f"{version!r}. Known versions: {sorted(_CHECKSUMS_BY_VERSION.keys())}. "+ f"Add to _CHECKSUMS_BY_VERSION (see module docstring)."+ )+ return pooch.create(+ path=pooch.os_cache(_CACHE_NAMESPACE),+ base_url=f"{_BASE_URL}/v{version}/",+ registry=checksums,+ )+++async def ensure_temporal_binaries(+ settings: Settings | None = None,+) -> dict[str, Path]:+ """Return ``{"temporal-server": Path, "temporal-sql-tool": Path}``.++ Idempotent — first call downloads, subsequent calls hit the pooch+ cache (XDG / OS-conventional dir). Async-locked so concurrent+ callers don't double-download. Version comes from+ ``settings.temporal_binary_version`` (env: ``TEMPORAL_BINARY_VERSION``);+ falls back to ``_DEFAULT_VERSION`` when no settings passed.+ """+ global _cached+ if settings is None:+ settings = Settings()+ version = (settings.temporal_binary_version or _DEFAULT_VERSION).lstrip("v")++ async with _lock:+ if _cached is not None:+ return _cached+ _cached = await asyncio.to_thread(_fetch_sync, version)+ logger.info(+ "[Temporal install] binaries ready (v=%s): %s",+ version, {k: str(v) for k, v in _cached.items()},+ )+ return _cached+++def _fetch_sync(version: str) -> dict[str, Path]:+ """Synchronous pooch fetch + post-extraction binary location.++ The release tarball contains both ``temporal-server`` and+ ``temporal-sql-tool`` (plus the ``temporal`` CLI and ``tctl``) at+ the root of the archive. We extract everything via pooch's+ processor and return the names listed in ``_BINARY_NAMES``.+ """+ pup = _resolver(version)+ asset = _asset_name(version)+ processor = pooch.Unzip() if asset.endswith(".zip") else pooch.Untar()+ extracted = pup.fetch(asset, processor=processor, progressbar=True)+ suffix = ".exe" if platform.system() == "Windows" else ""++ paths: dict[str, Path] = {}+ for name in _BINARY_NAMES:+ target = f"{name}{suffix}"+ match = next((Path(p) for p in extracted if Path(p).name == target), None)+ if match is None:+ raise RuntimeError(+ f"[Temporal install] Binary {target!r} not found in {asset!r}. "+ f"Extracted files: {[Path(p).name for p in extracted]}"+ )+ paths[name] = match+ # Pooch preserves file mode on POSIX, but if the archive was+ # repacked without exec bits, ensure the binary is runnable.+ if platform.system() != "Windows":+ mode = match.stat().st_mode+ match.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)+ return paths+++__all__ = ["ensure_temporal_binaries"]diff --git a/server/services/temporal/_refresh.py b/server/services/temporal/_refresh.pynew file mode 100644index 00000000..a32d8a1f--- /dev/null+++ b/server/services/temporal/_refresh.py@@ -0,0 +1,52 @@+"""WS-connect status broadcast for the Temporal+Postgres 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 ``{postgres, temporal}`` status shape consumed by both+this refresh callback and ``_handlers.py``'s WS commands.+"""+from __future__ import annotations++from typing import Any++from core.logging import get_logger++logger = get_logger(__name__)+++def temporal_status_snapshot() -> dict[str, Any]:+ """Return ``{"postgres": {...}, "temporal": {...}}`` snapshots.++ Both runtimes' ``status_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_postgres_runtime,+ get_temporal_server_runtime,+ )++ return {+ "postgres": get_postgres_runtime().status_snapshot(),+ "temporal": get_temporal_server_runtime().status_snapshot(),+ }+++async def refresh_temporal_status() -> None:+ """Broadcast the Temporal + Postgres status snapshots on WS connect."""+ from services.status_broadcaster import get_status_broadcaster++ broadcaster = get_status_broadcaster()+ await broadcaster.broadcast({+ "type": "temporal_status",+ "data": temporal_status_snapshot(),+ })+++__all__ = ["refresh_temporal_status", "temporal_status_snapshot"]diff --git a/server/services/temporal/_runtime.py b/server/services/temporal/_runtime.pynew file mode 100644index 00000000..824ea5b4--- /dev/null+++ b/server/services/temporal/_runtime.py@@ -0,0 +1,273 @@+"""Postgres + Temporal server lifecycle.++Two supervisor subclasses:++ - :class:`PostgresRuntime` subclasses :class:`BaseSupervisor` directly.+ pgserver manages its own subprocess (start / stop / port binding),+ so we don't drive ``anyio.open_process`` — we just wrap its+ lifecycle in the uniform start/stop/status surface.++ - :class:`TemporalServerRuntime` subclasses :class:`BaseProcessSupervisor`.+ Fires the binary downloaded by :mod:`services.temporal._install`+ against the YAML config rendered by :mod:`services.temporal._config`.++Both use 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, BaseSupervisor+from services.temporal._config import parse_postgres_uri++logger = get_logger(__name__)++# Default Postgres port; only used as a fallback in ``PostgresRuntime.port``+# before pgserver has actually started and reported its dynamic port.+_PG_DEFAULT_PORT = 5432++# How long each TCP-readiness probe waits per attempt. Mirrors+# ``machina.tcp.probe_tcp_port``'s semantics inside the server-side+# supervisor — 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 both runtimes' ``health_check`` overrides. Mirrors+ :func:`machina.tcp.probe_tcp_port` but keeps server-side modules+ independent of the ``machina`` 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 PostgresRuntime(BaseSupervisor):+ """pgserver-managed PostgreSQL 16.2.++ pgserver (https://pypi.org/project/pgserver/) bundles full Postgres+ binaries cross-platform via pip and exposes a Python API for the+ process lifecycle. We wrap that API in BaseSupervisor's start/stop+ surface so the rest of the system (status broadcasts, supervisor,+ FastAPI lifespan) treats it uniformly with every other supervised+ binary.+ """++ name = "temporal-postgres"++ def __init__(self, settings: Optional[Settings] = None) -> None:+ super().__init__()+ if settings is None:+ settings = Settings()+ self.settings = settings+ self._pg: Any = None # pgserver.Server instance++ # ---- subclass surface (BaseSupervisor) -------------------------------++ def is_running(self) -> bool:+ return self._pg is not None++ async def _do_start(self) -> None:+ # Lazy import: pgserver pulls a heavy native dep tree; only+ # load it when the Postgres backend is actually selected.+ import pgserver++ data_dir = Path(self.settings.data_dir) / "postgres"+ data_dir.mkdir(parents=True, exist_ok=True)++ def _start_sync() -> Any:+ return pgserver.get_server(str(data_dir), cleanup_mode=None)++ self._pg = await asyncio.to_thread(_start_sync)+ logger.info("[%s] pgserver ready at %s", self.label, self._pg.get_uri())++ async def _do_stop(self) -> None:+ pg = self._pg+ self._pg = None+ if pg is None:+ return++ def _stop_sync() -> None:+ try:+ pg.cleanup()+ except Exception as exc: # noqa: BLE001 — best-effort shutdown+ logger.warning("[postgres] cleanup raised %r (continuing)", exc)++ await asyncio.to_thread(_stop_sync)+ logger.info("[%s] stopped", self.label)++ async def health_check(self) -> bool:+ if not self.is_running():+ return False+ # pgserver may report running before the socket is accepting;+ # use the shared TCP probe — same idiom every supervised+ # service uses for `ready_port` readiness checks.+ return await _probe_tcp_port(self.port)++ def _extra_status(self) -> dict[str, Any]:+ return {+ "uri": self.uri,+ "port": self.port,+ "data_dir": str(Path(self.settings.data_dir) / "postgres"),+ }++ # ---- public read-only properties -------------------------------------++ @property+ def uri(self) -> Optional[str]:+ return self._pg.get_uri() if self._pg else None++ @property+ def port(self) -> int:+ # pgserver picks a free port at start; fall back to the default+ # when called before _do_start (e.g. early status snapshots).+ if self._pg is None:+ return _PG_DEFAULT_PORT+ return parse_postgres_uri(self._pg.get_uri())["port"]+++class TemporalServerRuntime(BaseProcessSupervisor):+ """Temporal server binary, supervised via BaseProcessSupervisor.++ The binary lands on disk via :func:`services.temporal._install.ensure_temporal_binaries`+ (pooch-cached); the YAML config is rendered by+ :func:`services.temporal._config.render_temporal_config` pointing at+ the running :class:`PostgresRuntime` instance.++ BaseProcessSupervisor handles all signal, restart, and tree-kill+ semantics — we only override the four required methods plus+ ``_pre_spawn`` (download + bootstrap) and ``health_check``+ (gRPC port probe).+ """++ name = "temporal-server"+ pipe_streams = True+ graceful_shutdown = sys.platform == "win32"++ def __init__(+ self,+ settings: Optional[Settings] = None,+ postgres: Optional[PostgresRuntime] = 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.+ # Reusing it avoids inventing a parallel ``temporal_server_grace_seconds``.+ self.terminate_grace_seconds = float(+ settings.temporal_graceful_shutdown_seconds,+ )+ self._postgres = postgres or PostgresRuntime.get_instance(settings)+ self._binaries: Optional[dict[str, Path]] = None+ self._config_path: Optional[Path] = None++ # ---- BaseProcessSupervisor overrides ---------------------------------++ async def _pre_spawn(self) -> None:+ from services.temporal._install import ensure_temporal_binaries+ from services.temporal._config import (+ bootstrap_temporal_schemas,+ render_temporal_config,+ )++ if self._postgres.uri is None:+ raise RuntimeError(+ f"[{self.label}] Postgres runtime not started; "+ "schedule the postgres ServiceSpec before this one"+ )++ # 1. Download / cache temporal-server + temporal-sql-tool.+ # Version pin lives in settings.temporal_binary_version.+ self._binaries = await ensure_temporal_binaries(self.settings)++ # 2. Idempotent schema bootstrap.+ await bootstrap_temporal_schemas(+ sql_tool=self._binaries["temporal-sql-tool"],+ postgres_uri=self._postgres.uri,+ binary_path=self._binaries["temporal-server"],+ )++ # 3. Render YAML config pointing at the Postgres URI.+ self._config_path = render_temporal_config(+ settings=self.settings,+ postgres_uri=self._postgres.uri,+ )++ def binary_path(self) -> Path:+ if self._binaries is None:+ # Called before _pre_spawn — e.g. if BaseProcessSupervisor+ # tries to validate the binary exists. Return a placeholder;+ # _pre_spawn populates the real path before the existence+ # check in _do_start runs.+ return Path("temporal-server")+ return self._binaries["temporal-server"]++ def argv(self) -> list[str]:+ return [str(self.binary_path()), "start", "--config", str(self._config_path)]++ def cwd(self) -> Path:+ return Path(self.settings.data_dir) / "_temporal"++ def env(self) -> dict[str, str]:+ # Temporal reads everything from YAML; 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,+ "config_path": str(self._config_path) if self._config_path else None,+ "binary_version": self.settings.temporal_binary_version,+ }+++# ---- module-level singleton accessors -----------------------------------++def get_postgres_runtime(settings: Optional[Settings] = None) -> PostgresRuntime:+ """Return the Postgres runtime singleton."""+ return PostgresRuntime.get_instance(settings)+++def get_temporal_server_runtime(+ settings: Optional[Settings] = None,+) -> TemporalServerRuntime:+ """Return the Temporal server runtime singleton."""+ return TemporalServerRuntime.get_instance(settings)+++__all__ = [+ "PostgresRuntime",+ "TemporalServerRuntime",+ "get_postgres_runtime",+ "get_temporal_server_runtime",+]