@modelriver/cli 1.2.6 → 2.0.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/README.md +198 -3
- package/package.json +29 -15
- package/src/cli.js +232 -0
- package/src/commands/listen.js +17 -8
- package/src/commands/login.js +59 -16
- package/src/commands/test-webhook.js +10 -3
- package/src/commands/tool-calls.js +138 -0
- package/src/commands/tools.js +762 -0
- package/src/commands/trigger.js +8 -3
- package/src/commands/webhook.js +8 -5
- package/src/commands/websocket.js +185 -58
- package/src/index.js +2 -166
- package/src/lib/api-client.js +116 -11
- package/src/lib/cli-websocket-client.js +381 -137
- package/src/lib/config.js +141 -13
- package/src/lib/tool-forwarder.js +325 -0
- package/src/lib/tool-session-store.js +361 -0
- package/src/lib/tool-signature.js +141 -0
- package/src/lib/webhook-verifier.js +43 -16
- package/src/lib/websocket-client.js +29 -3
- package/src/utils/logger.js +8 -7
- package/src/utils/secrets.js +44 -0
- package/src/utils/tool-approvals.js +238 -0
- package/src/utils/url-helpers.js +117 -0
- package/src/utils/webhook-payload.js +9 -6
- package/tool-signature.js +3 -0
|
@@ -0,0 +1,762 @@
|
|
|
1
|
+
const ApiClient = require('../lib/api-client');
|
|
2
|
+
const CLIWebSocketClient = require('../lib/cli-websocket-client');
|
|
3
|
+
const config = require('../lib/config');
|
|
4
|
+
const {
|
|
5
|
+
ForwardTargetError,
|
|
6
|
+
parseForwardTarget,
|
|
7
|
+
resolveLoopback,
|
|
8
|
+
callTimeoutMs,
|
|
9
|
+
forwardToolCall,
|
|
10
|
+
} = require('../lib/tool-forwarder');
|
|
11
|
+
const Logger = require('../utils/logger');
|
|
12
|
+
const Formatter = require('../utils/formatter');
|
|
13
|
+
const { plainText } = require('../utils/tool-approvals');
|
|
14
|
+
const { maskSessionToken } = require('../utils/secrets');
|
|
15
|
+
const ToolSessionStore = require('../lib/tool-session-store');
|
|
16
|
+
|
|
17
|
+
const RESULT_PUSH_TIMEOUT_MS = 15000;
|
|
18
|
+
// How many call ids and reply refs a session remembers, so a repeated
|
|
19
|
+
// tool_call is never forwarded twice (oldest forgotten first).
|
|
20
|
+
const SEEN_LIMIT = 10000;
|
|
21
|
+
// How long Ctrl+C waits for the server to take the last replies.
|
|
22
|
+
const SHUTDOWN_REPLY_CAP_MS = 1000;
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Format a body for --print: pretty JSON when it parses, text otherwise.
|
|
26
|
+
* The model wrote the arguments and the endpoint wrote the result, so both
|
|
27
|
+
* are shown as plain text: control characters can't drive the terminal.
|
|
28
|
+
*/
|
|
29
|
+
function formatBody(body) {
|
|
30
|
+
if (body === null || body === undefined) return '(none)';
|
|
31
|
+
if (typeof body !== 'string') return plainText(Formatter.json(body));
|
|
32
|
+
try {
|
|
33
|
+
return plainText(Formatter.json(JSON.parse(body)));
|
|
34
|
+
} catch (error) {
|
|
35
|
+
return plainText(body);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* The tool's name, marked when the server says the tool changes something.
|
|
41
|
+
* Calls without an `effect` (older servers) are shown as before.
|
|
42
|
+
* @param {object} call - tool_call payload
|
|
43
|
+
*/
|
|
44
|
+
function toolLabel(call) {
|
|
45
|
+
const name = plainText((call && call.tool) || '(unknown tool)');
|
|
46
|
+
return call && call.effect === 'write' ? `${name} [write]` : name;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* One output line per call: time, tool, status (or error), duration.
|
|
51
|
+
* @param {string|object} toolOrCall - the tool name, or the tool_call payload
|
|
52
|
+
* @param {object} result
|
|
53
|
+
*/
|
|
54
|
+
function describeResult(toolOrCall, result) {
|
|
55
|
+
const time = Formatter.timestamp(new Date());
|
|
56
|
+
const label = typeof toolOrCall === 'object' && toolOrCall !== null
|
|
57
|
+
? toolLabel(toolOrCall)
|
|
58
|
+
: plainText(toolOrCall || '(unknown tool)');
|
|
59
|
+
const outcome = result.error
|
|
60
|
+
? `${result.error}${result.status ? ` (HTTP ${result.status})` : ''}`
|
|
61
|
+
: `${result.status}`;
|
|
62
|
+
return `[${time}] ${label} → ${outcome} ${result.ms}ms`;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Forwards the server's tool calls and sends back their results.
|
|
67
|
+
*
|
|
68
|
+
* Every call is answered exactly once. A result that can't be sent because the
|
|
69
|
+
* socket is down or the channel is rejoining is kept and sent after the rejoin,
|
|
70
|
+
* until the call's deadline (its timeout_ms from arrival); then it is dropped,
|
|
71
|
+
* because the server has stopped waiting for it.
|
|
72
|
+
*/
|
|
73
|
+
class ToolCallRelay {
|
|
74
|
+
/**
|
|
75
|
+
* @param {object} ctx - {wsClient, topic, origin, print, lookup, now,
|
|
76
|
+
* forwarded, onForward}. `forwarded` lists call ids an earlier run of
|
|
77
|
+
* this session already handed to the local server; `onForward(callId)`
|
|
78
|
+
* is called before each new call is forwarded, so it can be saved.
|
|
79
|
+
*/
|
|
80
|
+
constructor({ wsClient, topic, origin, print = false, lookup, now = Date.now, forwarded = [], onForward = null }) {
|
|
81
|
+
this.wsClient = wsClient;
|
|
82
|
+
this.topic = topic;
|
|
83
|
+
this.origin = origin;
|
|
84
|
+
this.print = print;
|
|
85
|
+
this.lookup = lookup;
|
|
86
|
+
this.now = now;
|
|
87
|
+
this.stopping = false;
|
|
88
|
+
// Every call_id and reply_ref this session has seen: a call is
|
|
89
|
+
// forwarded to the local server at most once.
|
|
90
|
+
this.seenCallIds = new Set(forwarded);
|
|
91
|
+
this.seenReplyRefs = new Set();
|
|
92
|
+
this.onForward = onForward;
|
|
93
|
+
// reply_ref -> {call, deadline, state: forwarding|sending|queued|answered, reply, timer, sending, controller}
|
|
94
|
+
this.inFlight = new Map();
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
canSend() {
|
|
98
|
+
const ws = this.wsClient;
|
|
99
|
+
return typeof ws.isJoined === 'function' ? ws.isJoined(this.topic) : true;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Handle one `tool_call`: forward it, then send `tool_result`.
|
|
104
|
+
* Never rejects.
|
|
105
|
+
* @param {object} call - tool_call payload
|
|
106
|
+
* @returns {Promise<object|null>} the forward result
|
|
107
|
+
*/
|
|
108
|
+
async handle(call) {
|
|
109
|
+
if (!call || typeof call !== 'object' || typeof call.reply_ref !== 'string') {
|
|
110
|
+
Logger.warning('Ignored a tool_call without a reply_ref');
|
|
111
|
+
return null;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// The same message again: the first copy answers it.
|
|
115
|
+
if (this.seenReplyRefs.has(call.reply_ref)) {
|
|
116
|
+
safely(() => Logger.warning(`Ignored a repeated tool_call for ${toolLabel(call)} (call ${call.call_id || '?'}); it was already forwarded.`));
|
|
117
|
+
return null;
|
|
118
|
+
}
|
|
119
|
+
remember(this.seenReplyRefs, call.reply_ref);
|
|
120
|
+
|
|
121
|
+
// The same call under a new reply_ref: never forward it twice. Answer
|
|
122
|
+
// without sending it, so the server doesn't wait for nothing.
|
|
123
|
+
if (typeof call.call_id === 'string' && call.call_id !== '') {
|
|
124
|
+
if (this.seenCallIds.has(call.call_id)) {
|
|
125
|
+
safely(() => Logger.warning(`Not forwarding ${toolLabel(call)} (call ${call.call_id}) again: this session already forwarded it once. Sent connection_failed.`));
|
|
126
|
+
const entry = this.track(call);
|
|
127
|
+
await this.send(entry, { reply_ref: call.reply_ref, error: 'connection_failed' });
|
|
128
|
+
return { status: 0, body: null, error: 'connection_failed', message: 'Repeated call, not forwarded', ms: 0, repeated: true };
|
|
129
|
+
}
|
|
130
|
+
remember(this.seenCallIds, call.call_id);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
const entry = this.track(call);
|
|
134
|
+
|
|
135
|
+
if (this.stopping) {
|
|
136
|
+
// Not forwarded, so answered as refused: ModelRiver then records the
|
|
137
|
+
// call as not sent. connection_failed would mean "sent, no answer",
|
|
138
|
+
// which for a tool that changes something is recorded as unknown.
|
|
139
|
+
const result = { status: 0, body: null, error: 'target_refused', message: 'The CLI is stopping', ms: 0 };
|
|
140
|
+
await this.send(entry, { reply_ref: call.reply_ref, error: 'target_refused' });
|
|
141
|
+
return result;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
if (this.print) {
|
|
145
|
+
safely(() => {
|
|
146
|
+
Logger.log(`\n→ ${toolLabel(call)} POST ${plainText(call.path)} (call ${plainText(call.call_id || '?')})`);
|
|
147
|
+
Logger.log(` Arguments: ${formatBody(call.body)}`);
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
// Saved before the call leaves, so a CLI restarted on this session
|
|
152
|
+
// knows it went out and never forwards it again.
|
|
153
|
+
if (this.onForward && typeof call.call_id === 'string' && call.call_id !== '') {
|
|
154
|
+
safely(() => this.onForward(call.call_id));
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
let result;
|
|
158
|
+
try {
|
|
159
|
+
result = await forwardToolCall(call, { origin: this.origin, lookup: this.lookup, signal: entry.controller.signal });
|
|
160
|
+
} catch (error) {
|
|
161
|
+
result = { status: 0, body: null, error: 'connection_failed', message: error.message, ms: 0 };
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// Ctrl+C already answered this call.
|
|
165
|
+
if (entry.state === 'answered') return result;
|
|
166
|
+
|
|
167
|
+
safely(() => this.logResult(call, result));
|
|
168
|
+
|
|
169
|
+
// The server takes either {reply_ref, status, body} or {reply_ref, error}.
|
|
170
|
+
const reply = result.error
|
|
171
|
+
? { reply_ref: call.reply_ref, error: result.error }
|
|
172
|
+
: { reply_ref: call.reply_ref, status: result.status, body: result.body };
|
|
173
|
+
|
|
174
|
+
await this.send(entry, reply);
|
|
175
|
+
return result;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/** Start tracking a call until it is answered. */
|
|
179
|
+
track(call) {
|
|
180
|
+
const entry = {
|
|
181
|
+
call,
|
|
182
|
+
deadline: this.now() + callTimeoutMs(call),
|
|
183
|
+
state: 'forwarding',
|
|
184
|
+
reply: null,
|
|
185
|
+
timer: null,
|
|
186
|
+
sending: null,
|
|
187
|
+
// Ctrl+C (or a takeover) aborts the local request through this.
|
|
188
|
+
controller: new AbortController(),
|
|
189
|
+
};
|
|
190
|
+
this.inFlight.set(call.reply_ref, entry);
|
|
191
|
+
return entry;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
logResult(call, result) {
|
|
195
|
+
const line = describeResult(call, result);
|
|
196
|
+
if (result.error) {
|
|
197
|
+
Logger.error(line);
|
|
198
|
+
} else if (result.status >= 200 && result.status < 300) {
|
|
199
|
+
Logger.success(line);
|
|
200
|
+
} else {
|
|
201
|
+
Logger.warning(line);
|
|
202
|
+
}
|
|
203
|
+
if (result.message) Logger.log(` ${plainText(result.message)}`);
|
|
204
|
+
// A local timeout: the server may have done the work without answering.
|
|
205
|
+
if (result.error === 'timeout') warnMayHaveRun(call);
|
|
206
|
+
|
|
207
|
+
if (this.print && result.body !== null && result.body !== undefined) {
|
|
208
|
+
Logger.log(` Result: ${formatBody(result.body)}`);
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Ctrl+C stopped a call before the local server answered.
|
|
214
|
+
*/
|
|
215
|
+
warnStopped(call, replied = true) {
|
|
216
|
+
Logger.warning(` Stopped ${toolLabel(call)} (call ${call.call_id || '?'}) before your server answered${replied ? '; sent connection_failed' : ''}.`);
|
|
217
|
+
warnMayHaveRun(call);
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* Another connection took over the session: abort every local request
|
|
222
|
+
* still open (its channel is gone, so nothing is sent back) and say which
|
|
223
|
+
* calls may already have run.
|
|
224
|
+
*/
|
|
225
|
+
abortInFlight() {
|
|
226
|
+
this.stopping = true;
|
|
227
|
+
for (const entry of [...this.inFlight.values()]) {
|
|
228
|
+
clearTimeout(entry.timer);
|
|
229
|
+
const forwarding = entry.state === 'forwarding';
|
|
230
|
+
entry.state = 'answered';
|
|
231
|
+
this.inFlight.delete(entry.call.reply_ref);
|
|
232
|
+
if (forwarding) {
|
|
233
|
+
entry.controller.abort();
|
|
234
|
+
safely(() => this.warnStopped(entry.call, false));
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* Send a reply now, or keep it for after the rejoin.
|
|
241
|
+
*/
|
|
242
|
+
async send(entry, reply) {
|
|
243
|
+
entry.reply = reply;
|
|
244
|
+
if (entry.state === 'answered') return;
|
|
245
|
+
if (!this.canSend()) {
|
|
246
|
+
this.queue(entry);
|
|
247
|
+
return;
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
entry.state = 'sending';
|
|
251
|
+
entry.sending = this.wsClient.push(this.topic, 'tool_result', reply, { timeoutMs: RESULT_PUSH_TIMEOUT_MS });
|
|
252
|
+
try {
|
|
253
|
+
// {status: "received"}, or {status: "already_answered"} when ModelRiver
|
|
254
|
+
// already took a result for this call (a copy sent before a reconnect
|
|
255
|
+
// got there first). Either way the call is done.
|
|
256
|
+
await entry.sending;
|
|
257
|
+
this.complete(entry);
|
|
258
|
+
} catch (error) {
|
|
259
|
+
if (entry.state === 'answered') return;
|
|
260
|
+
const reason = refusalReason(error);
|
|
261
|
+
if (reason === 'unknown_reply_ref') {
|
|
262
|
+
// The call is no longer waiting: it timed out, or was never sent to
|
|
263
|
+
// this session. Sending again can't help, so this is final.
|
|
264
|
+
Logger.log(` ModelRiver is no longer waiting for the result of ${entry.call.tool || 'this call'} (it timed out, or was not sent to this session).`);
|
|
265
|
+
this.complete(entry);
|
|
266
|
+
return;
|
|
267
|
+
}
|
|
268
|
+
const lostConnection = (error && error.reason === 'disconnected') || reason === 'unmatched topic';
|
|
269
|
+
if (lostConnection || !this.canSend()) {
|
|
270
|
+
// The socket closed (or the channel is rejoining) before the server
|
|
271
|
+
// replied; send it again once the channel is back.
|
|
272
|
+
if (this.canSend() && reason !== 'unmatched topic' && !entry.retriedAtOnce) {
|
|
273
|
+
entry.retriedAtOnce = true;
|
|
274
|
+
await this.send(entry, reply);
|
|
275
|
+
} else {
|
|
276
|
+
this.queue(entry);
|
|
277
|
+
}
|
|
278
|
+
return;
|
|
279
|
+
}
|
|
280
|
+
Logger.warning(` The server did not accept the result for ${entry.call.tool || 'this call'}: ${error.message}`);
|
|
281
|
+
this.complete(entry);
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
queue(entry) {
|
|
286
|
+
const left = entry.deadline - this.now();
|
|
287
|
+
if (left <= 0) {
|
|
288
|
+
this.drop(entry);
|
|
289
|
+
return;
|
|
290
|
+
}
|
|
291
|
+
if (entry.state !== 'queued') {
|
|
292
|
+
Logger.warning(` Not connected; the result for ${entry.call.tool || 'this call'} will be sent after reconnecting.`);
|
|
293
|
+
}
|
|
294
|
+
entry.state = 'queued';
|
|
295
|
+
clearTimeout(entry.timer);
|
|
296
|
+
entry.timer = setTimeout(() => this.drop(entry), left);
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
drop(entry) {
|
|
300
|
+
if (entry.state === 'answered') return;
|
|
301
|
+
Logger.error(` Dropped the result for ${entry.call.tool || 'this call'}: not reconnected before its ${callTimeoutMs(entry.call)}ms deadline.`);
|
|
302
|
+
this.complete(entry);
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
complete(entry) {
|
|
306
|
+
clearTimeout(entry.timer);
|
|
307
|
+
entry.state = 'answered';
|
|
308
|
+
if (this.inFlight.get(entry.call.reply_ref) === entry) {
|
|
309
|
+
this.inFlight.delete(entry.call.reply_ref);
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/**
|
|
314
|
+
* The channel is joined again: send every result that was kept.
|
|
315
|
+
* @returns {Promise<void>}
|
|
316
|
+
*/
|
|
317
|
+
flush() {
|
|
318
|
+
const queued = [...this.inFlight.values()].filter((entry) => entry.state === 'queued');
|
|
319
|
+
return Promise.all(queued.map((entry) => {
|
|
320
|
+
clearTimeout(entry.timer);
|
|
321
|
+
return this.send(entry, entry.reply);
|
|
322
|
+
})).then(() => undefined);
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* Ctrl+C: answer what is still open, best effort, within capMs. Calls still
|
|
327
|
+
* being forwarded have their local request aborted and get
|
|
328
|
+
* {error: "connection_failed"}; kept results are sent.
|
|
329
|
+
* @param {number} [capMs]
|
|
330
|
+
* @returns {Promise<void>}
|
|
331
|
+
*/
|
|
332
|
+
async shutdown(capMs = SHUTDOWN_REPLY_CAP_MS) {
|
|
333
|
+
this.stopping = true;
|
|
334
|
+
const waits = [];
|
|
335
|
+
for (const entry of [...this.inFlight.values()]) {
|
|
336
|
+
if (entry.state === 'answered') continue;
|
|
337
|
+
if (entry.state === 'sending') {
|
|
338
|
+
waits.push(entry.sending);
|
|
339
|
+
continue;
|
|
340
|
+
}
|
|
341
|
+
const forwarding = entry.state === 'forwarding';
|
|
342
|
+
const reply = forwarding
|
|
343
|
+
? { reply_ref: entry.call.reply_ref, error: 'connection_failed' }
|
|
344
|
+
: entry.reply;
|
|
345
|
+
clearTimeout(entry.timer);
|
|
346
|
+
entry.state = 'answered';
|
|
347
|
+
this.inFlight.delete(entry.call.reply_ref);
|
|
348
|
+
if (forwarding) {
|
|
349
|
+
// Stop the local request first, so nothing more is read from it.
|
|
350
|
+
entry.controller.abort();
|
|
351
|
+
safely(() => this.warnStopped(entry.call));
|
|
352
|
+
}
|
|
353
|
+
if (this.canSend()) {
|
|
354
|
+
waits.push(this.wsClient.push(this.topic, 'tool_result', reply, { timeoutMs: capMs }));
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
if (waits.length === 0) return;
|
|
358
|
+
|
|
359
|
+
let timer;
|
|
360
|
+
await Promise.race([
|
|
361
|
+
Promise.allSettled(waits),
|
|
362
|
+
new Promise((resolve) => { timer = setTimeout(resolve, capMs); }),
|
|
363
|
+
]);
|
|
364
|
+
clearTimeout(timer);
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* Say that a call which got no answer may still have run on the local
|
|
370
|
+
* server, unless the server says the tool only reads.
|
|
371
|
+
*/
|
|
372
|
+
function warnMayHaveRun(call) {
|
|
373
|
+
if (call.effect === 'write') {
|
|
374
|
+
Logger.warning(' This tool changes something: the call may already have run on your server. ' +
|
|
375
|
+
'ModelRiver records its outcome as unknown and never sends it again.');
|
|
376
|
+
} else if (call.effect !== 'read') {
|
|
377
|
+
// No effect from the server (older servers): it may be either kind.
|
|
378
|
+
Logger.warning(' If this tool changes something, the call may already have run on your server. ' +
|
|
379
|
+
'ModelRiver records its outcome as unknown and never sends it again.');
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
/** Add to a bounded set, forgetting the oldest entry when full. */
|
|
384
|
+
function remember(set, value) {
|
|
385
|
+
set.add(value);
|
|
386
|
+
if (set.size > SEEN_LIMIT) set.delete(set.values().next().value);
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
function safely(fn) {
|
|
390
|
+
try {
|
|
391
|
+
fn();
|
|
392
|
+
} catch (error) {
|
|
393
|
+
// Output must never stop a reply from being sent.
|
|
394
|
+
}
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
/**
|
|
398
|
+
* Why ModelRiver refused to (re)join the tool session, for people. The
|
|
399
|
+
* channel answers `unauthorized` for every reason, so all of them are named.
|
|
400
|
+
* @param {Error} error - from join()
|
|
401
|
+
* @returns {string|null} null when the join failed some other way
|
|
402
|
+
*/
|
|
403
|
+
function joinRefusedHint(error) {
|
|
404
|
+
if (refusalReason(error) !== 'unauthorized') return null;
|
|
405
|
+
return 'ModelRiver refused the tool session: hosted tools are turned off for this organization, ' +
|
|
406
|
+
'or the session has expired or belongs to another API key. ' +
|
|
407
|
+
'Run "modelriver tools" again; if it is refused again, ask for hosted tools to be turned on.';
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
/** The `reason` from a refused push's reply, if there is one. */
|
|
411
|
+
function refusalReason(error) {
|
|
412
|
+
const response = error && error.reply && error.reply.response;
|
|
413
|
+
return response && typeof response === 'object' ? response.reason : undefined;
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
/**
|
|
417
|
+
* Handle one `tool_call` with a one-off relay (used by tests).
|
|
418
|
+
* @param {object} call - tool_call payload
|
|
419
|
+
* @param {object} ctx - {wsClient, topic, origin, print, lookup}
|
|
420
|
+
* @returns {Promise<object|null>} the forward result
|
|
421
|
+
*/
|
|
422
|
+
function handleToolCall(call, ctx) {
|
|
423
|
+
return new ToolCallRelay(ctx).handle(call);
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/**
|
|
427
|
+
* The API key `tools` may use: --api-key, MODELRIVER_API_KEY or
|
|
428
|
+
* ~/.modelriver/config.json. Never a .modelriverrc in the current directory:
|
|
429
|
+
* a cloned repository could plant another account's key there, and that
|
|
430
|
+
* account could then send POST requests to servers on your machine.
|
|
431
|
+
*
|
|
432
|
+
* @param {string} [flagKey] - --api-key
|
|
433
|
+
* @param {object} [cfg] - Config instance
|
|
434
|
+
* @returns {{apiKey: string, source: string, ignoredLocalKey: boolean}}
|
|
435
|
+
*/
|
|
436
|
+
function resolveApiKey(flagKey, cfg = config) {
|
|
437
|
+
const localKey = cfg.getLocalRcApiKey();
|
|
438
|
+
if (flagKey) return { apiKey: flagKey, source: '--api-key', ignoredLocalKey: Boolean(localKey) };
|
|
439
|
+
|
|
440
|
+
const trusted = cfg.getTrustedApiKey();
|
|
441
|
+
if (trusted) return { apiKey: trusted.key, source: trusted.source, ignoredLocalKey: Boolean(localKey) };
|
|
442
|
+
|
|
443
|
+
if (localKey) {
|
|
444
|
+
throw new Error(
|
|
445
|
+
`"modelriver tools" does not use the API key in ${cfg.getLocalRcPath()}.\n` +
|
|
446
|
+
'A .modelriverrc can come with any repository you clone, and its key decides which account ' +
|
|
447
|
+
'sends tool calls to servers on this machine. Pass your own key with --api-key, set ' +
|
|
448
|
+
'MODELRIVER_API_KEY, or run "modelriver login".'
|
|
449
|
+
);
|
|
450
|
+
}
|
|
451
|
+
throw new Error('API key is required. Set MODELRIVER_API_KEY, use --api-key, or run "modelriver login".');
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
// setTimeout can't wait longer than this (about 24.8 days).
|
|
455
|
+
const MAX_TIMER_MS = 2 ** 31 - 1;
|
|
456
|
+
|
|
457
|
+
/**
|
|
458
|
+
* Call onExpired once expiresAt has passed.
|
|
459
|
+
* @param {string} expiresAt - ISO 8601 time
|
|
460
|
+
* @param {Function} onExpired
|
|
461
|
+
* @param {object} [options] - {now} for tests
|
|
462
|
+
* @returns {Function|null} cancel, or null when expiresAt can't be read
|
|
463
|
+
*/
|
|
464
|
+
function watchExpiry(expiresAt, onExpired, { now = Date.now } = {}) {
|
|
465
|
+
const at = Date.parse(expiresAt);
|
|
466
|
+
if (!Number.isFinite(at)) return null;
|
|
467
|
+
let timer = null;
|
|
468
|
+
const check = () => {
|
|
469
|
+
const left = at - now();
|
|
470
|
+
if (left <= 0) {
|
|
471
|
+
timer = null;
|
|
472
|
+
onExpired();
|
|
473
|
+
return;
|
|
474
|
+
}
|
|
475
|
+
timer = setTimeout(check, Math.min(left, MAX_TIMER_MS));
|
|
476
|
+
};
|
|
477
|
+
check();
|
|
478
|
+
return () => clearTimeout(timer);
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
/**
|
|
482
|
+
* modelriver tools --forward-to <url> [--print]
|
|
483
|
+
*
|
|
484
|
+
* Opens a CLI tool session and forwards each tool call the server sends for
|
|
485
|
+
* it to a server on this machine.
|
|
486
|
+
*/
|
|
487
|
+
async function toolsCommand(options) {
|
|
488
|
+
const { apiUrl, forwardTo, print, verbose, newSession } = options;
|
|
489
|
+
|
|
490
|
+
let apiKey;
|
|
491
|
+
try {
|
|
492
|
+
const resolved = resolveApiKey(options.apiKey);
|
|
493
|
+
apiKey = resolved.apiKey;
|
|
494
|
+
if (resolved.ignoredLocalKey) {
|
|
495
|
+
Logger.warning(`> Ignoring the API key in ${config.getLocalRcPath()}; "modelriver tools" uses ${resolved.source}.`);
|
|
496
|
+
}
|
|
497
|
+
} catch (error) {
|
|
498
|
+
Logger.error(error.message);
|
|
499
|
+
process.exit(1);
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
// Check the target before touching the network.
|
|
503
|
+
let target;
|
|
504
|
+
try {
|
|
505
|
+
target = parseForwardTarget(forwardTo);
|
|
506
|
+
await resolveLoopback(target.hostname);
|
|
507
|
+
} catch (error) {
|
|
508
|
+
Logger.error(error.message);
|
|
509
|
+
if (error instanceof ForwardTargetError) {
|
|
510
|
+
Logger.warning('> Tool calls are only forwarded to this machine: localhost, 127.0.0.0/8 or ::1.');
|
|
511
|
+
Logger.warning('> Example: modelriver tools --forward-to http://localhost:3000');
|
|
512
|
+
}
|
|
513
|
+
process.exit(1);
|
|
514
|
+
}
|
|
515
|
+
|
|
516
|
+
if (target.ignoredPath) {
|
|
517
|
+
Logger.warning(`> Only the origin of --forward-to is used (${target.origin}); each call keeps the path of the tool's endpoint URL.`);
|
|
518
|
+
}
|
|
519
|
+
|
|
520
|
+
const spinner = Logger.spinner('Connecting to ModelRiver...');
|
|
521
|
+
spinner.start();
|
|
522
|
+
|
|
523
|
+
let wsClient;
|
|
524
|
+
let started = false;
|
|
525
|
+
const fail = (message) => {
|
|
526
|
+
Logger.error(message);
|
|
527
|
+
if (wsClient) wsClient.close();
|
|
528
|
+
process.exit(1);
|
|
529
|
+
};
|
|
530
|
+
|
|
531
|
+
try {
|
|
532
|
+
const apiClient = new ApiClient(apiKey, apiUrl);
|
|
533
|
+
if (verbose) apiClient.verbose = true;
|
|
534
|
+
|
|
535
|
+
const connectResponse = await apiClient.connectCLI();
|
|
536
|
+
|
|
537
|
+
// A session this machine opened earlier for the same API key and local
|
|
538
|
+
// server is joined again, so requests that name it keep working after a
|
|
539
|
+
// restart. Its token stays in the config folder and is never printed.
|
|
540
|
+
const store = new ToolSessionStore();
|
|
541
|
+
const storeKey = ToolSessionStore.keyFor({ apiUrl: apiClient.apiUrl, apiKey, origin: target.origin });
|
|
542
|
+
let saved = null;
|
|
543
|
+
if (!newSession) {
|
|
544
|
+
try {
|
|
545
|
+
saved = store.load(storeKey);
|
|
546
|
+
} catch (error) {
|
|
547
|
+
saved = null;
|
|
548
|
+
}
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
let session = null;
|
|
552
|
+
let reused = false;
|
|
553
|
+
if (!saved) {
|
|
554
|
+
spinner.text = 'Opening tool session...';
|
|
555
|
+
session = await apiClient.createToolSession();
|
|
556
|
+
}
|
|
557
|
+
|
|
558
|
+
spinner.text = 'Connecting to WebSocket...';
|
|
559
|
+
wsClient = new CLIWebSocketClient(connectResponse.websocket_url, connectResponse.ws_token, Boolean(verbose), {
|
|
560
|
+
// Each reconnect needs a fresh token; the tool session stays the same.
|
|
561
|
+
refreshToken: () => apiClient.connectCLI(),
|
|
562
|
+
maxReconnectAttempts: Infinity,
|
|
563
|
+
});
|
|
564
|
+
await wsClient.connect();
|
|
565
|
+
|
|
566
|
+
// The session whose record this CLI may change in the session file.
|
|
567
|
+
let ownSessionId = saved ? saved.session_id : session.session_id;
|
|
568
|
+
let warnedNotSaved = false;
|
|
569
|
+
const relay = new ToolCallRelay({
|
|
570
|
+
wsClient,
|
|
571
|
+
// The topic holds the session's database ID; the cts_ token is only
|
|
572
|
+
// sent in the join params, which the server checks.
|
|
573
|
+
topic: saved ? saved.channel : session.channel,
|
|
574
|
+
origin: target.origin,
|
|
575
|
+
print,
|
|
576
|
+
forwarded: saved ? saved.forwarded : [],
|
|
577
|
+
onForward: (callId) => {
|
|
578
|
+
try {
|
|
579
|
+
store.addForwarded(storeKey, callId, ownSessionId);
|
|
580
|
+
} catch (error) {
|
|
581
|
+
if (!warnedNotSaved) {
|
|
582
|
+
warnedNotSaved = true;
|
|
583
|
+
Logger.warning(`> Could not record forwarded calls in ${store.file} (${error.message}). A restarted CLI won't know about calls this one forwarded.`);
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
},
|
|
587
|
+
});
|
|
588
|
+
|
|
589
|
+
// Subscribe before joining: the server may send a tool_call right behind
|
|
590
|
+
// the join reply, and it would be lost if nobody listened yet. Only calls
|
|
591
|
+
// on this session's topic are handled.
|
|
592
|
+
wsClient.on('tool_call', (call, callTopic) => {
|
|
593
|
+
if (relay.topic === null || callTopic !== relay.topic) return;
|
|
594
|
+
relay.handle(call);
|
|
595
|
+
});
|
|
596
|
+
|
|
597
|
+
if (saved) {
|
|
598
|
+
spinner.text = 'Rejoining your tool session...';
|
|
599
|
+
try {
|
|
600
|
+
await wsClient.join(saved.channel, { session_token: saved.session_id });
|
|
601
|
+
session = saved;
|
|
602
|
+
reused = true;
|
|
603
|
+
} catch (error) {
|
|
604
|
+
// "unauthorized": the session expired or was removed, or hosted tools
|
|
605
|
+
// was turned off. Anything else (a timeout) is a real failure.
|
|
606
|
+
if (refusalReason(error) !== 'unauthorized') throw error;
|
|
607
|
+
relay.topic = null;
|
|
608
|
+
spinner.stop();
|
|
609
|
+
Logger.warning(`> The saved tool session (${maskSessionToken(saved.session_id)}) can no longer be joined; opening a new one. Requests that named the old session need the new ID.`);
|
|
610
|
+
spinner.start();
|
|
611
|
+
spinner.text = 'Opening tool session...';
|
|
612
|
+
session = await apiClient.createToolSession();
|
|
613
|
+
// Forgotten only once a new session exists. If opening one fails too
|
|
614
|
+
// (hosted tools is off for the organization, say), the saved session
|
|
615
|
+
// is kept, so it can be rejoined when that is put right.
|
|
616
|
+
// Only if it is still the one this CLI tried: another CLI with
|
|
617
|
+
// --new-session may have saved a newer one under the same key.
|
|
618
|
+
try { store.remove(storeKey, saved.session_id); } catch (removeError) { /* nothing saved to remove */ }
|
|
619
|
+
ownSessionId = session.session_id;
|
|
620
|
+
relay.topic = session.channel;
|
|
621
|
+
relay.seenCallIds.clear();
|
|
622
|
+
}
|
|
623
|
+
}
|
|
624
|
+
const topic = session.channel;
|
|
625
|
+
|
|
626
|
+
// Results kept while disconnected go out once the channel is back.
|
|
627
|
+
wsClient.onClient('rejoin', (rejoined) => {
|
|
628
|
+
if (rejoined === topic) relay.flush();
|
|
629
|
+
});
|
|
630
|
+
|
|
631
|
+
// A close the client won't recover from (e.g. the server closed with
|
|
632
|
+
// code 1000) would otherwise leave the CLI "active" on a dead socket.
|
|
633
|
+
wsClient.onClient('close', (code, reason, willReconnect) => {
|
|
634
|
+
if (willReconnect || wsClient.closing || !started) return;
|
|
635
|
+
fail(`The server closed the connection (code ${code}${reason ? `: ${reason}` : ''}). Run "modelriver tools" again for a new session.`);
|
|
636
|
+
});
|
|
637
|
+
|
|
638
|
+
wsClient.onClient('reconnect_failed', () => {
|
|
639
|
+
fail('Could not reconnect to ModelRiver. Run "modelriver tools" again for a new session.');
|
|
640
|
+
});
|
|
641
|
+
|
|
642
|
+
wsClient.onClient('rejoin_error', (failedTopic, error) => {
|
|
643
|
+
if (failedTopic !== topic) return;
|
|
644
|
+
if (refusalReason(error) === 'unauthorized') {
|
|
645
|
+
try { store.remove(storeKey, session.session_id); } catch (removeError) { /* nothing saved to remove */ }
|
|
646
|
+
}
|
|
647
|
+
fail(joinRefusedHint(error) ||
|
|
648
|
+
`Could not rejoin the tool session (${error.message}). It may have expired; run "modelriver tools" again.`);
|
|
649
|
+
});
|
|
650
|
+
|
|
651
|
+
// One socket per session: when another connection joins this session,
|
|
652
|
+
// the server pushes `replaced` to this one and closes its channel. Stop,
|
|
653
|
+
// rather than rejoin and fight the newer connection for the session.
|
|
654
|
+
wsClient.on('replaced', (_payload, replacedTopic) => {
|
|
655
|
+
if (replacedTopic !== topic) return;
|
|
656
|
+
relay.abortInFlight();
|
|
657
|
+
fail('Another connection took over this tool session (another "modelriver tools" using the same session). ' +
|
|
658
|
+
'Tool calls now go there, so this one has stopped.');
|
|
659
|
+
});
|
|
660
|
+
|
|
661
|
+
wsClient.onClient('channel_close', (closedTopic) => {
|
|
662
|
+
if (closedTopic !== topic) return;
|
|
663
|
+
fail('The server closed the tool session. Run "modelriver tools" again for a new one.');
|
|
664
|
+
});
|
|
665
|
+
|
|
666
|
+
if (!reused) {
|
|
667
|
+
spinner.text = 'Joining tool channel...';
|
|
668
|
+
// join() keeps the params, so a rejoin after a reconnect sends them again.
|
|
669
|
+
await wsClient.join(topic, { session_token: session.session_id });
|
|
670
|
+
try {
|
|
671
|
+
// With the calls forwarded so far: one can arrive right behind the
|
|
672
|
+
// join, before this line runs.
|
|
673
|
+
store.save(storeKey, session, [...relay.seenCallIds]);
|
|
674
|
+
} catch (error) {
|
|
675
|
+
spinner.stop();
|
|
676
|
+
Logger.warning(`> Could not save the session in ${store.file} (${error.message}). A restarted CLI will open a new session.`);
|
|
677
|
+
spinner.start();
|
|
678
|
+
}
|
|
679
|
+
}
|
|
680
|
+
started = true;
|
|
681
|
+
// A result that was ready before the join was complete goes out now.
|
|
682
|
+
relay.flush();
|
|
683
|
+
|
|
684
|
+
spinner.succeed('Tool forwarding active');
|
|
685
|
+
|
|
686
|
+
if (reused) {
|
|
687
|
+
// Never printed in full again: it was shown once, when it was opened.
|
|
688
|
+
Logger.success(`\n> Session: ${maskSessionToken(session.session_id)} (rejoined: the session this machine already had)`);
|
|
689
|
+
} else {
|
|
690
|
+
Logger.success(`\n> Session: ${session.session_id}`);
|
|
691
|
+
}
|
|
692
|
+
if (session.project_id) {
|
|
693
|
+
Logger.info(`> Project: ${session.project_id}`);
|
|
694
|
+
}
|
|
695
|
+
if (session.expires_at) {
|
|
696
|
+
Logger.info(`> Expires: ${session.expires_at}`);
|
|
697
|
+
}
|
|
698
|
+
Logger.info(`> Forwarding tool calls to ${target.origin}`);
|
|
699
|
+
if (reused) {
|
|
700
|
+
Logger.log('\nRequests that already name this session in "tool_route" keep working; calls waiting for approval');
|
|
701
|
+
Logger.log('are sent here once approved. The session ID was printed when the session was opened.');
|
|
702
|
+
Logger.log('For a new session (and a new ID), start again with --new-session.');
|
|
703
|
+
} else {
|
|
704
|
+
Logger.log('\nAdd this to a POST /v1/ai/async request to send its tool calls here:');
|
|
705
|
+
Logger.log(` "tool_route": {"cli_session": "${session.session_id}"}`);
|
|
706
|
+
Logger.log('Or send one and follow it (approvals included) from another terminal:');
|
|
707
|
+
Logger.log(` modelriver websocket -w <workflow> -m "..." --end-user <id> --cli-session ${session.session_id}`);
|
|
708
|
+
Logger.log('\nThe session ID works like a password while it is valid. Do not commit or share it.');
|
|
709
|
+
Logger.log(`It is saved in ${store.file} (readable only by you), so starting "modelriver tools" again with the`);
|
|
710
|
+
Logger.log('same API key and --forward-to rejoins this session.');
|
|
711
|
+
}
|
|
712
|
+
Logger.warning('> Press Ctrl+C to stop\n');
|
|
713
|
+
|
|
714
|
+
// At expires_at the session stops working; say so and stop rather than
|
|
715
|
+
// stay "active" on a dead session.
|
|
716
|
+
watchExpiry(session.expires_at, () => {
|
|
717
|
+
relay.abortInFlight();
|
|
718
|
+
fail(`This tool session expired (${session.expires_at}). Start "modelriver tools" again for a new session ID.`);
|
|
719
|
+
});
|
|
720
|
+
|
|
721
|
+
let stopping = false;
|
|
722
|
+
const cleanup = async () => {
|
|
723
|
+
if (stopping) process.exit(130); // second Ctrl+C: leave now
|
|
724
|
+
stopping = true;
|
|
725
|
+
Logger.warning('\n> Stopping tool forwarding...');
|
|
726
|
+
try {
|
|
727
|
+
await relay.shutdown();
|
|
728
|
+
} finally {
|
|
729
|
+
wsClient.close();
|
|
730
|
+
process.exit(0);
|
|
731
|
+
}
|
|
732
|
+
};
|
|
733
|
+
process.on('SIGINT', cleanup);
|
|
734
|
+
process.on('SIGTERM', cleanup);
|
|
735
|
+
} catch (error) {
|
|
736
|
+
spinner.fail('Failed to start tool forwarding');
|
|
737
|
+
Logger.error(error.message);
|
|
738
|
+
const joinHint = joinRefusedHint(error);
|
|
739
|
+
if (joinHint) {
|
|
740
|
+
Logger.warning(`> ${joinHint}`);
|
|
741
|
+
} else if (error.response?.status === 401) {
|
|
742
|
+
Logger.warning('> Check your API key (modelriver login, or --api-key).');
|
|
743
|
+
} else if (error.response?.status === 403 || error.response?.status === 404) {
|
|
744
|
+
Logger.warning('> Hosted tools may not be enabled for this project, or the server does not support CLI tool sessions yet.');
|
|
745
|
+
} else if (error.response?.status === 429) {
|
|
746
|
+
// Either the session limit, or ModelRiver's rate limiter (another body).
|
|
747
|
+
const body = error.response.data && typeof error.response.data === 'object' ? error.response.data : {};
|
|
748
|
+
if (body.error === 'too_many_cli_tool_sessions') {
|
|
749
|
+
Logger.warning('> You already have 5 connected tool sessions for this project. Stop one and try again.');
|
|
750
|
+
} else {
|
|
751
|
+
const retry = body.retry_after ?? error.response.headers?.['retry-after'];
|
|
752
|
+
Logger.warning(retry !== undefined && retry !== null
|
|
753
|
+
? `> Rate limited by ModelRiver. Try again in ${plainText(retry)} seconds.`
|
|
754
|
+
: '> Rate limited by ModelRiver. Try again shortly.');
|
|
755
|
+
}
|
|
756
|
+
}
|
|
757
|
+
if (wsClient) wsClient.close();
|
|
758
|
+
process.exit(1);
|
|
759
|
+
}
|
|
760
|
+
}
|
|
761
|
+
|
|
762
|
+
module.exports = { watchExpiry, toolsCommand, handleToolCall, describeResult, formatBody, toolLabel, resolveApiKey, ToolCallRelay };
|