toolmenu 0.16.0 → 0.17.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 +9 -2
- package/dist/auth.js +2 -1
- package/dist/auto.js +33 -2
- package/dist/breakdown.js +3 -31
- package/dist/catalog.d.ts +1 -1
- package/dist/catalog.js +4 -3
- package/dist/cli.js +42 -6
- package/dist/config.d.ts +9 -0
- package/dist/config.js +11 -0
- package/dist/connect.d.ts +1 -0
- package/dist/connect.js +46 -16
- package/dist/diff.js +51 -13
- package/dist/explain.d.ts +9 -4
- package/dist/explain.js +90 -25
- package/dist/failures.js +5 -4
- package/dist/help.js +2 -1
- package/dist/mrtr.d.ts +27 -6
- package/dist/mrtr.js +116 -37
- package/dist/options.d.ts +4 -0
- package/dist/options.js +1 -0
- package/dist/probe.d.ts +8 -0
- package/dist/probe.js +9 -1
- package/dist/report.js +2 -1
- package/dist/rules/gated.js +5 -5
- package/dist/rules/handles.d.ts +12 -0
- package/dist/rules/handles.js +88 -0
- package/dist/rules/headers.js +4 -4
- package/dist/rules/identities.d.ts +23 -0
- package/dist/rules/identities.js +84 -0
- package/dist/rules/index.js +5 -0
- package/dist/rules/refs.js +10 -78
- package/dist/rules/rule.d.ts +2 -0
- package/dist/rules/search.js +3 -2
- package/dist/rules/spec.js +2 -1
- package/dist/schema-ref.d.ts +35 -0
- package/dist/schema-ref.js +178 -0
- package/dist/search.d.ts +8 -0
- package/dist/search.js +4 -1
- package/dist/session.d.ts +17 -0
- package/dist/session.js +156 -66
- package/dist/snapshot.d.ts +10 -1
- package/dist/snapshot.js +20 -3
- package/package.json +1 -1
package/dist/explain.js
CHANGED
|
@@ -129,9 +129,9 @@ export function seconds(ms) {
|
|
|
129
129
|
return `${ms < 10_000 ? (Math.round(ms / 100) / 10).toFixed(1) : Math.round(ms / 1000)} s`;
|
|
130
130
|
}
|
|
131
131
|
/** The command line, for a message: arguments with spaces quoted, cut at 120 characters. Never the --env values. */
|
|
132
|
-
export function commandLine(command, args) {
|
|
132
|
+
export function commandLine(command, args, { cut = true } = {}) {
|
|
133
133
|
const quoted = [command, ...args].map((a) => (/^[\w@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)).join(' ');
|
|
134
|
-
return quoted.length > 120 ? `${quoted.slice(0, 119)}…` : quoted;
|
|
134
|
+
return cut && quoted.length > 120 ? `${quoted.slice(0, 119)}…` : quoted;
|
|
135
135
|
}
|
|
136
136
|
/** The stderr fact: the last lines, and a note of how many came before. */
|
|
137
137
|
export function stderrFact(trace) {
|
|
@@ -148,35 +148,96 @@ function strayFact(trace) {
|
|
|
148
148
|
return ['stdout', `${quoted}${more}`];
|
|
149
149
|
}
|
|
150
150
|
const LOG_TO_STDERR = 'Log to stderr; stdout carries the protocol (in Node, console.error rather than console.log; in Python, logging or print(..., file=sys.stderr)).';
|
|
151
|
-
// A CLI's usage: argparse, click, yargs, commander, System.CommandLine, stricli.
|
|
152
|
-
|
|
153
|
-
//
|
|
154
|
-
// "
|
|
155
|
-
const
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
151
|
+
// A CLI's usage: argparse, click, yargs, commander, System.CommandLine, stricli. Only
|
|
152
|
+
// where a line starts with it ("usage: x", "Usage: npx …") or a header stands alone on
|
|
153
|
+
// its line ("Options:", "Commands:", "USAGE"), so "memory usage 120MB" or a startup log
|
|
154
|
+
// "Options: {...}" isn't one.
|
|
155
|
+
const USAGE = [
|
|
156
|
+
/(?:^|\n)[ \t]*usage:[ \t]+\S/i,
|
|
157
|
+
/(?:^|\n)(?:USAGE|[ \t]*(?:usage|(?:sub)?commands|options|examples|flags):)[ \t]*(?=\n|$)/i,
|
|
158
|
+
/\s<command>|\[command\]|\bCOMMAND \[ARGS\]|arguments are required|subcommands? must be present|no command (?:specified|given)|required command was not provided|\b(?:run|see):? \S+ --help\b/i,
|
|
159
|
+
];
|
|
160
|
+
// A row of a command or option table: " serve Start the Poppy MCP server.",
|
|
161
|
+
// " t3-watch start Run the service", " -v, --version Show the version". A command
|
|
162
|
+
// starts lowercase, so a padded log level ("INFO Starting") isn't one.
|
|
163
|
+
const HELP_ROW = /^[ \t]*(?:[a-z][\w.-]*(?: [a-z][\w-]*)?(?: [[<][^\]>]*[\]>])*|-{1,2}[\w-]+(?:, -{1,2}[\w-]+)?(?: <[^>]+>)?) {2,}\S/;
|
|
164
|
+
/** Help output, even when the "Usage:" line scrolled out of the stderr kept: three table rows or more. */
|
|
165
|
+
const helpRows = (text) => text.split('\n').filter((l) => HELP_ROW.test(l)).length >= 3;
|
|
166
|
+
// The subcommands that usually start the MCP server, most specific first.
|
|
159
167
|
const SUBCOMMANDS = ['mcp start', 'mcp serve', 'server start', 'mcp', 'stdio', 'serve', 'server', 'start'];
|
|
160
168
|
// An HTTP server's address in its log: "MCP server listening on http://localhost:3001/mcp",
|
|
161
169
|
// "StreamableHTTP endpoint available at http://127.0.0.1:3333/mcp".
|
|
162
|
-
const HTTP_URL = /\b(?:listening|available|running|serving|started)\b[^\n]{0,60}?(https?:\/\/[^\s"'<>]+)/
|
|
170
|
+
const HTTP_URL = /\b(?:listening|available|running|serving|started)\b[^\n]{0,60}?(https?:\/\/[^\s"'<>]+)/gi;
|
|
163
171
|
const HTTP_PORT = /\blistening on (?:port )?:?(\d{2,5})\b/i;
|
|
172
|
+
/** An address the server itself listens on: loopback, all interfaces, or one with a port. A docs or release link isn't one. */
|
|
173
|
+
function ownAddress(raw) {
|
|
174
|
+
const url = raw.replace(/[.,;)]+$/, '');
|
|
175
|
+
try {
|
|
176
|
+
const u = new URL(url);
|
|
177
|
+
const local = /^(?:localhost|127\.\d+\.\d+\.\d+|0\.0\.0\.0|\[::1?\])$/.test(u.hostname);
|
|
178
|
+
return local || u.port ? url.replace('//0.0.0.0', '//localhost') : undefined;
|
|
179
|
+
}
|
|
180
|
+
catch {
|
|
181
|
+
return undefined;
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* Subcommands the help text offers where a command goes, and only there:
|
|
186
|
+
* - a `{a,b,mcp}` list (argparse);
|
|
187
|
+
* - the command column of a table row, the words before its two-space gap
|
|
188
|
+
* (" serve Start…", " server start Starts…", "t3-watch start Run…");
|
|
189
|
+
* - a usage line: one that starts "usage:", or the indented lines under a "Usage:" or
|
|
190
|
+
* "USAGE" header, up to the next blank line ("mcp start [--transport…]").
|
|
191
|
+
* Never a wrapped description line or a log line ("Error: server crashed").
|
|
192
|
+
*/
|
|
193
|
+
function offeredSubcommand(text) {
|
|
194
|
+
const offered = new Set();
|
|
195
|
+
const add = (words) => {
|
|
196
|
+
// The command, and the word after a program name in front of it.
|
|
197
|
+
for (const start of [0, 1])
|
|
198
|
+
for (const n of [1, 2])
|
|
199
|
+
if (words.length >= start + n)
|
|
200
|
+
offered.add(words.slice(start, start + n).join(' '));
|
|
201
|
+
};
|
|
202
|
+
for (const m of text.matchAll(/\{([^{}\n]*)\}/g))
|
|
203
|
+
for (const w of m[1].split(','))
|
|
204
|
+
offered.add(w.trim());
|
|
205
|
+
let inUsage = false;
|
|
206
|
+
for (const line of text.split('\n')) {
|
|
207
|
+
if (!line.trim()) {
|
|
208
|
+
inUsage = false;
|
|
209
|
+
continue;
|
|
210
|
+
}
|
|
211
|
+
if (/^\s*(?:usage:|USAGE)\s*$/i.test(line)) {
|
|
212
|
+
inUsage = true;
|
|
213
|
+
continue;
|
|
214
|
+
}
|
|
215
|
+
const usage = /^\s*usage:\s+(.*)$/i.exec(line);
|
|
216
|
+
// A command, maybe followed by its arguments ("server [options]", "serve <port>"), then the gap.
|
|
217
|
+
const row = /^[ \t]*([a-z][\w.-]*(?: [a-z][\w-]*)?)(?: [[<][^\]>]*[\]>])* {2,}\S/.exec(line);
|
|
218
|
+
const words = (usage ? usage[1] : inUsage ? line : row ? row[1] : '').trim().split(/\s+/).filter((w) => /^[a-z][\w.-]*$/.test(w));
|
|
219
|
+
if (words.length)
|
|
220
|
+
add(words.slice(0, 3));
|
|
221
|
+
}
|
|
222
|
+
return SUBCOMMANDS.find((c) => offered.has(c));
|
|
223
|
+
}
|
|
164
224
|
/**
|
|
165
225
|
* What the server's own output says about how it was started, as a next step: a
|
|
166
|
-
* CLI that printed its usage and wants a subcommand
|
|
167
|
-
* HTTP port instead of talking on stdio.
|
|
226
|
+
* CLI that printed its usage and wants a subcommand (only when it `exited`), or a
|
|
227
|
+
* server that opened an HTTP port instead of talking on stdio. `command` is the whole
|
|
228
|
+
* command line, uncut, so the suggestion can be run as written.
|
|
168
229
|
*/
|
|
169
|
-
export function startupHint(trace, command) {
|
|
230
|
+
export function startupHint(trace, command, { exited = true } = {}) {
|
|
170
231
|
const text = [...trace.strayHead, ...trace.stderrExcerpt().lines].join('\n');
|
|
171
|
-
const url = HTTP_URL.
|
|
232
|
+
const url = [...text.matchAll(HTTP_URL)].map((m) => ownAddress(m[1])).find(Boolean);
|
|
172
233
|
const port = url ? undefined : HTTP_PORT.exec(text)?.[1];
|
|
173
234
|
if (url || port) {
|
|
174
235
|
const flag = /--stdio\b/.test(text) ? '--stdio' : /--transport[ =]?(?:\[?stdio|<)/i.test(text) ? '--transport stdio' : undefined;
|
|
175
236
|
const where = url ?? `http://localhost:${port}/mcp`;
|
|
176
237
|
return `The server started an HTTP server (${where}) instead of talking on its stdin and stdout. Start it in stdio mode (${flag ? `its output mentions ${flag}` : 'often --stdio or --transport stdio'}), or run toolmenu against the address while the server runs: toolmenu snapshot ${where}`;
|
|
177
238
|
}
|
|
178
|
-
if (USAGE.test(text) ||
|
|
179
|
-
const sub =
|
|
239
|
+
if (exited && (USAGE.some((re) => re.test(text)) || helpRows(text))) {
|
|
240
|
+
const sub = offeredSubcommand(text);
|
|
180
241
|
return `The command printed its usage and exited: it wants a subcommand or an argument it wasn't given. ${sub ? `Its usage lists “${sub}”: try ${command} ${sub}` : 'Its usage (above) or its docs say what starts the MCP server: add that after the command.'}`;
|
|
181
242
|
}
|
|
182
243
|
return undefined;
|
|
@@ -283,6 +344,8 @@ function serverAnswered(error, stage, facts, next) {
|
|
|
283
344
|
}
|
|
284
345
|
function explainStdio(error, trace, context, target) {
|
|
285
346
|
const command = commandLine(target.command, target.args);
|
|
347
|
+
// Uncut: a suggestion has to run as written.
|
|
348
|
+
const whole = commandLine(target.command, target.args, { cut: false });
|
|
286
349
|
const spawnError = causes(error).find((e) => typeof e.syscall === 'string' && e.syscall.startsWith('spawn'));
|
|
287
350
|
if (spawnError) {
|
|
288
351
|
const code = spawnError.code;
|
|
@@ -330,7 +393,7 @@ function explainStdio(error, trace, context, target) {
|
|
|
330
393
|
else if (rejected) {
|
|
331
394
|
next = REJECTED_NEXT;
|
|
332
395
|
}
|
|
333
|
-
else if ((hint = startupHint(trace,
|
|
396
|
+
else if ((hint = startupHint(trace, whole, { exited: !!exit }))) {
|
|
334
397
|
next = hint;
|
|
335
398
|
}
|
|
336
399
|
else if (trace.strayCount) {
|
|
@@ -370,13 +433,15 @@ function explainStdio(error, trace, context, target) {
|
|
|
370
433
|
: rejected
|
|
371
434
|
? `${stage} timed out after ${seconds(waitedHere)}: the server is running but never answered; its stderr looks like rejected credentials (“${rejected}”).`
|
|
372
435
|
: `${stage} timed out after ${seconds(waitedHere)}: the server is running but never answered.`;
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
436
|
+
// Still running: no usage hint (that one is for a CLI that printed it and exited),
|
|
437
|
+
// and rejected credentials say more than an address in the log.
|
|
438
|
+
const hint = startupHint(trace, whole, { exited: false });
|
|
439
|
+
const next = rejected
|
|
440
|
+
? REJECTED_NEXT
|
|
441
|
+
: hint
|
|
442
|
+
? hint
|
|
443
|
+
: trace.strayCount
|
|
444
|
+
? LOG_TO_STDERR
|
|
380
445
|
: stage === 'tools/list'
|
|
381
446
|
? 'The server answered initialize, then hung on tools/list: check its logs (stderr above). If building the list is just slow, raise --timeout.'
|
|
382
447
|
: 'Check the command starts an MCP server on stdio (some need an argument such as "stdio" or "--stdio"). If it is only slow to start (npx downloading, a first build), raise --timeout.';
|
package/dist/failures.js
CHANGED
|
@@ -13,8 +13,9 @@ const CLIENT = /client capabilit(?:y|ies)\b[^.]{0,60}\b(?:do(?:es)? not|don't|do
|
|
|
13
13
|
// Something this machine lacks: "Could not find Google Chrome executable"
|
|
14
14
|
// (Chrome DevTools), "Chromium distribution 'chrome' is not found at" (Playwright),
|
|
15
15
|
// or the wrong operating system: "Editmamei runs on Windows and macOS; this process
|
|
16
|
-
// is on "linux"" (editmamei), "Unsupported platform: linux"
|
|
17
|
-
|
|
16
|
+
// is on "linux"" (editmamei), "Unsupported platform: linux" (an OS name, not any
|
|
17
|
+
// "platform" argument: "Unsupported platform: myspace" is the tool's own error).
|
|
18
|
+
const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bnot installed\b|command not found|cannot find (module|package)|\bENOENT\b|\bruns on [^.;]{0,40}; this (?:process|machine|system) is on\b|\bunsupported (?:platform|operating system|OS)(?:\s*[.!]?\s*$|\s*\.\s|[^.\n]{0,40}?\b(?:linux|darwin|macos|win32|windows(?:_nt)?|freebsd|openbsd|aix|sunos|android)(?![a-z]))|\bnot supported on (?:this|the current) (?:platform|operating system|OS)\b/i;
|
|
18
19
|
// "401 Bad credentials" (GitHub), "Authorization Expired" (Sentry), "Invalid
|
|
19
20
|
// token" (Firecrawl), "authentication token is not valid" (Apify), "Please provide
|
|
20
21
|
// a valid access token" (Supabase), "NetlifyUnauthError: You're not logged into
|
|
@@ -178,7 +179,7 @@ export const FAILURE_LABELS = {
|
|
|
178
179
|
environment: 'something missing on this machine',
|
|
179
180
|
network: 'the network',
|
|
180
181
|
'not-found': 'a 404 on a call that named nothing (usually the account or site behind the credentials)',
|
|
181
|
-
client: "a client
|
|
182
|
+
client: "a client capability the request didn't declare",
|
|
182
183
|
'invalid-arguments': 'the arguments',
|
|
183
184
|
other: 'other errors',
|
|
184
185
|
};
|
|
@@ -196,7 +197,7 @@ export function setupFailureAdvice(classes, transport) {
|
|
|
196
197
|
if (set.has('environment'))
|
|
197
198
|
steps.push('If something is missing on this machine (a browser, a binary, a module), install it where the server runs, or run the server in its own container image.');
|
|
198
199
|
if (set.has('client'))
|
|
199
|
-
steps.push("If a tool needs
|
|
200
|
+
steps.push("If a tool needs a client capability toolmenu doesn't declare (roots and sampling, which 2026-07-28 deprecates, or one the error names), those calls only checked that the menu stays put, and the server isn't at fault.");
|
|
200
201
|
if (set.has('network'))
|
|
201
202
|
steps.push('If the server calls an upstream API, check this machine can reach it (DNS, proxy, firewall).');
|
|
202
203
|
return { fix: steps.join(' ') || 'Check the quoted errors: they came from before the tool ran.', confidence: 'unsure' };
|
package/dist/help.js
CHANGED
|
@@ -18,6 +18,7 @@ const OPTIONS = {
|
|
|
18
18
|
header: ['--header "<k>: <v>"', ['HTTP header, repeatable (e.g. "Authorization: Bearer ...")']],
|
|
19
19
|
env: ['--env <K=V>', ['environment variable for a stdio server, repeatable. The server only', 'gets a minimal environment (PATH, HOME, ...) plus these']],
|
|
20
20
|
protocol: ['--protocol <auto|legacy|modern>', ['which handshake to make (default: auto)', 'legacy: the 2025 handshake only; modern: 2026-07-28 only, an error if the server lacks it']],
|
|
21
|
+
as: ['--as <name>[:<credential>]', ['list the menu as this identity too, repeatable: a header ("reader:Authorization:', 'Bearer ...") or env var ("admin:ROLE=admin") on top of --header/--env. The first', 'is the main one (its menu is saved); the others are compared with it']],
|
|
21
22
|
'no-auth': ['--no-auth', ["don't use a stored OAuth login (toolmenu auth login) for this server"]],
|
|
22
23
|
timeout: ['--timeout <ms>', ['per-request timeout (default: 30000)']],
|
|
23
24
|
processes: ['--processes <n>', ['server processes (stdio) or connections (HTTP) to compare, the main', 'one included (default: 2). 1 opens no second one: for servers with one', 'session per client']],
|
|
@@ -77,7 +78,7 @@ const HELP = {
|
|
|
77
78
|
'reports what in the menu confuses agents or breaks prompt caches.',
|
|
78
79
|
SERVER_NOTE,
|
|
79
80
|
],
|
|
80
|
-
own: ['out', 'no-write', 'routes', 'catalog'],
|
|
81
|
+
own: ['out', 'no-write', 'routes', 'catalog', 'as'],
|
|
81
82
|
shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
|
|
82
83
|
examples: [
|
|
83
84
|
'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
|
package/dist/mrtr.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { type Connection, type Elicitation } from './connect.js';
|
|
2
2
|
/** Rounds answered before toolmenu stops: a tool still asking after this is stuck. */
|
|
3
3
|
export declare const MAX_ROUNDS = 3;
|
|
4
|
+
/** Rounds that carry only requestState (the tool keeps working, asks nothing) before toolmenu stops. */
|
|
5
|
+
export declare const MAX_CONTINUATIONS = 10;
|
|
4
6
|
export type InputKind = 'form' | 'url' | 'roots' | 'sampling' | 'other';
|
|
5
7
|
export interface InputTrace {
|
|
6
8
|
/** input_required results answered. */
|
|
@@ -9,20 +11,39 @@ export interface InputTrace {
|
|
|
9
11
|
kinds: InputKind[];
|
|
10
12
|
/**
|
|
11
13
|
* none: it asked for nothing. completed: it answered after the decline(s).
|
|
12
|
-
* loop: it asked the same again after
|
|
13
|
-
* gave-up: still asking
|
|
14
|
+
* loop: it asked the same again after every decline, until the round limit.
|
|
15
|
+
* gave-up: still asking at the round limit, not always the same thing.
|
|
16
|
+
* unfinished: still returning requestState-only rounds (working, asking nothing)
|
|
17
|
+
* at MAX_CONTINUATIONS or after 3 × the request timeout in all.
|
|
14
18
|
* undeclared: it asked for something the request didn't declare (roots, sampling).
|
|
15
19
|
* decline-failed: the retry carrying the decline failed with a protocol error.
|
|
20
|
+
* bad-state: its requestState isn't a string, so it can't be echoed byte for byte;
|
|
21
|
+
* calling again without it would run the tool again from scratch.
|
|
16
22
|
*/
|
|
17
|
-
outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'undeclared' | 'decline-failed';
|
|
23
|
+
outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'unfinished' | 'undeclared' | 'decline-failed' | 'bad-state';
|
|
18
24
|
/** Kinds asked for that the request didn't declare. */
|
|
19
25
|
undeclared?: InputKind[];
|
|
20
|
-
/** The protocol error a retry failed with (decline-failed). */
|
|
21
|
-
error?:
|
|
26
|
+
/** The protocol error a retry failed with (decline-failed): the server's words, and its JSON-RPC code. */
|
|
27
|
+
error?: {
|
|
28
|
+
message: string;
|
|
29
|
+
code?: number;
|
|
30
|
+
};
|
|
31
|
+
/** Rounds that carried only requestState, the tool asking for nothing. */
|
|
32
|
+
continuations?: number;
|
|
22
33
|
/** A raw result on the wire without resultType, which 2026-07-28 servers MUST send. */
|
|
23
34
|
missingResultType?: boolean;
|
|
24
35
|
}
|
|
25
36
|
type CallResult = Awaited<ReturnType<Connection['client']['callTool']>>;
|
|
37
|
+
/**
|
|
38
|
+
* An error thrown after the tool already asked for input: it carries what the tool
|
|
39
|
+
* asked (session still reports it), and says the first leg ran on the server, so a
|
|
40
|
+
* tool that isn't read-only must not be called again from scratch.
|
|
41
|
+
*/
|
|
42
|
+
export declare class AfterInputError extends Error {
|
|
43
|
+
readonly cause: unknown;
|
|
44
|
+
readonly input: InputTrace;
|
|
45
|
+
constructor(cause: unknown, input: InputTrace);
|
|
46
|
+
}
|
|
26
47
|
/**
|
|
27
48
|
* Call a tool, answering any input it asks for. On a 2025-era connection it's a
|
|
28
49
|
* plain call (the SDK client's elicitation handler answers there). `result` is
|
package/dist/mrtr.js
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Multi round-trip requests (2026-07-28, SEP-2322). A tool that needs input
|
|
3
|
+
* answers tools/call with `resultType: "input_required"`, its `inputRequests`, and
|
|
4
|
+
* maybe a `requestState`; the client calls again with `inputResponses` and the
|
|
5
|
+
* `requestState` echoed byte for byte. toolmenu drives the rounds itself
|
|
6
|
+
* (allowInputRequired) so it can see them: every elicitation is declined (or
|
|
7
|
+
* cancelled, --elicitation cancel), no LLM, the same answer every run.
|
|
8
|
+
*/
|
|
9
|
+
import { canonical } from './compare.js';
|
|
10
|
+
import { quietExclusions } from './connect.js';
|
|
11
|
+
import { httpStatus, tooMany } from './failures.js';
|
|
1
12
|
/** Rounds answered before toolmenu stops: a tool still asking after this is stuck. */
|
|
2
13
|
export const MAX_ROUNDS = 3;
|
|
14
|
+
/** Rounds that carry only requestState (the tool keeps working, asks nothing) before toolmenu stops. */
|
|
15
|
+
export const MAX_CONTINUATIONS = 10;
|
|
3
16
|
const DECLARED = new Set(['form', 'url']);
|
|
4
17
|
function kindOf(request) {
|
|
5
18
|
if (request.method === 'elicitation/create')
|
|
@@ -10,15 +23,43 @@ function kindOf(request) {
|
|
|
10
23
|
return 'sampling';
|
|
11
24
|
return 'other';
|
|
12
25
|
}
|
|
13
|
-
/**
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
26
|
+
/**
|
|
27
|
+
* What a request asks, without its key: the same question under a new key each
|
|
28
|
+
* round reads the same. Its message counts, but not its counters, case or spacing:
|
|
29
|
+
* "Go ahead? (asked 2 times)" is "Go ahead? (asked 1 times)" again, while "Delete
|
|
30
|
+
* a.txt?" then "Delete b.txt?" are two questions with one form.
|
|
31
|
+
*/
|
|
32
|
+
function question(request) {
|
|
33
|
+
const p = request.params ?? {};
|
|
34
|
+
// A URL-mode request has no schema: the page it sends the user to is the question.
|
|
35
|
+
// Its path, not its query: a fresh ?state= each time is still the same page.
|
|
36
|
+
const page = p.mode === 'url' && typeof p.url === 'string' ? p.url.split(/[?#]/)[0] : undefined;
|
|
37
|
+
const message = typeof p.message === 'string' ? p.message.toLowerCase().replace(/\d+/g, '#').replace(/\s+/g, ' ').trim() : undefined;
|
|
38
|
+
return canonical({ method: request.method, mode: p.mode, requestedSchema: p.requestedSchema, url: page, message });
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* An error thrown after the tool already asked for input: it carries what the tool
|
|
42
|
+
* asked (session still reports it), and says the first leg ran on the server, so a
|
|
43
|
+
* tool that isn't read-only must not be called again from scratch.
|
|
44
|
+
*/
|
|
45
|
+
export class AfterInputError extends Error {
|
|
46
|
+
cause;
|
|
47
|
+
input;
|
|
48
|
+
constructor(cause, input) {
|
|
49
|
+
super(cause instanceof Error ? cause.message : String(cause));
|
|
50
|
+
this.cause = cause;
|
|
51
|
+
this.input = input;
|
|
52
|
+
const code = cause?.code;
|
|
53
|
+
if (code !== undefined)
|
|
54
|
+
this.code = code;
|
|
55
|
+
const status = cause?.status;
|
|
56
|
+
if (status !== undefined)
|
|
57
|
+
this.status = status;
|
|
19
58
|
}
|
|
20
|
-
return JSON.stringify(value);
|
|
21
59
|
}
|
|
60
|
+
/** The words of an error, first line only. */
|
|
61
|
+
const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split('\n')[0].trim();
|
|
62
|
+
const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
|
|
22
63
|
/**
|
|
23
64
|
* Call a tool, answering any input it asks for. On a 2025-era connection it's a
|
|
24
65
|
* plain call (the SDK client's elicitation handler answers there). `result` is
|
|
@@ -31,65 +72,103 @@ export async function callWithInput(conn, params, options) {
|
|
|
31
72
|
const kinds = [];
|
|
32
73
|
let missingResultType = false;
|
|
33
74
|
let previous;
|
|
34
|
-
|
|
75
|
+
// Whether any round asked something other than the round before: a loop asks the same every time.
|
|
76
|
+
let changed = false;
|
|
35
77
|
let rounds = 0;
|
|
78
|
+
let continuations = 0;
|
|
36
79
|
let call = { ...params };
|
|
80
|
+
// Whether the request being sent carries a decline (inputResponses), not just requestState.
|
|
81
|
+
let carriesDecline = false;
|
|
37
82
|
const trace = (outcome, more = {}) => ({
|
|
38
83
|
rounds,
|
|
39
84
|
kinds,
|
|
40
85
|
outcome,
|
|
86
|
+
...(continuations ? { continuations } : {}),
|
|
41
87
|
...(missingResultType ? { missingResultType } : {}),
|
|
42
88
|
...more,
|
|
43
89
|
});
|
|
90
|
+
const finished = () => (rounds ? 'completed' : 'none');
|
|
91
|
+
// However many rounds, one call step gets 3 × the request timeout in all.
|
|
92
|
+
const deadline = options.timeoutMs !== undefined ? Date.now() + 3 * options.timeoutMs : undefined;
|
|
44
93
|
for (;;) {
|
|
45
94
|
const mark = conn.wire.responses.length;
|
|
46
95
|
let result;
|
|
47
96
|
try {
|
|
48
|
-
result = (await conn.client.callTool(call, { timeout: options.timeoutMs, allowInputRequired: true }));
|
|
97
|
+
result = (await quietExclusions(() => conn.client.callTool(call, { timeout: options.timeoutMs, allowInputRequired: true })));
|
|
49
98
|
}
|
|
50
99
|
catch (error) {
|
|
51
|
-
//
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
100
|
+
// What the server sent decides what failed, not the error the SDK raised.
|
|
101
|
+
const wire = conn.wire.since(mark, 'tools/call').at(-1);
|
|
102
|
+
const answered = wire?.result;
|
|
103
|
+
if (isObject(answered) && !('resultType' in answered)) {
|
|
104
|
+
// No resultType: the SDK client rejects it ("missing required resultType").
|
|
105
|
+
// The server did answer; session/result-type says why clients won't take it.
|
|
56
106
|
missingResultType = true;
|
|
57
|
-
return { result: answered, input: trace(
|
|
107
|
+
return { result: answered, input: trace(finished()) };
|
|
108
|
+
}
|
|
109
|
+
if (isObject(answered) && answered.resultType === 'input_required' && (isObject(answered.inputRequests) || answered.requestState !== undefined)) {
|
|
110
|
+
// The SDK can throw after the fact (output-schema checks on a cached
|
|
111
|
+
// definition): the server asked for input, so carry on with what it sent.
|
|
112
|
+
// Not one with neither inputRequests nor requestState: the SDK is right to
|
|
113
|
+
// reject that, and calling again from scratch would repeat the tool. A
|
|
114
|
+
// requestState that isn't a string ends the call below (bad-state).
|
|
115
|
+
result = answered;
|
|
116
|
+
}
|
|
117
|
+
else {
|
|
118
|
+
// The server's own JSON-RPC error to a retry that carried a decline is its
|
|
119
|
+
// answer to the decline. Anything else goes back to session's handling as a
|
|
120
|
+
// failed call: an SDK check on a result the server did send, a timeout, a lost
|
|
121
|
+
// connection, a rate limit (429 or its words), or a failure before any decline.
|
|
122
|
+
const refused = !!wire?.error && carriesDecline && httpStatus(error) !== 429 && !tooMany(error);
|
|
123
|
+
if (!refused)
|
|
124
|
+
throw rounds || continuations ? new AfterInputError(error, trace(finished())) : error;
|
|
125
|
+
const code = wire.error.code;
|
|
126
|
+
return { input: trace('decline-failed', { error: { message: firstLine(wire.error.message ?? error), ...(typeof code === 'number' ? { code } : {}) } }) };
|
|
58
127
|
}
|
|
59
|
-
// The first call failing is an ordinary failed step; a retry that carried a
|
|
60
|
-
// decline failing is the server's answer to the decline.
|
|
61
|
-
if (rounds === 0)
|
|
62
|
-
throw error;
|
|
63
|
-
return { input: trace('decline-failed', { error }) };
|
|
64
128
|
}
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
129
|
+
if (result.resultType !== 'input_required')
|
|
130
|
+
return { result: result, input: trace(finished()) };
|
|
131
|
+
const required = result;
|
|
132
|
+
// requestState as the server sent it: the SDK client drops one that isn't a string
|
|
133
|
+
// without a word, and calling again without it would run the tool from scratch.
|
|
134
|
+
const sent = conn.wire.since(mark, 'tools/call').at(-1)?.result;
|
|
135
|
+
const state = isObject(sent) && 'requestState' in sent ? sent.requestState : required.requestState;
|
|
136
|
+
const asked = Object.entries(isObject(required.inputRequests) ? required.inputRequests : {});
|
|
137
|
+
if (state !== undefined && typeof state !== 'string') {
|
|
138
|
+
for (const [, request] of asked)
|
|
139
|
+
if (!kinds.includes(kindOf(request)))
|
|
140
|
+
kinds.push(kindOf(request));
|
|
141
|
+
return { input: trace('bad-state') };
|
|
70
142
|
}
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
143
|
+
if (!asked.length) {
|
|
144
|
+
// Only requestState: the tool keeps working and asks nothing. Send it back.
|
|
145
|
+
if (continuations >= MAX_CONTINUATIONS || (deadline !== undefined && Date.now() >= deadline))
|
|
146
|
+
return { input: trace('unfinished') };
|
|
147
|
+
continuations++;
|
|
148
|
+
call = { ...params, ...(state !== undefined ? { requestState: state } : {}) };
|
|
149
|
+
carriesDecline = false;
|
|
150
|
+
continue;
|
|
151
|
+
}
|
|
152
|
+
const askedKinds = asked.map(([, request]) => kindOf(request));
|
|
153
|
+
for (const k of askedKinds)
|
|
74
154
|
if (!kinds.includes(k))
|
|
75
155
|
kinds.push(k);
|
|
76
|
-
|
|
77
|
-
const undeclared = [...new Set(Object.values(asked).map(kindOf).filter((k) => !DECLARED.has(k)))];
|
|
156
|
+
const undeclared = [...new Set(askedKinds.filter((k) => !DECLARED.has(k)))];
|
|
78
157
|
if (undeclared.length)
|
|
79
158
|
return { input: trace('undeclared', { undeclared }) };
|
|
80
|
-
// The same
|
|
81
|
-
const signature = canonical(asked);
|
|
82
|
-
if (previous !== undefined && signature
|
|
83
|
-
|
|
159
|
+
// The same question again after a decline, whatever its key or wording: the tool didn't take the answer.
|
|
160
|
+
const signature = canonical(asked.map(([, request]) => question(request)).sort());
|
|
161
|
+
if (previous !== undefined && signature !== previous)
|
|
162
|
+
changed = true;
|
|
84
163
|
if (rounds >= MAX_ROUNDS)
|
|
85
|
-
return { input: trace(
|
|
164
|
+
return { input: trace(changed ? 'gave-up' : 'loop') };
|
|
86
165
|
previous = signature;
|
|
87
166
|
rounds++;
|
|
88
|
-
const state = result.requestState;
|
|
89
167
|
call = {
|
|
90
168
|
...params,
|
|
91
|
-
inputResponses: Object.fromEntries(
|
|
169
|
+
inputResponses: Object.fromEntries(asked.map(([key]) => [key, { action }])),
|
|
92
170
|
...(state !== undefined ? { requestState: state } : {}),
|
|
93
171
|
};
|
|
172
|
+
carriesDecline = true;
|
|
94
173
|
}
|
|
95
174
|
}
|
package/dist/options.d.ts
CHANGED
package/dist/options.js
CHANGED
|
@@ -12,6 +12,7 @@ export const CLI_OPTIONS = {
|
|
|
12
12
|
'fail-on': { type: 'string' },
|
|
13
13
|
header: { type: 'string', multiple: true },
|
|
14
14
|
env: { type: 'string', multiple: true },
|
|
15
|
+
as: { type: 'string', multiple: true },
|
|
15
16
|
timeout: { type: 'string' },
|
|
16
17
|
protocol: { type: 'string' },
|
|
17
18
|
elicitation: { type: 'string' },
|
package/dist/probe.d.ts
CHANGED
|
@@ -14,6 +14,14 @@ export declare const PROBE_SEED = "1";
|
|
|
14
14
|
* a stdio server. Other runtimes ignore it.
|
|
15
15
|
*/
|
|
16
16
|
export declare function seeded(target: Target, seed: string): Target;
|
|
17
|
+
/** Credentials for one identity (snapshot --as, config identities): HTTP headers or stdio env vars. */
|
|
18
|
+
export interface Identity {
|
|
19
|
+
name: string;
|
|
20
|
+
headers?: Record<string, string>;
|
|
21
|
+
env?: Record<string, string>;
|
|
22
|
+
}
|
|
23
|
+
/** The target as this identity: its headers (HTTP) or env vars (stdio) over the ones given. */
|
|
24
|
+
export declare function asIdentity(target: Target, identity: Identity | undefined): Target;
|
|
17
25
|
/** A command that starts the server in a container: the seed (and --env) don't reach it unless passed through. */
|
|
18
26
|
export declare function isContainerWrapper(target: Target): boolean;
|
|
19
27
|
/**
|
package/dist/probe.js
CHANGED
|
@@ -20,6 +20,14 @@ export function seeded(target, seed) {
|
|
|
20
20
|
return target;
|
|
21
21
|
return { ...target, env: { ...target.env, PYTHONHASHSEED: seed } };
|
|
22
22
|
}
|
|
23
|
+
/** The target as this identity: its headers (HTTP) or env vars (stdio) over the ones given. */
|
|
24
|
+
export function asIdentity(target, identity) {
|
|
25
|
+
if (!identity)
|
|
26
|
+
return target;
|
|
27
|
+
if (target.kind === 'http')
|
|
28
|
+
return { ...target, headers: { ...target.headers, ...identity.headers } };
|
|
29
|
+
return { ...target, env: { ...target.env, ...identity.env } };
|
|
30
|
+
}
|
|
23
31
|
/** A command that starts the server in a container: the seed (and --env) don't reach it unless passed through. */
|
|
24
32
|
export function isContainerWrapper(target) {
|
|
25
33
|
return target.kind === 'stdio' && /^(docker|podman|nerdctl)(\.exe)?$/.test(basename(target.command));
|
|
@@ -50,7 +58,7 @@ export async function probeMenu(target, timeoutMs, waits, waited) {
|
|
|
50
58
|
const c = await connect(target, { timeoutMs });
|
|
51
59
|
try {
|
|
52
60
|
const list = await listTools(c, { timeoutMs });
|
|
53
|
-
return buildMenu(list.tools, { name: c.server.name, version: c.server.version, protocolVersion: c.protocolVersion, era: c.era });
|
|
61
|
+
return buildMenu(list.tools, { name: c.server.name, version: c.server.version, protocolVersion: c.protocolVersion, era: c.era }, list.listMeta);
|
|
54
62
|
}
|
|
55
63
|
finally {
|
|
56
64
|
await c.close().catch(() => { });
|
package/dist/report.js
CHANGED
|
@@ -482,7 +482,8 @@ function callCounts(s) {
|
|
|
482
482
|
return undefined;
|
|
483
483
|
const n = (o) => calls.filter((st) => st.outcome === o).length;
|
|
484
484
|
const notSent = n('not-sent');
|
|
485
|
-
|
|
485
|
+
const stuck = n('needs-input');
|
|
486
|
+
return `${calls.length} · ${n('answered')} answered, ${plural(n('tool-error'), 'tool error')}, ${n('failed')} failed${stuck ? `, ${stuck} never finished (input rounds)` : ''}${notSent ? `, ${notSent} not sent` : ''}`;
|
|
486
487
|
}
|
|
487
488
|
export function formatPlan(scenario, name) {
|
|
488
489
|
const lines = [`toolmenu session --plan ${name}`, ` allow_writes: ${scenario.allowWrites}${scenario.allowWrites ? '' : ' (tools not marked readOnlyHint will be refused)'}`, ''];
|
package/dist/rules/gated.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { unlockers } from '../session.js';
|
|
1
|
+
import { definite, unlockers } from '../session.js';
|
|
2
2
|
import { singular, VERBS, words } from '../words.js';
|
|
3
3
|
import { names } from './rule.js';
|
|
4
4
|
/**
|
|
@@ -17,10 +17,10 @@ export const gated = {
|
|
|
17
17
|
// Only an unlock whose parameter lists what it unlocks (an enum of toolsets or
|
|
18
18
|
// domains), the kind session --auto walks: "Enables Cross-Region Restore on a
|
|
19
19
|
// vault" turns on a feature, not tools (Azure, 418 tools).
|
|
20
|
-
// And only one
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
const found = unlockers(ctx.menu.tools).filter((u) => u.param && u.values.length && u
|
|
20
|
+
// And only one that surely unlocks tools (definite): an enum of domains alone is
|
|
21
|
+
// as often data (Garmin's garmin_sync { domains: [sleep, hrv] } downloads them).
|
|
22
|
+
// session --auto still tries such a tool once.
|
|
23
|
+
const found = unlockers(ctx.menu.tools).filter((u) => u.param && u.values.length && definite(u));
|
|
24
24
|
if (!found.length)
|
|
25
25
|
return [];
|
|
26
26
|
// A value whose tools are already listed adds nothing: the same server started
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { MenuTool } from '../types.js';
|
|
2
|
+
import { type Rule } from './rule.js';
|
|
3
|
+
/** A call made with a handle that can't exist (session --auto): the parameter, and the kind of handle. */
|
|
4
|
+
export interface HandleProbe {
|
|
5
|
+
param: string;
|
|
6
|
+
kind: string;
|
|
7
|
+
}
|
|
8
|
+
/** The handle kinds some tool in the menu creates. */
|
|
9
|
+
export declare function createdKinds(tools: MenuTool[]): Set<string>;
|
|
10
|
+
/** Parameters of a tool that take a handle of this kind: session_id, cartToken, `session`. */
|
|
11
|
+
export declare function handleParams(tool: MenuTool, kind: string): string[];
|
|
12
|
+
export declare const handleLifetime: Rule;
|