@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/dist/response.js
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
// What the agent actually did in a turn.
|
|
2
|
+
//
|
|
3
|
+
// Keeping only the `type === "message"` items of `output[]` would throw away
|
|
4
|
+
// every tool the agent called, and "did it actually call that tool?" would be
|
|
5
|
+
// unanswerable: not for lack of data, but because it was discarded on arrival.
|
|
6
|
+
//
|
|
7
|
+
// Verified against the gateway this was built on:
|
|
8
|
+
// the non-streaming `output[]` contains EXACTLY three item types —
|
|
9
|
+
// function_call {name, arguments (a JSON *string*), call_id}
|
|
10
|
+
// function_call_output {call_id, output}
|
|
11
|
+
// message {role, content:[{type:"output_text", text}]}
|
|
12
|
+
// There is no `reasoning` item — the gateway does not expose thinking over HTTP.
|
|
13
|
+
// So a full tool trace needs no streaming and no protocol change; it is already
|
|
14
|
+
// sitting in the response we get today.
|
|
15
|
+
const int = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.round(v) : null);
|
|
16
|
+
/** Token counts in either wire shape the gateway sends (Responses or Chat
|
|
17
|
+
* Completions), bare or under `usage`; null when neither count is there. */
|
|
18
|
+
export function usageFrom(body) {
|
|
19
|
+
if (!body || typeof body !== "object")
|
|
20
|
+
return null;
|
|
21
|
+
const b = body;
|
|
22
|
+
const u = (b.usage && typeof b.usage === "object" ? b.usage : b);
|
|
23
|
+
const tokensIn = int(u.input_tokens) ?? int(u.prompt_tokens) ?? int(u.inputTokens);
|
|
24
|
+
const tokensOut = int(u.output_tokens) ?? int(u.completion_tokens) ?? int(u.outputTokens);
|
|
25
|
+
if (tokensIn === null && tokensOut === null)
|
|
26
|
+
return null;
|
|
27
|
+
const details = (u.input_tokens_details ?? u.prompt_tokens_details ?? {});
|
|
28
|
+
const tokensCached = int(details.cached_tokens) ?? int(u.cached_tokens) ?? int(u.cachedInputTokens);
|
|
29
|
+
return { tokensIn, tokensOut, tokensCached };
|
|
30
|
+
}
|
|
31
|
+
/** How much of a tool's arguments to keep. Long enough to identify the call,
|
|
32
|
+
* short enough that a file-write's payload doesn't land in the database. */
|
|
33
|
+
const MAX_ARGS_PREVIEW = 200;
|
|
34
|
+
/** Collapse a tool's arguments to a compact preview. `arguments` arrives as a
|
|
35
|
+
* JSON *string*; when it parses we re-render it compactly (dropping whitespace
|
|
36
|
+
* the model emitted), and when it doesn't we keep the raw string rather than
|
|
37
|
+
* losing it. */
|
|
38
|
+
export function previewArgs(raw, max = MAX_ARGS_PREVIEW) {
|
|
39
|
+
if (raw === undefined || raw === null)
|
|
40
|
+
return undefined;
|
|
41
|
+
let text;
|
|
42
|
+
if (typeof raw === "string") {
|
|
43
|
+
try {
|
|
44
|
+
text = JSON.stringify(JSON.parse(raw));
|
|
45
|
+
}
|
|
46
|
+
catch {
|
|
47
|
+
text = raw;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
else {
|
|
51
|
+
text = JSON.stringify(raw);
|
|
52
|
+
}
|
|
53
|
+
text = text.trim();
|
|
54
|
+
if (!text || text === "{}")
|
|
55
|
+
return undefined;
|
|
56
|
+
return text.length > max ? `${text.slice(0, max)}…` : text;
|
|
57
|
+
}
|
|
58
|
+
/** A failed tool result as text: a string as-is, anything else as JSON. */
|
|
59
|
+
export function errorText(output) {
|
|
60
|
+
if (typeof output === "string")
|
|
61
|
+
return output;
|
|
62
|
+
if (output === undefined || output === null)
|
|
63
|
+
return undefined;
|
|
64
|
+
try {
|
|
65
|
+
return JSON.stringify(output);
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
return String(output);
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
export function outputLength(output) {
|
|
72
|
+
if (typeof output === "string")
|
|
73
|
+
return output.length;
|
|
74
|
+
if (Array.isArray(output)) {
|
|
75
|
+
return output.reduce((n, part) => n + (typeof part?.text === "string" ? part.text.length : 0), 0);
|
|
76
|
+
}
|
|
77
|
+
return undefined;
|
|
78
|
+
}
|
|
79
|
+
/** Split a /v1/responses body into the reply text and the trace of what it took
|
|
80
|
+
* to produce it. Never throws — a malformed body yields empty text, which the
|
|
81
|
+
* caller already handles as "(no reply)". */
|
|
82
|
+
export function summarizeResponse(body) {
|
|
83
|
+
const output = body?.output;
|
|
84
|
+
const head = body;
|
|
85
|
+
const usage = usageFrom(body);
|
|
86
|
+
const ident = {
|
|
87
|
+
...(typeof head?.id === "string" && head.id ? { id: head.id } : {}),
|
|
88
|
+
...(typeof head?.model === "string" && head.model ? { model: head.model } : {}),
|
|
89
|
+
...(usage ? { usage } : {}),
|
|
90
|
+
};
|
|
91
|
+
const empty = { text: "", tools: [], unknownTypes: [], ...ident };
|
|
92
|
+
if (!Array.isArray(output))
|
|
93
|
+
return empty;
|
|
94
|
+
const parts = [];
|
|
95
|
+
const tools = [];
|
|
96
|
+
const unknownTypes = [];
|
|
97
|
+
// call_id → index in `tools`, so a result can be attached to the call it
|
|
98
|
+
// belongs to rather than to whichever call happened to be last.
|
|
99
|
+
const byCallId = new Map();
|
|
100
|
+
for (const item of output) {
|
|
101
|
+
switch (item?.type) {
|
|
102
|
+
case "message": {
|
|
103
|
+
if (!Array.isArray(item.content))
|
|
104
|
+
break;
|
|
105
|
+
for (const c of item.content) {
|
|
106
|
+
if (c?.type === "output_text" && c.text)
|
|
107
|
+
parts.push(c.text);
|
|
108
|
+
}
|
|
109
|
+
break;
|
|
110
|
+
}
|
|
111
|
+
case "function_call": {
|
|
112
|
+
const name = typeof item.name === "string" && item.name ? item.name : "(unnamed tool)";
|
|
113
|
+
if (item.call_id)
|
|
114
|
+
byCallId.set(item.call_id, tools.length);
|
|
115
|
+
tools.push({ name, args: previewArgs(item.arguments) });
|
|
116
|
+
break;
|
|
117
|
+
}
|
|
118
|
+
case "function_call_output": {
|
|
119
|
+
const at = item.call_id ? byCallId.get(item.call_id) : undefined;
|
|
120
|
+
const failed = item.is_error === true || item.isError === true || item.status === "error" || item.error !== undefined;
|
|
121
|
+
if (failed) {
|
|
122
|
+
const error = errorText(item.error ?? item.output)?.trim() || undefined;
|
|
123
|
+
if (at !== undefined && tools[at])
|
|
124
|
+
tools[at].error = error;
|
|
125
|
+
else
|
|
126
|
+
tools.push({ name: "(unmatched result)", ...(error ? { error } : {}) });
|
|
127
|
+
break;
|
|
128
|
+
}
|
|
129
|
+
const chars = outputLength(item.output);
|
|
130
|
+
// A result with no matching call still counts as evidence of a tool
|
|
131
|
+
// running, so it's recorded rather than dropped.
|
|
132
|
+
if (at !== undefined && tools[at])
|
|
133
|
+
tools[at].outputChars = chars;
|
|
134
|
+
else
|
|
135
|
+
tools.push({ name: "(unmatched result)", outputChars: chars });
|
|
136
|
+
break;
|
|
137
|
+
}
|
|
138
|
+
default:
|
|
139
|
+
if (item?.type)
|
|
140
|
+
unknownTypes.push(item.type);
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
return { text: parts.join("\n").trim(), tools, unknownTypes, ...ident };
|
|
144
|
+
}
|
|
145
|
+
/** One log line naming what the turn actually did — `search_notes×3`
|
|
146
|
+
* style, with result sizes, so a search that found nothing is visible as such. */
|
|
147
|
+
export function describeTools(tools) {
|
|
148
|
+
if (!tools.length)
|
|
149
|
+
return "no tools called";
|
|
150
|
+
const counts = new Map();
|
|
151
|
+
for (const t of tools) {
|
|
152
|
+
const at = counts.get(t.name) ?? { n: 0, chars: 0 };
|
|
153
|
+
at.n += 1;
|
|
154
|
+
at.chars += t.outputChars ?? 0;
|
|
155
|
+
counts.set(t.name, at);
|
|
156
|
+
}
|
|
157
|
+
return [...counts]
|
|
158
|
+
.map(([name, { n, chars }]) => `${name}${n > 1 ? `×${n}` : ""} (${chars} chars back)`)
|
|
159
|
+
.join(", ");
|
|
160
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
export interface ApprovalDetails {
|
|
2
|
+
command?: string;
|
|
3
|
+
choices?: string[];
|
|
4
|
+
}
|
|
5
|
+
/** Extract the approval payload without depending on one gateway event wrapper. */
|
|
6
|
+
export declare function approvalDetailsFromEvent(value: unknown): ApprovalDetails | undefined;
|
|
7
|
+
export interface RunEventCapture {
|
|
8
|
+
command?: string;
|
|
9
|
+
choices?: string[];
|
|
10
|
+
snapshot(): ApprovalDetails;
|
|
11
|
+
close(): void;
|
|
12
|
+
}
|
|
13
|
+
/** Subscribe to a run's non-destructive event feed. The caller owns close(). */
|
|
14
|
+
export declare function captureRunEvents(options: {
|
|
15
|
+
url: string;
|
|
16
|
+
apiKey: string;
|
|
17
|
+
runId: string;
|
|
18
|
+
fetchImpl?: typeof fetch;
|
|
19
|
+
}): RunEventCapture;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { createSseParser } from "./stream.js";
|
|
2
|
+
/** Extract the approval payload without depending on one gateway event wrapper. */
|
|
3
|
+
export function approvalDetailsFromEvent(value) {
|
|
4
|
+
if (!value || typeof value !== "object")
|
|
5
|
+
return undefined;
|
|
6
|
+
const object = value;
|
|
7
|
+
const nested = [object, object.data, object.event, object.payload, object.details]
|
|
8
|
+
.filter((candidate) => Boolean(candidate && typeof candidate === "object"));
|
|
9
|
+
for (const candidate of nested) {
|
|
10
|
+
const command = [candidate.command, candidate.command_text, candidate.tool, candidate.name].find((item) => typeof item === "string" && item.trim().length > 0);
|
|
11
|
+
const rawChoices = candidate.choices ?? candidate.options ?? candidate.allowed;
|
|
12
|
+
const choices = Array.isArray(rawChoices)
|
|
13
|
+
? rawChoices.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean)
|
|
14
|
+
: undefined;
|
|
15
|
+
if (command || choices?.length)
|
|
16
|
+
return { ...(command ? { command: command.trim() } : {}), ...(choices?.length ? { choices } : {}) };
|
|
17
|
+
}
|
|
18
|
+
return undefined;
|
|
19
|
+
}
|
|
20
|
+
/** Subscribe to a run's non-destructive event feed. The caller owns close(). */
|
|
21
|
+
export function captureRunEvents(options) {
|
|
22
|
+
const controller = new AbortController();
|
|
23
|
+
let command;
|
|
24
|
+
let choices;
|
|
25
|
+
const fetchImpl = options.fetchImpl ?? fetch;
|
|
26
|
+
void (async () => {
|
|
27
|
+
try {
|
|
28
|
+
const response = await fetchImpl(`${options.url}/v1/runs/${encodeURIComponent(options.runId)}/events`, {
|
|
29
|
+
headers: { accept: "text/event-stream", authorization: `Bearer ${options.apiKey}` },
|
|
30
|
+
signal: controller.signal,
|
|
31
|
+
});
|
|
32
|
+
if (!response.ok || !response.body)
|
|
33
|
+
return;
|
|
34
|
+
const parser = createSseParser();
|
|
35
|
+
const decoder = new TextDecoder();
|
|
36
|
+
const consume = (events) => {
|
|
37
|
+
for (const event of events) {
|
|
38
|
+
if (event.data === "[DONE]")
|
|
39
|
+
continue;
|
|
40
|
+
try {
|
|
41
|
+
const details = approvalDetailsFromEvent(JSON.parse(event.data));
|
|
42
|
+
if (details?.command)
|
|
43
|
+
command = details.command;
|
|
44
|
+
if (details?.choices?.length)
|
|
45
|
+
choices = details.choices;
|
|
46
|
+
}
|
|
47
|
+
catch {
|
|
48
|
+
// An unrelated or malformed event must not affect the turn.
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
};
|
|
52
|
+
for await (const chunk of response.body) {
|
|
53
|
+
consume(parser.push(decoder.decode(chunk, { stream: true })));
|
|
54
|
+
}
|
|
55
|
+
consume(parser.flush());
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
// Best effort: the approval path still sends a status-only DM if this feed fails.
|
|
59
|
+
}
|
|
60
|
+
})();
|
|
61
|
+
return {
|
|
62
|
+
snapshot: () => ({ ...(command ? { command } : {}), ...(choices ? { choices } : {}) }),
|
|
63
|
+
close: () => controller.abort(),
|
|
64
|
+
};
|
|
65
|
+
}
|
package/dist/state.d.ts
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { type RoomEngagement, type ThreadRoot } from "./threading.js";
|
|
2
|
+
import type { Log } from "./config.js";
|
|
3
|
+
import { ConversationEpochs } from "./conversation-epochs.js";
|
|
4
|
+
import type { HeldFollowUp } from "./followups.js";
|
|
5
|
+
export interface JsonStateFileOptions<T> {
|
|
6
|
+
/** Raw JSON → state. A throw counts as an invalid file. */
|
|
7
|
+
parse: (raw: unknown) => T;
|
|
8
|
+
/** State → the JSON value written. Defaults to the state itself. */
|
|
9
|
+
serialize?: (value: T) => unknown;
|
|
10
|
+
log: Log;
|
|
11
|
+
/** Names the file in "could not persist <label> to <path>". */
|
|
12
|
+
label: string;
|
|
13
|
+
/** Names the file in "<invalidLabel> <path> is not valid JSON"; unset, junk is ignored silently. */
|
|
14
|
+
invalidLabel?: string;
|
|
15
|
+
}
|
|
16
|
+
export interface JsonStateFile<T> {
|
|
17
|
+
readonly path: string;
|
|
18
|
+
/** undefined when the file is missing or invalid — a first boot, not an error. */
|
|
19
|
+
load(): T | undefined;
|
|
20
|
+
/** Best-effort: a failed write logs and never throws. */
|
|
21
|
+
persist(value: T): void;
|
|
22
|
+
}
|
|
23
|
+
/** One small JSON file of best-effort state, read on boot and rewritten on change. */
|
|
24
|
+
export declare function jsonStateFile<T>(path: string, opts: JsonStateFileOptions<T>): JsonStateFile<T>;
|
|
25
|
+
/** Drop oldest-first until `keys` fits `max`, never evicting `keep` (the key just written). */
|
|
26
|
+
export declare function evictOldest(keys: Set<string> | Map<string, unknown>, max: number, keep: string): void;
|
|
27
|
+
export interface PauseState {
|
|
28
|
+
active: boolean;
|
|
29
|
+
by?: string;
|
|
30
|
+
}
|
|
31
|
+
export interface BridgeStateOptions {
|
|
32
|
+
pauseFile: string;
|
|
33
|
+
conversationEpochFile: string;
|
|
34
|
+
engagementFile: string;
|
|
35
|
+
log: Log;
|
|
36
|
+
}
|
|
37
|
+
/** The three state files: each env var if set, else under ~/rocketchat-bridge/. */
|
|
38
|
+
export declare function stateFilesFromEnv(env?: NodeJS.ProcessEnv): Omit<BridgeStateOptions, "log">;
|
|
39
|
+
/** Loads every persisted file on creation; `P` is the webhook payload a held follow-up carries. */
|
|
40
|
+
export declare function createBridgeState<P>(opts: BridgeStateOptions): {
|
|
41
|
+
paused: Readonly<PauseState>;
|
|
42
|
+
pause(by: string | undefined): void;
|
|
43
|
+
resume(): void;
|
|
44
|
+
conversationEpochs: ConversationEpochs;
|
|
45
|
+
rooms: Map<string, RoomEngagement>;
|
|
46
|
+
roomFor: (id: string) => RoomEngagement;
|
|
47
|
+
persistEngagement: () => void;
|
|
48
|
+
/** Turn locks, one per CONVERSATION (not per room). */
|
|
49
|
+
busyConversations: Set<string>;
|
|
50
|
+
/** Messages held while their conversation was busy. */
|
|
51
|
+
heldFollowUps: Map<string, HeldFollowUp<P>>;
|
|
52
|
+
startedConversations: Set<string>;
|
|
53
|
+
markConversationStarted(conversation: string): void;
|
|
54
|
+
/** A cached root; `null` = RC would not give it to us, `undefined` = never read. */
|
|
55
|
+
cachedThreadRoot: (tmid: string) => ThreadRoot | null | undefined;
|
|
56
|
+
cacheThreadRoot(tmid: string, root: ThreadRoot | null): void;
|
|
57
|
+
};
|
package/dist/state.js
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
// The bridge's room state: the pause switch, conversation epochs, engagement,
|
|
2
|
+
// turn locks, held follow-ups, started conversations and the thread-root cache.
|
|
3
|
+
// Every state file keeps a stable path, env var and JSON shape, so a new version
|
|
4
|
+
// reads what the previous one wrote.
|
|
5
|
+
import { readFileSync, writeFileSync } from "node:fs";
|
|
6
|
+
import os from "node:os";
|
|
7
|
+
import path from "node:path";
|
|
8
|
+
import { deserializeEngagement, MAX_TRACKED_IDS, serializeEngagement, } from "./threading.js";
|
|
9
|
+
import { ConversationEpochs } from "./conversation-epochs.js";
|
|
10
|
+
/** One small JSON file of best-effort state, read on boot and rewritten on change. */
|
|
11
|
+
export function jsonStateFile(path, opts) {
|
|
12
|
+
const serialize = opts.serialize ?? ((v) => v);
|
|
13
|
+
return {
|
|
14
|
+
path,
|
|
15
|
+
load() {
|
|
16
|
+
let raw;
|
|
17
|
+
try {
|
|
18
|
+
raw = readFileSync(path, "utf8");
|
|
19
|
+
}
|
|
20
|
+
catch {
|
|
21
|
+
return undefined;
|
|
22
|
+
}
|
|
23
|
+
try {
|
|
24
|
+
return opts.parse(JSON.parse(raw));
|
|
25
|
+
}
|
|
26
|
+
catch (err) {
|
|
27
|
+
if (opts.invalidLabel)
|
|
28
|
+
opts.log(`${opts.invalidLabel} ${path} is not valid JSON: ${err?.message ?? err}`);
|
|
29
|
+
return undefined;
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
persist(value) {
|
|
33
|
+
try {
|
|
34
|
+
writeFileSync(path, JSON.stringify(serialize(value)), "utf8");
|
|
35
|
+
}
|
|
36
|
+
catch (err) {
|
|
37
|
+
opts.log(`could not persist ${opts.label} to ${path}: ${err?.message ?? err}`);
|
|
38
|
+
}
|
|
39
|
+
},
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/** Drop oldest-first until `keys` fits `max`, never evicting `keep` (the key just written). */
|
|
43
|
+
export function evictOldest(keys, max, keep) {
|
|
44
|
+
while (keys.size > max) {
|
|
45
|
+
const oldest = keys.keys().next().value;
|
|
46
|
+
if (oldest === undefined || oldest === keep)
|
|
47
|
+
break;
|
|
48
|
+
keys.delete(oldest);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
/** The three state files: each env var if set, else under ~/rocketchat-bridge/. */
|
|
52
|
+
export function stateFilesFromEnv(env = process.env) {
|
|
53
|
+
const home = path.join(os.homedir(), "rocketchat-bridge");
|
|
54
|
+
return {
|
|
55
|
+
pauseFile: env.RC_PAUSE_STATE_FILE ?? path.join(home, "paused.json"),
|
|
56
|
+
conversationEpochFile: env.CONVERSATION_EPOCH_STATE_FILE ?? path.join(home, "conversation-epochs.json"),
|
|
57
|
+
engagementFile: env.ENGAGEMENT_STATE_FILE ?? path.join(home, "engaged-threads.json"),
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
/** How many conversations `startedConversations` remembers. */
|
|
61
|
+
const MAX_STARTED_CONVERSATIONS = 500;
|
|
62
|
+
/** Loads every persisted file on creation; `P` is the webhook payload a held follow-up carries. */
|
|
63
|
+
export function createBridgeState(opts) {
|
|
64
|
+
const { log } = opts;
|
|
65
|
+
// Persisted, so a pause survives a restart. A kill switch that a deploy or a
|
|
66
|
+
// crash silently undoes is worse than none: you'd believe it was off.
|
|
67
|
+
const pauseFile = jsonStateFile(opts.pauseFile, {
|
|
68
|
+
parse: (raw) => raw,
|
|
69
|
+
log,
|
|
70
|
+
label: "pause state",
|
|
71
|
+
});
|
|
72
|
+
const paused = { active: false };
|
|
73
|
+
const loadedPause = pauseFile.load();
|
|
74
|
+
if (loadedPause?.active) {
|
|
75
|
+
paused.active = true;
|
|
76
|
+
paused.by = typeof loadedPause.by === "string" ? loadedPause.by : undefined;
|
|
77
|
+
log(`RESUMING PAUSED: bridge is paused (by ${paused.by ?? "unknown"}). Resume it from a control verb, or delete ${opts.pauseFile}.`);
|
|
78
|
+
}
|
|
79
|
+
// A room's agent conversation is bounded: keyed on a daily epoch,
|
|
80
|
+
// bumped by `/new`. Persisted for the same reason as the pause — a reset that
|
|
81
|
+
// a restart quietly undoes would hand the room its old context straight back.
|
|
82
|
+
const conversationEpochs = new ConversationEpochs(opts.conversationEpochFile, log);
|
|
83
|
+
// Engagement: held in memory only, it would die on every restart and a
|
|
84
|
+
// thread the agent had been answering would go silent. Snapshotted on change and
|
|
85
|
+
// reloaded on boot; a broken file costs engagement memory, never a turn.
|
|
86
|
+
const engagementFile = jsonStateFile(opts.engagementFile, {
|
|
87
|
+
parse: deserializeEngagement,
|
|
88
|
+
serialize: serializeEngagement,
|
|
89
|
+
log,
|
|
90
|
+
label: "engaged threads",
|
|
91
|
+
invalidLabel: "engagement state file",
|
|
92
|
+
});
|
|
93
|
+
const rooms = engagementFile.load() ?? new Map();
|
|
94
|
+
if (rooms.size)
|
|
95
|
+
log(`restored engaged threads for ${rooms.size} room(s) from ${engagementFile.path}`);
|
|
96
|
+
function roomFor(id) {
|
|
97
|
+
let r = rooms.get(id);
|
|
98
|
+
if (!r) {
|
|
99
|
+
r = { engagedIds: new Set(), threadOwners: new Map() };
|
|
100
|
+
rooms.set(id, r);
|
|
101
|
+
}
|
|
102
|
+
return r;
|
|
103
|
+
}
|
|
104
|
+
// Unpersisted: losing it costs one redundant thread-root read,
|
|
105
|
+
// not silence, so it is not worth another file on disk.
|
|
106
|
+
const startedConversations = new Set();
|
|
107
|
+
const threadRoots = new Map();
|
|
108
|
+
return {
|
|
109
|
+
paused: paused,
|
|
110
|
+
pause(by) {
|
|
111
|
+
paused.active = true;
|
|
112
|
+
paused.by = by;
|
|
113
|
+
pauseFile.persist(paused);
|
|
114
|
+
},
|
|
115
|
+
resume() {
|
|
116
|
+
paused.active = false;
|
|
117
|
+
paused.by = undefined;
|
|
118
|
+
pauseFile.persist(paused);
|
|
119
|
+
},
|
|
120
|
+
conversationEpochs,
|
|
121
|
+
rooms,
|
|
122
|
+
roomFor,
|
|
123
|
+
persistEngagement: () => engagementFile.persist(rooms),
|
|
124
|
+
/** Turn locks, one per CONVERSATION (not per room). */
|
|
125
|
+
busyConversations: new Set(),
|
|
126
|
+
/** Messages held while their conversation was busy. */
|
|
127
|
+
heldFollowUps: new Map(),
|
|
128
|
+
startedConversations,
|
|
129
|
+
markConversationStarted(conversation) {
|
|
130
|
+
startedConversations.delete(conversation);
|
|
131
|
+
startedConversations.add(conversation);
|
|
132
|
+
evictOldest(startedConversations, MAX_STARTED_CONVERSATIONS, conversation);
|
|
133
|
+
},
|
|
134
|
+
/** A cached root; `null` = RC would not give it to us, `undefined` = never read. */
|
|
135
|
+
cachedThreadRoot: (tmid) => threadRoots.get(tmid),
|
|
136
|
+
cacheThreadRoot(tmid, root) {
|
|
137
|
+
threadRoots.set(tmid, root);
|
|
138
|
+
evictOldest(threadRoots, MAX_TRACKED_IDS * 4, tmid);
|
|
139
|
+
},
|
|
140
|
+
};
|
|
141
|
+
}
|
package/dist/stream.d.ts
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** A parsed SSE event. `data` is the raw JSON string; callers decode it. */
|
|
2
|
+
export interface SseEvent {
|
|
3
|
+
event?: string;
|
|
4
|
+
data: string;
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Incremental SSE parser.
|
|
8
|
+
*
|
|
9
|
+
* Chunks off a socket split anywhere — mid-line, mid-JSON, between the `event:`
|
|
10
|
+
* and its `data:`. So this buffers and only emits on a complete blank-line
|
|
11
|
+
* delimited record.
|
|
12
|
+
*/
|
|
13
|
+
export declare function createSseParser(): {
|
|
14
|
+
push(chunk: string): SseEvent[];
|
|
15
|
+
flush(): SseEvent[];
|
|
16
|
+
};
|
|
17
|
+
/** What a decoded stream event meant to us. */
|
|
18
|
+
export type StreamSignal =
|
|
19
|
+
/** `response.created` — the run's handle, sent before any text. The
|
|
20
|
+
* only thing on the stream that names the run, so it is the only way the
|
|
21
|
+
* bridge can later ask the gateway whether that run parked. */
|
|
22
|
+
{
|
|
23
|
+
kind: "created";
|
|
24
|
+
id: string;
|
|
25
|
+
} | {
|
|
26
|
+
kind: "delta";
|
|
27
|
+
text: string;
|
|
28
|
+
} | {
|
|
29
|
+
kind: "completed";
|
|
30
|
+
response: unknown;
|
|
31
|
+
} | {
|
|
32
|
+
kind: "error";
|
|
33
|
+
message: string;
|
|
34
|
+
} | {
|
|
35
|
+
kind: "done";
|
|
36
|
+
} | {
|
|
37
|
+
kind: "ignored";
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* Interpret one SSE event.
|
|
41
|
+
*
|
|
42
|
+
* Deliberately tolerant about which field carries the text: this gateway is
|
|
43
|
+
* OpenAI-compatible but we have been burned before by assuming a payload shape
|
|
44
|
+
* from a spec rather than from the wire. Anything unrecognised is `ignored`
|
|
45
|
+
* rather than fatal — an unknown event type must never sink a turn that is
|
|
46
|
+
* otherwise succeeding.
|
|
47
|
+
*/
|
|
48
|
+
export declare function interpretSseEvent(evt: SseEvent): StreamSignal;
|
|
49
|
+
/**
|
|
50
|
+
* The same interpretation, plus the event's own type NAME.
|
|
51
|
+
*
|
|
52
|
+
* Exists so a caller can take a census of what the gateway actually sends.
|
|
53
|
+
* `interpretSseEvent` collapses everything it doesn't act on into
|
|
54
|
+
* `ignored`, which is right for driving a reply and useless for measuring one:
|
|
55
|
+
* counting only what we consume is how "2 deltas" got read as "the gateway
|
|
56
|
+
* buffers", when `response.output_item.added` — the function_call events
|
|
57
|
+
* carrying live tool activity — were streaming past uncounted the whole time.
|
|
58
|
+
*
|
|
59
|
+
* The type is resolved here rather than by re-parsing at the call site, so the
|
|
60
|
+
* census and the behaviour can never disagree about what an event was.
|
|
61
|
+
*/
|
|
62
|
+
export declare function readSseEvent(evt: SseEvent): {
|
|
63
|
+
type: string;
|
|
64
|
+
signal: StreamSignal;
|
|
65
|
+
};
|
|
66
|
+
/** Render an event census smallest-key-first as `type=count`, for one log line. */
|
|
67
|
+
export declare function formatCensus(census: Map<string, number>): string;
|
package/dist/stream.js
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
// Reading the agent's /v1/responses SSE stream.
|
|
2
|
+
//
|
|
3
|
+
// The bridge streams for what only a stream gives: the run's handle for the park
|
|
4
|
+
// check and a census of every event type. Text is NOT shown live — RC
|
|
5
|
+
// notifies on a message's creation, never its edits, so replies post once,
|
|
6
|
+
// finished. Too-large replies are split by the client's `splitForRc`.
|
|
7
|
+
//
|
|
8
|
+
// Kept apart from main.ts so the parsing is unit-testable.
|
|
9
|
+
/**
|
|
10
|
+
* Incremental SSE parser.
|
|
11
|
+
*
|
|
12
|
+
* Chunks off a socket split anywhere — mid-line, mid-JSON, between the `event:`
|
|
13
|
+
* and its `data:`. So this buffers and only emits on a complete blank-line
|
|
14
|
+
* delimited record.
|
|
15
|
+
*/
|
|
16
|
+
export function createSseParser() {
|
|
17
|
+
let buffer = "";
|
|
18
|
+
const parseRecord = (record) => {
|
|
19
|
+
let event;
|
|
20
|
+
const dataLines = [];
|
|
21
|
+
for (const line of record.split("\n")) {
|
|
22
|
+
if (line.startsWith(":"))
|
|
23
|
+
continue; // comment / keep-alive
|
|
24
|
+
if (line.startsWith("event:"))
|
|
25
|
+
event = line.slice(6).trim();
|
|
26
|
+
else if (line.startsWith("data:"))
|
|
27
|
+
dataLines.push(line.slice(5).trimStart());
|
|
28
|
+
}
|
|
29
|
+
if (!dataLines.length)
|
|
30
|
+
return null;
|
|
31
|
+
return { event, data: dataLines.join("\n") };
|
|
32
|
+
};
|
|
33
|
+
return {
|
|
34
|
+
push(chunk) {
|
|
35
|
+
buffer += chunk;
|
|
36
|
+
const out = [];
|
|
37
|
+
let idx;
|
|
38
|
+
// Records are separated by a blank line. \r\n tolerated.
|
|
39
|
+
while ((idx = buffer.search(/\r?\n\r?\n/)) !== -1) {
|
|
40
|
+
const record = buffer.slice(0, idx);
|
|
41
|
+
buffer = buffer.slice(idx + buffer.slice(idx).match(/^\r?\n\r?\n/)[0].length);
|
|
42
|
+
const parsed = parseRecord(record);
|
|
43
|
+
if (parsed)
|
|
44
|
+
out.push(parsed);
|
|
45
|
+
}
|
|
46
|
+
return out;
|
|
47
|
+
},
|
|
48
|
+
// A stream that ends without a trailing blank line still has one record in
|
|
49
|
+
// hand; losing it would silently drop the last of the answer.
|
|
50
|
+
flush() {
|
|
51
|
+
const rest = buffer.trim();
|
|
52
|
+
buffer = "";
|
|
53
|
+
if (!rest)
|
|
54
|
+
return [];
|
|
55
|
+
const parsed = parseRecord(rest);
|
|
56
|
+
return parsed ? [parsed] : [];
|
|
57
|
+
},
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Interpret one SSE event.
|
|
62
|
+
*
|
|
63
|
+
* Deliberately tolerant about which field carries the text: this gateway is
|
|
64
|
+
* OpenAI-compatible but we have been burned before by assuming a payload shape
|
|
65
|
+
* from a spec rather than from the wire. Anything unrecognised is `ignored`
|
|
66
|
+
* rather than fatal — an unknown event type must never sink a turn that is
|
|
67
|
+
* otherwise succeeding.
|
|
68
|
+
*/
|
|
69
|
+
export function interpretSseEvent(evt) {
|
|
70
|
+
return readSseEvent(evt).signal;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* The same interpretation, plus the event's own type NAME.
|
|
74
|
+
*
|
|
75
|
+
* Exists so a caller can take a census of what the gateway actually sends.
|
|
76
|
+
* `interpretSseEvent` collapses everything it doesn't act on into
|
|
77
|
+
* `ignored`, which is right for driving a reply and useless for measuring one:
|
|
78
|
+
* counting only what we consume is how "2 deltas" got read as "the gateway
|
|
79
|
+
* buffers", when `response.output_item.added` — the function_call events
|
|
80
|
+
* carrying live tool activity — were streaming past uncounted the whole time.
|
|
81
|
+
*
|
|
82
|
+
* The type is resolved here rather than by re-parsing at the call site, so the
|
|
83
|
+
* census and the behaviour can never disagree about what an event was.
|
|
84
|
+
*/
|
|
85
|
+
export function readSseEvent(evt) {
|
|
86
|
+
if (evt.data === "[DONE]")
|
|
87
|
+
return { type: "[DONE]", signal: { kind: "done" } };
|
|
88
|
+
let parsed;
|
|
89
|
+
try {
|
|
90
|
+
parsed = JSON.parse(evt.data);
|
|
91
|
+
}
|
|
92
|
+
catch {
|
|
93
|
+
// Still worth naming: a stream full of unparseable records is a finding, and
|
|
94
|
+
// an empty census row would hide it.
|
|
95
|
+
return { type: evt.event ?? "(unparseable)", signal: { kind: "ignored" } };
|
|
96
|
+
}
|
|
97
|
+
const type = parsed.type ?? evt.event ?? "(untyped)";
|
|
98
|
+
const as = (signal) => ({ type, signal });
|
|
99
|
+
if (type === "response.created") {
|
|
100
|
+
// The id rides on the response object in the OpenAI shape and at the top
|
|
101
|
+
// level in some gateway builds; take whichever is there, and say `ignored`
|
|
102
|
+
// rather than inventing a handle when neither is.
|
|
103
|
+
const inner = parsed.response?.id;
|
|
104
|
+
const id = typeof inner === "string" ? inner : typeof parsed.id === "string" ? parsed.id : "";
|
|
105
|
+
return as(id ? { kind: "created", id } : { kind: "ignored" });
|
|
106
|
+
}
|
|
107
|
+
if (type.endsWith("output_text.delta") || type === "response.text.delta") {
|
|
108
|
+
const text = typeof parsed.delta === "string" ? parsed.delta : typeof parsed.text === "string" ? parsed.text : "";
|
|
109
|
+
return as(text ? { kind: "delta", text } : { kind: "ignored" });
|
|
110
|
+
}
|
|
111
|
+
if (type === "response.completed" || type === "response.done") {
|
|
112
|
+
return as({ kind: "completed", response: parsed.response ?? parsed });
|
|
113
|
+
}
|
|
114
|
+
if (type === "response.failed" || type === "error" || parsed.error) {
|
|
115
|
+
const err = parsed.error;
|
|
116
|
+
return as({ kind: "error", message: err?.message ?? "the agent reported a failed response" });
|
|
117
|
+
}
|
|
118
|
+
return as({ kind: "ignored" });
|
|
119
|
+
}
|
|
120
|
+
/** Render an event census smallest-key-first as `type=count`, for one log line. */
|
|
121
|
+
export function formatCensus(census) {
|
|
122
|
+
return [...census.entries()]
|
|
123
|
+
.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
|
|
124
|
+
.map(([type, n]) => `${type}=${n}`)
|
|
125
|
+
.join(" ");
|
|
126
|
+
}
|