toolmenu 0.13.0 → 0.14.1
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 -4
- package/dist/auth.js +6 -4
- package/dist/auto.d.ts +11 -1
- package/dist/auto.js +8 -3
- package/dist/breakdown.js +3 -1
- package/dist/cli.js +100 -25
- package/dist/close.d.ts +8 -0
- package/dist/close.js +18 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.js +3 -0
- package/dist/connect.d.ts +10 -0
- package/dist/connect.js +20 -7
- package/dist/diff.js +53 -7
- package/dist/explain.d.ts +10 -0
- package/dist/explain.js +29 -2
- package/dist/failures.d.ts +6 -0
- package/dist/failures.js +42 -2
- package/dist/help.d.ts +2 -0
- package/dist/help.js +13 -6
- package/dist/init.d.ts +1 -0
- package/dist/init.js +1 -1
- package/dist/options.d.ts +6 -0
- package/dist/options.js +2 -0
- package/dist/report.d.ts +1 -1
- package/dist/report.js +76 -2
- package/dist/rules/description.js +4 -3
- package/dist/rules/determinism.d.ts +1 -0
- package/dist/rules/determinism.js +30 -0
- package/dist/rules/gated.d.ts +7 -0
- package/dist/rules/gated.js +77 -0
- package/dist/rules/index.js +6 -2
- package/dist/rules/naming.js +26 -3
- package/dist/rules/rule.d.ts +7 -0
- package/dist/rules/spec.d.ts +6 -0
- package/dist/rules/spec.js +23 -0
- package/dist/rules/write.js +25 -7
- package/dist/session.d.ts +16 -1
- package/dist/session.js +54 -15
- package/dist/snapshot.d.ts +6 -0
- package/dist/snapshot.js +16 -0
- package/dist/types.d.ts +7 -0
- package/package.json +2 -2
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
|
-
|
|
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
|
-
|
|
375
|
-
|
|
376
|
-
|
|
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,
|
|
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
|
-
|
|
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.',
|
|
@@ -1106,7 +1148,11 @@ function expandRefs(schema) {
|
|
|
1106
1148
|
return { ...walk(target, [...stack, o.$ref]), ...walk(siblings, stack) };
|
|
1107
1149
|
}
|
|
1108
1150
|
}
|
|
1109
|
-
|
|
1151
|
+
// A $ref left as a $ref (a recursive definition past MAX_UNROLL): `definitions` and `$defs` are one
|
|
1152
|
+
// place under two spellings, and the root pool is dropped below, so the reference reads the same.
|
|
1153
|
+
// Left as written, a generator upgrade that renames the pool made every recursive $ref look like a
|
|
1154
|
+
// different option ("no longer accepts #/definitions/x" beside the unchanged #/$defs/x).
|
|
1155
|
+
return Object.fromEntries(Object.entries(o).map(([k, v]) => [k, k === '$ref' && typeof v === 'string' ? v.replace(/^#\/definitions\//, '#/$defs/') : walk(v, stack)]));
|
|
1110
1156
|
};
|
|
1111
1157
|
const { $defs: _defs, definitions: _definitions, ...rest } = schema;
|
|
1112
1158
|
try {
|
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
|
|
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
|
-
:
|
|
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.
|
package/dist/failures.d.ts
CHANGED
|
@@ -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)
|
|
15
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
];
|
|
@@ -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;
|