rterm-backend 1.9.0 → 2.3.1

package/LICENSE.md

@@ -23,6 +23,7 @@ Notable bundled/linked components include:
 - **node-pty** (MIT) — pseudo-terminal bindings
 - **better-sqlite3** (MIT) — SQLite bindings
 - **ws** (MIT) — WebSocket library
+- **@nats-io/transport-node, @nats-io/nats-core** (Apache-2.0) — NATS client
 - **@langchain/core, @langchain/langgraph** (MIT) — agent orchestration
 - **@modelcontextprotocol/sdk** (MIT) — Model Context Protocol
 - **web-tree-sitter, tree-sitter-bash** (MIT) — command parsing

package/README.md

@@ -10,7 +10,10 @@ drive it remotely.
 │ your agent / │ ◄────────────────────► │ rterm-backend (gybackend)        │
 │ program / CI │                        │  • AI agent (LLM + tools)        │
 └──────────────┘                        │  • SSH / WinRM / Serial / local  │
-                                        │  • fleet orchestration           │
+                                        │  • advanced automation           │
+                                        │    (event-driven triggers, DAG   │
+                                        │     playbooks, idempotent runs)  │
+                                        │  • NATS event mesh (fleet-wide)  │
                                         │  • scheduled automation (cron)   │
                                         │  • change management (MOP)       │
                                         └──────────────────────────────────┘
@@ -22,10 +25,10 @@ drive it remotely.
 npm install -g rterm-backend
 ```
 
-This installs the `gybackend` CLI plus the small set of native/runtime
-dependencies (`better-sqlite3`, `node-pty`, `ssh2`, tree-sitter wasm, and
-optional `serialport`). Everything else — the AI agent, MCP SDK, SSH/WinRM/
-Serial handling, automation engine — is bundled into the single CLI file.
+This installs the `gybackend` CLI plus a small set of native/runtime deps
+(`better-sqlite3`, `node-pty`, `ssh2`, tree-sitter wasm, `@nats-io/transport-node`,
+and optional `serialport`). Everything else — the AI agent, MCP SDK, SSH/WinRM/
+Serial handling, the automation engine, the NATS client — is bundled in.
 
 ## Run
 
@@ -33,11 +36,7 @@ Serial handling, automation engine — is bundled into the single CLI file.
 gybackend
 ```
 
-Or without a global install:
-
-```bash
-npx rterm-backend
-```
+Or without a global install: `npx rterm-backend`.
 
 On boot it prints the gateway endpoint:
 
@@ -47,6 +46,42 @@ On boot it prints the gateway endpoint:
 [gybackend] Data directory: ./.gybackend-data
 ```
 
+## Advanced Automation (v1.9.x)
+
+- **Event-driven triggers** — fire a playbook (or propose a MOP change) when a
+  terminal-output **pattern** matches, a monitor **threshold** is crossed, or a
+  **webhook** fires. Per-trigger cooldown + concurrency cap prevent storms.
+  Manage via the `manage_trigger` RPC/tool; persisted in the data dir.
+- **DAG / parallel playbooks** — `dependsOn` step graphs with capped parallelism
+  (`maxParallelSteps`), cycle detection, fan-out/fan-in.
+- **Parameterized runbooks with secrets** — `params[]` injected at run time,
+  `{{param.name}}` substitution, secret values masked in records/logs.
+- **Idempotent desired-state config** — steps with `desiredState` are skipped
+  when the target is already in the desired state (converge-style).
+- **Cross-host orchestration variables** — `captureVar` from one step's output
+  feeds `{{var}}` into later steps.
+
+## NATS event mesh (fleet-wide triggers)
+
+Point the backend at a [NATS server](https://nats.io) and every instance's
+terminal output + monitor snapshots publish onto shared subjects — so a trigger
+fires **across the whole fleet**, not just the local host. Configure in
+`settings.json`:
+
+```jsonc
+{
+  "nats": {
+    "enabled": true,
+    "url": "nats://localhost:4222",      // or "servers": ["nats://a:4222", "nats://b:4222"]
+    "prefix": "rterm"                     // subject prefix (default "rterm")
+  }
+}
+```
+
+Subjects: `rterm.term.data`, `rterm.monitor.snapshot`, `rterm.trigger.fire`.
+Run a NATS server with `nats-server` (single binary) as the mesh hub. Best-effort:
+a NATS outage never blocks local automation.
+
 ## Configure (environment variables)
 
 | Var | Default | Meaning |
@@ -56,17 +91,13 @@ On boot it prints the gateway endpoint:
 | `GYBACKEND_WS_PORT` | `17888` | gateway port |
 | `GYBACKEND_DATA_DIR` | `./.gybackend-data` | settings, ledgers, skills, sessions |
 | `GYBACKEND_BOOTSTRAP_LOCAL_TERMINAL` | `true` | open a local shell tab on boot |
-| `GYBACKEND_TERMINAL_ID` | `local-main` | id of the bootstrap terminal |
-| `GYBACKEND_TERMINAL_TITLE` | `Local` | title of the bootstrap terminal |
-| `GYBACKEND_TERMINAL_CWD` | — | cwd of the bootstrap terminal |
-| `GYBACKEND_TERMINAL_SHELL` | — | shell of the bootstrap terminal |
+| `GYBACKEND_TERMINAL_ID` | `local-main` | bootstrap terminal id |
+| `GYBACKEND_TERMINAL_TITLE` | `Local` | bootstrap terminal title |
+| `GYBACKEND_TERMINAL_CWD` | — | bootstrap terminal cwd |
+| `GYBACKEND_TERMINAL_SHELL` | — | bootstrap terminal shell |
 
 ### Share settings with the desktop app
 
-By default the daemon uses its **own** data dir (a blank slate). To reuse the
-desktop RTerm app's settings, saved connections, and model keys, point it at
-the app's settings directory:
-
 ```bash
 # macOS
 GYBACKEND_DATA_DIR="$HOME/Library/Application Support/rterm" gybackend
