@openenthrium/oe-runtime 1.6.8 → 1.7.0

package/README.md

@@ -19,16 +19,21 @@ Open Enthrium AI Agent Runtime (OE Runtime) is a standalone, cross-platform bina
 - **No LangChain. No Python. No code.** Agents are plain YAML files.
 - **No install.** Single binary for Windows, Linux, and macOS. No Node.js, no Docker on the target machine.
 - **45+ connector categories.** PostgreSQL, MySQL, MongoDB, S3, Slack, GitHub, SSH, REST API, Kafka, and more — all built in.
+- **Agent chains.** Chain agents together in YAML — auto chains fire in sequence; manual chains pause for human approval in CLI (y/n prompt), HTTP (`/approve-chain`), or any MCP-enabled AI chat (`approve_chain` tool).
 - **HTTP server mode.** `--serve` turns the runtime into a persistent API server any app can call.
+- **Messaging platform integration.** Receive messages from Telegram, Slack, WhatsApp, Teams and run agents in response — same YAML agents, same connectors, universal command language (`/run`, `/agents`, `/approve`, `/status`).
+- **Project system.** `oe-project.json` registers multiple agents by name, sets a default agent, and links projects together — one config, many agents.
 - **Self-hosted.** Runs entirely on your own machine. No call-home. Own your data.
 
 ---
 
 ## Sample Library
 
