@practicalworks/rc-bridge 0.0.0-stage → 0.1.0
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/LICENSE +21 -0
- package/README.md +157 -2
- package/dist/agent.d.ts +52 -0
- package/dist/agent.js +255 -0
- package/dist/attachment-deps.d.ts +15 -0
- package/dist/attachment-deps.js +13 -0
- package/dist/attachments.d.ts +255 -0
- package/dist/attachments.js +428 -0
- package/dist/config.d.ts +50 -0
- package/dist/config.js +92 -0
- package/dist/conversation-epochs.d.ts +41 -0
- package/dist/conversation-epochs.js +121 -0
- package/dist/denylist.d.ts +16 -0
- package/dist/denylist.js +86 -0
- package/dist/followups.d.ts +38 -0
- package/dist/followups.js +65 -0
- package/dist/hooks.d.ts +26 -0
- package/dist/hooks.js +88 -0
- package/dist/http.d.ts +33 -0
- package/dist/http.js +66 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +11 -0
- package/dist/lookback.d.ts +33 -0
- package/dist/lookback.js +85 -0
- package/dist/main.d.ts +2 -0
- package/dist/main.js +104 -0
- package/dist/plugin.d.ts +113 -0
- package/dist/plugin.js +1 -0
- package/dist/reactions.d.ts +42 -0
- package/dist/reactions.js +127 -0
- package/dist/response.d.ts +52 -0
- package/dist/response.js +160 -0
- package/dist/run-events.d.ts +19 -0
- package/dist/run-events.js +65 -0
- package/dist/state.d.ts +57 -0
- package/dist/state.js +141 -0
- package/dist/stream.d.ts +67 -0
- package/dist/stream.js +126 -0
- package/dist/threading.d.ts +335 -0
- package/dist/threading.js +451 -0
- package/dist/turn-timings.d.ts +19 -0
- package/dist/turn-timings.js +14 -0
- package/dist/turn.d.ts +37 -0
- package/dist/turn.js +450 -0
- package/package.json +53 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Practical Works
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,158 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @practicalworks/rc-bridge
|
|
2
2
|
|
|
3
|
-
|
|
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).
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
Rocket.Chat ──(Outgoing Webhook)──▶ rc-bridge ──▶ agent POST /v1/responses
|
|
10
|
+
▲ │ │
|
|
11
|
+
└──────(REST, bot credentials)─────┴──────── answer ◀───────┘
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
What the relay does on its own, with no plugins:
|
|
15
|
+
|
|
16
|
+
- **One conversation per thread.** Each turn names a `conversation` (`rc:<roomId>:<thread>`),
|
|
17
|
+
which the agent's Responses API chains server-side. A DM's top-level messages share one
|
|
18
|
+
conversation per room, bounded by a daily epoch; `/new` or `/reset` starts it over.
|
|
19
|
+
- **One request, one thread.** The answer goes into the thread the person is in, or a new
|
|
20
|
+
thread rooted on their message.
|
|
21
|
+
- **An addressing gate that fails closed.** It answers @mentions, DMs, the person who owns a
|
|
22
|
+
thread, and replies in a thread whose root tagged the bot. Other bots are dropped by
|
|
23
|
+
`payload.bot`, a denylist and a boot-time `users.list` refresh.
|
|
24
|
+
- **Reactions as receipts.** 👀 on pickup, then ✅, ⚠️ or ⏳. The answer is posted once, finished,
|
|
25
|
+
because Rocket.Chat notifies on creation and not on edits. An agent can answer with an emoji
|
|
26
|
+
by writing `[react: 👍]`.
|
|
27
|
+
- **Attachments.** Images go to the agent inline as `input_image` parts; PDFs and text uploads
|
|
28
|
+
are read to text and put in the prompt. A long paste that Rocket.Chat turned into a file is
|
|
29
|
+
read as the message.
|
|
30
|
+
- **Streaming.** When the endpoint streams, the bridge reads the run live, never aborts it, and,
|
|
31
|
+
if the endpoint also serves `GET /v1/runs/{id}`, notices a run parked on an approval.
|
|
32
|
+
- **Loop and flood bounds.** A per-thread post cap, a busy guard that holds the next message
|
|
33
|
+
instead of dropping it, and a once-per-outage error reply.
|
|
34
|
+
- **Two HTTP routes.** `POST /rocketchat/webhook` (token-checked, acked fast, the turn runs
|
|
35
|
+
detached) and `GET /health` (503 while draining, with recent turn timings).
|
|
36
|
+
|
|
37
|
+
## Run it
|
|
38
|
+
|
|
39
|
+
Node 20 or later.
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
npx @practicalworks/rc-bridge # or: rc-bridge, once installed
|
|
43
|
+
```
|
|
44
|
+
|
|
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.
|
|
47
|
+
|
|
48
|
+
### Rocket.Chat setup
|
|
49
|
+
|
|
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.
|
|
57
|
+
|
|
58
|
+
### Environment
|
|
59
|
+
|
|
60
|
+
Names only; set the values in your own environment.
|
|
61
|
+
|
|
62
|
+
Required:
|
|
63
|
+
|
|
64
|
+
| Name | What |
|
|
65
|
+
|---|---|
|
|
66
|
+
| `AGENT_API_KEY` | Bearer token for the agent endpoint |
|
|
67
|
+
| `ROCKETCHAT_URL` | Your Rocket.Chat base URL |
|
|
68
|
+
| `ROCKETCHAT_USER_ID` | The bot user's id |
|
|
69
|
+
| `ROCKETCHAT_AUTH_TOKEN` | The bot user's personal access token |
|
|
70
|
+
| `ROCKETCHAT_WEBHOOK_TOKEN` | The Outgoing Webhook's token |
|
|
71
|
+
|
|
72
|
+
Optional (defaults in `src/config.ts`, `src/state.ts` and `src/denylist.ts`):
|
|
73
|
+
|
|
74
|
+
| Name | What |
|
|
75
|
+
|---|---|
|
|
76
|
+
| `AGENT_API_URL` | The OpenAI-compatible endpoint, without `/v1` (default `http://127.0.0.1:8642`) |
|
|
77
|
+
| `AGENT_MODEL` | The `model` sent with each turn (default `agent`) |
|
|
78
|
+
| `AGENT_TIMEOUT_MS` | How long a turn may take before the bridge stops waiting (default 6 minutes) |
|
|
79
|
+
| `AGENT_PARK_CHECK_MS` | Stream silence before asking whether the run parked on an approval |
|
|
80
|
+
| `RC_STREAMING` | `0` turns streaming off |
|
|
81
|
+
| `ROCKETCHAT_BOT_USERNAME` | The bot's username, for mentions and the self-loop guard (default `bot`) |
|
|
82
|
+
| `ROCKETCHAT_TIMEOUT_MS` | Deadline per Rocket.Chat request |
|
|
83
|
+
| `RC_THREAD_SHOW` | "Also send to channel" on threaded replies; on by default, `0` turns it off |
|
|
84
|
+
| `RC_MAX_MESSAGE_CHARS` | Longer replies are split |
|
|
85
|
+
| `RC_MAX_IMAGE_BYTES`, `RC_MAX_IMAGES` | Image limits per turn |
|
|
86
|
+
| `RC_MAX_DOCUMENT_BYTES`, `RC_MAX_DOCUMENT_CHARS` | Document limits; the characters are the real bound |
|
|
87
|
+
| `RC_UPLOAD_LOOKBACK_MS` | How far back an addressed message looks for the sender's untagged images; `0` is off |
|
|
88
|
+
| `RC_LOOP_WINDOW_MS`, `RC_MAX_POSTS_PER_THREAD` | The post cap |
|
|
89
|
+
| `RC_BUSY_REPLY_COOLDOWN_MS` | How often "still on the previous message" may be said per conversation |
|
|
90
|
+
| `RC_NUDGE_WHEN_IGNORED` | `0` stops the "@mention me" nudge in threads the bot is in |
|
|
91
|
+
| `RESPOND_TO_ALL` | `1` answers every message that reaches the bridge, bypassing the addressing gate |
|
|
92
|
+
| `ROCKETCHAT_ALLOWED_ROOM_IDS` | Comma-separated room ids allowed to drive the agent |
|
|
93
|
+
| `ROCKETCHAT_IGNORE_USER_IDS`, `ROCKETCHAT_IGNORE_USERNAMES` | Static bot denylists, comma-separated |
|
|
94
|
+
| `ROCKETCHAT_BOT_DENYLIST_FILE` | A JSON denylist (`{ "ids": [], "usernames": [] }`) |
|
|
95
|
+
| `RC_BOT_REFRESH` | `0` skips the boot-time `users.list` refresh |
|
|
96
|
+
| `RC_PAUSE_STATE_FILE`, `CONVERSATION_EPOCH_STATE_FILE`, `ENGAGEMENT_STATE_FILE` | State files, under `~/rocketchat-bridge/` by default |
|
|
97
|
+
| `PORT` | Listen port (default `8081`) |
|
|
98
|
+
| `BRIDGE_DRAIN_DEADLINE_MS` | How long shutdown waits for running turns |
|
|
99
|
+
|
|
100
|
+
## Plugins
|
|
101
|
+
|
|
102
|
+
Everything a deployment adds (other voices, routing, approvals, control commands, traces)
|
|
103
|
+
arrives through a `BridgePlugin`. Every hook is optional:
|
|
104
|
+
|
|
105
|
+
| Hook | When it runs | How several plugins compose |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| `identityForRoom(roomId)` | Every post, reaction and attachment read: auth headers to speak AS in that room | First non-`undefined` answer wins; none means the bot's own |
|
|
108
|
+
| `isDirectMessageFallback(roomId)` | `rooms.info` refused the bot: is this nonetheless a DM? | First non-`undefined` answer wins; none means no |
|
|
109
|
+
| `targetForRoom(roomId)` | Which agent endpoint and profile a turn goes to | First non-`undefined` answer wins; none means the default target |
|
|
110
|
+
| `isOwnVoice(payload)` | Is this message ours, in a voice the core does not know? | Any `true` drops the message |
|
|
111
|
+
| `framing(turn)` | A preamble placed after the context header | Every answer, in plugin order |
|
|
112
|
+
| `outbound(text)` | Rewrites a reply before it is split: strip markers, pick a voice (`alias`, `avatar`) | Chained in plugin order; a later voice replaces an earlier one |
|
|
113
|
+
| `onAnswer(turn, text)` | Rewrites the answer before its single post | Chained in plugin order |
|
|
114
|
+
| `interceptReply(reply)` | A threaded reply, before the addressing gate; `true` consumes it | First `true` wins |
|
|
115
|
+
| `onRunParked(turn, run)` | The streamed run parked on an approval | Fan-out, awaited in order |
|
|
116
|
+
| `onTurnSettled(record)` | Every turn's outcome, ignored ones included | Fan-out, never awaited; a throw is logged |
|
|
117
|
+
| `controlVerbs` | `match(text)` claims a whole message as a command; `nearMiss(text)` answers usage | First match wins |
|
|
118
|
+
| `health()` | Fields merged into `/health` | Merged, later plugins win on a key clash |
|
|
119
|
+
|
|
120
|
+
Order matters only where hooks chain or the first answer wins. `composeHooks(plugins, log)`
|
|
121
|
+
applies these rules; `src/hooks.ts` is the whole of it.
|
|
122
|
+
|
|
123
|
+
A deployment with plugins composes the same pieces `src/main.ts` does, passing its list:
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
import { RocketChatClient } from "@practicalworks/rc-client";
|
|
127
|
+
import {
|
|
128
|
+
composeHooks, createAgentClient, createAttachmentDeps, createBridgeState, createHttpHandler,
|
|
129
|
+
createLog, createTurnHandler, createTurnTimings, loadCoreConfig, stateFilesFromEnv,
|
|
130
|
+
type BridgePlugin, type WebhookPayload,
|
|
131
|
+
} from "@practicalworks/rc-bridge";
|
|
132
|
+
|
|
133
|
+
const log = createLog();
|
|
134
|
+
const config = loadCoreConfig(log);
|
|
135
|
+
const plugins: BridgePlugin[] = [myPlugin];
|
|
136
|
+
const hooks = composeHooks(plugins, log);
|
|
137
|
+
const rc = new RocketChatClient({
|
|
138
|
+
baseUrl: config.rc.url, userId: config.rc.userId, authToken: config.rc.authToken,
|
|
139
|
+
timeoutMs: config.rc.timeoutMs, maxMessageChars: config.rc.maxMessageChars,
|
|
140
|
+
threadShow: config.rc.threadShow, // the client defaults this off; pass it
|
|
141
|
+
postCap: { rate: new Map(), maxPosts: config.loop.maxPostsPerThread, windowMs: config.loop.windowMs },
|
|
142
|
+
log,
|
|
143
|
+
identityForRoom: (roomId) => hooks.identityForRoom(roomId),
|
|
144
|
+
isDirectMessageFallback: (roomId) => hooks.isDirectMessageFallback(roomId),
|
|
145
|
+
outbound: (text) => hooks.outbound(text),
|
|
146
|
+
});
|
|
147
|
+
// …then createAttachmentDeps, createAgentClient, createBridgeState, createTurnHandler and
|
|
148
|
+
// createHttpHandler, exactly as in src/main.ts.
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Develop
|
|
152
|
+
|
|
153
|
+
From the repository root: `pnpm install`, then `pnpm build && pnpm typecheck && pnpm test`.
|
|
154
|
+
`src/boundary.test.ts` fails on any import outside this package, node built-ins and its
|
|
155
|
+
declared dependencies; `src/core.e2e.test.ts` runs `src/main.ts` against a fake Rocket.Chat and
|
|
156
|
+
a fake agent.
|
|
157
|
+
|
|
158
|
+
MIT licensed.
|
package/dist/agent.d.ts
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { type InlineImage } from "./attachments.js";
|
|
2
|
+
import { type ResponseSummary } from "./response.js";
|
|
3
|
+
import type { Log } from "./config.js";
|
|
4
|
+
/** Where a turn goes: one gateway profile. */
|
|
5
|
+
export interface AgentTarget {
|
|
6
|
+
url: string;
|
|
7
|
+
apiKey: string;
|
|
8
|
+
model: string;
|
|
9
|
+
}
|
|
10
|
+
/** ms from the request start; null when never seen (a non-streaming reply). */
|
|
11
|
+
export interface AgentTimings {
|
|
12
|
+
firstEventMs: number | null;
|
|
13
|
+
firstTextMs: number | null;
|
|
14
|
+
totalMs: number;
|
|
15
|
+
}
|
|
16
|
+
export type AgentTurn = ResponseSummary & {
|
|
17
|
+
timings: AgentTimings;
|
|
18
|
+
};
|
|
19
|
+
/** What a park check learned about the run behind a silent stream. */
|
|
20
|
+
export type ParkVerdict = "parked" | "running" | "unknown";
|
|
21
|
+
/** One read of a run: the subset of a run's state the park check uses. `parked` is present only when true. */
|
|
22
|
+
export type RunRead = {
|
|
23
|
+
ok: true;
|
|
24
|
+
done: boolean;
|
|
25
|
+
status: string;
|
|
26
|
+
runId: string;
|
|
27
|
+
parked?: true;
|
|
28
|
+
createdAt?: string;
|
|
29
|
+
lastEvent?: string;
|
|
30
|
+
} | {
|
|
31
|
+
ok: false;
|
|
32
|
+
error: string;
|
|
33
|
+
expired?: boolean;
|
|
34
|
+
};
|
|
35
|
+
export interface AgentClientOptions {
|
|
36
|
+
timeoutMs: number;
|
|
37
|
+
parkCheckMs: number;
|
|
38
|
+
/** RC_STREAMING; false forces the plain path outright. */
|
|
39
|
+
streaming: boolean;
|
|
40
|
+
log: Log;
|
|
41
|
+
fetchImpl?: typeof fetch;
|
|
42
|
+
}
|
|
43
|
+
/** Did the turn's own request pass its deadline? Not a failure: the gateway keeps
|
|
44
|
+
* working after we hang up, and the named conversation keeps its state. */
|
|
45
|
+
export declare function isTurnTimeout(err: unknown): boolean;
|
|
46
|
+
export declare function createAgentClient(opts: AgentClientOptions): {
|
|
47
|
+
ask: (target: AgentTarget, conversation: string, prompt: string, images?: InlineImage[]) => Promise<AgentTurn>;
|
|
48
|
+
askStreaming: (target: AgentTarget, conversation: string, prompt: string, images: InlineImage[], onCreated?: (responseId: string) => void, onParkCheck?: (responseId: string) => Promise<ParkVerdict>) => Promise<AgentTurn>;
|
|
49
|
+
readRun: (target: AgentTarget, runId: string) => Promise<RunRead>;
|
|
50
|
+
/** RC_STREAMING is on and the gateway has not answered in plain JSON. */
|
|
51
|
+
shouldTryStreaming: () => boolean;
|
|
52
|
+
};
|
package/dist/agent.js
ADDED
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
// The agent client, for an OpenAI-compatible Responses endpoint: one request
|
|
2
|
+
// builder for both the plain and the streamed turn, the silence watchdog, and a
|
|
3
|
+
// reader for GET /v1/runs/{id}. The "never abort mid-stream" rule lives here whole.
|
|
4
|
+
import { buildAgentInput } from "./attachments.js";
|
|
5
|
+
import { summarizeResponse } from "./response.js";
|
|
6
|
+
import { createSseParser, formatCensus, readSseEvent } from "./stream.js";
|
|
7
|
+
import { DeadlineError, fetchWithTimeout } from "@practicalworks/rc-client";
|
|
8
|
+
/** The deadline labels of the turn request itself, plain and streamed. */
|
|
9
|
+
const TURN_LABEL = "Agent /v1/responses";
|
|
10
|
+
const STREAM_TURN_LABEL = "Agent /v1/responses (stream)";
|
|
11
|
+
/** Did the turn's own request pass its deadline? Not a failure: the gateway keeps
|
|
12
|
+
* working after we hang up, and the named conversation keeps its state. */
|
|
13
|
+
export function isTurnTimeout(err) {
|
|
14
|
+
return err instanceof DeadlineError && (err.label === TURN_LABEL || err.label === STREAM_TURN_LABEL);
|
|
15
|
+
}
|
|
16
|
+
/** Run states the gateway will not move off. */
|
|
17
|
+
const TERMINAL_RUN_STATES = new Set(["completed", "failed", "cancelled", "canceled"]);
|
|
18
|
+
/** Not terminal, but will never advance: a person must act. Only the
|
|
19
|
+
* state actually observed on the wire is listed. */
|
|
20
|
+
const PARKED_RUN_STATES = new Set(["waiting_for_approval"]);
|
|
21
|
+
const RUN_READ_TIMEOUT_MS = 30_000;
|
|
22
|
+
const isTerminalRunStatus = (s) => TERMINAL_RUN_STATES.has(s.trim().toLowerCase());
|
|
23
|
+
const isParkedRunStatus = (s) => PARKED_RUN_STATES.has(s.trim().toLowerCase());
|
|
24
|
+
/** Sentinel for "nothing arrived within the window" — never a chunk. */
|
|
25
|
+
const IDLE = Symbol("idle");
|
|
26
|
+
/** Await `pending` for at most `ms`, then hand back IDLE. The promise itself is
|
|
27
|
+
* untouched — the caller keeps awaiting it — so this can never cancel a read. */
|
|
28
|
+
function raceIdle(pending, ms) {
|
|
29
|
+
let timer;
|
|
30
|
+
const idle = new Promise((resolve) => {
|
|
31
|
+
timer = setTimeout(() => resolve(IDLE), ms);
|
|
32
|
+
});
|
|
33
|
+
return Promise.race([pending, idle]).finally(() => clearTimeout(timer));
|
|
34
|
+
}
|
|
35
|
+
export function createAgentClient(opts) {
|
|
36
|
+
const { log, timeoutMs, parkCheckMs } = opts;
|
|
37
|
+
const fetchImpl = opts.fetchImpl ?? fetch;
|
|
38
|
+
/** Whether the gateway streams; undefined until it has answered once. Detected
|
|
39
|
+
* from the response's content-type, never from a guessed capabilities shape. */
|
|
40
|
+
let streamingSupported;
|
|
41
|
+
/** The ONE Responses request. With no images `input` is a bare string; with
|
|
42
|
+
* images it is the content-part form the gateway accepts for vision. */
|
|
43
|
+
async function postResponses(target, conversation, prompt, images, stream) {
|
|
44
|
+
const res = await fetchWithTimeout(`${target.url}/v1/responses`, {
|
|
45
|
+
method: "POST",
|
|
46
|
+
headers: {
|
|
47
|
+
"content-type": "application/json",
|
|
48
|
+
...(stream ? { accept: "text/event-stream" } : {}),
|
|
49
|
+
authorization: `Bearer ${target.apiKey}`,
|
|
50
|
+
},
|
|
51
|
+
body: JSON.stringify({
|
|
52
|
+
model: target.model,
|
|
53
|
+
input: buildAgentInput(prompt, images),
|
|
54
|
+
store: true,
|
|
55
|
+
conversation,
|
|
56
|
+
...(stream ? { stream: true } : {}),
|
|
57
|
+
}),
|
|
58
|
+
}, stream ? STREAM_TURN_LABEL : TURN_LABEL, timeoutMs, fetchImpl);
|
|
59
|
+
if (!res.ok) {
|
|
60
|
+
const detail = (await res.text()).slice(0, 500);
|
|
61
|
+
// A 400 on an image turn means this gateway no longer takes inline images.
|
|
62
|
+
// Fail loudly: retrying as text would read as if the agent saw the screenshot.
|
|
63
|
+
if (images.length && res.status === 400) {
|
|
64
|
+
throw new Error(`The agent rejected the image (400) — this gateway build may not support inline image input on /v1/responses. Detail: ${detail}`);
|
|
65
|
+
}
|
|
66
|
+
throw new Error(`Agent /v1/responses returned ${res.status}: ${detail}`);
|
|
67
|
+
}
|
|
68
|
+
return res;
|
|
69
|
+
}
|
|
70
|
+
const plainTimings = (startedAt) => ({
|
|
71
|
+
firstEventMs: null,
|
|
72
|
+
firstTextMs: null,
|
|
73
|
+
totalMs: Date.now() - startedAt,
|
|
74
|
+
});
|
|
75
|
+
/** One turn inside a named conversation, which the gateway auto-chains
|
|
76
|
+
* server-side: no response ids to track, and a gateway restart keeps it. */
|
|
77
|
+
async function ask(target, conversation, prompt, images = []) {
|
|
78
|
+
const startedAt = Date.now();
|
|
79
|
+
const res = await postResponses(target, conversation, prompt, images, false);
|
|
80
|
+
return { ...summarizeResponse(await res.json()), timings: plainTimings(startedAt) };
|
|
81
|
+
}
|
|
82
|
+
/** The same turn, streamed. The stream carries the run's handle for the
|
|
83
|
+
* park check and the event census; its text is never shown live, since
|
|
84
|
+
* RC notifies on creation and not on edits.
|
|
85
|
+
*
|
|
86
|
+
* - **Never abort mid-stream.** Disconnecting CANCELS the run on the gateway.
|
|
87
|
+
* The timeout bounds time to FIRST BYTE only.
|
|
88
|
+
* - **Never trust the stream for the trace.** `summarizeResponse` reads the tool
|
|
89
|
+
* calls from the completion event; with no completion, fall back to the
|
|
90
|
+
* accumulated text rather than losing the turn.
|
|
91
|
+
*/
|
|
92
|
+
async function askStreaming(target, conversation, prompt, images, onCreated,
|
|
93
|
+
// Called with the run's handle once the stream has been silent for
|
|
94
|
+
// parkCheckMs. `running` keeps watching; anything else stops the checks.
|
|
95
|
+
onParkCheck) {
|
|
96
|
+
const requestStartedAt = Date.now();
|
|
97
|
+
const res = await postResponses(target, conversation, prompt, images, true);
|
|
98
|
+
// Did we actually get a stream? The response itself is the feature detection.
|
|
99
|
+
const contentType = res.headers.get("content-type") ?? "";
|
|
100
|
+
if (!contentType.includes("text/event-stream")) {
|
|
101
|
+
if (streamingSupported !== false) {
|
|
102
|
+
log(`gateway answered ${contentType || "(no content-type)"} rather than SSE — using non-streaming replies`);
|
|
103
|
+
}
|
|
104
|
+
streamingSupported = false;
|
|
105
|
+
// Not an error: this IS the ordinary reply, parsed exactly as before.
|
|
106
|
+
return { ...summarizeResponse(await res.json()), timings: plainTimings(requestStartedAt) };
|
|
107
|
+
}
|
|
108
|
+
if (streamingSupported === undefined)
|
|
109
|
+
log("streaming enabled — reading the run live (text is posted once, finished)");
|
|
110
|
+
streamingSupported = true;
|
|
111
|
+
if (!res.body)
|
|
112
|
+
throw new Error("The agent returned no stream body");
|
|
113
|
+
const parser = createSseParser();
|
|
114
|
+
const decoder = new TextDecoder();
|
|
115
|
+
let accumulated = "";
|
|
116
|
+
let completed;
|
|
117
|
+
let streamError;
|
|
118
|
+
// The run's handle, from `response.created` — the only thing naming the run.
|
|
119
|
+
let responseId;
|
|
120
|
+
const streamStartedAt = Date.now();
|
|
121
|
+
let firstDeltaAt;
|
|
122
|
+
let deltaCount = 0;
|
|
123
|
+
// Every event type the gateway sent, counted, including ones we ignore.
|
|
124
|
+
const census = new Map();
|
|
125
|
+
// ANYTHING arriving vs TEXT arriving: far apart means only the text is late.
|
|
126
|
+
let firstEventAt;
|
|
127
|
+
const handle = (events) => {
|
|
128
|
+
for (const evt of events) {
|
|
129
|
+
const { type, signal } = readSseEvent(evt);
|
|
130
|
+
census.set(type, (census.get(type) ?? 0) + 1);
|
|
131
|
+
firstEventAt ??= Date.now();
|
|
132
|
+
if (signal.kind === "created") {
|
|
133
|
+
responseId ??= signal.id;
|
|
134
|
+
onCreated?.(responseId);
|
|
135
|
+
}
|
|
136
|
+
else if (signal.kind === "delta") {
|
|
137
|
+
firstDeltaAt ??= Date.now();
|
|
138
|
+
deltaCount++;
|
|
139
|
+
accumulated += signal.text;
|
|
140
|
+
}
|
|
141
|
+
else if (signal.kind === "completed") {
|
|
142
|
+
completed = signal.response;
|
|
143
|
+
}
|
|
144
|
+
else if (signal.kind === "error") {
|
|
145
|
+
streamError = signal.message;
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
};
|
|
149
|
+
// No timeout around the read loop — see above. What there IS: a
|
|
150
|
+
// silence watchdog that never touches the socket. After parkCheckMs of
|
|
151
|
+
// nothing, ask the gateway (separate GET) whether the run parked; the pending
|
|
152
|
+
// read is kept and awaited again, so the stream is consumed to its end.
|
|
153
|
+
const chunks = res.body[Symbol.asyncIterator]();
|
|
154
|
+
let pending;
|
|
155
|
+
let watching = Boolean(onParkCheck);
|
|
156
|
+
for (;;) {
|
|
157
|
+
pending ??= chunks.next();
|
|
158
|
+
const next = watching ? await raceIdle(pending, parkCheckMs) : await pending;
|
|
159
|
+
if (next === IDLE) {
|
|
160
|
+
if (!responseId) {
|
|
161
|
+
// `response.created` is the first event; none by now means nothing to ask about.
|
|
162
|
+
log(`park check: stream silent ${parkCheckMs}ms and no response.created id — cannot check this run`);
|
|
163
|
+
watching = false;
|
|
164
|
+
continue;
|
|
165
|
+
}
|
|
166
|
+
const verdict = await onParkCheck(responseId);
|
|
167
|
+
log(`park check: /v1/runs/${responseId} → ${verdict}`);
|
|
168
|
+
if (verdict !== "running")
|
|
169
|
+
watching = false;
|
|
170
|
+
continue;
|
|
171
|
+
}
|
|
172
|
+
pending = undefined;
|
|
173
|
+
if (next.done)
|
|
174
|
+
break;
|
|
175
|
+
handle(parser.push(decoder.decode(next.value, { stream: true })));
|
|
176
|
+
}
|
|
177
|
+
handle(parser.flush());
|
|
178
|
+
// Say what was measured, not what it means: `first event` far below `first
|
|
179
|
+
// text` means the gateway talks the whole time and only the TEXT is late.
|
|
180
|
+
const at = (t) => (t ? `${t - streamStartedAt}ms` : "never");
|
|
181
|
+
log(`stream: ${formatCensus(census)} | ${deltaCount} text delta(s), ` +
|
|
182
|
+
`first event at ${at(firstEventAt)}, first text at ${at(firstDeltaAt)}, ` +
|
|
183
|
+
`done at ${Date.now() - streamStartedAt}ms`);
|
|
184
|
+
const sinceRequest = (t) => (t === undefined ? null : t - requestStartedAt);
|
|
185
|
+
const timings = {
|
|
186
|
+
firstEventMs: sinceRequest(firstEventAt),
|
|
187
|
+
firstTextMs: sinceRequest(firstDeltaAt),
|
|
188
|
+
totalMs: Date.now() - requestStartedAt,
|
|
189
|
+
};
|
|
190
|
+
if (streamError)
|
|
191
|
+
throw new Error(`Agent stream failed: ${streamError}`);
|
|
192
|
+
if (completed) {
|
|
193
|
+
const summary = summarizeResponse(completed);
|
|
194
|
+
// Prefer the completion's own text; fall back to the accumulated deltas.
|
|
195
|
+
return summary.text ? { ...summary, timings } : { ...summary, text: accumulated, timings };
|
|
196
|
+
}
|
|
197
|
+
return { text: accumulated, tools: [], unknownTypes: [], timings };
|
|
198
|
+
}
|
|
199
|
+
/** One GET of a run. A PLAIN GET — nothing held open, the stream never touched. */
|
|
200
|
+
async function getRun(target, runId) {
|
|
201
|
+
const base = target.url.replace(/\/+$/, "");
|
|
202
|
+
let res;
|
|
203
|
+
try {
|
|
204
|
+
res = await fetchWithTimeout(`${base}/v1/runs/${encodeURIComponent(runId)}`,
|
|
205
|
+
// Never follow a redirect: a followed Access 302 is a 200 of HTML.
|
|
206
|
+
{ method: "GET", redirect: "manual", headers: { "content-type": "application/json", authorization: `Bearer ${target.apiKey}` } }, "Agent /v1/runs", RUN_READ_TIMEOUT_MS, fetchImpl);
|
|
207
|
+
}
|
|
208
|
+
catch (err) {
|
|
209
|
+
return { ok: false, error: `Could not reach the agent at ${base}: ${err?.message ?? err}` };
|
|
210
|
+
}
|
|
211
|
+
const text = await res.text();
|
|
212
|
+
if (!res.ok || (res.status >= 300 && res.status < 400)) {
|
|
213
|
+
return { ok: false, error: `Agent /v1/runs returned ${res.status}: ${text.slice(0, 300)}`, status: res.status };
|
|
214
|
+
}
|
|
215
|
+
try {
|
|
216
|
+
return { ok: true, body: JSON.parse(text) };
|
|
217
|
+
}
|
|
218
|
+
catch {
|
|
219
|
+
return { ok: false, error: `The agent returned non-JSON: ${text.slice(0, 200)}` };
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
/** Read a run's state for the park check. A parked status is read twice: the
|
|
223
|
+
* first GET can briefly show the pre-approval snapshot. */
|
|
224
|
+
async function readRun(target, runId) {
|
|
225
|
+
let res = await getRun(target, runId);
|
|
226
|
+
if (!res.ok) {
|
|
227
|
+
return res.status === 404
|
|
228
|
+
? { ok: false, error: `Agent run \`${runId}\` expired before it was resolved.`, expired: true }
|
|
229
|
+
: { ok: false, error: res.error };
|
|
230
|
+
}
|
|
231
|
+
if (isParkedRunStatus(String(res.body?.status ?? "unknown"))) {
|
|
232
|
+
const confirmed = await getRun(target, runId);
|
|
233
|
+
if (confirmed.ok)
|
|
234
|
+
res = confirmed;
|
|
235
|
+
}
|
|
236
|
+
const body = res.body;
|
|
237
|
+
const status = String(body?.status ?? "unknown");
|
|
238
|
+
const metadata = {
|
|
239
|
+
...(typeof body?.created_at === "string" ? { createdAt: body.created_at } : {}),
|
|
240
|
+
...(typeof body?.last_event === "string" ? { lastEvent: body.last_event } : {}),
|
|
241
|
+
};
|
|
242
|
+
if (isTerminalRunStatus(status))
|
|
243
|
+
return { ok: true, done: true, status, runId, ...metadata };
|
|
244
|
+
return isParkedRunStatus(status)
|
|
245
|
+
? { ok: true, done: false, status, runId, parked: true, ...metadata }
|
|
246
|
+
: { ok: true, done: false, status, runId, ...metadata };
|
|
247
|
+
}
|
|
248
|
+
return {
|
|
249
|
+
ask,
|
|
250
|
+
askStreaming,
|
|
251
|
+
readRun,
|
|
252
|
+
/** RC_STREAMING is on and the gateway has not answered in plain JSON. */
|
|
253
|
+
shouldTryStreaming: () => opts.streaming && streamingSupported !== false,
|
|
254
|
+
};
|
|
255
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { RocketChatClient } from "@practicalworks/rc-client";
|
|
2
|
+
import type { AttachmentDeps, AttachmentLimits, ImageResizer } from "./attachments.js";
|
|
3
|
+
import type { Log } from "./config.js";
|
|
4
|
+
export interface AttachmentDepsOptions {
|
|
5
|
+
rc: Pick<RocketChatClient, "headersForRoom" | "get">;
|
|
6
|
+
/** The Rocket.Chat base URL that upload links are relative to. */
|
|
7
|
+
rcUrl: string;
|
|
8
|
+
limits: AttachmentLimits;
|
|
9
|
+
/** Shrinks or converts an image the limits would skip; absent, it is skipped. */
|
|
10
|
+
resizeImage?: ImageResizer;
|
|
11
|
+
log: Log;
|
|
12
|
+
}
|
|
13
|
+
/** Reads run as the ROOM's identity, not the bot's: an account that speaks in a
|
|
14
|
+
* room for the bot can read uploads there that the bot itself cannot. */
|
|
15
|
+
export declare function createAttachmentDeps(opts: AttachmentDepsOptions): (roomId: string) => Promise<AttachmentDeps>;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** Reads run as the ROOM's identity, not the bot's: an account that speaks in a
|
|
2
|
+
* room for the bot can read uploads there that the bot itself cannot. */
|
|
3
|
+
export function createAttachmentDeps(opts) {
|
|
4
|
+
const { rc, rcUrl, limits, resizeImage, log } = opts;
|
|
5
|
+
return async (roomId) => ({
|
|
6
|
+
rcUrl,
|
|
7
|
+
headers: await rc.headersForRoom(roomId),
|
|
8
|
+
get: (url, headers) => rc.get(url, headers, "Rocket.Chat attachment"),
|
|
9
|
+
limits,
|
|
10
|
+
...(resizeImage ? { resizeImage } : {}),
|
|
11
|
+
log,
|
|
12
|
+
});
|
|
13
|
+
}
|