Skip to content

Self-improving AI Employees for everyone

feat(temporal): plugin-folder pattern + pooch + pgserver — replaces temporal-server npm package

trohitg6c8fc9ea88d6
diff --git a/.env.template b/.env.template
index 94be0351..390e558c 100644
--- a/.env.template
+++ b/.env.template
@@ -47,6 +47,7 @@ TEMPORAL_NAMESPACE=default
TEMPORAL_TASK_QUEUE=machina-tasks
TEMPORAL_PER_TYPE_DISPATCH=true
TEMPORAL_AGENT_WORKFLOW_ENABLED=true
+TEMPORAL_BACKEND=sqlite
# Data directory (base for all persistent storage: DBs, workspaces, logs)
DATA_DIR=data
diff --git a/CLAUDE.md b/CLAUDE.md
index 71b56d52..cca720b5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1583,8 +1583,16 @@ TEMPORAL_PER_TYPE_DISPATCH=true # F4.A flag — per-type activity dispat
TEMPORAL_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.md
index 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). |
## Debugging
diff --git a/machina/commands/_supervised_runtime.py b/machina/commands/_supervised_runtime.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 90c4fcb8..e04e7379 100644
--- a/machina/commands/dev.py
+++ b/machina/commands/dev.py
@@ -25,6 +25,7 @@ from machina.platform_ import platform_name, project_root
from machina.buildenv import validate_build
from machina.ports import kill_port
from machina.supervisor import Manager, ServiceSpec
+from machina.commands._temporal_specs import temporal_specs
def _has_vite(root: Path) -> bool:
@@ -78,16 +79,7 @@ def _build_specs(root: Path, cfg, *, daemon: bool, use_vite: bool) -> list[Servi
ready_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.py
index 81bb69ab..6afdf1ef 100644
--- a/machina/commands/start.py
+++ b/machina/commands/start.py
@@ -28,6 +28,7 @@ from machina.buildenv import validate_build, venv_python
from machina.ports import kill_port
from machina.run import which_argv
from machina.supervisor import Manager, RestartPolicy, ServiceSpec
+from machina.commands._temporal_specs import temporal_specs
def _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 specs
diff --git a/package.json b/package.json
index 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.js
index 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.toml
index 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__.py
index 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 TemporalExecutor
from .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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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",
+]