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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
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__.pynew file mode 100644index 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.pynew file mode 100644index 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 Truediff --git a/builtin-extensions/serverkit-tramo/backend/host_service.py b/builtin-extensions/serverkit-tramo/backend/host_service.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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_newdiff --git a/builtin-extensions/serverkit-tramo/backend/tramo.py b/builtin-extensions/serverkit-tramo/backend/tramo.pynew file mode 100644index 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.pynew file mode 100644index 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.jsonnew file mode 100644index 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"+ }+ ]+ }+}