-Download [oe-runtime-samples.zip](https://github.com/enthrium/open-enthrium-ai-agent-runtime/releases/latest/download/oe-runtime-samples.zip) for 21 ready-to-run starter kits — each with a complete `agent.yaml` + `oe-config.json`:
+Download [oe-runtime-samples.zip](https://github.com/enthrium/open-enthrium-ai-agent-runtime/releases/latest/download/oe-runtime-samples.zip) for 24 ready-to-run starter kits — each with a complete `agent.yaml` + `oe-config.json`:
 
-`sql-databases` · `nosql-cache` · `file-storage` · `cloud-drives` · `email` · `team-messaging` · `telegram` · `productivity-crm` · `rest-api` · `graphql` · `ssh` · `message-queues` · `iot-messaging` · `web-search` · `ocr-vision` · `image-generation` · `speech-audio` · `video-generation` · `music-generation` · `blockchain-web3` · `directory-identity`
+**Getting started** — `hello-world` · `chains` · `my-ai-project`
+
+**By connector** — `sql-databases` · `nosql-cache` · `file-storage` · `cloud-drives` · `email` · `team-messaging` · `telegram` · `productivity-crm` · `rest-api` · `graphql` · `ssh` · `message-queues` · `iot-messaging` · `web-search` · `ocr-vision` · `image-generation` · `speech-audio` · `video-generation` · `music-generation` · `blockchain-web3` · `directory-identity`
 
 ---
 
@@ -119,6 +124,17 @@ connectors:
 | `connectors` | No | Connector references matched to credentials in `oe-config.json` |
 | `steps` | No | Named workflow steps injected sequentially into the system prompt |
 | `maxRounds` | No | Max LLM tool-call iterations (default: 25) |
+| `chains` | No | Agents to run after this one completes — see Agent Chains below |
+
+**`chains` syntax:**
+```yaml
+chains:
+  - next_agent: ./followup.yaml     # relative path from this agent file
+    trigger_type: auto              # fires immediately, output passed as context
+
+  - next_agent: ./notify.yaml
+    trigger_type: manual            # CLI: y/n prompt · HTTP: /approve-chain · MCP: approve_chain tool
+```
 
 **3. Run it**
 
@@ -177,30 +193,46 @@ All endpoints require the `x-api-key` header when `server.apiKey` is set in your
 | Method | Path | Description |
 |---|---|---|
 | `GET` | `/health` | Liveness check — returns `{ "status": "ok", "version": "..." }` |
+| `GET` | `/status` | Health + project info + connector list + uptime |
+| `POST` | `/command` | Universal command endpoint — `{ text: "/run agent-name" }` |
 | `POST` | `/run` | Run an agent from an inline YAML string |
 | `POST` | `/run-file` | Run an agent from a YAML file path on disk |
+| `POST` | `/approve-chain` | Approve or reject a pending manual chain |
+| `POST` | `/webhook/telegram` | Telegram webhook receiver (enabled via `server.webhook`) |
+| `POST` | `/webhook/slack` | Slack webhook receiver (enabled via `server.webhook`) |
 
-**POST /run** — body:
+**POST /run-file** — body:
 ```json
 {
-  "yaml": "name: Hi\nsteps:\n  - name: Greet\n    content: Say hi!",
-  "params": {},
+  "file": "/path/to/agent.yaml",
+  "params": { "topic": "AI trends" },
   "input": "Run"
 }
 ```
 
-**POST /run-file** — body:
+**Response** (both /run and /run-file):
 ```json
 {
-  "file": "/path/to/agent.yaml",
-  "params": { "topic": "AI trends" },
-  "input": "Run"
+  "success": true,
+  "output": "Agent output...",
+  "chains": [
+    { "agent": "Follow-up Agent", "output": "Chain complete ✅", "chains": [], "pending_chains": [] }
+  ],
+  "pending_chains": [
+    { "chain_id": "abc123xyz", "next_agent": "./notify.yaml", "output_preview": "Agent output..." }
+  ],
+  "duration_ms": 1234
 }
 ```
 
-**Response** (both /run and /run-file):
+**POST /approve-chain** — approve or reject a manual chain:
 ```json
-{ "success": true, "output": "...", "duration_ms": 1234 }
+{ "chain_id": "abc123xyz", "approved": true }
+```
+
+Response:
+```json
+{ "success": true, "approved": true, "output": "...", "chains": [], "pending_chains": [], "duration_ms": 890 }
 ```
 
 **Example curl:**
@@ -208,19 +240,114 @@ All endpoints require the `x-api-key` header when `server.apiKey` is set in your
 # Health check
 curl http://localhost:3333/health -H "x-api-key: your-secret"
 
-# Run inline agent
-curl -X POST http://localhost:3333/run \
+# Run agent from file (with chain support)
+curl -X POST http://localhost:3333/run-file \
   -H "x-api-key: your-secret" \
   -H "Content-Type: application/json" \
-  -d '{"yaml":"name: Hi\nsteps:\n  - name: Greet\n    content: Say hi!","input":"Run"}'
+  -d '{"file":"/path/to/agent.yaml"}'
 
-# Run agent from file
-curl -X POST http://localhost:3333/run-file \
+# Approve a pending manual chain
+curl -X POST http://localhost:3333/approve-chain \
+  -H "x-api-key: your-secret" \
+  -H "Content-Type: application/json" \
+  -d '{"chain_id":"abc123xyz","approved":true}'
+```
+
+---
+
+## Project System
+
+`oe-project.json` sits alongside `oe-config.json` and registers multiple agents by name — so any interface (Telegram, Slack, HTTP, MCP) can invoke them by name rather than file path.
+
+```json
+{
+  "name": "Sales Pipeline",
+  "version": "1.0.0",
+  "description": "Outbound sales automation",
+  "author": "Your Name",
+  "tags": ["sales", "outbound"],
+  "agents": [
+    { "name": "prospecting",  "file": "./prospecting.yaml",  "description": "Find and qualify leads" },
+    { "name": "outreach",     "file": "./outreach.yaml",     "description": "Send personalised emails" },
+    { "name": "chat",         "file": "./chat-bot.yaml",     "description": "Conversational assistant", "default": true }
+  ],
+  "links": [
+    { "name": "support", "project": "../support-project/oe-project.json" }
+  ]
+}
+```
+
+| Field | Description |
+|---|---|
+| `name`, `version`, `author`, `tags` | Project metadata |
+| `agents[].name` | Short name used to invoke the agent (`/run prospecting`) |
+| `agents[].file` | Path to the YAML agent file (relative to `oe-project.json`) |
+| `agents[].default` | `true` — runs this agent when user sends a plain message (no command) |
+| `links` | Cross-project references — run agents from linked projects |
+
+---
+
+## Messaging Platforms (Telegram, Slack, WhatsApp, Teams)
+
+OE Runtime's HTTP server can receive messages from any webhook-based messaging platform and run agents in response — no separate bot framework needed.
+
+**`oe-config.json` — enable webhook receiver:**
+
+```json
+{
+  "llm": { "provider": "openai", "apiKey": "sk-...", "model": "gpt-4o" },
+  "server": {
+    "enabled": true,
+    "port": 3333,
+    "publicUrl": "https://your-public-domain.com",
+    "webhook": {
+      "enabled": true,
+      "auto_reply": true
+    }
+  },
+  "connectors": [
+    {
+      "connection_name": "My Telegram Bot",
+      "connection_type": "telegram",
+      "baseUrl": "https://api.telegram.org/botYOUR_BOT_TOKEN"
+    }
+  ]
+}
+```
+
+OE Runtime automatically calls Telegram's `setWebhook` on startup. For Slack, paste the URL shown in the terminal into your Slack app's Event Subscriptions.
+
+**Universal command language** — same commands work from Telegram, Slack, HTTP, or MCP:
+
+| Command | Action |
+|---|---|
+| `/run <name>` | Run agent by name (from `oe-project.json`) |
+| `/run <path>` | Run agent by file path |
+| `/agents` | List all registered agents |
+| `/approve` | Approve a pending manual chain |
+| `/cancel` | Cancel a pending chain |
+| `/status` | Health check — LLM, connectors, uptime |
+| `/projects` | List linked projects |
+| `/help` | Show all commands |
+| Any message | Runs the `"default": true` agent |
+
+**POST /command** — same commands from HTTP clients:
+```bash
+curl -X POST http://localhost:3333/command \
   -H "x-api-key: your-secret" \
   -H "Content-Type: application/json" \
-  -d '{"file":"/path/to/agent.yaml","params":{"topic":"AI trends"},"input":"Run"}'
+  -d '{"text": "/run prospecting"}'
 ```
 
+**Supported platforms:**
+
+| Platform | Webhook endpoint | Auto-registers |
+|---|---|---|
+| Telegram | `POST /webhook/telegram` | ✅ Yes — calls `setWebhook` on startup |
+| Slack | `POST /webhook/slack` | No — paste URL in Slack Event Subscriptions |
+| WhatsApp (Meta) | `POST /webhook/whatsapp` | No — paste URL in Meta Developer dashboard |
+| GitHub | `POST /webhook/github` | No — paste URL in repo webhook settings |
+
 ---
 
 ## Binary vs Node.js Mode

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@openenthrium/oe-runtime",
-    "version": "1.6.8",
+    "version": "1.7.0",
     "description": "OE Runtime - run AI agents against enterprise data sources. One binary, one YAML agent, one config file.",
     "homepage": "https://www.openenthrium.com/runtime.html",
     "repository": {