@practicalworks/rc-bridge 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +98 -21
  2. package/package.json +26 -15
package/README.md CHANGED
@@ -1,9 +1,13 @@
1
1
  # @practicalworks/rc-bridge
2
2
 
3
- Puts Rocket.Chat in front of an OpenAI-compatible agent. A Rocket.Chat **Outgoing
4
- Webhook** POSTs each message to the bridge; the bridge sends the turn to the agent's
5
- `/v1/responses` endpoint and posts the answer back through Rocket.Chat's REST API as the
6
- bot user, via [`@practicalworks/rc-client`](../client).
3
+ **Put your AI agent in Rocket.Chat.** A small Node service that relays Rocket.Chat messages
4
+ to an agent and posts the answers back, with one conversation per thread, reactions as
5
+ receipts, images and files, and streaming. It runs from env with no code, and has a plugin API
6
+ for when you want more.
7
+
8
+ [![npm](https://img.shields.io/npm/v/@practicalworks/rc-bridge)](https://www.npmjs.com/package/@practicalworks/rc-bridge)
9
+ [![ci](https://github.com/PracticalWorks/rc-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/PracticalWorks/rc-bridge/actions/workflows/ci.yml)
10
+ [![MIT licence](https://img.shields.io/badge/licence-MIT-blue)](https://github.com/PracticalWorks/rc-bridge/blob/main/LICENSE)
7
11
 
8
12
  ```
9
13
  Rocket.Chat ──(Outgoing Webhook)──▶ rc-bridge ──▶ agent POST /v1/responses
@@ -11,7 +15,72 @@ Rocket.Chat ──(Outgoing Webhook)──▶ rc-bridge ──▶ agent POST /v
11
15
  └──────(REST, bot credentials)─────┴──────── answer ◀───────┘
12
16
  ```
13
17
 
14
- What the relay does on its own, with no plugins:
18
+ **Contents:** [Quick start](#quick-start) · [What it does](#what-it-does) ·
19
+ [Troubleshooting](#troubleshooting) · [Configuration reference](#configuration-reference) ·
20
+ [Plugins](#plugins) · [Develop](#develop)
21
+
22
+ ## Quick start
23
+
24
+ About five minutes if you administer a Rocket.Chat.
25
+
26
+ **You need:**
27
+
28
+ - Node 20 or later.
29
+ - A Rocket.Chat where you can create users and integrations.
30
+ - An agent server with an OpenAI-style **Responses API** (`POST /v1/responses`) that accepts a
31
+ *named* conversation: the bridge sends `conversation: "rc:<room>:<thread>"` and expects the
32
+ server to create or continue it. Agent gateways built for chat apps do this. OpenAI's own
33
+ hosted API does not, because it only accepts the `conv_…` ids it issued.
34
+ - An HTTPS address Rocket.Chat can reach the bridge on: a reverse proxy, or a tunnel while you
35
+ try it.
36
+
37
+ **1. Create the bot.** In Rocket.Chat, add a user for the bot (role `bot`), log in as it, and
38
+ create a personal access token under *My Account → Personal Access Tokens*. Note its user id,
39
+ its token and its username.
40
+
41
+ **2. Point a webhook at the bridge.** *Administration → Integrations → New → Outgoing*:
42
+
43
+ - Event trigger: `Message Sent`.
44
+ - Channel: the channels it should hear (for example `#ask-agent`), or `all_direct_messages`.
45
+ - URLs: `https://<your bridge address>/rocketchat/webhook`.
46
+ - Token: invent a long random string. The bridge checks it on every call.
47
+
48
+ **3. Configure.** Put this in a `.env` file, or in your process manager's env:
49
+
50
+ ```sh
51
+ # Your agent server
52
+ AGENT_API_URL=https://agent.example.com # without /v1
53
+ AGENT_API_KEY= # its bearer token
54
+ AGENT_MODEL=agent # the `model` sent with each turn
55
+
56
+ # Rocket.Chat
57
+ ROCKETCHAT_URL=https://chat.example.com
58
+ ROCKETCHAT_USER_ID= # the bot's user id (step 1)
59
+ ROCKETCHAT_AUTH_TOKEN= # the bot's personal access token (step 1)
60
+ ROCKETCHAT_BOT_USERNAME=agent # the bot's username (step 1)
61
+ ROCKETCHAT_WEBHOOK_TOKEN= # the token you invented (step 2)
62
+ ROCKETCHAT_ALLOWED_ROOM_IDS= # optional: comma-separated room ids; unset = any room the webhook fires from
63
+
64
+ PORT=8081
65
+ ```
66
+
67
+ **4. Run it.**
68
+
69
+ ```sh
70
+ npx @practicalworks/rc-bridge
71
+ # or install it: npm install -g @practicalworks/rc-bridge && rc-bridge
72
+ ```
73
+
74
+ The bridge does not read `.env` files itself; load the file with your process manager, or with
75
+ `node --env-file=.env $(which rc-bridge)` on a global install. It logs what it is listening on, and
76
+ `curl http://localhost:8081/health` answers `200`.
77
+
78
+ **5. Say hello.** In a channel the webhook hears, write `@agent hello`. You should see 👀 on your
79
+ message, then the answer in a thread. In a DM with the bot you don't need the @mention.
80
+
81
+ ## What it does
82
+
83
+ With no plugins:
15
84
 
16
85
  - **One conversation per thread.** Each turn names a `conversation` (`rc:<roomId>:<thread>`),
17
86
  which the agent's Responses API chains server-side. A DM's top-level messages share one
@@ -34,28 +103,36 @@ What the relay does on its own, with no plugins:
34
103
  - **Two HTTP routes.** `POST /rocketchat/webhook` (token-checked, acked fast, the turn runs
35
104
  detached) and `GET /health` (503 while draining, with recent turn timings).
36
105
 
37
- ## Run it
106
+ The bridge has two HTTP routes: `POST /rocketchat/webhook` and `GET /health`. It serves plain HTTP
107
+ on `PORT`, so put TLS in front of it.
38
108
 
39
- Node 20 or later.
109
+ ## Troubleshooting
40
110
 
41
- ```sh
42
- npx @practicalworks/rc-bridge # or: rc-bridge, once installed
43
- ```
111
+ **No 👀, no answer.** Rocket.Chat never reached the bridge, or the bridge dropped the message.
112
+ - *Administration → Integrations → your webhook → History* shows each call and the bridge's
113
+ response. No entry means the trigger did not match: check the event, the channel and that the
114
+ integration is enabled.
115
+ - A `401` (`bad token`) in that history means `ROCKETCHAT_WEBHOOK_TOKEN` does not match the integration's token.
116
+ - A call that never connected means Rocket.Chat cannot reach your URL: it has to be HTTPS and reachable
117
+ from the Rocket.Chat server, not just from your laptop.
118
+ - The message was not addressed to the bot. In a channel, @mention it (or reply in a thread it is
119
+ already in). `RESPOND_TO_ALL=1` answers everything, which is rarely what you want in a busy room.
120
+ - The room is not in `ROCKETCHAT_ALLOWED_ROOM_IDS`.
121
+
122
+ **👀, then ⚠️.** The agent call failed, and the bridge's log has the status and the first 500
123
+ characters of the server's reply. A `400` that mentions `conversation` means your server does not
124
+ accept named conversations (see *You need* above). A `401` means `AGENT_API_KEY` is wrong.
44
125
 
45
- It listens on `PORT` over plain HTTP; put TLS in front of it (a reverse proxy or a tunnel),
46
- since Rocket.Chat needs an HTTPS URL to reach it.
126
+ **👀, then ⏳.** The turn ran past `AGENT_TIMEOUT_MS` (6 minutes by default). The bridge stops
127
+ waiting but the agent keeps working in the same conversation, so ask for the result in the thread.
47
128
 
48
- ### Rocket.Chat setup
129
+ **The bot answers its own messages, or another bot's.** Set `ROCKETCHAT_BOT_USERNAME` to the bot's
130
+ real username, and list other bots in `ROCKETCHAT_IGNORE_USERNAMES`.
49
131
 
50
- 1. A bot user for the bridge, and a personal access token for it. Its user id and token are
51
- `ROCKETCHAT_USER_ID` and `ROCKETCHAT_AUTH_TOKEN`; its username is `ROCKETCHAT_BOT_USERNAME`.
52
- 2. **Administration → Integrations → New → Outgoing**: event `Message Sent`, the channels it
53
- should hear, URL `https://<where the bridge is reachable>/rocketchat/webhook`, and a token
54
- you invent, which is also `ROCKETCHAT_WEBHOOK_TOKEN`.
55
- 3. Set `ROCKETCHAT_ALLOWED_ROOM_IDS` to the rooms allowed to drive the agent. Unset, any room the
56
- webhook fires from can.
132
+ **Check it's alive:** `GET /health` returns recent turn timings. It returns `503` while the bridge
133
+ is shutting down.
57
134
 
58
- ### Environment
135
+ ## Configuration reference
59
136
 
60
137
  Names only; set the values in your own environment.
61
138
 
package/package.json CHANGED
@@ -1,8 +1,31 @@
1
1
  {
2
2
  "name": "@practicalworks/rc-bridge",
3
- "version": "0.1.1",
4
- "description": "Puts Rocket.Chat in front of an OpenAI-compatible agent: an outgoing-webhook relay with one conversation per thread, reactions as receipts, attachments, streaming, and a plugin seam.",
3
+ "version": "0.1.2",
4
+ "description": "Put your AI agent in Rocket.Chat: a relay to an OpenAI-style Responses API with one conversation per thread, reactions as receipts, images and files, streaming, and a plugin API.",
5
+ "keywords": [
6
+ "rocket.chat",
7
+ "rocketchat",
8
+ "bridge",
9
+ "agent",
10
+ "openai",
11
+ "rocket-chat",
12
+ "ai-agent",
13
+ "llm",
14
+ "chatbot",
15
+ "responses-api",
16
+ "webhook"
17
+ ],
18
+ "homepage": "https://github.com/PracticalWorks/rc-bridge/tree/main/packages/bridge#readme",
19
+ "bugs": {
20
+ "url": "https://github.com/PracticalWorks/rc-bridge/issues"
21
+ },
5
22
  "license": "MIT",
23
+ "author": "Practical Works <hello@practical.works> (https://practical.works)",
24
+ "repository": {
25
+ "type": "git",
26
+ "url": "git+https://github.com/PracticalWorks/rc-bridge.git",
27
+ "directory": "packages/bridge"
28
+ },
6
29
  "type": "module",
7
30
  "main": "dist/index.js",
8
31
  "types": "dist/index.d.ts",
@@ -18,19 +41,12 @@
18
41
  "files": [
19
42
  "dist"
20
43
  ],
21
- "keywords": [
22
- "rocket.chat",
23
- "rocketchat",
24
- "bridge",
25
- "agent",
26
- "openai"
27
- ],
28
44
  "engines": {
29
45
  "node": ">=20"
30
46
  },
31
47
  "dependencies": {
32
48
  "unpdf": "^1.8.0",
33
- "@practicalworks/rc-client": "0.1.1"
49
+ "@practicalworks/rc-client": "0.1.2"
34
50
  },
35
51
  "devDependencies": {
36
52
  "@types/node": "^22.0.0",
@@ -38,11 +54,6 @@
38
54
  "typescript": "^5.5.0",
39
55
  "vitest": "^3.0.0"
40
56
  },
41
- "repository": {
42
- "type": "git",
43
- "url": "git+https://github.com/PracticalWorks/rc-bridge.git",
44
- "directory": "packages/bridge"
45
- },
46
57
  "publishConfig": {
47
58
  "registry": "https://registry.npmjs.org/",
48
59
  "access": "public",