Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(automations): serverkit-tramo extension backend (Phase 1)

Juan Denis38c1e3309706
diff --git a/builtin-extensions/serverkit-tramo/backend/__init__.py b/builtin-extensions/serverkit-tramo/backend/__init__.py
new file mode 100644
index 00000000..b86d1323
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/backend/__init__.py
@@ -0,0 +1,10 @@
+"""ServerKit Automations extension backend package (tramo engine).
+
+Embeds tramo (github.com/jhd3197/tramo) as the panel's workflow-automation
+surface. The panel is the system of record for workflow docs; a managed
+``@tramo/server`` Docker container on the panel host is the executor. See
+docs/plans/45_TRAMO_AUTOMATIONS_EXTENSION_PLAN.md.
+"""
+from .tramo import tramo_bp
+
+__all__ = ['tramo_bp']
diff --git a/builtin-extensions/serverkit-tramo/backend/events_bridge.py b/builtin-extensions/serverkit-tramo/backend/events_bridge.py
new file mode 100644
index 00000000..1bb35df2
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/backend/events_bridge.py
@@ -0,0 +1,166 @@
+"""Panel <-> tramo wiring (serverkit-tramo / Automations extension, plan 45 Phase 3).
+
+Two integrations that let panel automations reach the outside world and act back
+on the panel:
+
+* **Events bridge** — one managed :class:`EventSubscription` whose ``url`` points
+ at the container's ``serverkit:event`` webhook trigger (``/sk/events`` via the
+ hooks passthrough). Subscribing to ``["*"]`` means every panel event is POSTed
+ to tramo; workflows filter with ``if``/``switch`` on ``trigger.body.event``.
+ Toggled on/off from the Settings tab; its id is remembered in plugin config.
+
+* **Call-back key** — a scoped :class:`ApiKey` named ``serverkit-tramo`` issued
+ on engine install and injected into the container as ``SERVERKIT_API_KEY`` so
+ the ``@tramo/serverkit`` pack can start/stop/deploy apps, run backups, and send
+ notifications. Revoked on uninstall.
+
+All helpers are best-effort and never raise into install/uninstall.
+"""
+import logging
+
+from app import db
+
+logger = logging.getLogger(__name__)
+
+SLUG = 'serverkit-tramo'
+
+# Scopes the call-back key is granted. Matches the @tramo/serverkit pack actions:
+# app-control/deploy (apps:*), backup-run (backups:write), list/get (read).
+CALLBACK_KEY_NAME = 'serverkit-tramo'
+CALLBACK_SCOPES = ['read', 'apps:read', 'apps:write', 'apps:deploy', 'backups:write']
+
+# The path (under the hooks passthrough) the managed subscription targets, and
+# which the container maps to a serverkit:event webhook-trigger node.
+EVENTS_TRIGGER_PATH = 'sk/events'
+
+
+def _config():
+ from app.plugins_sdk import config as plugin_config
+ return plugin_config(SLUG)
+
+
+def _save_config(updates):
+ from app.models.plugin import InstalledPlugin
+ row = InstalledPlugin.query.filter_by(slug=SLUG).first()
+ if not row:
+ return False
+ merged = dict(row.config or {})
+ merged.update(updates)
+ row.config = merged
+ db.session.commit()
+ return True
+
+
+def _admin_user_id():
+ """Owner for the managed ApiKey / EventSubscription (first admin, else any)."""
+ from app.models.user import User
+ admin = User.query.filter_by(role=User.ROLE_ADMIN).order_by(User.id).first()
+ if admin:
+ return admin.id
+ any_user = User.query.order_by(User.id).first()
+ return any_user.id if any_user else None
+
+
+# --------------------------------------------------------------------------- #
+# Call-back key
+# --------------------------------------------------------------------------- #
+
+def issue_callback_key():
+ """Issue (or reissue) the scoped ``serverkit-tramo`` ApiKey.
+
+ Returns the RAW key string (only available at creation) or None on failure.
+ The key id is stored in plugin config for later revocation.
+ """
+ from app.models.api_key import ApiKey
+
+ user_id = _admin_user_id()
+ if not user_id:
+ logger.warning('tramo: no user to own the call-back API key')
+ return None
+
+ # Revoke any previous managed key first (rotate).
+ revoke_callback_key()
+
+ raw, prefix, key_hash = ApiKey.generate_key()
+ key = ApiKey(
+ user_id=user_id,
+ name=CALLBACK_KEY_NAME,
+ key_prefix=prefix,
+ key_hash=key_hash,
+ )
+ key.set_scopes(CALLBACK_SCOPES)
+ db.session.add(key)
+ db.session.commit()
+ _save_config({'callback_key_id': key.id})
+ return raw
+
+
+def revoke_callback_key():
+ """Revoke the managed call-back ApiKey (best-effort)."""
+ from datetime import datetime
+ from app.models.api_key import ApiKey
+
+ key_id = _config().get('callback_key_id')
+ if not key_id:
+ return False
+ key = ApiKey.query.get(key_id)
+ if key:
+ key.is_active = False
+ key.revoked_at = datetime.utcnow()
+ db.session.commit()
+ _save_config({'callback_key_id': None})
+ return True
+
+
+# --------------------------------------------------------------------------- #
+# Events bridge
+# --------------------------------------------------------------------------- #
+
+def is_events_bridge_enabled():
+ return bool(_config().get('events_subscription_id'))
+
+
+def enable_events_bridge():
+ """Create the managed EventSubscription (idempotent). Returns its id or None."""
+ from app.models.event_subscription import EventSubscription
+
+ existing_id = _config().get('events_subscription_id')
+ if existing_id and EventSubscription.query.get(existing_id):
+ return existing_id
+
+ user_id = _admin_user_id()
+ if not user_id:
+ logger.warning('tramo: no user to own the events subscription')
+ return None
+
+ from .host_service import TramoHostService
+ port = TramoHostService.host_port()
+ secret = EventSubscription.generate_secret()
+
+ sub = EventSubscription(
+ user_id=user_id,
+ name='Automations (tramo) events bridge',
+ url=f'http://127.0.0.1:{port}/{EVENTS_TRIGGER_PATH}',
+ secret=secret,
+ is_active=True,
+ )
+ sub.set_events(['*'])
+ db.session.add(sub)
+ db.session.commit()
+ _save_config({'events_subscription_id': sub.id, 'events_secret': secret})
+ return sub.id
+
+
+def disable_events_bridge():
+ """Delete the managed EventSubscription (best-effort). Returns True if removed."""
+ from app.models.event_subscription import EventSubscription
+
+ sub_id = _config().get('events_subscription_id')
+ if not sub_id:
+ return False
+ sub = EventSubscription.query.get(sub_id)
+ if sub:
+ db.session.delete(sub)
+ db.session.commit()
+ _save_config({'events_subscription_id': None, 'events_secret': None})
+ return True
diff --git a/builtin-extensions/serverkit-tramo/backend/host_service.py b/builtin-extensions/serverkit-tramo/backend/host_service.py
new file mode 100644
index 00000000..21dbcdc9
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/backend/host_service.py
@@ -0,0 +1,416 @@
+"""tramo engine host service (serverkit-tramo / Automations extension).
+
+Runs ``@tramo/server`` (the headless tramo workflow host) in a managed Docker
+container so the panel host can execute automation workflows: webhooks, cron,
+run history, approvals. Driven through tramo's HTTP API, published on loopback
+only.
+
+Design mirrors serverkit-mail's :class:`StalwartService` exactly:
+
+* **Two choke-points** — every Docker invocation goes through :meth:`_docker`
+ (privilege escalation, timeouts, error shaping) and every tramo-API call goes
+ through :meth:`_api` (Bearer auth, JSON, error shaping). Nothing else shells
+ out or talks HTTP.
+* **Best-effort, Linux-only** — on Windows (dev) or when Docker is absent, calls
+ return a clean error dict instead of raising.
+* **Panel DB is the source of truth** — workflow docs live in
+ ``ext_serverkit_tramo_*``; :mod:`workflow_store` materializes enabled docs into
+ the bind-mounted workflows dir and this service restarts the container.
+* **Secrets in the config store** — the generated Bearer API key, the container
+ ``host_port``, an encrypted map of pack credentials (TELEGRAM_BOT_TOKEN, ...),
+ and the scoped panel call-back key all live in the plugin config store
+ (``plugins_sdk.config`` + the ``_save_config`` pattern), encrypted at rest.
+
+The container is a *stateless executor*: it reads workflow ``.json`` files once
+at boot (no server-side editing) and keeps run history in an in-memory ring, so
+the panel harvests runs (see jobs) and re-deploys by restarting the container.
+"""
+import logging
+import os
+import secrets
+import subprocess
+
+import requests
+
+from app.utils.system import run_privileged, is_command_available
+
+try:
+ from app.utils.crypto import encrypt_secret, decrypt_secret_safe
+except Exception: # pragma: no cover - crypto util should always be present
+ encrypt_secret = None
+ decrypt_secret_safe = None
+
+logger = logging.getLogger(__name__)
+
+SLUG = 'serverkit-tramo'
+
+# Pinned tramo-server image (GHCR, full-pack entry). Bumped deliberately like the
+# Stalwart image, not floated. Published by the tramo repo's docker CI (plan 45
+# Phase 0); until that ships this tag will not pull on a real box.
+IMAGE = 'ghcr.io/jhd3197/tramo-server:0.1.1'
+CONTAINER_NAME = 'serverkit-tramo'
+
+# Host data dirs (bind-mounted). workflows/ holds the materialized <slug>.json
+# docs; state/ is tramo's durable checkpoint store (suspend/resume survives a
+# restart, so re-deploy = restart is safe).
+DATA_DIR = '/var/serverkit/tramo'
+HOST_WORKFLOWS_DIR = f'{DATA_DIR}/workflows'
+HOST_STATE_DIR = f'{DATA_DIR}/state'
+CONTAINER_WORKFLOWS_DIR = '/workflows'
+CONTAINER_STATE_DIR = '/state'
+CONTAINER_PORT = 3000
+
+# tramo HTTP API — published on 127.0.0.1 only, never reachable off-host.
+API_HOST = '127.0.0.1'
+DEFAULT_HOST_PORT = 8377
+API_TIMEOUT = 15
+RUN_TIMEOUT = 120
+DOCKER_TIMEOUT = 180
+
+DOCS_URL = 'https://github.com/jhd3197/tramo'
+
+
+class TramoHostService:
+ """Stateless wrapper around Docker + the tramo-server HTTP API."""
+
+ # ---------- config (plugin config store) ----------
+
+ @classmethod
+ def _config(cls):
+ """Saved extension settings from the plugin config store."""
+ from app.plugins_sdk import config as plugin_config
+ return plugin_config(SLUG)
+
+ @classmethod
+ def _save_config(cls, updates):
+ """Merge *updates* into the plugin's stored config.
+
+ The SDK ``config()`` helper is read-only (the panel owns writes), so
+ generated secrets are persisted through the InstalledPlugin row directly.
+ Returns False when the plugin row is absent (dev shells / tests without a
+ row).
+ """
+ from app import db
+ from app.models.plugin import InstalledPlugin
+ row = InstalledPlugin.query.filter_by(slug=SLUG).first()
+ if not row:
+ logger.warning('%s: no InstalledPlugin row; config not persisted', SLUG)
+ return False
+ merged = dict(row.config or {})
+ merged.update(updates)
+ row.config = merged
+ db.session.commit()
+ return True
+
+ # ---------- secret helpers ----------
+
+ @classmethod
+ def _encrypt(cls, plaintext):
+ if not plaintext:
+ return plaintext
+ if encrypt_secret is None:
+ return plaintext
+ return encrypt_secret(plaintext)
+
+ @classmethod
+ def _decrypt(cls, value):
+ if not value:
+ return value
+ if decrypt_secret_safe is None:
+ return value
+ return decrypt_secret_safe(value)
+
+ @classmethod
+ def host_port(cls):
+ """Loopback host port the container's API is published on."""
+ try:
+ return int(cls._config().get('host_port') or DEFAULT_HOST_PORT)
+ except (TypeError, ValueError):
+ return DEFAULT_HOST_PORT
+
+ @classmethod
+ def api_base(cls):
+ return f'http://{API_HOST}:{cls.host_port()}/api'
+
+ @classmethod
+ def api_key(cls):
+ """Decrypted Bearer API key (empty string when not installed)."""
+ return cls._decrypt(cls._config().get('api_key')) or ''
+
+ @classmethod
+ def get_pack_secrets(cls):
+ """Decrypted {ENV_NAME: value} map of pack credentials."""
+ stored = cls._config().get('pack_secrets') or {}
+ out = {}
+ for k, v in stored.items():
+ out[k] = cls._decrypt(v)
+ return out
+
+ @classmethod
+ def set_pack_secrets(cls, secrets_map):
+ """Encrypt and persist a {ENV_NAME: value} map. Empty value deletes a key.
+
+ Returns the new set of configured env-var names (values never returned).
+ """
+ current = dict(cls._config().get('pack_secrets') or {})
+ for name, value in (secrets_map or {}).items():
+ name = (name or '').strip()
+ if not name:
+ continue
+ if value in (None, ''):
+ current.pop(name, None)
+ else:
+ current[name] = cls._encrypt(str(value))
+ cls._save_config({'pack_secrets': current})
+ return sorted(current.keys())
+
+ # ---------- docker choke-point ----------
+
+ @classmethod
+ def _docker(cls, args, timeout=DOCKER_TIMEOUT):
+ """Run ``docker <args>`` and return a normalized result dict. Never raises."""
+ if os.name == 'nt':
+ return {'success': False,
+ 'error': 'The Automations extension is not supported on Windows.'}
+ if not is_command_available('docker'):
+ return {'success': False, 'not_installed': True,
+ 'error': 'Docker is not installed on this host.'}
+ cmd = ['docker'] + list(args)
+ try:
+ result = run_privileged(cmd, timeout=timeout)
+ except subprocess.TimeoutExpired:
+ return {'success': False, 'error': f'docker timed out after {timeout}s'}
+ except (OSError, subprocess.SubprocessError) as e:
+ return {'success': False, 'error': f'Failed to run docker: {e}'}
+ out = {
+ 'success': result.returncode == 0,
+ 'returncode': result.returncode,
+ 'stdout': result.stdout or '',
+ 'stderr': result.stderr or '',
+ }
+ if not out['success']:
+ out['error'] = (out['stderr'] or out['stdout'] or 'docker failed').strip()
+ return out
+
+ # ---------- tramo API choke-point ----------
+
+ @classmethod
+ def _api(cls, method, path, payload=None, timeout=API_TIMEOUT):
+ """Call the container's tramo HTTP API (loopback only).
+
+ Returns ``{'success': True, 'data': <json-or-None>, 'status_code': int}``
+ or an error dict. Auth is Bearer with the generated API key. Never raises.
+ """
+ if os.name == 'nt':
+ return {'success': False,
+ 'error': 'The Automations extension is not supported on Windows.'}
+ key = cls.api_key()
+ if not key:
+ return {'success': False,
+ 'error': 'tramo API key is not configured. Reinstall the engine.'}
+ headers = {'Authorization': f'Bearer {key}'}
+ try:
+ resp = requests.request(
+ method, cls.api_base() + path,
+ headers=headers, json=payload, timeout=timeout,
+ )
+ except requests.RequestException as e:
+ return {'success': False,
+ 'error': f'tramo API is unreachable: {e}'}
+ result = {'success': resp.status_code < 400, 'status_code': resp.status_code}
+ if resp.status_code >= 400:
+ try:
+ body = resp.json()
+ detail = (body.get('error') or body.get('message')
+ or body.get('detail') or resp.text)
+ except ValueError:
+ detail = resp.text
+ result['error'] = f'tramo API error ({resp.status_code}): {detail}'.strip()
+ return result
+ if not resp.content:
+ result['data'] = None
+ return result
+ try:
+ result['data'] = resp.json()
+ except ValueError:
+ result['data'] = resp.text
+ return result
+
+ # ---------- container lifecycle ----------
+
+ @classmethod
+ def is_installed(cls):
+ """True when the managed container exists (running or not)."""
+ if os.name == 'nt':
+ return False
+ res = cls._docker(['inspect', '--format', '{{.State.Running}}',
+ CONTAINER_NAME], timeout=20)
+ return bool(res.get('success'))
+
+ @classmethod
+ def _panel_port(cls):
+ """Port the panel API listens on (for the container's call-back URL)."""
+ return str(cls._config().get('panel_port')
+ or os.environ.get('PORT') or '5000')
+
+ @classmethod
+ def get_status(cls):
+ """Installed / running / health summary, best-effort."""
+ status = {
+ 'installed': False,
+ 'running': False,
+ 'healthy': None,
+ 'state': 'not_installed', # not_installed|stopped|unhealthy|ready
+ 'engine': 'tramo',
+ 'image': IMAGE,
+ 'container': CONTAINER_NAME,
+ 'host_port': cls.host_port(),
+ 'api': f'{API_HOST}:{cls.host_port()}',
+ 'docs_url': DOCS_URL,
+ }
+ if os.name == 'nt':
+ status['error'] = 'The Automations extension is not supported on Windows.'
+ return status
+ res = cls._docker(['inspect', '--format', '{{.State.Running}}',
+ CONTAINER_NAME], timeout=20)
+ if not res.get('success'):
+ return status
+ status['installed'] = True
+ running = res.get('stdout', '').strip() == 'true'
+ status['running'] = running
+ if not running:
+ status['state'] = 'stopped'
+ return status
+ # Running: probe health to distinguish ready from starting/unhealthy.
+ probe = cls._api('GET', '/health', timeout=8)
+ if probe.get('success'):
+ status['healthy'] = True
+ status['state'] = 'ready'
+ data = probe.get('data')
+ if isinstance(data, dict):
+ status['version'] = data.get('version')
+ else:
+ status['healthy'] = False
+ status['state'] = 'unhealthy'
+ status['health_error'] = probe.get('error')
+ return status
+
+ @classmethod
+ def health(cls):
+ """Raw health probe (GET /api/health). Best-effort dict."""
+ if not cls.is_installed():
+ return {'success': False, 'error': 'The Automations engine is not installed.'}
+ return cls._api('GET', '/health', timeout=8)
+
+ @classmethod
+ def install(cls, host_port=None, callback_url=None, callback_api_key=None):
+ """Create and start the tramo-server container.
+
+ * Workflows + checkpoint state bind-mounted under ``DATA_DIR``.
+ * HTTP API published on **127.0.0.1 only** with a generated Bearer key.
+ * Pack credentials + the scoped panel call-back key (SERVERKIT_URL /
+ SERVERKIT_API_KEY) injected as container env.
+ """
+ if os.name == 'nt':
+ return {'success': False,
+ 'error': 'The Automations extension is not supported on Windows.'}
+ if cls.is_installed():
+ return {'success': False,
+ 'error': 'The Automations container already exists. Uninstall it first.'}
+
+ port = int(host_port or cls.host_port())
+
+ dir_res = run_privileged(['mkdir', '-p', HOST_WORKFLOWS_DIR, HOST_STATE_DIR])
+ if getattr(dir_res, 'returncode', 1) != 0:
+ return {'success': False,
+ 'error': f'Could not create data directory {DATA_DIR}: '
+ f'{(getattr(dir_res, "stderr", "") or "").strip()}'}
+
+ api_key = secrets.token_urlsafe(32)
+
+ run_args = cls._build_run_args(port, api_key, callback_url, callback_api_key)
+ res = cls._docker(run_args)
+ if not res.get('success'):
+ return {'success': False,
+ 'error': res.get('error', 'Failed to start the tramo container')}
+
+ persisted = cls._save_config({
+ 'api_key': cls._encrypt(api_key),
+ 'host_port': port,
+ 'panel_port': cls._panel_port(),
+ })
+ result = {'success': True,
+ 'message': 'Automations engine installed',
+ 'container': CONTAINER_NAME,
+ 'host_port': port,
+ 'state': 'ready'}
+ if not persisted:
+ result['warning'] = ('Container started but the API key could not be '
+ 'persisted to the plugin config store.')
+ return result
+
+ @classmethod
+ def _build_run_args(cls, port, api_key, callback_url=None, callback_api_key=None):
+ """Assemble the ``docker run`` argv. Split out so tests can assert it."""
+ run_args = [
+ 'run', '-d',
+ '--name', CONTAINER_NAME,
+ '--restart', 'unless-stopped',
+ # Let workflows call back to the panel on the host loopback.
+ '--add-host', 'host.docker.internal:host-gateway',
+ ]
+ # API published on 127.0.0.1 only.
+ run_args += ['-p', f'{API_HOST}:{port}:{CONTAINER_PORT}']
+ run_args += [
+ '-v', f'{HOST_WORKFLOWS_DIR}:{CONTAINER_WORKFLOWS_DIR}',
+ '-v', f'{HOST_STATE_DIR}:{CONTAINER_STATE_DIR}',
+ ]
+ # Bearer auth + load all first-party integration packs (full-pack entry).
+ run_args += ['-e', f'TRAMO_API_KEY={api_key}']
+ run_args += ['-e', 'TRAMO_PACKS=all']
+ # Panel call-back (SERVERKIT_URL/SERVERKIT_API_KEY consumed by the
+ # @tramo/serverkit pack via env fallback).
+ url = callback_url or f'http://host.docker.internal:{cls._panel_port()}'
+ run_args += ['-e', f'SERVERKIT_URL={url}']
+ if callback_api_key:
+ run_args += ['-e', f'SERVERKIT_API_KEY={callback_api_key}']
+ # Pack credentials (decrypted from the config store).
+ for name, value in cls.get_pack_secrets().items():
+ run_args += ['-e', f'{name}={value}']
+ run_args += [IMAGE]
+ return run_args
+
+ @classmethod
+ def uninstall(cls, keep_data=True):
+ """Remove the container; optionally delete the data directory."""
+ if os.name == 'nt':
+ return {'success': False,
+ 'error': 'The Automations extension is not supported on Windows.'}
+ res = cls._docker(['rm', '-f', CONTAINER_NAME])
+ if not res.get('success'):
+ # A missing container is not an error for uninstall.
+ if 'No such container' not in (res.get('error') or ''):
+ return {'success': False,
+ 'error': res.get('error', 'Failed to remove the tramo container')}
+ if not keep_data:
+ rm = run_privileged(['rm', '-rf', DATA_DIR])
+ if getattr(rm, 'returncode', 1) != 0:
+ return {'success': True,
+ 'warning': f'Container removed but data at {DATA_DIR} could '
+ f'not be deleted: {(getattr(rm, "stderr", "") or "").strip()}'}
+ cls._save_config({'api_key': None})
+ return {'success': True,
+ 'message': 'Automations engine removed'
+ + ('' if keep_data else ' (data deleted)')}
+
+ @classmethod
+ def control(cls, action):
+ """Start / stop / restart the managed container."""
+ if action not in ('start', 'stop', 'restart'):
+ return {'success': False, 'error': f'Invalid action: {action!r}'}
+ if not cls.is_installed():
+ return {'success': False, 'error': 'The Automations engine is not installed.'}
+ res = cls._docker([action, CONTAINER_NAME], timeout=60)
+ if not res.get('success'):
+ return {'success': False, 'error': res.get('error', f'docker {action} failed')}
+ return {'success': True, 'message': f'Automations engine {action}ed', 'action': action}
diff --git a/builtin-extensions/serverkit-tramo/backend/jobs.py b/builtin-extensions/serverkit-tramo/backend/jobs.py
new file mode 100644
index 00000000..cd152d5d
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/backend/jobs.py
@@ -0,0 +1,126 @@
+"""Background job handlers (serverkit-tramo / Automations extension).
+
+Registered via the manifest ``jobs`` block; each handler takes the ``job`` row
+and must never raise (a raised handler fails the job loudly -- these are
+best-effort maintenance tasks).
+
+* ``tramo.harvest_runs`` (:func:`harvest_runs`) -- pull recent runs from the
+ engine and upsert them into ``ext_serverkit_tramo_runs`` before the container's
+ in-memory ring evicts them; notify admins once per newly-seen failed run.
+* ``tramo.health_check`` (:func:`health_check`) -- probe ``GET /api/health`` and
+ notify ``tramo.host_unreachable`` after repeated failures.
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+SLUG = 'serverkit-tramo'
+
+# Consecutive health failures before we notify (avoids flapping on a restart).
+_HEALTH_FAIL_THRESHOLD = 2
+
+
+def harvest_runs(job):
+ """Harvest recent runs from the engine into the DB. Never raises."""
+ try:
+ from .host_service import TramoHostService
+ from .run_sync import upsert_run
+
+ if not TramoHostService.is_installed():
+ return {'skipped': True, 'reason': 'engine not installed'}
+
+ res = TramoHostService._api('GET', '/runs?limit=200')
+ if not res.get('success'):
+ return {'skipped': True, 'reason': res.get('error', 'runs fetch failed')}
+
+ data = res.get('data')
+ runs = data if isinstance(data, list) else (data or {}).get('runs') \
+ or (data or {}).get('items') or []
+
+ harvested = 0
+ new_failures = 0
+ for run_json in runs:
+ row, is_new = upsert_run(run_json)
+ if row is None:
+ continue
+ harvested += 1
+ if is_new and (row.status or '').lower() in ('failed', 'error'):
+ _notify_run_failed(row)
+ new_failures += 1
+
+ return {'harvested': harvested, 'new_failures': new_failures}
+ except Exception as e: # noqa: BLE001 -- a maintenance job must not crash the loop
+ logger.warning('tramo harvest_runs job failed: %s', e)
+ return {'error': str(e)}
+
+
+def _notify_run_failed(row):
+ try:
+ from app.plugins_sdk import notify
+ notify.send('tramo.run_failed', to='admins',
+ data={'run_id': row.run_id,
+ 'workflow': row.workflow_slug,
+ 'error': row.error},
+ category='system')
+ except Exception as e: # noqa: BLE001
+ logger.debug('tramo.run_failed notify failed: %s', e)
+
+
+def health_check(job):
+ """Probe engine health; notify after repeated failure. Never raises."""
+ try:
+ from .host_service import TramoHostService
+
+ if not TramoHostService.is_installed():
+ _reset_health_streak()
+ return {'skipped': True, 'reason': 'engine not installed'}
+
+ res = TramoHostService.health()
+ if res.get('success'):
+ _reset_health_streak()
+ return {'healthy': True}
+
+ streak = _bump_health_streak()
+ if streak == _HEALTH_FAIL_THRESHOLD:
+ _notify_unreachable(res.get('error'))
+ return {'healthy': False, 'streak': streak}
+ except Exception as e: # noqa: BLE001
+ logger.warning('tramo health_check job failed: %s', e)
+ return {'error': str(e)}
+
+
+def _health_config():
+ from app.plugins_sdk import config as plugin_config
+ return plugin_config(SLUG)
+
+
+def _save_health(updates):
+ from app import db
+ from app.models.plugin import InstalledPlugin
+ row = InstalledPlugin.query.filter_by(slug=SLUG).first()
+ if not row:
+ return
+ merged = dict(row.config or {})
+ merged.update(updates)
+ row.config = merged
+ db.session.commit()
+
+
+def _bump_health_streak():
+ streak = int(_health_config().get('health_fail_streak') or 0) + 1
+ _save_health({'health_fail_streak': streak})
+ return streak
+
+
+def _reset_health_streak():
+ if _health_config().get('health_fail_streak'):
+ _save_health({'health_fail_streak': 0})
+
+
+def _notify_unreachable(error):
+ try:
+ from app.plugins_sdk import notify
+ notify.send('tramo.host_unreachable', to='admins',
+ data={'error': error}, category='system')
+ except Exception as e: # noqa: BLE001
+ logger.debug('tramo.host_unreachable notify failed: %s', e)
diff --git a/builtin-extensions/serverkit-tramo/backend/lifecycle.py b/builtin-extensions/serverkit-tramo/backend/lifecycle.py
new file mode 100644
index 00000000..aedd4fd1
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/backend/lifecycle.py
@@ -0,0 +1,78 @@
+"""Install / uninstall lifecycle hooks (serverkit-tramo / Automations extension).
+
+Contract (per the plugin SDK): a single positional arg -- the InstalledPlugin
+row. ``on_uninstall`` also accepts a ``purge`` flag. Everything here is wrapped
+so a hook failure never blocks install/uninstall.
+
+``on_install`` registers the extension's notification events and retires any
+ghost ``serverkit-workflows`` row left over from the builder this extension
+replaces (plan 45 Phase 4). It does NOT start the container -- the operator does
+that from the Automations Settings tab (mail pattern).
+
+``on_uninstall`` tears down everything provisioned by the engine: the container,
+the scoped call-back ApiKey, and the managed events-bridge subscription. Data
+dirs are deleted only on ``--purge``.
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def on_install(plugin):
+ """Register notification events; retire the replaced Workflow Builder row."""
+ try:
+ from app.plugins_sdk import notify
+ notify.register_event(
+ 'tramo.host_unreachable',
+ 'The Automations engine became unreachable',
+ template='generic', severity='warning', category='system')
+ notify.register_event(
+ 'tramo.run_failed',
+ 'An automation run failed',
+ template='generic', severity='warning', category='system')
+ logger.info('serverkit-tramo installed: notification events registered')
+ except Exception as e: # noqa: BLE001
+ logger.warning('serverkit-tramo on_install notify hook error: %s', e)
+
+ _retire_workflow_builder_row()
+
+
+def _retire_workflow_builder_row():
+ """Remove any lingering serverkit-workflows InstalledPlugin row.
+
+ The Workflow Builder extension is deleted from disk in plan 45 Phase 4, so
+ its backend/frontend no longer load, but an old InstalledPlugin row would
+ otherwise haunt the Marketplace as a broken entry (uninstall deletes the
+ row, so we mirror that). Best-effort.
+ """
+ try:
+ from app import db
+ from app.models.plugin import InstalledPlugin
+ row = InstalledPlugin.query.filter_by(slug='serverkit-workflows').first()
+ if row:
+ db.session.delete(row)
+ db.session.commit()
+ logger.info('serverkit-tramo: retired ghost serverkit-workflows row')
+ except Exception as e: # noqa: BLE001
+ logger.debug('serverkit-tramo: could not retire workflows row: %s', e)
+
+
+def on_uninstall(plugin, purge=False):
+ """Stop/remove the container, revoke the call-back key, drop the events sub."""
+ try:
+ from .host_service import TramoHostService
+ if TramoHostService.is_installed():
+ result = TramoHostService.uninstall(keep_data=not purge)
+ logger.info('serverkit-tramo on_uninstall container: %s', result)
+ else:
+ logger.info('serverkit-tramo on_uninstall: container not present')
+ except Exception as e: # noqa: BLE001
+ logger.warning('serverkit-tramo on_uninstall container error: %s', e)
+
+ try:
+ from . import events_bridge
+ events_bridge.revoke_callback_key()
+ events_bridge.disable_events_bridge()
+ logger.info('serverkit-tramo on_uninstall: call-back key + events bridge removed')
+ except Exception as e: # noqa: BLE001
+ logger.warning('serverkit-tramo on_uninstall bridge error: %s', e)
diff --git a/builtin-extensions/serverkit-tramo/backend/models.py b/builtin-extensions/serverkit-tramo/backend/models.py
new file mode 100644
index 00000000..721bf4f5
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/backend/models.py
@@ -0,0 +1,137 @@
+"""Data models for the serverkit-tramo (Automations) extension.
+
+Two tables, both namespaced ``ext_serverkit_tramo_*`` (dash -> underscore) so
+``--purge`` on uninstall drops exactly these:
+
+* :class:`TramoWorkflow` — a workflow *document* the panel owns. The ``doc``
+ column holds a tramo ``WorkflowDoc`` (plain JSON) edited in the browser; the
+ ``slug`` doubles as the server-side workflow id and the ``<slug>.json``
+ filename materialized into the container's bind-mounted workflows dir.
+* :class:`TramoRun` — a persisted summary of one execution, harvested from the
+ container's in-memory run ring (which evicts after 1000 runs) so run history
+ survives a restart.
+
+Registration mirrors the serverkit-k8s pattern: importing this module defines
+the tables on the shared metadata as a side effect; the manifest's
+``models: "models:register"`` then calls :func:`register` (a no-op passthrough)
+and the platform runs ``db.create_all()``.
+"""
+import json
+from datetime import datetime
+
+from app import db
+
+
+class TramoWorkflow(db.Model):
+ __tablename__ = 'ext_serverkit_tramo_workflows'
+
+ id = db.Column(db.Integer, primary_key=True)
+ name = db.Column(db.String(255), nullable=False)
+ # Server-side workflow id + <slug>.json filename. Unique, URL-safe.
+ slug = db.Column(db.String(255), unique=True, nullable=False, index=True)
+
+ # tramo WorkflowDoc JSON (edited by the embedded editor).
+ doc = db.Column(db.Text, nullable=True)
+
+ enabled = db.Column(db.Boolean, default=True, nullable=False)
+ # Bumped on every doc save so the editor/UI can detect stale state.
+ doc_version = db.Column(db.Integer, default=1, nullable=False)
+
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+ # Stamped when this workflow was last materialized + deployed to the engine.
+ deployed_at = db.Column(db.DateTime, nullable=True)
+
+ def get_doc(self):
+ """Return the parsed WorkflowDoc (empty dict if unset/invalid)."""
+ if not self.doc:
+ return {}
+ try:
+ return json.loads(self.doc)
+ except (ValueError, TypeError):
+ return {}
+
+ def set_doc(self, doc):
+ """Store a WorkflowDoc (dict or JSON string)."""
+ if doc is None:
+ self.doc = None
+ elif isinstance(doc, str):
+ self.doc = doc
+ else:
+ self.doc = json.dumps(doc)
+
+ def is_dirty(self):
+ """True when the doc changed since the last deploy (needs redeploy)."""
+ if not self.deployed_at:
+ return self.enabled
+ if not self.updated_at:
+ return False
+ return self.updated_at > self.deployed_at
+
+ def to_dict(self, include_doc=False):
+ out = {
+ 'id': self.id,
+ 'name': self.name,
+ 'slug': self.slug,
+ 'enabled': self.enabled,
+ 'doc_version': self.doc_version,
+ 'dirty': self.is_dirty(),
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ 'deployed_at': self.deployed_at.isoformat() if self.deployed_at else None,
+ }
+ if include_doc:
+ out['doc'] = self.get_doc()
+ return out
+
+
+class TramoRun(db.Model):
+ __tablename__ = 'ext_serverkit_tramo_runs'
+
+ id = db.Column(db.Integer, primary_key=True)
+ # tramo's own run id (from GET /api/runs). Unique so harvest upserts.
+ run_id = db.Column(db.String(255), unique=True, nullable=False, index=True)
+ workflow_slug = db.Column(db.String(255), nullable=True, index=True)
+ status = db.Column(db.String(32), nullable=True) # running|success|failed|suspended...
+ source = db.Column(db.String(32), nullable=True) # api|webhook|cron|replay
+ error = db.Column(db.Text, nullable=True)
+
+ usage = db.Column(db.Text, nullable=True) # JSON token/cost usage
+ pending_approvals = db.Column(db.Text, nullable=True) # JSON list
+ raw = db.Column(db.Text, nullable=True) # full run JSON as returned
+
+ started_at = db.Column(db.DateTime, nullable=True)
+ finished_at = db.Column(db.DateTime, nullable=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+
+ def _json(self, value):
+ if not value:
+ return None
+ try:
+ return json.loads(value)
+ except (ValueError, TypeError):
+ return None
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'run_id': self.run_id,
+ 'workflow_slug': self.workflow_slug,
+ 'status': self.status,
+ 'source': self.source,
+ 'error': self.error,
+ 'usage': self._json(self.usage),
+ 'pending_approvals': self._json(self.pending_approvals) or [],
+ 'started_at': self.started_at.isoformat() if self.started_at else None,
+ 'finished_at': self.finished_at.isoformat() if self.finished_at else None,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ }
+
+
+def register(db): # noqa: A002 - signature dictated by the platform (fn(db))
+ """No-op passthrough required by the manifest ``models: "models:register"``.
+
+ Importing this module already defined the tables on ``db.metadata``; the
+ platform runs ``db.create_all()``. Nothing else to do here.
+ """
+ return [TramoWorkflow, TramoRun]
diff --git a/builtin-extensions/serverkit-tramo/backend/run_sync.py b/builtin-extensions/serverkit-tramo/backend/run_sync.py
new file mode 100644
index 00000000..dc3effa7
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/backend/run_sync.py
@@ -0,0 +1,94 @@
+"""Run persistence helpers (serverkit-tramo / Automations extension).
+
+``@tramo/server`` keeps run history in an in-memory ring of 1000 (it evicts old
+runs and loses everything on restart), so the panel harvests run summaries into
+:class:`TramoRun`. Both the harvest job and the manual-run proxy funnel through
+:func:`upsert_run` (keyed on the tramo run id) so a run is never duplicated.
+
+tramo's run JSON field names are not frozen, so :func:`parse_run` reads a few
+aliases defensively and keeps the untouched original in ``raw``.
+"""
+import json
+import logging
+from datetime import datetime
+
+from app import db
+
+from .models import TramoRun
+
+logger = logging.getLogger(__name__)
+
+
+def _first(d, *keys):
+ for k in keys:
+ if isinstance(d, dict) and d.get(k) not in (None, ''):
+ return d.get(k)
+ return None
+
+
+def _parse_dt(value):
+ if not value:
+ return None
+ if isinstance(value, (int, float)):
+ try:
+ return datetime.utcfromtimestamp(value / 1000 if value > 1e12 else value)
+ except (ValueError, OSError):
+ return None
+ try:
+ return datetime.fromisoformat(str(value).replace('Z', '+00:00')).replace(tzinfo=None)
+ except (ValueError, TypeError):
+ return None
+
+
+def _json_dump(value):
+ if value is None:
+ return None
+ if isinstance(value, str):
+ return value
+ try:
+ return json.dumps(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def parse_run(run_json):
+ """Map a tramo run object to TramoRun column values (dict)."""
+ run_id = _first(run_json, 'id', 'runId', 'run_id')
+ return {
+ 'run_id': str(run_id) if run_id is not None else None,
+ 'workflow_slug': _first(run_json, 'workflowId', 'workflow_id',
+ 'workflowSlug', 'workflow_slug', 'workflow'),
+ 'status': _first(run_json, 'status', 'state'),
+ 'source': _first(run_json, 'source', 'trigger', 'triggerType', 'trigger_type'),
+ 'error': _first(run_json, 'error', 'errorMessage', 'error_message'),
+ 'usage': _json_dump(_first(run_json, 'usage', 'cost', 'tokens')),
+ 'pending_approvals': _json_dump(_first(run_json, 'pendingApprovals',
+ 'pending_approvals', 'approvals')),
+ 'started_at': _parse_dt(_first(run_json, 'startedAt', 'started_at', 'startTime')),
+ 'finished_at': _parse_dt(_first(run_json, 'finishedAt', 'finished_at',
+ 'endTime', 'completedAt')),
+ 'raw': _json_dump(run_json),
+ }
+
+
+def upsert_run(run_json):
+ """Insert or update a TramoRun from a tramo run object.
+
+ Returns ``(row, is_new)``. ``is_new`` is True only when the row did not exist
+ before, so callers can fire a one-shot notification on first sight.
+ """
+ fields = parse_run(run_json)
+ if not fields.get('run_id'):
+ return None, False
+
+ row = TramoRun.query.filter_by(run_id=fields['run_id']).first()
+ is_new = row is None
+ if is_new:
+ row = TramoRun(run_id=fields['run_id'])
+ db.session.add(row)
+ for key, value in fields.items():
+ if key == 'run_id':
+ continue
+ setattr(row, key, value)
+ db.session.commit()
+ return row, is_new
diff --git a/builtin-extensions/serverkit-tramo/backend/tramo.py b/builtin-extensions/serverkit-tramo/backend/tramo.py
new file mode 100644
index 00000000..3b01a21c
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/backend/tramo.py
@@ -0,0 +1,359 @@
+"""Automations API endpoints (serverkit-tramo extension, tramo engine).
+
+Mounted under ``/api/v1/tramo`` via the manifest's ``url_prefix``. Thin routing
+layer over the extension services -- all Docker, tramo-API, and DB work happens
+in :mod:`host_service`, :mod:`workflow_store`, :mod:`run_sync`, and
+:mod:`events_bridge`.
+
+Auth split (same as serverkit-mail / serverkit-k8s): reads need viewer, mutations
+need admin. The ONE exception is the inbound-webhook passthrough
+(``/hooks/<path>``) which is intentionally auth-exempt so external services can
+POST to a workflow's ``webhook-trigger`` node through the panel's public domain;
+per-trigger HMAC (tramo native) covers spoofing and the container stays
+loopback-only. The plugin-disabled 503 guard (attached by plugin_service) still
+runs on every route including the passthrough.
+"""
+import logging
+
+import requests
+from flask import Blueprint, jsonify, request, Response
+
+from app.middleware.rbac import admin_required, viewer_required
+
+from .host_service import TramoHostService, RUN_TIMEOUT
+from .workflow_store import WorkflowStore
+from . import events_bridge
+from .run_sync import upsert_run
+from .models import TramoRun
+
+logger = logging.getLogger(__name__)
+
+tramo_bp = Blueprint('tramo', __name__)
+
+_NOT_INSTALLED = ('The Automations engine is not installed. Install it from the '
+ 'Automations Settings tab (admin only).')
+
+# Response/hop headers we must not blindly relay when proxying.
+_HOP_HEADERS = {'content-length', 'transfer-encoding', 'connection',
+ 'content-encoding', 'host'}
+
+
+def _installed_or_error():
+ if not TramoHostService.is_installed():
+ return jsonify({'error': _NOT_INSTALLED}), 503
+ return None
+
+
+# ── Workflows CRUD ──
+
+@tramo_bp.route('/workflows', methods=['GET'])
+@viewer_required
+def list_workflows():
+ return jsonify({'workflows': WorkflowStore.list_workflows()}), 200
+
+
+@tramo_bp.route('/workflows/<slug>', methods=['GET'])
+@viewer_required
+def get_workflow(slug):
+ wf = WorkflowStore.get(slug)
+ if not wf:
+ return jsonify({'error': 'Workflow not found'}), 404
+ return jsonify(wf.to_dict(include_doc=True)), 200
+
+
+@tramo_bp.route('/workflows', methods=['POST'])
+@admin_required
+def create_workflow():
+ data = request.get_json(silent=True) or {}
+ try:
+ wf = WorkflowStore.create(
+ name=data.get('name'),
+ doc=data.get('doc'),
+ enabled=data.get('enabled', True),
+ )
+ except ValueError as e:
+ return jsonify({'error': str(e)}), 400
+ return jsonify(wf.to_dict(include_doc=True)), 201
+
+
+@tramo_bp.route('/workflows/<slug>', methods=['PUT'])
+@admin_required
+def update_workflow(slug):
+ data = request.get_json(silent=True) or {}
+ try:
+ wf = WorkflowStore.update(
+ slug,
+ name=data.get('name'),
+ doc=data.get('doc'),
+ enabled=data.get('enabled'),
+ )
+ except ValueError as e:
+ code = 404 if 'not found' in str(e).lower() else 400
+ return jsonify({'error': str(e)}), code
+ return jsonify(wf.to_dict(include_doc=True)), 200
+
+
+@tramo_bp.route('/workflows/<slug>', methods=['DELETE'])
+@admin_required
+def delete_workflow(slug):
+ try:
+ WorkflowStore.delete(slug)
+ except ValueError as e:
+ return jsonify({'error': str(e)}), 404
+ return jsonify({'deleted': True}), 200
+
+
+@tramo_bp.route('/deploy', methods=['POST'])
+@admin_required
+def deploy():
+ result = WorkflowStore.deploy()
+ if not result.get('success'):
+ code = 503 if 'not installed' in (result.get('error') or '') else 400
+ return jsonify({'error': result.get('error', 'Deploy failed'),
+ 'materialized': result.get('materialized')}), code
+ return jsonify(result), 200
+
+
+# ── Runs / approvals (proxied to the engine) ──
+
+@tramo_bp.route('/workflows/<slug>/run', methods=['POST'])
+@admin_required
+def run_workflow(slug):
+ guard = _installed_or_error()
+ if guard:
+ return guard
+ wf = WorkflowStore.get(slug)
+ if not wf:
+ return jsonify({'error': 'Workflow not found'}), 404
+ payload = request.get_json(silent=True) or {}
+ res = TramoHostService._api('POST', f'/workflows/{slug}/run', payload,
+ timeout=RUN_TIMEOUT)
+ if not res.get('success'):
+ return jsonify({'error': res.get('error', 'Run failed')}), 502
+ summary = res.get('data') or {}
+ try:
+ row, _ = upsert_run(summary if isinstance(summary, dict) else {})
+ run_dict = row.to_dict() if row else None
+ except Exception as e: # noqa: BLE001
+ logger.warning('tramo: failed to persist run summary: %s', e)
+ run_dict = None
+ return jsonify({'run': run_dict, 'result': summary}), 200
+
+
+@tramo_bp.route('/runs', methods=['GET'])
+@viewer_required
+def list_runs():
+ q = TramoRun.query
+ slug = request.args.get('workflow')
+ status = request.args.get('status')
+ if slug:
+ q = q.filter_by(workflow_slug=slug)
+ if status:
+ q = q.filter_by(status=status)
+ try:
+ limit = min(int(request.args.get('limit', 100)), 500)
+ except (TypeError, ValueError):
+ limit = 100
+ rows = q.order_by(TramoRun.id.desc()).limit(limit).all()
+ return jsonify({'runs': [r.to_dict() for r in rows]}), 200
+
+
+@tramo_bp.route('/runs/<run_id>', methods=['GET'])
+@viewer_required
+def get_run(run_id):
+ row = TramoRun.query.filter_by(run_id=run_id).first()
+ if not row:
+ return jsonify({'error': 'Run not found'}), 404
+ return jsonify(row.to_dict()), 200
+
+
+@tramo_bp.route('/runs/<run_id>/replay', methods=['POST'])
+@admin_required
+def replay_run(run_id):
+ guard = _installed_or_error()
+ if guard:
+ return guard
+ res = TramoHostService._api('POST', f'/runs/{run_id}/replay')
+ if not res.get('success'):
+ return jsonify({'error': res.get('error', 'Replay failed')}), 502
+ try:
+ if isinstance(res.get('data'), dict):
+ upsert_run(res['data'])
+ except Exception as e: # noqa: BLE001
+ logger.debug('replay upsert failed: %s', e)
+ return jsonify(res.get('data') or {'replayed': True}), 200
+
+
+@tramo_bp.route('/approvals', methods=['GET'])
+@viewer_required
+def list_approvals():
+ guard = _installed_or_error()
+ if guard:
+ return guard
+ res = TramoHostService._api('GET', '/approvals')
+ if not res.get('success'):
+ return jsonify({'approvals': [], 'note': res.get('error')}), 200
+ data = res.get('data')
+ approvals = data if isinstance(data, list) else (data or {}).get('approvals', [])
+ return jsonify({'approvals': approvals}), 200
+
+
+@tramo_bp.route('/runs/<run_id>/approve', methods=['POST'])
+@admin_required
+def approve_run(run_id):
+ guard = _installed_or_error()
+ if guard:
+ return guard
+ payload = request.get_json(silent=True) or {}
+ res = TramoHostService._api('POST', f'/runs/{run_id}/approve', payload)
+ if not res.get('success'):
+ return jsonify({'error': res.get('error', 'Approve failed')}), 502
+ return jsonify(res.get('data') or {'approved': True}), 200
+
+
+# ── Host (engine) lifecycle ──
+
+@tramo_bp.route('/host/status', methods=['GET'])
+@viewer_required
+def host_status():
+ return jsonify(TramoHostService.get_status()), 200
+
+
+@tramo_bp.route('/host/install', methods=['POST'])
+@admin_required
+def host_install():
+ data = request.get_json(silent=True) or {}
+ # Issue the scoped call-back key so workflows can act back on the panel.
+ callback_key = events_bridge.issue_callback_key()
+ result = TramoHostService.install(
+ host_port=data.get('host_port'),
+ callback_api_key=callback_key,
+ )
+ if not result.get('success'):
+ # Roll back the key we just issued if the container didn't start.
+ events_bridge.revoke_callback_key()
+ return jsonify({'error': result.get('error', 'Install failed')}), 400
+ return jsonify(result), 201
+
+
+@tramo_bp.route('/host/install', methods=['DELETE'])
+@admin_required
+def host_uninstall():
+ keep_data = (request.args.get('keep_data', 'true').lower()
+ not in ('false', '0', 'no'))
+ result = TramoHostService.uninstall(keep_data=keep_data)
+ events_bridge.revoke_callback_key()
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Uninstall failed')}), 400
+ return jsonify(result), 200
+
+
+@tramo_bp.route('/host/control/<action>', methods=['POST'])
+@admin_required
+def host_control(action):
+ guard = _installed_or_error()
+ if guard:
+ return guard
+ result = TramoHostService.control(action)
+ if not result.get('success'):
+ return jsonify({'error': result.get('error', 'Control failed')}), 400
+ return jsonify(result), 200
+
+
+# ── Settings ──
+
+@tramo_bp.route('/settings', methods=['GET'])
+@viewer_required
+def get_settings():
+ return jsonify({
+ 'host_port': TramoHostService.host_port(),
+ 'events_bridge_enabled': events_bridge.is_events_bridge_enabled(),
+ # Names only -- secret values are never returned.
+ 'pack_secret_names': sorted(TramoHostService.get_pack_secrets().keys()),
+ }), 200
+
+
+@tramo_bp.route('/settings', methods=['PUT'])
+@admin_required
+def update_settings():
+ data = request.get_json(silent=True) or {}
+ out = {}
+
+ if 'pack_secrets' in data and isinstance(data['pack_secrets'], dict):
+ out['pack_secret_names'] = TramoHostService.set_pack_secrets(data['pack_secrets'])
+
+ if 'host_port' in data:
+ try:
+ port = int(data['host_port'])
+ if not (1024 <= port <= 65535):
+ raise ValueError
+ TramoHostService._save_config({'host_port': port})
+ out['host_port'] = port
+ except (TypeError, ValueError):
+ return jsonify({'error': 'host_port must be an integer 1024-65535'}), 400
+
+ if 'events_bridge_enabled' in data:
+ if data['events_bridge_enabled']:
+ events_bridge.enable_events_bridge()
+ else:
+ events_bridge.disable_events_bridge()
+ out['events_bridge_enabled'] = events_bridge.is_events_bridge_enabled()
+
+ return jsonify(out), 200
+
+
+# ── Legacy Workflow Builder export (read-only, admin) ──
+
+@tramo_bp.route('/legacy-workflows', methods=['GET'])
+@admin_required
+def legacy_workflows():
+ """Read-only dump of the retired Workflow Builder's rows (plan 45 Phase 4).
+
+ The old ``workflows`` tables are kept (no data loss); this lets an operator
+ rebuild those flows by hand in tramo. Never fails if the model is gone.
+ """
+ try:
+ from app.models.workflow import Workflow
+ except Exception: # noqa: BLE001
+ return jsonify({'workflows': [], 'note': 'legacy workflow model not present'}), 200
+ try:
+ rows = Workflow.query.all()
+ out = [w.to_dict() if hasattr(w, 'to_dict') else {'id': w.id, 'name': getattr(w, 'name', None)}
+ for w in rows]
+ except Exception as e: # noqa: BLE001
+ return jsonify({'workflows': [], 'note': f'could not read legacy workflows: {e}'}), 200
+ return jsonify({'workflows': out}), 200
+
+
+# ── Inbound webhook passthrough (AUTH-EXEMPT) ──
+
+@tramo_bp.route('/hooks/<path:subpath>',
+ methods=['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
+def hooks_passthrough(subpath):
+ """Forward an external webhook to the engine's trigger dispatcher.
+
+ Intentionally has NO auth decorator: external services POST here through the
+ panel's public domain to fire a ``webhook-trigger`` node. The container is
+ loopback-only, so this is the only way in; per-trigger HMAC (configured on
+ the node) authenticates the payload.
+ """
+ if not TramoHostService.is_installed():
+ return jsonify({'error': _NOT_INSTALLED}), 503
+
+ target = f'http://127.0.0.1:{TramoHostService.host_port()}/hooks/{subpath}'
+ fwd_headers = {k: v for k, v in request.headers
+ if k.lower() not in _HOP_HEADERS}
+ try:
+ upstream = requests.request(
+ request.method, target,
+ params=request.args,
+ data=request.get_data(),
+ headers=fwd_headers,
+ timeout=30,
+ )
+ except requests.RequestException as e:
+ return jsonify({'error': f'Automations engine unreachable: {e}'}), 502
+
+ resp_headers = [(k, v) for k, v in upstream.headers.items()
+ if k.lower() not in _HOP_HEADERS]
+ return Response(upstream.content, status=upstream.status_code, headers=resp_headers)
diff --git a/builtin-extensions/serverkit-tramo/backend/workflow_store.py b/builtin-extensions/serverkit-tramo/backend/workflow_store.py
new file mode 100644
index 00000000..f90073e1
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/backend/workflow_store.py
@@ -0,0 +1,204 @@
+"""Workflow document store (serverkit-tramo / Automations extension).
+
+CRUD over :class:`TramoWorkflow` rows plus the two engine-facing operations:
+
+* :meth:`WorkflowStore.materialize` — write every *enabled* workflow's doc as
+ ``<slug>.json`` into the container's bind-mounted workflows dir and prune the
+ files of disabled/deleted workflows.
+* :meth:`WorkflowStore.deploy` — materialize, then restart the container so
+ ``@tramo/server`` re-reads the dir (it loads workflows once at boot), then
+ stamp ``deployed_at`` on the enabled rows.
+
+File I/O goes through small choke-point classmethods (``_write_file`` /
+``_remove_file`` / ``_list_files``) so it stays privileged (the data dir is
+root-owned) and mockable in tests.
+"""
+import json
+import logging
+import os
+import re
+import tempfile
+
+from app import db
+
+from .models import TramoWorkflow
+from .host_service import TramoHostService, HOST_WORKFLOWS_DIR
+
+logger = logging.getLogger(__name__)
+
+_SLUG_RE = re.compile(r'[^a-z0-9]+')
+
+
+def slugify(value):
+ """Lowercase, hyphenated, URL/filename-safe slug."""
+ base = _SLUG_RE.sub('-', (value or '').strip().lower()).strip('-')
+ return base or 'workflow'
+
+
+class WorkflowStore:
+ """DB CRUD + engine materialization for automation workflows."""
+
+ # ---------- CRUD ----------
+
+ @classmethod
+ def list_workflows(cls):
+ rows = TramoWorkflow.query.order_by(TramoWorkflow.updated_at.desc()).all()
+ return [w.to_dict() for w in rows]
+
+ @classmethod
+ def get(cls, slug):
+ return TramoWorkflow.query.filter_by(slug=slug).first()
+
+ @classmethod
+ def _unique_slug(cls, name, ignore_id=None):
+ base = slugify(name)
+ candidate = base
+ n = 2
+ while True:
+ existing = TramoWorkflow.query.filter_by(slug=candidate).first()
+ if not existing or existing.id == ignore_id:
+ return candidate
+ candidate = f'{base}-{n}'
+ n += 1
+
+ @classmethod
+ def create(cls, name, doc=None, enabled=True):
+ name = (name or '').strip()
+ if not name:
+ raise ValueError('A workflow name is required')
+ wf = TramoWorkflow(
+ name=name,
+ slug=cls._unique_slug(name),
+ enabled=bool(enabled),
+ doc_version=1,
+ )
+ wf.set_doc(doc if doc is not None else cls._empty_doc(wf.slug, name))
+ db.session.add(wf)
+ db.session.commit()
+ return wf
+
+ @classmethod
+ def update(cls, slug, name=None, doc=None, enabled=None):
+ wf = cls.get(slug)
+ if not wf:
+ raise ValueError('Workflow not found')
+ if name is not None:
+ name = name.strip()
+ if not name:
+ raise ValueError('A workflow name is required')
+ wf.name = name
+ if enabled is not None:
+ wf.enabled = bool(enabled)
+ if doc is not None:
+ wf.set_doc(doc)
+ wf.doc_version = (wf.doc_version or 1) + 1
+ db.session.commit()
+ return wf
+
+ @classmethod
+ def delete(cls, slug):
+ wf = cls.get(slug)
+ if not wf:
+ raise ValueError('Workflow not found')
+ db.session.delete(wf)
+ db.session.commit()
+ # Best-effort prune the materialized file.
+ try:
+ cls._remove_file(slug)
+ except Exception as e: # noqa: BLE001
+ logger.debug('could not remove workflow file for %s: %s', slug, e)
+ return True
+
+ @staticmethod
+ def _empty_doc(slug, name):
+ """A minimal valid tramo WorkflowDoc so a new workflow opens cleanly."""
+ return {
+ 'id': slug,
+ 'name': name,
+ 'nodes': [],
+ 'edges': [],
+ }
+
+ # ---------- engine materialization ----------
+
+ @classmethod
+ def _write_file(cls, slug, doc):
+ """Write ``<slug>.json`` into the workflows dir (privileged). Linux-only."""
+ if os.name == 'nt':
+ return
+ payload = json.dumps(doc, indent=2)
+ dest = f'{HOST_WORKFLOWS_DIR}/{slug}.json'
+ from app.utils.system import run_privileged
+ run_privileged(['mkdir', '-p', HOST_WORKFLOWS_DIR])
+ with tempfile.NamedTemporaryFile('w', suffix='.json', delete=False) as tmp:
+ tmp.write(payload)
+ tmp_path = tmp.name
+ try:
+ run_privileged(['cp', tmp_path, dest])
+ finally:
+ try:
+ os.unlink(tmp_path)
+ except OSError:
+ pass
+
+ @classmethod
+ def _remove_file(cls, slug):
+ if os.name == 'nt':
+ return
+ from app.utils.system import run_privileged
+ run_privileged(['rm', '-f', f'{HOST_WORKFLOWS_DIR}/{slug}.json'])
+
+ @classmethod
+ def _list_files(cls):
+ """Slugs currently materialized in the workflows dir."""
+ if os.name == 'nt':
+ return []
+ from app.utils.system import run_privileged
+ res = run_privileged(['ls', '-1', HOST_WORKFLOWS_DIR])
+ if getattr(res, 'returncode', 1) != 0:
+ return []
+ out = getattr(res, 'stdout', '') or ''
+ return [line[:-5] for line in out.splitlines()
+ if line.strip().endswith('.json')]
+
+ @classmethod
+ def materialize(cls):
+ """Write enabled docs, prune the rest. Returns a summary dict."""
+ enabled = TramoWorkflow.query.filter_by(enabled=True).all()
+ enabled_slugs = {w.slug for w in enabled}
+ written = []
+ for wf in enabled:
+ cls._write_file(wf.slug, wf.get_doc())
+ written.append(wf.slug)
+ pruned = []
+ for slug in cls._list_files():
+ if slug not in enabled_slugs:
+ cls._remove_file(slug)
+ pruned.append(slug)
+ return {'written': written, 'pruned': pruned}
+
+ @classmethod
+ def deploy(cls):
+ """Materialize + restart the engine + stamp ``deployed_at``.
+
+ Restart is required because ``@tramo/server`` reads the workflows dir
+ only at boot (no reload endpoint yet). The checkpoint store preserves any
+ suspended runs across the restart.
+ """
+ from datetime import datetime
+
+ if not TramoHostService.is_installed():
+ return {'success': False,
+ 'error': 'The Automations engine is not installed. Install it '
+ 'from the Automations Settings tab first.'}
+ summary = cls.materialize()
+ restart = TramoHostService.control('restart')
+ if not restart.get('success'):
+ return {'success': False,
+ 'error': restart.get('error', 'Failed to restart the engine'),
+ 'materialized': summary}
+ now = datetime.utcnow()
+ for wf in TramoWorkflow.query.filter_by(enabled=True).all():
+ wf.deployed_at = now
+ db.session.commit()
+ return {'success': True, 'message': 'Automations deployed', 'materialized': summary}
diff --git a/builtin-extensions/serverkit-tramo/plugin.json b/builtin-extensions/serverkit-tramo/plugin.json
new file mode 100644
index 00000000..46ea234b
--- /dev/null
+++ b/builtin-extensions/serverkit-tramo/plugin.json
@@ -0,0 +1,55 @@
+{
+ "name": "serverkit-tramo",
+ "display_name": "Automations",
+ "version": "1.0.0",
+ "description": "Node-based automation builder powered by tramo. Design workflows on a visual canvas (triggers, actions, branches, loops, approval gates) that react to panel events or run on a schedule, with 21 brand integration packs (Telegram, GitHub, Gmail, Discord, Notion, Stripe, Cloudflare, Postgres, Twilio and more). Enabled workflows deploy to a managed tramo container on the panel host that runs them headless, with run history, approvals, and inbound webhooks proxied through the panel. This replaces the older drag-and-drop Workflow Builder.",
+ "author": "ServerKit",
+ "license": "MIT",
+ "category": "deployment",
+ "homepage": "https://github.com/jhd3197/ServerKit",
+ "permissions": ["docker", "shell", "filesystem", "network"],
+ "min_panel_version": "1.7.0",
+ "entry_point": "tramo:tramo_bp",
+ "url_prefix": "/api/v1/tramo",
+ "models": "models:register",
+ "lifecycle": {
+ "install": "lifecycle:on_install",
+ "uninstall": "lifecycle:on_uninstall"
+ },
+ "jobs": [
+ { "kind": "tramo.harvest_runs", "handler": "jobs:harvest_runs" },
+ { "kind": "tramo.health_check", "handler": "jobs:health_check" }
+ ],
+ "schedules": [
+ { "name": "tramo-harvest-runs", "kind": "tramo.harvest_runs", "interval_seconds": 120 },
+ { "name": "tramo-health-check", "kind": "tramo.health_check", "interval_seconds": 300 }
+ ],
+ "icon": "<circle cx=\"18\" cy=\"5\" r=\"3\"/><circle cx=\"6\" cy=\"12\" r=\"3\"/><circle cx=\"18\" cy=\"19\" r=\"3\"/><path d=\"M8.59 13.51l6.83 3.98\"/><path d=\"M15.41 6.51l-6.82 3.98\"/>",
+ "contributions": {
+ "nav": [
+ {
+ "id": "automations",
+ "label": "Automations",
+ "route": "/automations",
+ "category": "operations",
+ "icon": "<circle cx=\"18\" cy=\"5\" r=\"3\"/><circle cx=\"6\" cy=\"12\" r=\"3\"/><circle cx=\"18\" cy=\"19\" r=\"3\"/><path d=\"M8.59 13.51l6.83 3.98\"/><path d=\"M15.41 6.51l-6.82 3.98\"/>"
+ }
+ ],
+ "routes": [
+ { "path": "automations", "component": "AutomationsPage" },
+ { "path": "automations/:tab", "component": "AutomationsPage" },
+ { "path": "automations/edit/:slug", "component": "AutomationEditorPage", "layout": "full" }
+ ],
+ "page_titles": {
+ "/automations": "Automations"
+ },
+ "command_palette": [
+ {
+ "label": "Automations",
+ "path": "/automations",
+ "category": "Pages",
+ "keywords": "automation workflow tramo trigger action schedule webhook telegram github integration pipeline event"
+ }
+ ]
+ }
+}