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/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
- const USAGE = /(?:^|\n)\s*(?:usage|(?:sub)?commands|options|examples|flags):|\bUSAGE\b|\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;
153
- // A table of commands or options, two or more rows: " t3-watch start Run the service",
154
- // " --version Show version number". Help output, even without a "Usage:" line.
155
- const HELP_ROWS = /(?:^|\n)\s*(?:[\w.-]+ [\w-]+|-{1,2}[\w-]+(?:, -{1,2}[\w-]+)?) {2,}\S[^\n]*\n\s*(?:[\w.-]+ [\w-]+|-{1,2}[\w-]+(?:, -{1,2}[\w-]+)?) {2,}\S/;
156
- // The subcommands that usually start the MCP server, most specific first. A word
157
- // on its own ({mcp}, " mcp Start…", "mcp start [--transport…]"), not part of a
158
- // name like agentation-mcp.
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"'<>]+)/i;
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, or a server that opened an
167
- * HTTP port instead of talking on stdio. Undefined when it says neither.
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.exec(text)?.[1]?.replace(/[.,;)]+$/, '').replace('//0.0.0.0', '//localhost');
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) || HELP_ROWS.test(text)) {
179
- const sub = SUBCOMMANDS.find((c) => new RegExp(`(?:^|[\\s{,|\\[])${c.replace(' ', '\\s+')}(?=[\\s},|\\]]|$)`, 'm').test(text));
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, command))) {
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
- const hint = startupHint(trace, command);
374
- const next = hint
375
- ? hint
376
- : trace.strayCount
377
- ? LOG_TO_STDERR
378
- : rejected
379
- ? REJECTED_NEXT
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
- 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|\b(?:unsupported|not supported on (?:this|the current)) (?:platform|operating system|OS)\b/i;
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 feature toolmenu doesn't offer (roots or sampling)",
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 roots or sampling from the client, toolmenu doesn't provide them (2026-07-28 deprecates both): those calls only checked that the menu stays put, and the server isn't at fault.");
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 { Connection, Elicitation } from './connect.js';
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 a decline, until the round limit.
13
- * gave-up: still asking (different things) at the round limit.
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?: unknown;
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
- /** Keys sorted at every level: the same request asked twice reads the same. */
14
- function canonical(value) {
15
- if (Array.isArray(value))
16
- return `[${value.map(canonical).join(',')}]`;
17
- if (value && typeof value === 'object') {
18
- return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
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
- let repeated = false;
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
- // A result without resultType: the SDK client rejects it ("missing required
52
- // resultType"). The server did answer, so the step did too; the finding says why
53
- // clients won't take it.
54
- const answered = conn.wire.since(mark, 'tools/call').at(-1)?.result;
55
- if (answered && !('resultType' in answered)) {
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(rounds ? 'completed' : 'none') };
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
- const raw = conn.wire.since(mark, 'tools/call').at(-1)?.result;
66
- if (raw && !('resultType' in raw))
67
- missingResultType = true;
68
- if (result.resultType !== 'input_required') {
69
- return { result: result, input: trace(rounds ? 'completed' : 'none') };
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
- const asked = result.inputRequests ?? {};
72
- for (const request of Object.values(asked)) {
73
- const k = kindOf(request);
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 requests again after a decline: the tool didn't take the answer.
81
- const signature = canonical(asked);
82
- if (previous !== undefined && signature === previous && Object.keys(asked).length)
83
- repeated = true;
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(repeated ? 'loop' : 'gave-up') };
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(Object.keys(asked).map((key) => [key, { action }])),
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
@@ -28,6 +28,10 @@ export declare const CLI_OPTIONS: {
28
28
  readonly type: 'string';
29
29
  readonly multiple: true;
30
30
  };
31
+ readonly as: {
32
+ readonly type: 'string';
33
+ readonly multiple: true;
34
+ };
31
35
  readonly timeout: {
32
36
  readonly type: 'string';
33
37
  };
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
- return `${calls.length} · ${n('answered')} answered, ${plural(n('tool-error'), 'tool error')}, ${n('failed')} failed${notSent ? `, ${notSent} not sent` : ''}`;
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)'}`, ''];
@@ -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 whose name or description says it unlocks tools: an enum of
21
- // domains alone is as often data (Garmin's garmin_sync { domains: [sleep, hrv] }
22
- // downloads them). session --auto still tries such a tool once.
23
- const found = unlockers(ctx.menu.tools).filter((u) => u.param && u.values.length && u.claims);
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;