@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.
- package/README.md +98 -21
- package/package.json +26 -15
package/README.md
CHANGED
|
@@ -1,9 +1,13 @@
|
|
|
1
1
|
# @practicalworks/rc-bridge
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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
|
+
[](https://www.npmjs.com/package/@practicalworks/rc-bridge)
|
|
9
|
+
[](https://github.com/PracticalWorks/rc-bridge/actions/workflows/ci.yml)
|
|
10
|
+
[](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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
109
|
+
## Troubleshooting
|
|
40
110
|
|
|
41
|
-
|
|
42
|
-
|
|
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
|
-
|
|
46
|
-
|
|
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
|
-
|
|
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
|
-
|
|
51
|
-
|
|
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
|
-
|
|
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.
|
|
4
|
-
"description": "
|
|
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.
|
|
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",
|