toolmenu 0.13.0 → 0.14.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/diff.js CHANGED
@@ -20,6 +20,7 @@ export const DIFF_RULES = {
20
20
  'diff/description': { severity: 'info', class: 'notice' },
21
21
  'diff/param-dropped': { severity: 'info', class: 'notice' },
22
22
  'diff/schema-other': { severity: 'info', class: 'notice' },
23
+ 'diff/param-default': { severity: 'info', class: 'notice' },
23
24
  // Restructured ($ref, $defs) but accepts the same input: bytes and tokens changed.
24
25
  'diff/schema-equivalent': { severity: 'info', class: 'notice' },
25
26
  // Only the declared $schema dialect changed: one finding for the menu.
@@ -103,7 +104,9 @@ export function diffMenus(before, after, options = {}) {
103
104
  raw.push(...compareTool(from, to).filter((f) => f.rule !== 'diff/description' && f.rule !== 'diff/other'));
104
105
  collapseDialects(raw);
105
106
  collapseMenuWide(raw);
106
- const moved = compareMenus(oldTools, newTools).filter((c) => c.kind === 'moved');
107
+ // A session's union menu is in unlock order, which no client was served: no order to compare.
108
+ const unordered = before.from === 'session' || after.from === 'session';
109
+ const moved = unordered ? [] : compareMenus(oldTools, newTools).filter((c) => c.kind === 'moved');
107
110
  if (moved.length) {
108
111
  const names = moved.map((m) => m.tool);
109
112
  raw.push({
@@ -371,9 +374,15 @@ function compareTool(old, t) {
371
374
  // Too large to expand on either side: compare both as written, so an expanded
372
375
  // side isn't read against a $ref on the other ("object → any"), and say so.
373
376
  const expanded = ea.expanded && eb.expanded;
374
- const a = expanded ? ea.schema : old.inputSchema;
375
- const b = expanded ? eb.schema : t.inputSchema;
376
- if (!expanded && canonical(old.inputSchema) !== canonical(t.inputSchema)) {
377
+ // A schema generator upgrade moves `definitions` to `$defs` along with the dialect:
378
+ // as written, every $ref reads as pointing somewhere else. Said once, as the dialect.
379
+ const moved = !expanded && typeof old.inputSchema?.$schema === 'string' && typeof t.inputSchema?.$schema === 'string' && old.inputSchema.$schema !== t.inputSchema.$schema;
380
+ const [oldRaw, newRaw] = moved ? [defsPool(old.inputSchema), defsPool(t.inputSchema)] : [old.inputSchema, t.inputSchema];
381
+ const a = expanded ? ea.schema : oldRaw;
382
+ const b = expanded ? eb.schema : newRaw;
383
+ // The dialect itself is said below (diff/schema-dialect), not as a reason to look by hand.
384
+ const unversioned = (x) => { const { $schema: _s, ...rest } = (x ?? {}); return rest; };
385
+ if (!expanded && canonical(moved ? unversioned(oldRaw) : oldRaw) !== canonical(moved ? unversioned(newRaw) : newRaw)) {
377
386
  const which = ea.expanded ? 'the new input schema expands' : eb.expanded ? 'the old input schema expands' : 'the old and new input schemas expand';
378
387
  out.push({
379
388
  rule: 'diff/schema-other',
@@ -406,7 +415,7 @@ function compareTool(old, t) {
406
415
  // what they point to is compared here, definition by definition, by name. A
407
416
  // narrowed enum inside one is still breaking.
408
417
  if (!expanded)
409
- compareDefinitions({ tool: name, out }, name, old.inputSchema ?? {}, t.inputSchema ?? {});
418
+ compareDefinitions({ tool: name, out }, name, oldRaw ?? {}, newRaw ?? {});
410
419
  collapsePlaces(out, found);
411
420
  const shell = (s) => {
412
421
  const { properties: _p, required: _r, $defs: _d, definitions: _df, ...rest } = (s ?? {});
@@ -492,6 +501,27 @@ function sameTypes(node) {
492
501
  }
493
502
  return out;
494
503
  }
504
+ /**
505
+ * The schema with `definitions` spelled `$defs`: its entries moved into `$defs`, and
506
+ * local `#/definitions/…` $refs pointing at `#/$defs/…`. The two are one place in a
507
+ * JSON pointer's eyes, so this changes no meaning. Used where two schemas are compared
508
+ * as written and their dialects differ.
509
+ */
510
+ function defsPool(schema) {
511
+ if (!schema || typeof schema !== 'object')
512
+ return schema;
513
+ const rewrite = (node) => {
514
+ if (Array.isArray(node))
515
+ return node.map(rewrite);
516
+ if (!node || typeof node !== 'object')
517
+ return node;
518
+ return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, k === '$ref' && typeof v === 'string' ? v.replace(/^#\/definitions\//, '#/$defs/') : rewrite(v)]));
519
+ };
520
+ const { definitions, ...rest } = rewrite(schema);
521
+ if (!definitions || typeof definitions !== 'object')
522
+ return rest;
523
+ return { ...rest, $defs: { ...definitions, ...(rest.$defs ?? {}) } };
524
+ }
495
525
  /** `$defs` and `definitions` entries of two unexpanded schemas, compared by name. */
496
526
  function compareDefinitions(w, name, oldS, newS) {
497
527
  const list = (names) => [...names].sort((x, y) => x.localeCompare(y, 'en', { numeric: true })).slice(0, 8).join(', ') + (names.length > 8 ? `, and ${names.length - 8} more` : '');
@@ -775,7 +805,19 @@ function compareSchema(w, at, before, after, depth) {
775
805
  // A union against a plain schema is covered by its options entirely.
776
806
  if (union && !(oldOptions && newOptions))
777
807
  return;
778
- const rest = (s) => residual(s, { object, items: arrays, union });
808
+ // A default is the value a call that leaves the parameter out gets: said with both
809
+ // values, not as an unclassified keyword (a date default built from the clock).
810
+ const shown = (v) => (v === undefined ? '(none)' : JSON.stringify(v));
811
+ if (canonical(before.default) !== canonical(after.default)) {
812
+ say(w, 'diff/param-default', at, `: the default changed: ${shown(before.default)} → ${shown(after.default)}`, 'Calls that leave it out now get the new value.', [before, after], {
813
+ fix: 'If the default is built from the clock or the environment, give a fixed one or none, and say in the description what an absent value means.',
814
+ });
815
+ }
816
+ const rest = (s) => {
817
+ const r = residual(s, { object, items: arrays, union });
818
+ delete r.default;
819
+ return r;
820
+ };
779
821
  if ((union || oldType === newType || accepts(after, before)) && canonical(rest(before)) !== canonical(rest(after))) {
780
822
  say(w, 'diff/schema-other', at, ` changed in keywords toolmenu doesn't classify: ${changedKeys(rest(before), rest(after))}`, '', [before, after], {
781
823
  fix: 'Review it: a tighter constraint (a lower maximum, a new pattern or format) rejects calls that met the old one.',
package/dist/explain.d.ts CHANGED
@@ -78,6 +78,14 @@ export declare function seconds(ms: number): string;
78
78
  export declare function commandLine(command: string, args: string[]): string;
79
79
  /** The stderr fact: the last lines, and a note of how many came before. */
80
80
  export declare function stderrFact(trace: Trace): [string, string];
81
+ /** A request header that carries credentials: Authorization, a cookie, or a name with key, token, secret or auth in it (x-mcp-api-key). */
82
+ export declare function isCredentialHeader(name: string): boolean;
83
+ /**
84
+ * The header a refusal names ("missing or invalid x-mcp-api-key header",
85
+ * "header 'X-Api-Key' required"), lower-cased. Only Authorization, or a hyphenated name
86
+ * that carries credentials (x-api-key): "the header" and "content-type header" aren't asked for.
87
+ */
88
+ export declare function namedHeader(body: string | undefined): string | undefined;
81
89
  /** A short, readable excerpt of a response body: an HTML page's title or first words, JSON's message. Never the whole body. */
82
90
  export declare function bodyExcerpt(body: string | undefined, max?: number): string | undefined;
83
91
  export interface ExplainContext {
@@ -95,6 +103,8 @@ export interface ExplainContext {
95
103
  oauth?: boolean;
96
104
  /** The stage when it isn't the connect handshake (tools/list). */
97
105
  stage?: string;
106
+ /** --protocol, when it isn't auto. */
107
+ protocol?: 'legacy' | 'modern';
98
108
  }
99
109
  /**
100
110
  * The error as a ConnectError that says what happened, or the error unchanged
package/dist/explain.js CHANGED
@@ -162,6 +162,25 @@ const STATUS_TEXT = {
162
162
  408: 'Request Timeout', 410: 'Gone', 415: 'Unsupported Media Type', 500: 'Internal Server Error', 502: 'Bad Gateway',
163
163
  503: 'Service Unavailable', 504: 'Gateway Timeout',
164
164
  };
165
+ const CREDENTIAL_WORDS = new Set(['authorization', 'cookie', 'key', 'apikey', 'token', 'secret', 'auth', 'password']);
166
+ /** A request header that carries credentials: Authorization, a cookie, or a name with key, token, secret or auth in it (x-mcp-api-key). */
167
+ export function isCredentialHeader(name) {
168
+ return name.toLowerCase().split(/[-_]/).some((w) => CREDENTIAL_WORDS.has(w));
169
+ }
170
+ /**
171
+ * The header a refusal names ("missing or invalid x-mcp-api-key header",
172
+ * "header 'X-Api-Key' required"), lower-cased. Only Authorization, or a hyphenated name
173
+ * that carries credentials (x-api-key): "the header" and "content-type header" aren't asked for.
174
+ */
175
+ export function namedHeader(body) {
176
+ if (!body)
177
+ return undefined;
178
+ const name = /\b([A-Za-z][\w-]*)["'`]?\s+header\b/i.exec(body)?.[1] ?? /\bheader\s*[:(]?\s*["'`]?([A-Za-z][\w-]*)/i.exec(body)?.[1];
179
+ if (!name)
180
+ return undefined;
181
+ const lower = name.toLowerCase();
182
+ return lower === 'authorization' || (/-/.test(lower) && isCredentialHeader(lower)) ? lower : undefined;
183
+ }
165
184
  /** A short, readable excerpt of a response body: an HTML page's title or first words, JSON's message. Never the whole body. */
166
185
  export function bodyExcerpt(body, max = 100) {
167
186
  if (!body?.trim())
@@ -188,6 +207,11 @@ export function explain(error, trace, context) {
188
207
  const login = causes(error).find((e) => e instanceof LoginNeededError);
189
208
  if (login)
190
209
  return login;
210
+ // --protocol modern on a server without server/discover: the choice failed, not the connection.
211
+ if (context.protocol === 'modern' && causes(error).some((e) => /did not offer pinned protocol version|Version negotiation failed/i.test(e.message))) {
212
+ const where = context.target.kind === 'stdio' ? commandLine(context.target.command, context.target.args) : context.target.url;
213
+ return new ConnectError("The server doesn't speak the 2026-07-28 protocol, and --protocol modern allows nothing else.", [['server', where], ['stage', 'server/discover']], 'Drop --protocol (or use --protocol auto) to fall back to the 2025 handshake, or --protocol legacy to check it as a 2025 server on purpose.', 'server/discover', { cause: error });
214
+ }
191
215
  return context.target.kind === 'stdio' ? explainStdio(error, trace, context, context.target) : explainHttp(error, trace, context, context.target);
192
216
  }
193
217
  /**
@@ -397,14 +421,17 @@ function explainHttp(error, trace, context, target) {
397
421
  if (excerpt)
398
422
  facts.push([/html/i.test(shortType) || /<html|<!doctype/i.test(body ?? '') ? 'page' : 'body', `“${excerpt}”`]);
399
423
  if (status === 401 || status === 403) {
400
- const ownAuth = Object.keys(target.headers ?? {}).some((h) => /^(authorization|x-api-key|api-key|cookie)$/i.test(h));
424
+ const named = namedHeader(body);
425
+ const ownAuth = Object.keys(target.headers ?? {}).some((h) => isCredentialHeader(h) || h.toLowerCase() === named);
401
426
  const next = context.oauth
402
427
  ? `The stored login was refused: log in again with toolmenu auth login ${target.url} (or skip it with --no-auth).`
403
428
  : ownAuth
404
429
  ? status === 401
405
430
  ? 'The credentials you sent were refused: check the token is current and meant for this server.'
406
431
  : "The credentials were accepted but don't grant access: check the account's permissions or the token's scopes."
407
- : `If the server uses OAuth, log in once with: toolmenu auth login ${target.url} (if it takes an API key instead, pass it with --header "Authorization: Bearer …").`;
432
+ : named && named !== 'authorization'
433
+ ? `The server asks for ${/^[aeiox]/.test(named) ? 'an' : 'a'} ${named} header: pass it with --header "${named}: <key>".`
434
+ : `If the server uses OAuth, log in once with: toolmenu auth login ${target.url} (if it takes an API key instead, pass it with --header "Authorization: Bearer …").`;
408
435
  return new ConnectError(status === 401 ? `${host} wants credentials: ${stage} got HTTP 401 Unauthorized.` : `${host} refused access: ${stage} got HTTP 403 Forbidden.`, facts.filter(([l]) => l !== 'answer'), next, stage, { cause: error, status });
409
436
  }
410
437
  // The server's own JSON-RPC error: its words, not a page.
@@ -19,6 +19,12 @@ export declare function tooMany(error: unknown): boolean;
19
19
  * the waiting off.
20
20
  */
21
21
  export declare const RATE_LIMIT_WAITS_MS: number[];
22
+ /**
23
+ * A tool's error text with the reason up front: "400 Bad Request: {"message":"Filter by
24
+ * X is mandatory"}" says "400 Bad Request: Filter by X is mandatory". Text with no JSON
25
+ * message in it is returned as it is.
26
+ */
27
+ export declare function errorWords(text: string): string;
22
28
  /** What to do about a rate limit toolmenu couldn't wait out. */
23
29
  export declare const RATE_LIMIT_ADVICE = "The limit counts every request from this address, toolmenu's included: give the run its own server instance, or raise the limit for it.";
24
30
  /** Quoted words that end a sentence: “Rate limit exceeded”. but “Try again later.” (no second period). */
package/dist/failures.js CHANGED
@@ -11,8 +11,10 @@ export const SETUP_FAILURES = new Set(['auth', 'environment', 'network', 'not-fo
11
11
  const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bnot installed\b|command not found|cannot find (module|package)|\bENOENT\b/i;
12
12
  // "401 Bad credentials" (GitHub), "Authorization Expired" (Sentry), "Invalid
13
13
  // token" (Firecrawl), "authentication token is not valid" (Apify), "Please provide
14
- // a valid access token" (Supabase). Not a bare "token": plenty of errors mention one.
15
- const AUTH = /\b(401|403)\b|unauthori[sz]ed|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|valid (access )?token/i;
14
+ // a valid access token" (Supabase), "NetlifyUnauthError: You're not logged into
15
+ // Netlify" (Netlify), "The API key you provided was rejected" (Pinecone). Not a
16
+ // bare "token": plenty of errors mention one.
17
+ const AUTH = /\b(401|403)\b|unauthori[sz]ed|unauth(enticated|error)|forbidden|bad credentials|authori[sz]ation expired|re-?authori[sz]e|not authenticated|not logged (?:in|into)\b(?! to the browser)|authentication (token|failed|required|error)|(invalid|expired|revoked) (api[ _-]?key|access token|token|credentials)|(token|api[ _-]?key|credentials) (is |are )?(not valid|invalid|expired)|(api[ _-]?key|access token|credentials)\b[^.]{0,30}\b(was|were|is|are) (rejected|refused|revoked)|valid (access )?token/i;
16
18
  const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH)\b|socket hang up|getaddrinfo|network error/i;
17
19
  // "Either 'page_id' OR both 'title' and 'space_key' must be provided" (Atlassian),
18
20
  // "**Input Error**" (Sentry), JSON-RPC's invalid params.
@@ -44,6 +46,44 @@ export function tooMany(error) {
44
46
  * the waiting off.
45
47
  */
46
48
  export const RATE_LIMIT_WAITS_MS = waitsFrom(process.env.TOOLMENU_RATE_LIMIT_WAITS_MS) ?? [2000, 4000, 8000, 16_000, 32_000];
49
+ /**
50
+ * A tool's error text with the reason up front: "400 Bad Request: {"message":"Filter by
51
+ * X is mandatory"}" says "400 Bad Request: Filter by X is mandatory". Text with no JSON
52
+ * message in it is returned as it is.
53
+ */
54
+ export function errorWords(text) {
55
+ const start = text.indexOf('{');
56
+ const end = text.lastIndexOf('}');
57
+ if (start < 0 || end < start)
58
+ return text;
59
+ let reason;
60
+ try {
61
+ const body = JSON.parse(text.slice(start, end + 1));
62
+ const pick = (o) => {
63
+ if (typeof o !== 'object' || o === null)
64
+ return undefined;
65
+ const r = o;
66
+ for (const key of ['message', 'detail', 'error_description', 'error']) {
67
+ const v = r[key];
68
+ if (typeof v === 'string' && v.trim())
69
+ return v.trim();
70
+ const inner = typeof v === 'object' ? pick(v) : undefined;
71
+ if (inner)
72
+ return inner;
73
+ }
74
+ return undefined;
75
+ };
76
+ reason = pick(body);
77
+ }
78
+ catch {
79
+ reason = undefined;
80
+ }
81
+ if (!reason)
82
+ return text;
83
+ const lead = text.slice(0, start).trim().replace(/[:\-–]+$/, '').trim();
84
+ const tail = text.slice(end + 1).trim();
85
+ return [lead ? `${lead}: ${reason}` : reason, tail].filter(Boolean).join(' ');
86
+ }
47
87
  /** What to do about a rate limit toolmenu couldn't wait out. */
48
88
  export const RATE_LIMIT_ADVICE = "The limit counts every request from this address, toolmenu's included: give the run its own server instance, or raise the limit for it.";
49
89
  /** Quoted words that end a sentence: “Rate limit exceeded”. but “Try again later.” (no second period). */
package/dist/help.d.ts CHANGED
@@ -7,3 +7,5 @@ export declare function commandHelp(command: Command): string;
7
7
  /** The message for a command toolmenu doesn't have. */
8
8
  export declare function unknownCommand(name: string): string;
9
9
  export declare function isCommand(name: string): name is Command;
10
+ /** The options a command takes, as spelled on the command line (no "--"). */
11
+ export declare function commandOptions(command: Command): string[];
package/dist/help.js CHANGED
@@ -17,6 +17,7 @@ const OPTIONS = {
17
17
  'fail-on': ['--fail-on <level>', ['exit 1 on findings at this level or above: error (default), warn, info']],
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
+ 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']],
20
21
  'no-auth': ['--no-auth', ["don't use a stored OAuth login (toolmenu auth login) for this server"]],
21
22
  timeout: ['--timeout <ms>', ['per-request timeout (default: 30000)']],
22
23
  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']],
@@ -27,11 +28,12 @@ const OPTIONS = {
27
28
  init: ['--init', ["write a starter scenario from the server's menu (to --scenario,", 'default scenario.yml; never overwrites)']],
28
29
  auto: ['--auto', ['build the steps from the menu: every read-only tool whose required', 'arguments the schema can fill (const, default, examples, enum, type),', 'then the first call again']],
29
30
  'open-world': ['--open-world', ['with --auto, also call read-only tools marked openWorldHint: true', '(web search, fetch, scraping): they may cost API credits']],
30
- 'max-calls': ['--max-calls <n>', ['with --auto, at most n calls (default: 20)']],
31
+ 'max-calls': ['--max-calls <n>', ['with --auto, at most n calls in all, the tools unlocks bring', 'included (default: 20, plus --max-calls-per-unlock for each unlock value)']],
32
+ 'max-calls-per-unlock': ['--max-calls-per-unlock <n>', ['with --auto, at most n calls for the tools each unlock value', 'brings (default: 5), so every toolset gets some']],
31
33
  value: ['--value <k=v>', ['with --auto, a value for a required parameter, by name', '(repo_path=/src) or for one tool (get_issue.key=ABC-1);', 'repeatable; JSON values allowed']],
32
34
  'values-file': ['--values-file <path>', ['with --auto, the same as a YAML/JSON map']],
33
35
  'assume-read-only': ['--assume-read-only <tools>', ["with --auto, call these tools although the server doesn't", 'mark them readOnlyHint (exact names, comma-separated; tools', 'marked or named as writes are still never called)']],
34
- 'save-scenario': ['--save-scenario <path>', ['with --auto, write the steps it ran as a scenario file']],
36
+ 'save-scenario': ['--save-scenario <path>', ['with --auto, write the plan made before the run as a scenario file', '(calls planned later for tools an unlock brings are not in it)']],
35
37
  'union-out': ['--union-out <path>', ['write every tool the session saw as a menu file, to commit as the', 'baseline for diff (tools behind unlocks included)']],
36
38
  versions: ['--versions <n|all>', ['how many of the most recent versions to inspect (default: 10), or all']],
37
39
  'include-prereleases': ['--include-prereleases', ['include versions like 1.2.0-beta.1']],
@@ -62,7 +64,7 @@ const HELP = {
62
64
  SERVER_NOTE,
63
65
  ],
64
66
  own: ['init-out', 'with-session'],
65
- shared: ['config', 'header', 'env', 'no-auth', 'timeout', 'processes'],
67
+ shared: ['config', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
66
68
  examples: ['toolmenu init -- node dist/index.js', 'toolmenu init --with-session https://example.com/mcp'],
67
69
  exits: ['0 baseline and workflow written', "2 couldn't connect, a file already exists, or bad usage"],
68
70
  },
@@ -75,7 +77,7 @@ const HELP = {
75
77
  SERVER_NOTE,
76
78
  ],
77
79
  own: ['out', 'no-write', 'routes', 'catalog'],
78
- shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'timeout', 'processes'],
80
+ shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
79
81
  examples: [
80
82
  'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
81
83
  'toolmenu snapshot --format markdown --header "Authorization: Bearer $TOKEN" https://example.com/mcp',
@@ -104,8 +106,8 @@ const HELP = {
104
106
  'prompt cache, a different menu in a fresh process.',
105
107
  SERVER_NOTE,
106
108
  ],
107
- own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'max-calls', 'save-scenario', 'union-out'],
108
- shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'timeout', 'processes'],
109
+ own: ['scenario', 'auto', 'init', 'plan', 'value', 'values-file', 'assume-read-only', 'open-world', 'max-calls', 'max-calls-per-unlock', 'save-scenario', 'union-out'],
110
+ shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
109
111
  examples: [
110
112
  'toolmenu session --auto -- node dist/index.js',
111
113
  'toolmenu session --auto --value repo_path=/src -- uvx mcp-server-git',
@@ -196,3 +198,8 @@ export function unknownCommand(name) {
196
198
  export function isCommand(name) {
197
199
  return COMMANDS.includes(name);
198
200
  }
201
+ /** The options a command takes, as spelled on the command line (no "--"). */
202
+ export function commandOptions(command) {
203
+ const { own, shared } = HELP[command];
204
+ return [...own, ...shared].map((k) => (k === 'init-out' || k === 'history-out' ? 'out' : k));
205
+ }
package/dist/init.d.ts CHANGED
@@ -45,6 +45,7 @@ export interface WorkflowOptions {
45
45
  export declare function workflowYaml(opts: WorkflowOptions): string;
46
46
  /** The secret names the workflow refers to, to tell the user what to add. */
47
47
  export declare function secretsNeeded(target: Target): string[];
48
+ export declare function shellWord(w: string): string;
48
49
  /** Something in the setup that won't work in CI as written. */
49
50
  export interface Problem {
50
51
  /** What is wrong, and where. */
package/dist/init.js CHANGED
@@ -218,7 +218,7 @@ export function secretsNeeded(target) {
218
218
  function secretName(header) {
219
219
  return 'MCP_' + header.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
220
220
  }
221
- function shellWord(w) {
221
+ export function shellWord(w) {
222
222
  return /^[\w./:=@%+,-]+$/.test(w) ? w : `'${w.replace(/'/g, `'\\''`)}'`;
223
223
  }
224
224
  function yamlString(s) {
package/dist/options.d.ts CHANGED
@@ -31,6 +31,9 @@ export declare const CLI_OPTIONS: {
31
31
  readonly timeout: {
32
32
  readonly type: 'string';
33
33
  };
34
+ readonly protocol: {
35
+ readonly type: 'string';
36
+ };
34
37
  readonly 'no-auth': {
35
38
  readonly type: 'boolean';
36
39
  };
@@ -110,6 +113,9 @@ export declare const CLI_OPTIONS: {
110
113
  readonly 'max-calls': {
111
114
  readonly type: 'string';
112
115
  };
116
+ readonly 'max-calls-per-unlock': {
117
+ readonly type: 'string';
118
+ };
113
119
  readonly 'save-scenario': {
114
120
  readonly type: 'string';
115
121
  };
package/dist/options.js CHANGED
@@ -13,6 +13,7 @@ export const CLI_OPTIONS = {
13
13
  header: { type: 'string', multiple: true },
14
14
  env: { type: 'string', multiple: true },
15
15
  timeout: { type: 'string' },
16
+ protocol: { type: 'string' },
16
17
  'no-auth': { type: 'boolean' },
17
18
  port: { type: 'string' },
18
19
  scope: { type: 'string' },
@@ -39,6 +40,7 @@ export const CLI_OPTIONS = {
39
40
  catalog: { type: 'boolean' },
40
41
  'open-world': { type: 'boolean' },
41
42
  'max-calls': { type: 'string' },
43
+ 'max-calls-per-unlock': { type: 'string' },
42
44
  'save-scenario': { type: 'string' },
43
45
  value: { type: 'string', multiple: true },
44
46
  'values-file': { type: 'string' },
package/dist/report.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import type { DiffResult } from './diff.js';
2
2
  import type { HistoryResult } from './history.js';
3
3
  import { type Scenario, type SessionResult } from './session.js';
4
- import type { Finding, Menu, Severity } from './types.js';
4
+ import { type Finding, type Menu, type Severity } from './types.js';
5
5
  export type Format = 'text' | 'json' | 'github' | 'markdown';
6
6
  export declare function counts(findings: Finding[]): Record<Severity, number>;
7
7
  export declare function formatSnapshot(menu: Menu, findings: Finding[], format: Format, outPath?: string): string;
package/dist/report.js CHANGED
@@ -1,4 +1,5 @@
1
- import { stepLabel } from './session.js';
1
+ import { clip, stepLabel, stepsText } from './session.js';
2
+ import { SEVERITY_RANK } from './types.js';
2
3
  import { breakdown, breakdownLines, breakdownMarkdown } from './breakdown.js';
3
4
  import { autoSummary } from './auto.js';
4
5
  const LABEL = { error: 'ERROR', warn: 'WARN ', info: 'INFO ' };
@@ -354,6 +355,9 @@ export function formatSession(s, format) {
354
355
  `\`${s.server.name ?? 'server'}\` ${s.server.version ?? ''} · protocol ${s.server.protocolVersion ?? '?'} · ${s.transport} · ${s.baseline.tools} → ${s.final.tools} tools · ~${s.baseline.tokens.toLocaleString('en-US')} → ~${s.final.tokens.toLocaleString('en-US')} tokens (estimate)`,
355
356
  '',
356
357
  ...(s.auto ? [...autoSummary(s.auto).map((l, i) => (i === 0 ? `**${l.replace(/^auto: /, 'auto:** ')}` : `- ${l.trim()}`)), ''] : []),
358
+ ...(callCounts(s) ? [`**Calls:** ${callCounts(s)}`, ''] : []),
359
+ ...(menuChange(s) ? [`**Menu:** ${menuChange(s)}`, ''] : []),
360
+ ...causes(s.findings, (count, f, where, text) => count ? `**${count}:**` : `- ${f.severity === 'error' ? '**ERROR**' : LABEL[f.severity].trim()} \`${f.rule}\` · ${where} · ${mdCell(text)}`),
357
361
  '| Step | Menu | list_changed | Scope |',
358
362
  '|---|---|---|---|',
359
363
  ...s.steps.map((st) => `| ${st.index}. ${mdCell(st.label)} | ${st.status !== 'ok' ? st.status : st.changed ? `changed (${st.tools} tools)` : 'no change'} | ${st.changed ? (st.listChanged ? 'received' : '**missing**') : ''} | ${st.scope ?? ''} |`),
@@ -368,8 +372,12 @@ export function formatSession(s, format) {
368
372
  ` ${s.server.name ?? 'server'} ${s.server.version ?? ''} · protocol ${s.server.protocolVersion ?? '?'} · ${s.transport}`,
369
373
  ` baseline: ${plural(s.baseline.tools, 'tool')} · ${tok(s.baseline.tokens)} tokens (estimate) · listening for list_changed: ${s.listening ? 'yes' : 'no'}`,
370
374
  ...(s.auto ? autoSummary(s.auto).map((l, i) => (i === 0 ? ` ${l}` : ` ${l}`)) : []),
371
- ` fresh-${s.transport === 'stdio' ? 'process' : 'connection'} check: ${s.connectionCheck === undefined ? 'not checked' : s.connectionCheck === 'same' ? 'the same menu' : 'a DIFFERENT menu'}`,
375
+ ...(callCounts(s) ? [` calls: ${callCounts(s)}`] : []),
376
+ // Before the first step only: what a fresh one sees after a change is each step's scope.
377
+ ` fresh-${s.transport === 'stdio' ? 'process' : 'connection'} check of the starting menu: ${s.connectionCheck === undefined ? 'not checked' : s.connectionCheck === 'same' ? 'the same' : 'DIFFERENT'}`,
372
378
  '',
379
+ ...(menuChange(s) ? [`menu: ${menuChange(s)}`] : []),
380
+ ...causes(s.findings, (count, f, where, text) => (count ? `${count}:` : ` ${LABEL[f.severity]} ${f.rule} · ${where} · ${text}`)),
373
381
  ];
374
382
  const at = (step) => s.findings.filter((f) => f.step === step);
375
383
  const block = (findings) => {
@@ -391,6 +399,8 @@ export function formatSession(s, format) {
391
399
  before = step.tools;
392
400
  const facts = [
393
401
  step.status !== 'ok' ? step.status : '',
402
+ // A tool error or a failure is said in the step's note; an answer otherwise wouldn't be said at all.
403
+ step.outcome === 'answered' ? 'answered' : '',
394
404
  step.changed ? `menu changed${delta ? ` · ${delta > 0 ? '+' : '−'}${plural(Math.abs(delta), 'tool')}` : ''}` : step.status === 'ok' ? 'no change' : '',
395
405
  step.changed ? (step.listChanged ? 'list_changed received' : 'no list_changed') : '',
396
406
  step.scope ? `scope: ${step.scope}` : '',
@@ -410,6 +420,70 @@ export function formatSession(s, format) {
410
420
  lines.push(summaryLine(s.findings));
411
421
  return lines.join('\n');
412
422
  }
423
+ /**
424
+ * A session's errors and warnings, one line each, before the step log: what to fix
425
+ * without reading every step. `line` renders the count heading (count set) or one
426
+ * finding, info included. Empty when there are no findings.
427
+ */
428
+ function causes(findings, line) {
429
+ // Errors first, info last; the step order within each (the sort is stable).
430
+ const all = [...findings].sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
431
+ if (!all.length)
432
+ return [];
433
+ const c = counts(findings);
434
+ const count = [c.error ? plural(c.error, 'error') : '', c.warn ? plural(c.warn, 'warning') : '', c.info ? `${c.info} info` : ''].filter(Boolean).join(', ');
435
+ const out = [line(count)];
436
+ for (const f of all) {
437
+ const where = f.steps?.length ? stepsText(f.steps) : f.step === 0 ? 'before step 1' : f.step ? `step ${f.step}` : 'the whole run';
438
+ // Without the "Steps 2 and 7: " the line already says.
439
+ const text = lead(f.message.replace(/^Steps? [\d–, and]+: /, ''), 100);
440
+ out.push(line(undefined, f, `${f.confidence === 'unsure' ? 'unsure · ' : ''}${where}`, text));
441
+ }
442
+ return [...out, ''];
443
+ }
444
+ /**
445
+ * The start of a message, at most `max` characters: up to the last sentence end
446
+ * that fits, or cut with an ellipsis when none does. A sentence end inside quotes
447
+ * or brackets, or after "vs." or "e.g.", isn't one (a server's quoted words).
448
+ */
449
+ function lead(text, max) {
450
+ if (text.length <= max)
451
+ return text;
452
+ let depth = 0;
453
+ let straight = false;
454
+ let end = -1;
455
+ for (let i = 0; i < max; i++) {
456
+ const ch = text[i];
457
+ if (ch === '"')
458
+ straight = !straight;
459
+ else if ('“(['.includes(ch))
460
+ depth++;
461
+ else if ('”)]'.includes(ch))
462
+ depth = Math.max(0, depth - 1);
463
+ else if (ch === '.' && depth === 0 && !straight && text[i + 1] === ' ' && /[A-Z+~]/.test(text[i + 2] ?? '') && !/\b(vs|e\.g|i\.e|etc)$/i.test(text.slice(0, i)))
464
+ end = i;
465
+ }
466
+ return end > 0 ? text.slice(0, end + 1) : clip(text, max);
467
+ }
468
+ /** "menu: 5 → 8 tools (+3) · ~290 → ~479 tokens (+189, estimate) · changed at steps 2, 4, 5 and 7", or nothing when it never changed. */
469
+ function menuChange(s) {
470
+ const changed = s.steps.filter((st) => st.changed).map((st) => st.index);
471
+ if (!changed.length)
472
+ return undefined;
473
+ const signed = (n) => (n >= 0 ? `+${n.toLocaleString('en-US')}` : `−${Math.abs(n).toLocaleString('en-US')}`);
474
+ const tools = s.final.tools - s.baseline.tools;
475
+ const tokens = s.final.tokens - s.baseline.tokens;
476
+ return `${s.baseline.tools} → ${s.final.tools} tools${tools ? ` (${signed(tools)})` : ''} · ~${s.baseline.tokens.toLocaleString('en-US')} → ~${s.final.tokens.toLocaleString('en-US')} tokens (${signed(tokens)}, estimate) · changed at ${stepsText(changed)}`;
477
+ }
478
+ /** "calls: 6 · 6 answered, 0 tool errors, 0 failed" (and how many weren't sent), or nothing without call steps. */
479
+ function callCounts(s) {
480
+ const calls = s.steps.filter((st) => st.outcome);
481
+ if (!calls.length)
482
+ return undefined;
483
+ const n = (o) => calls.filter((st) => st.outcome === o).length;
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` : ''}`;
486
+ }
413
487
  export function formatPlan(scenario, name) {
414
488
  const lines = [`toolmenu session --plan ${name}`, ` allow_writes: ${scenario.allowWrites}${scenario.allowWrites ? '' : ' (tools not marked readOnlyHint will be refused)'}`, ''];
415
489
  scenario.steps.forEach((step, i) => lines.push(`step ${i + 1}: ${stepLabel(step)}${step.kind === 'wait_for' ? ` (up to ${step.timeoutMs} ms)` : ''}`));
@@ -185,7 +185,7 @@ export const lateInstruction = {
185
185
  // Past the default cut is description/buried's.
186
186
  const hidden = pastTheCut(text, all.filter((n) => n !== tool.name), SHORT_CUT).filter((i) => i.at < limit);
187
187
  if (hidden.length)
188
- late.push({ tool, at: hidden[0].at, sentence: sentenceAround(text, hidden[0].at), more: hidden.length - 1 });
188
+ late.push({ tool, at: hidden[0].at, straddles: hidden[0].straddles, sentence: sentenceAround(text, hidden[0].at), more: hidden.length - 1 });
189
189
  }
190
190
  if (late.length === 0)
191
191
  return [];
@@ -195,8 +195,9 @@ export const lateInstruction = {
195
195
  {
196
196
  ...(one ? { tool: late[0].tool.name } : {}),
197
197
  confidence: 'unsure',
198
- message: `${one ? `The ${late[0].tool.name} description gives` : `${late.length} descriptions give`} the agent instructions after character ${SHORT_CUT}, where a client that cuts descriptions short never shows them (one real client cut at ${SHORT_CUT}). ${client} sends ${num(limit)} characters, so there they arrive.`,
199
- detail: late.map((l) => `${l.tool.name}: char ${num(l.at)}: “${clip(l.sentence, 120)}”${l.more ? ` (and ${l.more} more after it)` : ''}`),
198
+ message: `${one ? `The ${late[0].tool.name} description gives` : `${late.length} descriptions give`} the agent instructions ${late.every((l) => l.straddles) ? `that run past character ${SHORT_CUT}` : late.some((l) => l.straddles) ? `after character ${SHORT_CUT} or running past it` : `after character ${SHORT_CUT}`}, where a client that cuts descriptions short never shows them (one real client cut at ${SHORT_CUT}). ${client} sends ${num(limit)} characters, so there they arrive.`,
199
+ // One that starts before the cut and runs past it is cut in the middle: say so, or "char 264" reads as before the cut.
200
+ detail: late.map((l) => `${l.tool.name}: char ${num(l.at)}${l.straddles ? ` (runs past ${SHORT_CUT})` : ''}: “${clip(l.sentence, 120)}”${l.more ? ` (and ${l.more} more after it)` : ''}`),
200
201
  fix: `If your client cuts descriptions, set descriptionLimit to its cut and toolmenu checks against that. Otherwise, moving ${one ? 'the instruction' : 'each instruction'} into the first sentences is cheap insurance.`,
201
202
  },
202
203
  ];
@@ -24,3 +24,4 @@ export declare function varianceFinding(main: MenuTool[], other: MenuTool[], opt
24
24
  }) | undefined;
25
25
  export declare const processVariance: Rule;
26
26
  export declare const connectionVariance: Rule;
27
+ export declare const hostSpecific: Rule;
@@ -238,3 +238,33 @@ function varianceRule(id, transport) {
238
238
  }
239
239
  export const processVariance = varianceRule('menu/process-variance', 'stdio');
240
240
  export const connectionVariance = varianceRule('menu/connection-variance', 'http');
241
+ /**
242
+ * A container or machine ID written into a description: two processes on one
243
+ * host serve the same menu, so menu/process-variance can't see it, but every
244
+ * install serves a different one (desktop-commander: "Container: 47d516a481f8").
245
+ * A run of 12–64 hex characters with a digit and a letter, right after a host word
246
+ * (container, host, hostname, machine, instance, pod, optionally "ID"): a fixed
247
+ * example ID ("Page ID, e.g. 1429989f…", an ObjectId, a pinned SHA) is the same on
248
+ * every install, so a hex value alone isn't enough.
249
+ */
250
+ const HOST_ID = /\b(?:container|host(?:name)?|machine|instance|pod)(?:[ _-]?id)?\b[\s:=#'"(]{1,4}((?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{12,64})(?![\w-])/i;
251
+ export const hostSpecific = {
252
+ id: 'menu/host-specific',
253
+ severity: 'info',
254
+ summary: 'A description holds a value that differs per host',
255
+ run(ctx) {
256
+ const findings = [];
257
+ for (const tool of ctx.menu.tools) {
258
+ const id = HOST_ID.exec(tool.description ?? '')?.[1];
259
+ if (!id)
260
+ continue;
261
+ findings.push({
262
+ tool: tool.name,
263
+ confidence: 'unsure',
264
+ message: `${tool.name}'s description contains ${id}, which looks like a container or machine ID. A value that differs per host gives every install a different menu, so no two share a prompt cache, and a restart on the same host won't show it.`,
265
+ fix: `Leave host details out of the description; if the agent needs them, return them from a tool call.`,
266
+ });
267
+ }
268
+ return findings;
269
+ },
270
+ };
@@ -0,0 +1,7 @@
1
+ import { type Rule } from './rule.js';
2
+ /**
3
+ * A server that unlocks tools and says its list can change may have served only
4
+ * its starting set. A baseline made from that misses every tool behind the unlock,
5
+ * so a diff can't see their breaking changes (a real server: 18 of 115 tools).
6
+ */
7
+ export declare const gated: Rule;