toolmenu 0.21.0 → 0.24.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.
Files changed (62) hide show
  1. package/README.md +96 -37
  2. package/dist/apps.d.ts +56 -0
  3. package/dist/apps.js +99 -0
  4. package/dist/auto.js +2 -2
  5. package/dist/card.d.ts +18 -0
  6. package/dist/card.js +39 -0
  7. package/dist/cli.d.ts +1 -1
  8. package/dist/cli.js +70 -11
  9. package/dist/colour.d.ts +8 -0
  10. package/dist/colour.js +70 -0
  11. package/dist/config.d.ts +2 -0
  12. package/dist/config.js +2 -0
  13. package/dist/connect.d.ts +15 -0
  14. package/dist/connect.js +54 -7
  15. package/dist/diff.js +113 -6
  16. package/dist/explain.d.ts +16 -0
  17. package/dist/explain.js +14 -0
  18. package/dist/failures.d.ts +18 -5
  19. package/dist/failures.js +27 -12
  20. package/dist/help.d.ts +1 -1
  21. package/dist/help.js +18 -3
  22. package/dist/mcp-env.d.ts +5 -0
  23. package/dist/mcp-env.js +5 -0
  24. package/dist/mcp.d.ts +65 -0
  25. package/dist/mcp.js +293 -0
  26. package/dist/mrtr.d.ts +9 -1
  27. package/dist/mrtr.js +17 -0
  28. package/dist/options.d.ts +3 -0
  29. package/dist/options.js +1 -0
  30. package/dist/probe.d.ts +11 -1
  31. package/dist/probe.js +18 -3
  32. package/dist/report.js +12 -5
  33. package/dist/rule-docs.json +94 -4
  34. package/dist/rules/apps.d.ts +11 -0
  35. package/dist/rules/apps.js +156 -0
  36. package/dist/rules/capabilities.d.ts +21 -0
  37. package/dist/rules/capabilities.js +103 -0
  38. package/dist/rules/card.d.ts +7 -0
  39. package/dist/rules/card.js +65 -0
  40. package/dist/rules/clients.js +1 -0
  41. package/dist/rules/description.js +3 -0
  42. package/dist/rules/headers.d.ts +0 -2
  43. package/dist/rules/headers.js +7 -12
  44. package/dist/rules/ids.js +35 -1
  45. package/dist/rules/index.js +18 -2
  46. package/dist/rules/naming.js +3 -0
  47. package/dist/rules/network.d.ts +21 -0
  48. package/dist/rules/network.js +63 -0
  49. package/dist/rules/rule.d.ts +18 -0
  50. package/dist/rules/search.js +1 -0
  51. package/dist/rules/spec.d.ts +9 -1
  52. package/dist/rules/spec.js +117 -3
  53. package/dist/rules/write.d.ts +0 -6
  54. package/dist/rules/write.js +11 -5
  55. package/dist/session.js +60 -11
  56. package/dist/snapshot.d.ts +5 -0
  57. package/dist/snapshot.js +89 -5
  58. package/dist/types.d.ts +5 -0
  59. package/dist/words.d.ts +8 -0
  60. package/dist/words.js +30 -2
  61. package/package.json +8 -7
  62. package/schemas/server-card.json +260 -0