@@ -78,45 +109,23 @@ set GYBACKEND_DATA_DIR=%APPDATA%\rterm && gybackend
 
 ## Drive it remotely
 
-The gateway is **WebSocket JSON-RPC**. Request `{ "id": "1", "method": "<name>",
+The gateway is **WebSocket JSON-RPC**: request `{ "id": "1", "method": "<name>",
 "params": {...} }` → response `{ "type": "gateway:response", "id": "1", "ok":
-true|false, "result"|"error" }`. Progress streams back as `gateway:event` /
-`gateway:raw` messages. Localhost connections skip token auth by default.
-
-Quick check with [`websocat`](https://github.com/vi/websocat):
+true|false, "result"|"error" }`. Localhost skips token auth by default.
 
 ```bash
 echo '{"id":"1","method":"gateway:ping"}' | websocat -n1 ws://127.0.0.1:17888
 # -> {"type":"gateway:response","id":"1","ok":true,"result":{"pong":true,...}}
 ```
 
-Run an AI agent task on a server:
-
-```bash
-websocat ws://127.0.0.1:17888
-{"id":"1","method":"gateway:createSession"}
-{"id":"2","method":"agent:startTaskAsync","params":{"sessionId":"<sid>","userInput":"Update AV signatures on the saved WinRM connection AWS-Windows-Server-1 and report the version"}}
-```
-
-**Full RPC reference + client libraries** (Node CLI, Python, websocat examples):
-see the [`rterm-gateway` skill](https://github.com/DrOlu/agent-skills/tree/main/skills/rterm-gateway).
-
-## What you can do with it
-
-- **AI agent tasks** — `agent:startTask` / `agent:startTaskAsync` (multi-step, tool-using)
-- **Terminals** — open/run SSH, WinRM, Serial, local tabs and send commands
-- **Files** — read/write/transfer on any connected host (`filesystem:*`)
-- **Fleet** — run a command across many servers, collect structured results
-- **Automation** — playbooks, scheduled cron jobs, config templates
-- **Change management (MOP)** — plan → approve → run with validation + automatic rollback
-- **Settings/policy** — manage connections, command policy, skills, memory, models
+**Full RPC reference + clients:** the [`rterm-gateway` skill](https://github.com/DrOlu/agent-skills/tree/main/skills/rterm-gateway) (Node CLI, Python, websocat).
+**Lifecycle management:** the [`rterm-backend` skill](https://github.com/DrOlu/agent-skills/tree/main/skills/rterm-backend).
 
 ## Requirements
 
-- **Node.js ≥ 18** on the host. Native deps (`better-sqlite3`, `node-pty`,
-  `ssh2` crypto, tree-sitter) install prebuilt binaries for common platforms;
-  on unusual platforms they build from source (needs a C/C++ toolchain).
+**Node.js ≥ 18.** Native deps install prebuilt binaries for common platforms; on
+unusual platforms they compile from source (needs a C/C++ toolchain).
 
 ## License
 
-See `LICENSE.md`. RTerm — Hyperspace Technologies — https://github.com/DrOlu/RTerm
+CC BY-NC 4.0 — see `LICENSE.md`. RTerm — Hyperspace Technologies — https://github.com/DrOlu/RTerm