package/dist/mcp.d.ts ADDED
@@ -0,0 +1,65 @@
1
+ import { McpServer } from '@modelcontextprotocol/server';
2
+ import { SECRET_ARGS_ENV } from './mcp-env.js';
3
+ export { SECRET_ARGS_ENV };
4
+ /** A whole run's ceiling. Each request inside it already has the CLI's own --timeout. */
5
+ export declare const RUN_LIMIT_MS: number;
6
+ export interface CliRun {
7
+ code: number;
8
+ stdout: string;
9
+ stderr: string;
10
+ /** Why the run was stopped, when toolmenu mcp stopped it. */
11
+ stopped?: string;
12
+ }
13
+ /** Kill every run still going, at once: toolmenu mcp itself is exiting. */
14
+ export declare function killAllNow(): void;
15
+ /** Stop every run still going, and wait for it: the client closed the connection. */
16
+ export declare function stopAll(): Promise<void>;
17
+ export interface RunOptions {
18
+ /** Arguments that carry credentials, passed through the environment (SECRET_ARGS_ENV). */
19
+ secretArgs?: string[];
20
+ signal?: AbortSignal;
21
+ limitMs?: number;
22
+ }
23
+ /** Run the toolmenu CLI with these arguments, from this folder. */
24
+ export declare function runCli(args: string[], cwd: string, options?: RunOptions): Promise<CliRun>;
25
+ type Text = {
26
+ content: {
27
+ type: 'text';
28
+ text: string;
29
+ }[];
30
+ isError?: boolean;
31
+ };
32
+ /** A CLI run as a tool result. Findings are a report, not a failure: only exit 2 (couldn't run) is an error. */
33
+ export declare function toResult(run: CliRun): Text;
34
+ type ServerArgs = {
35
+ command?: string[];
36
+ url?: string;
37
+ headers?: Record<string, string>;
38
+ env?: Record<string, string>;
39
+ cwd?: string;
40
+ };
41
+ export interface ServerSpec {
42
+ /** Before "--": the URL, if any. */
43
+ before: string[];
44
+ /** Header and env values, passed through the environment. */
45
+ secret: string[];
46
+ /** "--" and the command, if any. */
47
+ after: string[];
48
+ }
49
+ /** The CLI arguments that name the server, or why they can't. */
50
+ export declare function serverArgs(a: ServerArgs): ServerSpec | {
51
+ error: string;
52
+ };
53
+ /** The folder a call runs in, or why it can't. */
54
+ export declare function folder(baseCwd: string, cwd?: string): {
55
+ dir: string;
56
+ } | {
57
+ error: string;
58
+ };
59
+ export declare function build(baseCwd?: string): McpServer;
60
+ /**
61
+ * Serve over stdio until the client closes stdin, then stop every run still going.
62
+ * A client that closes stdin may send SIGTERM before the runs are stopped: on that, or
63
+ * on any exit, what's left is killed at once rather than left running.
64
+ */
65
+ export declare function serveMcp(): Promise<void>;
package/dist/mcp.js ADDED
@@ -0,0 +1,293 @@
1
+ /*
2
+ * `toolmenu mcp`: toolmenu as an MCP server (stdio), so an agent building an MCP
3
+ * server can check its menu while it works. Each tool runs the CLI in a child process
4
+ * (no shell) and returns its report: the same checks, options, config and exit codes
5
+ * as on the command line, and a crash or hang in one check can't take the server down.
6
+ *
7
+ * Each child runs in its own process group, so cancelling a call, its time running
8
+ * out, or the client closing the connection stops the child and the server it started.
9
+ */
10
+ import { spawn, spawnSync } from 'node:child_process';
11
+ import { statSync } from 'node:fs';
12
+ import { isAbsolute, resolve } from 'node:path';
13
+ import { fileURLToPath } from 'node:url';
14
+ import { McpServer } from '@modelcontextprotocol/server';
15
+ import { serveStdio } from '@modelcontextprotocol/server/stdio';
16
+ import * as z from 'zod';
17
+ import { CLIENT_NAMES } from './clients.js';
18
+ import { VERSION } from './version.js';
19
+ import { SECRET_ARGS_ENV } from './mcp-env.js';
20
+ export { SECRET_ARGS_ENV };
21
+ const CLI = fileURLToPath(new URL('./cli.js', import.meta.url));
22
+ /** A whole run's ceiling. Each request inside it already has the CLI's own --timeout. */
23
+ export const RUN_LIMIT_MS = 10 * 60_000;
24
+ const OUTPUT_LIMIT = 64 * 1024 * 1024;
25
+ const WINDOWS = process.platform === 'win32';
26
+ /**
27
+ * Runs still going, by the CLI's pid. On Linux and macOS each run is a process group
28
+ * (the CLI and the server it started), kept until nothing in it is alive, not until
29
+ * the CLI exits: a server that ignores SIGTERM outlives the CLI that started it.
30
+ * Windows has no process groups to signal: there a run is the CLI's process tree,
31
+ * which taskkill /T ends while the CLI is still its root.
32
+ */
33
+ const runs = new Map();
34
+ /** Whether anything in the run is still alive. */
35
+ function runAlive(pid) {
36
+ if (WINDOWS) {
37
+ const child = runs.get(pid);
38
+ return !!child && child.exitCode === null && child.signalCode === null;
39
+ }
40
+ try {
41
+ process.kill(-pid, 0);
42
+ return true;
43
+ }
44
+ catch {
45
+ return false;
46
+ }
47
+ }
48
+ /** Signal the whole run. On Windows, any stop is taskkill /T /F: there's no polite one for a console process. */
49
+ function signalRun(pid, signal) {
50
+ if (WINDOWS) {
51
+ spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
52
+ return;
53
+ }
54
+ try {
55
+ process.kill(-pid, signal);
56
+ }
57
+ catch {
58
+ // Already gone.
59
+ }
60
+ }
61
+ /** Stop a run: SIGTERM, then SIGKILL to whatever in it is still there 2 s later. */
62
+ async function stopRun(pid) {
63
+ if (runAlive(pid)) {
64
+ signalRun(pid, 'SIGTERM');
65
+ const end = Date.now() + 2_000;
66
+ while (runAlive(pid) && Date.now() < end)
67
+ await new Promise((r) => setTimeout(r, 50));
68
+ if (runAlive(pid))
69
+ signalRun(pid, 'SIGKILL');
70
+ }
71
+ runs.delete(pid);
72
+ }
73
+ /** Kill every run still going, at once: toolmenu mcp itself is exiting. */
74
+ export function killAllNow() {
75
+ for (const pid of runs.keys())
76
+ signalRun(pid, 'SIGKILL');
77
+ }
78
+ /** Stop every run still going, and wait for it: the client closed the connection. */
79
+ export async function stopAll() {
80
+ await Promise.all([...runs.keys()].map(stopRun));
81
+ }
82
+ /** Run the toolmenu CLI with these arguments, from this folder. */
83
+ export function runCli(args, cwd, options = {}) {
84
+ const { secretArgs = [], signal, limitMs = RUN_LIMIT_MS } = options;
85
+ return new Promise((done) => {
86
+ if (signal?.aborted)
87
+ return done({ code: 2, stdout: '', stderr: '', stopped: 'The call was cancelled before it started.' });
88
+ // NO_COLOR: the report goes to an agent, not a terminal. NODE_NO_WARNINGS: Node's
89
+ // own notices (experimental features) aren't findings, and would read as if they
90
+ // were. Neither reaches the server under test: it gets a minimal environment.
91
+ const env = { ...process.env, NO_COLOR: '1', NODE_NO_WARNINGS: '1' };
92
+ delete env[SECRET_ARGS_ENV];
93
+ if (secretArgs.length)
94
+ env[SECRET_ARGS_ENV] = JSON.stringify(secretArgs);
95
+ // detached: its own process group (Linux, macOS). On Windows it would open a console
96
+ // window for every run instead, so there the run stays attached and hidden.
97
+ const child = spawn(process.execPath, [CLI, ...args], { cwd, env, detached: !WINDOWS, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
98
+ if (child.pid)
99
+ runs.set(child.pid, child);
100
+ let stdout = '';
101
+ let stderr = '';
102
+ let stopped;
103
+ const halt = (why) => {
104
+ stopped ??= why;
105
+ if (child.pid)
106
+ void stopRun(child.pid);
107
+ };
108
+ child.stdout.on('data', (d) => {
109
+ stdout += d;
110
+ if (stdout.length > OUTPUT_LIMIT)
111
+ halt(`The report passed ${OUTPUT_LIMIT / 1024 / 1024} MB, so the run was stopped.`);
112
+ });
113
+ child.stderr.on('data', (d) => {
114
+ stderr += d;
115
+ if (stderr.length > OUTPUT_LIMIT)
116
+ stderr = stderr.slice(-OUTPUT_LIMIT);
117
+ });
118
+ const timer = setTimeout(() => halt(`The run took longer than ${limitMs / 60_000} minutes, so it was stopped. A server that is slow to answer each request can be given a longer --timeout in toolmenu.config.json, or fewer calls (max_calls).`), limitMs);
119
+ const onAbort = () => halt('The call was cancelled, so the run was stopped.');
120
+ signal?.addEventListener('abort', onAbort, { once: true });
121
+ let finished = false;
122
+ // A child that fails to start can emit both error and close: answer once.
123
+ const finish = (code) => {
124
+ if (finished)
125
+ return;
126
+ finished = true;
127
+ clearTimeout(timer);
128
+ signal?.removeEventListener('abort', onAbort);
129
+ // Whatever the CLI left behind (a server it couldn't stop) goes with it.
130
+ if (child.pid)
131
+ void stopRun(child.pid);
132
+ done({ code, stdout, stderr, ...(stopped ? { stopped } : {}) });
133
+ };
134
+ // Never Node's own error message: it repeats the command line.
135
+ child.on('error', (error) => {
136
+ stderr += `toolmenu mcp couldn't start the toolmenu CLI (${error.code ?? 'error'}).`;
137
+ finish(2);
138
+ });
139
+ child.on('close', (code) => finish(stopped ? 2 : code ?? 2));
140
+ });
141
+ }
142
+ /** A CLI run as a tool result. Findings are a report, not a failure: only exit 2 (couldn't run) is an error. */
143
+ export function toResult(run) {
144
+ const out = run.stdout.trim();
145
+ if (run.code === 2) {
146
+ const why = [run.stopped, run.stderr.trim()].filter(Boolean).join('\n\n') || out || 'toolmenu exited with code 2.';
147
+ return { content: [{ type: 'text', text: why }], isError: true };
148
+ }
149
+ const notes = run.stderr.trim();
150
+ const tail = run.code === 1 ? '\n\nExit 1: there are error-level findings.' : '';
151
+ return { content: [{ type: 'text', text: `${out || 'No output.'}${tail}${notes ? `\n\nNotes:\n${notes}` : ''}` }] };
152
+ }
153
+ const serverShape = {
154
+ command: z
155
+ .array(z.string())
156
+ .min(1)
157
+ .optional()
158
+ .describe('The command that starts a stdio server, one word per item: ["node", "dist/server.js"]. Give this or url.'),
159
+ url: z.string().optional().describe('A Streamable HTTP endpoint: https://example.com/mcp. Give this or command.'),
160
+ headers: z.record(z.string(), z.string()).optional().describe('HTTP headers for a url server: {"Authorization": "Bearer ..."}.'),
161
+ env: z.record(z.string(), z.string()).optional().describe('Environment variables for a command server. It gets a minimal environment plus these.'),
162
+ cwd: z.string().optional().describe('Folder to run from: where the server starts, toolmenu.config.json is read and relative paths resolve. Default: where toolmenu mcp runs.'),
163
+ };
164
+ /** The CLI arguments that name the server, or why they can't. */
165
+ export function serverArgs(a) {
166
+ if (!a.command === !a.url)
167
+ return { error: 'Give the server as command (a stdio server, e.g. ["node", "dist/server.js"]) or url (an HTTP server), one of the two.' };
168
+ if (a.url) {
169
+ if (a.env && Object.keys(a.env).length)
170
+ return { error: 'env goes with command: an HTTP server is already running. Use headers for credentials.' };
171
+ if (!/^https?:\/\//.test(a.url))
172
+ return { error: `url must be an http(s) URL; got "${a.url}". For a stdio server, give command.` };
173
+ return { before: [a.url], secret: Object.entries(a.headers ?? {}).flatMap(([k, v]) => ['--header', `${k}: ${v}`]), after: [] };
174
+ }
175
+ if (a.headers && Object.keys(a.headers).length)
176
+ return { error: 'headers go with url. Pass a stdio server its credentials with env.' };
177
+ return { before: [], secret: Object.entries(a.env ?? {}).flatMap(([k, v]) => ['--env', `${k}=${v}`]), after: ['--', ...a.command] };
178
+ }
179
+ /** The folder a call runs in, or why it can't. */
180
+ export function folder(baseCwd, cwd) {
181
+ const dir = cwd ? resolve(baseCwd, cwd) : baseCwd;
182
+ try {
183
+ if (statSync(dir).isDirectory())
184
+ return { dir };
185
+ return { error: `cwd "${cwd ?? dir}" is a file, not a folder.` };
186
+ }
187
+ catch {
188
+ return { error: `cwd "${cwd ?? dir}" doesn't exist (resolved to ${dir}). Give the server's project folder.` };
189
+ }
190
+ }
191
+ /** A path as an absolute one, so a value starting with "-" can't be read as an option. */
192
+ const absolute = (dir, path) => (isAbsolute(path) ? path : resolve(dir, path));
193
+ const failed = (text) => ({ content: [{ type: 'text', text }], isError: true });
194
+ export function build(baseCwd = process.cwd()) {
195
+ const server = new McpServer({ name: 'toolmenu', version: VERSION }, {
196
+ capabilities: { tools: {} },
197
+ // The same four tools for everyone, always: an hour, and shared caches may keep it.
198
+ cacheHints: { 'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' }, 'server/discover': { ttlMs: 3_600_000, cacheScope: 'public' } },
199
+ instructions: "toolmenu checks an MCP server's tool list (its menu) the way clients and agents meet it. " +
200
+ 'After changing a server\'s tools: snapshot_menu for findings and token cost, diff_menus against the committed menu.json for breaking changes, check_session to see whether the menu changes mid-session. ' +
201
+ 'Each finding ends with a → Next: step; explain_rule says what a rule checks.',
202
+ });
203
+ /** Run a command for a server: the folder checked, credentials kept out of argv. */
204
+ const forServer = async (a, ctx, args) => {
205
+ const s = serverArgs(a);
206
+ if ('error' in s)
207
+ return failed(s.error);
208
+ const f = folder(baseCwd, a.cwd);
209
+ if ('error' in f)
210
+ return failed(f.error);
211
+ return toResult(await runCli([...args(f.dir, s), ...s.after], f.dir, { secretArgs: s.secret, signal: ctx.mcpReq.signal }));
212
+ };
213
+ server.registerTool('snapshot_menu', {
214
+ description: "Check an MCP server's tool list: start or connect to it, list its tools, and report findings (what agents misread, what breaks clients or prompt caches) and the token cost. " +
215
+ 'Writes the menu file only when save_as is given (the baseline for diff_menus).',
216
+ inputSchema: {
217
+ ...serverShape,
218
+ save_as: z.string().optional().describe('Write the menu here (menu.json for a baseline), relative to cwd. Default: not written.'),
219
+ client: z.enum(CLIENT_NAMES).optional().describe('Also check the menu as this client loads it: what it cuts, finds and refuses.'),
220
+ catalog: z.boolean().optional().describe('Also read the operations behind a search tool or command routers.'),
221
+ },
222
+ annotations: { title: 'Snapshot a server menu', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
223
+ }, (a, ctx) => forServer(a, ctx, (dir, s) => [
224
+ 'snapshot',
225
+ ...s.before,
226
+ a.save_as ? `--out=${absolute(dir, a.save_as)}` : '--no-write',
227
+ ...(a.client ? [`--client=${a.client}`] : []),
228
+ ...(a.catalog ? ['--catalog'] : []),
229
+ ]));
230
+ server.registerTool('diff_menus', {
231
+ description: 'Compare two menu files (from snapshot_menu save_as, or toolmenu snapshot): breaking changes for clients, the token change per conversation, and the version bump it needs. Reads files only.',
232
+ inputSchema: {
233
+ before: z.string().describe('The older menu file, e.g. the committed menu.json.'),
234
+ after: z.string().describe('The newer menu file.'),
235
+ release: z.string().optional().describe('The release versions to check the bump against: "1.4.0..1.5.0".'),
236
+ cwd: serverShape.cwd,
237
+ },
238
+ annotations: { title: 'Diff two menus', readOnlyHint: true, openWorldHint: false },
239
+ }, async (a, ctx) => {
240
+ const f = folder(baseCwd, a.cwd);
241
+ if ('error' in f)
242
+ return failed(f.error);
243
+ const args = ['diff', absolute(f.dir, a.before), absolute(f.dir, a.after), ...(a.release ? [`--release=${a.release}`] : [])];
244
+ return toResult(await runCli(args, f.dir, { signal: ctx.mcpReq.signal }));
245
+ });
246
+ server.registerTool('check_session', {
247
+ description: "Check whether an MCP server's menu changes while an agent works: call its tools marked readOnlyHint whose arguments the schema can fill, list the menu after each call, and report each change with the call that caused it. " +
248
+ 'Calls only read-only tools; never one marked openWorldHint unless open_world is set.',
249
+ inputSchema: {
250
+ ...serverShape,
251
+ max_calls: z.number().int().min(1).optional().describe('At most this many calls (default 20).'),
252
+ open_world: z.boolean().optional().describe('Also call read-only tools marked openWorldHint (web search, fetch): they may cost API credits.'),
253
+ },
254
+ annotations: { title: 'Run a session against a server', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
255
+ }, (a, ctx) => forServer(a, ctx, (_dir, s) => [
256
+ 'session',
257
+ '--auto',
258
+ ...s.before,
259
+ ...(a.max_calls ? [`--max-calls=${a.max_calls}`] : []),
260
+ ...(a.open_world ? ['--open-world'] : []),
261
+ ]));
262
+ server.registerTool('explain_rule', {
263
+ description: "Explain a toolmenu rule by the name a finding gives (naming/vague-id): what it checks, its default level and how to change it. Without rule, lists every rule.",
264
+ inputSchema: { rule: z.string().optional().describe('The rule, as a finding names it: naming/vague-id, or just vague-id.') },
265
+ annotations: { title: 'Explain a rule', readOnlyHint: true, openWorldHint: false },
266
+ }, async (a, ctx) => {
267
+ if (a.rule !== undefined && !/^[a-z0-9][a-z0-9/_-]*$/i.test(a.rule))
268
+ return failed(`"${a.rule}" isn't a rule name. Rules look like naming/vague-id; call explain_rule without rule to list them.`);
269
+ return toResult(await runCli(['explain', ...(a.rule ? [a.rule] : [])], baseCwd, { signal: ctx.mcpReq.signal }));
270
+ });
271
+ return server;
272
+ }
273
+ /**
274
+ * Serve over stdio until the client closes stdin, then stop every run still going.
275
+ * A client that closes stdin may send SIGTERM before the runs are stopped: on that, or
276
+ * on any exit, what's left is killed at once rather than left running.
277
+ */
278
+ export async function serveMcp() {
279
+ process.once('exit', killAllNow);
280
+ for (const [signal, code] of [['SIGTERM', 143], ['SIGINT', 130], ['SIGHUP', 129]]) {
281
+ process.once(signal, () => {
282
+ killAllNow();
283
+ process.exit(code);
284
+ });
285
+ }
286
+ const handle = serveStdio(() => build());
287
+ await new Promise((done) => {
288
+ process.stdin.once('end', done);
289
+ process.stdin.once('close', done);
290
+ });
291
+ await stopAll();
292
+ await handle.close().catch(() => { });
293
+ }
package/dist/mrtr.d.ts CHANGED
@@ -20,7 +20,7 @@ export interface InputTrace {
20
20
  * bad-state: its requestState isn't a string, so it can't be echoed byte for byte;
21
21
  * calling again without it would run the tool again from scratch.
22
22
  */
23
- outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'unfinished' | 'undeclared' | 'decline-failed' | 'bad-state';
23
+ outcome: 'none' | 'completed' | 'loop' | 'gave-up' | 'unfinished' | 'undeclared' | 'decline-failed' | 'bad-state' | 'task';
24
24
  /** Kinds asked for that the request didn't declare. */
25
25
  undeclared?: InputKind[];
26
26
  /** The protocol error a retry failed with (decline-failed): the server's words, and its JSON-RPC code. */
@@ -32,6 +32,14 @@ export interface InputTrace {
32
32
  continuations?: number;
33
33
  /** A raw result on the wire without resultType, which 2026-07-28 servers MUST send. */
34
34
  missingResultType?: boolean;
35
+ /**
36
+ * task: the server answered with a CreateTaskResult (resultType "task", ext-tasks),
37
+ * which it MUST NOT send to a client that didn't declare io.modelcontextprotocol/tasks.
38
+ */
39
+ task?: {
40
+ taskId?: string;
41
+ status?: string;
42
+ };
35
43
  }
36
44
  type CallResult = Awaited<ReturnType<Connection['client']['callTool']>>;
37
45
  /**
package/dist/mrtr.js CHANGED
@@ -13,6 +13,16 @@ import { httpStatus, tooMany } from './failures.js';
13
13
  export const MAX_ROUNDS = 3;
14
14
  /** Rounds that carry only requestState (the tool keeps working, asks nothing) before toolmenu stops. */
15
15
  export const MAX_CONTINUATIONS = 10;
16
+ /** A CreateTaskResult (ext-tasks): resultType "task", with the task's id and status. */
17
+ function taskOf(result) {
18
+ if (!isObject(result) || result.resultType !== 'task')
19
+ return undefined;
20
+ const task = isObject(result.task) ? result.task : result;
21
+ return {
22
+ ...(typeof task.taskId === 'string' ? { taskId: task.taskId } : {}),
23
+ ...(typeof task.status === 'string' ? { status: task.status } : {}),
24
+ };
25
+ }
16
26
  const DECLARED = new Set(['form', 'url']);
17
27
  function kindOf(request) {
18
28
  if (request.method === 'elicitation/create')
@@ -100,6 +110,10 @@ export async function callWithInput(conn, params, options) {
100
110
  // What the server sent decides what failed, not the error the SDK raised.
101
111
  const wire = conn.wire.since(mark, 'tools/call').at(-1);
102
112
  const answered = wire?.result;
113
+ // A task handle toolmenu didn't ask for (it declares no Tasks support): nothing to poll.
114
+ const task = taskOf(answered);
115
+ if (task)
116
+ return { input: trace('task', { task }) };
103
117
  if (isObject(answered) && !('resultType' in answered)) {
104
118
  // No resultType: the SDK client rejects it ("missing required resultType").
105
119
  // The server did answer; session/result-type says why clients won't take it.
@@ -126,6 +140,9 @@ export async function callWithInput(conn, params, options) {
126
140
  return { input: trace('decline-failed', { error: { message: firstLine(wire.error.message ?? error), ...(typeof code === 'number' ? { code } : {}) } }) };
127
141
  }
128
142
  }
143
+ const task = taskOf(conn.wire.since(mark, 'tools/call').at(-1)?.result ?? result);
144
+ if (task)
145
+ return { input: trace('task', { task }) };
129
146
  if (result.resultType !== 'input_required')
130
147
  return { result: result, input: trace(finished()) };
131
148
  const required = result;
package/dist/options.d.ts CHANGED
@@ -5,6 +5,9 @@ export declare const CLI_OPTIONS: {
5
5
  readonly 'out-dir': {
6
6
  readonly type: 'string';
7
7
  };
8
+ readonly 'offline-check': {
9
+ readonly type: 'boolean';
10
+ };
8
11
  readonly concurrency: {
9
12
  readonly type: 'string';
10
13
  };
package/dist/options.js CHANGED
@@ -5,6 +5,7 @@
5
5
  export const CLI_OPTIONS = {
6
6
  out: { type: 'string' },
7
7
  'out-dir': { type: 'string' },
8
+ 'offline-check': { type: 'boolean' },
8
9
  concurrency: { type: 'string' },
9
10
  'no-write': { type: 'boolean' },
10
11
  routes: { type: 'string' },
package/dist/probe.d.ts CHANGED
@@ -44,4 +44,14 @@ export declare function probeMenu(target: Target, timeoutMs: number, waits?: num
44
44
  * HTTP probe that differs is retried once: a rolling deploy can serve two
45
45
  * versions for a moment.
46
46
  */
47
- export declare function probeVariance(target: Target, main: MenuTool[], processes: number, timeoutMs: number, waits?: number[]): Promise<Probe[]>;
47
+ /**
48
+ * probeMenu, on the protocol an earlier connection got. Negotiated as usual (so errors
49
+ * read as they always have); only a probe that ends on the other protocol is asked
50
+ * again, pinned to that one. Under load a version probe can time out and fall back to
51
+ * 2025 in one process only, and a menu from another protocol differs in ways no
52
+ * client sees (mastra's $schema): a false variance (the 0.22 corpus run).
53
+ */
54
+ export declare function probeSameEra(target: Target, era: string | undefined, timeoutMs: number, waits?: number[], waited?: {
55
+ ms: number;
56
+ }, seen?: Set<string>): Promise<Menu>;
57
+ export declare function probeVariance(target: Target, main: MenuTool[], processes: number, timeoutMs: number, waits?: number[], era?: string, seen?: Set<string>): Promise<Probe[]>;
package/dist/probe.js CHANGED
@@ -75,15 +75,30 @@ export async function probeMenu(target, timeoutMs, waits, waited) {
75
75
  * HTTP probe that differs is retried once: a rolling deploy can serve two
76
76
  * versions for a moment.
77
77
  */
78
- export async function probeVariance(target, main, processes, timeoutMs, waits) {
78
+ /**
79
+ * probeMenu, on the protocol an earlier connection got. Negotiated as usual (so errors
80
+ * read as they always have); only a probe that ends on the other protocol is asked
81
+ * again, pinned to that one. Under load a version probe can time out and fall back to
82
+ * 2025 in one process only, and a menu from another protocol differs in ways no
83
+ * client sees (mastra's $schema): a false variance (the 0.22 corpus run).
84
+ */
85
+ export async function probeSameEra(target, era, timeoutMs, waits, waited, seen) {
86
+ const m = await probeMenu(target, timeoutMs, waits, waited);
87
+ if (m.server.era)
88
+ seen?.add(m.server.era);
89
+ if (!era || target.protocol || m.server.era === era)
90
+ return m;
91
+ return probeMenu({ ...target, protocol: era === 'modern' ? 'modern' : 'legacy' }, timeoutMs, waits, waited);
92
+ }
93
+ export async function probeVariance(target, main, processes, timeoutMs, waits, era, seen) {
79
94
  const probes = [];
80
95
  for (let i = 0; i < processes - 1; i++) {
81
96
  const seed = String(Number(PROBE_SEED) + i);
82
97
  const waited = { ms: 0 };
83
98
  try {
84
- let tools = (await probeMenu(seeded(target, seed), timeoutMs, waits, waited)).tools;
99
+ let tools = (await probeSameEra(seeded(target, seed), era, timeoutMs, waits, waited, seen)).tools;
85
100
  if (target.kind === 'http' && compareMenus(main, tools).length)
86
- tools = (await probeMenu(target, timeoutMs, waits, waited)).tools;
101
+ tools = (await probeSameEra(target, era, timeoutMs, waits, waited)).tools;
87
102
  probes.push({ tools });
88
103
  }
89
104
  catch (error) {
package/dist/report.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { agentMenu } from './apps.js';
1
2
  import { clip, stepLabel, stepsText } from './session.js';
2
3
  import { SEVERITY_RANK } from './types.js';
3
4
  import { breakdown, breakdownLines, breakdownMarkdown } from './breakdown.js';
@@ -28,7 +29,12 @@ function costLine(cost) {
28
29
  ].filter(Boolean);
29
30
  return `as ${cost.label}: ${parts.join(' · ')}`;
30
31
  }
32
+ /** " · 2 not shown to the agent (MCP Apps visibility without "model", ~60 tokens)", or nothing. */
33
+ function appOnlyNote(a) {
34
+ return a ? ` · ${a.tools} not shown to the agent (MCP Apps visibility without "model", ~${a.tokens.toLocaleString('en-US')} tokens)` : '';
35
+ }
31
36
  export function formatSnapshot(menu, findings, format, outPath, cost, notOffered = []) {
37
+ const view = agentMenu(menu);
32
38
  if (format === 'json') {
33
39
  return JSON.stringify({
34
40
  command: 'snapshot',
@@ -36,7 +42,8 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
36
42
  tools: menu.tools.length,
37
43
  totalTokens: menu.totalTokens,
38
44
  listMeta: menu.listMeta,
39
- breakdown: breakdown(menu),
45
+ ...(view.appOnly ? { appOnly: view.appOnly } : {}),
46
+ breakdown: breakdown(view.shown),
40
47
  ...(cost ? { client: cost } : {}),
41
48
  ...(menu.prompts ? { prompts: menu.prompts.length } : {}),
42
49
  ...(menu.resources ? { resources: menu.resources.length } : {}),
@@ -54,18 +61,18 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
54
61
  return [
55
62
  `### toolmenu snapshot: \`${s.name ?? 'server'}\` ${s.version ?? ''}`.trimEnd(),
56
63
  '',
57
- `Protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
64
+ `Protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
58
65
  ...(cost ? ['', `${costLine(cost)}. _${cost.basis}._`] : []),
59
66
  ...(otherLists(menu) ? ['', `Also listed: ${otherLists(menu)}`] : []),
60
67
  '',
61
68
  ...mdFindings(findings),
62
- ...mdBreakdown(menu),
69
+ ...mdBreakdown(view.shown),
63
70
  ].join('\n');
64
71
  }
65
72
  const s = menu.server;
66
73
  const lines = [
67
74
  `toolmenu snapshot ${s.name ?? 'unknown server'} ${s.version ?? ''}`.trimEnd(),
68
- ` protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)`,
75
+ ` protocol ${s.protocolVersion ?? 'unknown'} · ${plural(menu.tools.length, 'tool')} · ~${menu.totalTokens.toLocaleString('en-US')} tokens (estimate)${appOnlyNote(view.appOnly)}`,
69
76
  ];
70
77
  if (cost)
71
78
  lines.push(` ${costLine(cost)}`, ` ${cost.basis}`);
@@ -77,7 +84,7 @@ export function formatSnapshot(menu, findings, format, outPath, cost, notOffered
77
84
  if (outPath)
78
85
  lines.push(` wrote ${outPath}`);
79
86
  lines.push('');
80
- const where = breakdownLines(breakdown(menu), menu.tools.length);
87
+ const where = breakdownLines(breakdown(view.shown), view.shown.tools.length);
81
88
  if (where.length)
82
89
  lines.push(...where, '');
83
90
  lines.push(...findingLines(findings));