toolmenu 0.18.0 → 0.20.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 CHANGED
@@ -23,7 +23,15 @@ connections and releases, and checks **when** it changes:
23
23
  It also checks the menu clients will actually show: a broken `x-mcp-header` or a
24
24
  `$ref` they can't resolve hides a tool or fails every call to it. And when a tool
25
25
  stops to ask the user something, `session` answers "no" and says whether the tool
26
- can take it.
26
+ can take it. Handles a server mints (`session_id`) should say how long they last and
27
+ fail readably when unknown; menus that differ by who asks (`--as`) shouldn't be
28
+ cached as public; prompts and resources (`--lists`) are checked like tools. Run
29
+ against the reference server, `@modelcontextprotocol/server-everything` 2.1.0, with
30
+ no false findings ([bench/](bench/README.md)).
31
+ - **For your client.** `--client claude-code | claude-api-search | openai` checks the
32
+ menu the way that client loads it, from its own docs: what it costs up front and per
33
+ tool a search loads, where it cuts descriptions, what its search can find, and names
34
+ its API refuses.
27
35
  - **Between releases.** `diff` finds breaking changes and token growth, and checks
28
36
  the version bump.
29
37
 
@@ -247,9 +255,9 @@ the way OpenAPI breaking-change checkers do it:
247
255
 
248
256
  | Class | Changes | Rules |
249
257
  |---|---|---|
250
- | **breaking** (error) | tool removed or renamed, parameter removed, new required parameter, narrower or different type, enum narrowed, unlisted properties now rejected (`additionalProperties: false` added), a tool becoming less safe (no longer read-only, or additive → destructive) | `diff/tool-removed`, `diff/tool-renamed`, `diff/param-removed`, `diff/param-required`, `diff/param-type`, `diff/enum-narrowed`, `diff/properties-closed`, `diff/safety-hint` |
251
- | **minor** (info) | tool added, new optional parameter, parameter now optional, type or enum widened, unlisted properties now accepted (`additionalProperties: false` removed) | `diff/tool-added`, `diff/param-added`, `diff/param-relaxed`, `diff/type-widened`, `diff/enum-widened`, `diff/properties-opened` |
252
- | **notice** (info) | optional parameter dropped (extra properties still allowed), description changed (with the text diff: it changes what the agent does), output schema, annotations, other fields, order, a schema restructured but accepting the same input, only the declared `$schema` dialect changed | `diff/param-dropped`, `diff/description`, `diff/schema-other`, `diff/annotations`, `diff/other`, `diff/order`, `diff/schema-equivalent`, `diff/schema-dialect` |
258
+ | **breaking** (error) | tool removed or renamed, parameter removed, new required parameter, narrower or different type, enum narrowed, unlisted properties now rejected (`additionalProperties: false` added), a tool becoming less safe (no longer read-only, or additive → destructive); with `--lists` on both sides, a prompt removed or newly requiring an argument, a resource template removed | `diff/tool-removed`, `diff/tool-renamed`, `diff/param-removed`, `diff/param-required`, `diff/param-type`, `diff/enum-narrowed`, `diff/properties-closed`, `diff/safety-hint`, `diff/prompt-removed`, `diff/prompt-argument-required`, `diff/resource-template-removed` |
259
+ | **minor** (info) | tool added, new optional parameter, parameter now optional, type or enum widened, unlisted properties now accepted (`additionalProperties: false` removed), a prompt or resource template added | `diff/tool-added`, `diff/param-added`, `diff/param-relaxed`, `diff/type-widened`, `diff/enum-widened`, `diff/properties-opened`, `diff/prompt-added`, `diff/resource-template-added` |
260
+ | **notice** (info) | optional parameter dropped (extra properties still allowed), description changed (with the text diff: it changes what the agent does), output schema, annotations, other fields, order, a schema restructured but accepting the same input, only the declared `$schema` dialect changed, a prompt's description or optional arguments, resources added or gone (data, so no bump) | `diff/param-dropped`, `diff/description`, `diff/schema-other`, `diff/annotations`, `diff/other`, `diff/order`, `diff/schema-equivalent`, `diff/schema-dialect`, `diff/prompt-changed`, `diff/resources` |
253
261
 
254
262
  The same rules apply inside parameters: fields of an object parameter, array items,
255
263
  and the options of an `anyOf`/`oneOf` union (zod's unions, discriminated unions and
@@ -391,9 +399,12 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
391
399
  | `ids/handle-lifetime` | info | 2026-07-28: a tool that creates a handle another tool takes back (`start_session` → `session_id`) doesn't say how long it lasts (heuristic) |
392
400
  | `write/unannotated` | warn | Tools named like writes (`delete_`, `send_`…) with no annotations, as one summary grouped by the annotation each name suggests |
393
401
  | `naming/shared-word` | info | Nouns that name different things across tools (`list_team_audits` vs `get_audit_trail`), as one summary |
402
+ | `write/read-only-mismatch` | warn | A tool marked `readOnlyHint: true` whose name says it writes (`create_my_account`): clients act on the hint, and `--auto` doesn't call it on the hint alone (heuristic) |
394
403
  | `write/no-dry-run` | info | Destructive tools with no dry-run parameter or preview tool, as one summary |
395
404
  | `spec/discover` | info | The server only speaks the 2025 protocol, so 2026-07-28 rules are skipped |
396
405
  | `spec/deprecated`, `spec/cache-hints` | info | 2026-07-28: deprecated features still advertised; `ttlMs: 0`, or `cacheScope: "public"` on a server that took credentials |
406
+ | `lists/variance` | warn | With `--lists`: `prompts/list`, `resources/list` or `resources/templates/list` differs between two calls, or from a second process or connection (2026-07-28: lists no longer vary per connection) |
407
+ | `lists/schema` | error | With `--lists`: a list result that doesn't match the official schema (2026-07-28 requires `ttlMs` and `cacheScope` on each), or a declared list that fails to answer (warn; info for Method not found, or a setup failure such as missing credentials) |
397
408
  | `naming/client-name` | warn | With `--client`: tool names the client's API refuses: `^[a-zA-Z0-9_-]{1,128}$` for the Claude API, `^[a-zA-Z0-9_-]+$` up to 128 for OpenAI's functions. MCP allows names such as `files.read` that neither takes as they are |
398
409
  | `menu/auth-variance` | info | With `--as` (or `identities` in the config): the tool set differs by identity, what each adds, lacks or defines differently against the first, and its tokens. Allowed by the spec; a baseline of one identity's menu doesn't cover the others. An identity that can't be listed is said here too |
399
410
  | `spec/cache-scope-public` | warn | 2026-07-28, with `--as`: the tool set differs by identity, and `tools/list` says `cacheScope: "public"`, which lets shared caches serve one caller's list to another |
@@ -455,7 +466,7 @@ client doesn't document is left out, not guessed.
455
466
  |---|---|---|---|---|
456
467
  | `claude-code` | tool names; full definitions for tools marked `_meta["anthropic/alwaysLoad"]` | reads a description up to 4,096 characters | 16,384 through search, 4,096 up front | Claude API's |
457
468
  | `claude-api-search` | nothing from tools you defer (keep the 3–5 used most loaded) | name, description, argument names and descriptions; 5 results by default | none documented | `^[a-zA-Z0-9_-]{1,128}$` |
458
- | `openai` | not in OpenAI's spec, so no figure | not in the spec, so `search/findable` doesn't run | none documented | `^[a-zA-Z0-9_-]+$`, up to 128 |
469
+ | `openai` | each deferred function's name and description (its schema loads on demand); a deferred MCP server shows only its own name and description | how many results, and which fields, isn't documented, so `search/findable` doesn't run | none documented | `^[a-zA-Z0-9_-]+$`, up to 128 |
459
470
 
460
471
  The snapshot adds a line such as `as Claude Code: up front ~524 tokens · on demand ~344
461
472
  per tool a search loads (largest: update_contacts, ~2,093)`, and `--json` a `client`
@@ -493,6 +504,8 @@ toolmenu sees what the server sends. Plenty of agent failures happen elsewhere:
493
504
  (2026-07-28 only; an error if the server lacks it)
494
505
  --processes <n> server processes or connections to compare (default: 2);
495
506
  1 opens no second one, session's scope check included
507
+ --lists <kinds> snapshot: also read and check prompts, resources (comma-separated);
508
+ saved in the menu file beside the tools
496
509
  --client <name> snapshot: check the menu for one client, from its own docs:
497
510
  claude-code, claude-api-search or openai
498
511
  --as <name>:<cred> snapshot: list the menu as this identity too, repeatable:
package/dist/auto.js CHANGED
@@ -3,7 +3,7 @@ import { isMap, isNode, isScalar, parseDocument } from 'yaml';
3
3
  import { synthesizeArgs } from './args.js';
4
4
  import { createdKinds, handleParams } from './rules/handles.js';
5
5
  import { MAX_UNLOCKS, unlockers } from './session.js';
6
- import { COLLECTION_VERBS, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
6
+ import { COLLECTION_VERBS, commonWords, leadingVerb, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
7
7
  /** Marked or named as a write: never called on the user's word. Says why, or undefined. */
8
8
  export function writeSign(tool) {
9
9
  const a = tool.annotations ?? {};
@@ -42,7 +42,11 @@ export function autoScenario(menu, options = {}) {
42
42
  else
43
43
  assumed.add(name);
44
44
  }
45
- const readOnly = (t) => t.annotations?.readOnlyHint === true || assumed.has(t.name);
45
+ // The server's readOnlyHint, but not against a name that says it writes: a hosted
46
+ // server marked create_my_ideal_account read-only (write/read-only-mismatch).
47
+ const common = commonWords(menu.tools.map((t) => t.name));
48
+ const namedWrite = (t) => WRITE_VERBS.has(leadingVerb(t.name, common) ?? '');
49
+ const readOnly = (t) => (t.annotations?.readOnlyHint === true && !namedWrite(t)) || assumed.has(t.name);
46
50
  const { perTool, ignored: unusedValues } = resolveValues(menu, options.values ?? {});
47
51
  ignored.push(...unusedValues);
48
52
  const candidates = [];
@@ -63,7 +67,9 @@ export function autoScenario(menu, options = {}) {
63
67
  continue;
64
68
  const a = tool.annotations ?? {};
65
69
  if (!readOnly(tool)) {
66
- const write = writeSign(tool);
70
+ const write = a.readOnlyHint === true && namedWrite(tool)
71
+ ? `the server marks it readOnlyHint, but its name starts with "${leadingVerb(tool.name, common)}", a write: not called on the hint alone`
72
+ : writeSign(tool);
67
73
  skipped.push(write || a.readOnlyHint !== undefined ? { tool: tool.name, reason: 'not read-only', ...(write ? { why: write } : {}) } : { tool: tool.name, reason: 'unmarked' });
68
74
  continue;
69
75
  }
package/dist/catalog.js CHANGED
@@ -294,6 +294,10 @@ const FAILED_AS = {
294
294
  what: ['wanted credentials before it would list its commands', 'wanted credentials before they would list their commands'],
295
295
  fix: "Rerun with the server's credentials (--env for a stdio server, --header for HTTP); if these routers aren't yours to watch, ignore this.",
296
296
  },
297
+ payment: {
298
+ what: ['asked for payment before it would list its commands', 'asked for payment before they would list their commands'],
299
+ fix: "Listing these routers' commands costs money here; rerun with an account that has credit if they're yours to watch, or ignore this.",
300
+ },
297
301
  environment: {
298
302
  what: ["needs something this machine doesn't have", "need something this machine doesn't have"],
299
303
  fix: 'Install what the error names where toolmenu starts the server (the same container or CI image), then rerun.',
package/dist/cli.js CHANGED
@@ -3,6 +3,7 @@ import { writeFile } from 'node:fs/promises';
3
3
  import { join } from 'node:path';
4
4
  import { parseArgs } from 'node:util';
5
5
  import { CLIENT_NAMES, CLIENTS } from './clients.js';
6
+ import { LIST_WORDS } from './lists.js';
6
7
  import { loadConfig } from './config.js';
7
8
  import { ELICITATIONS, PROTOCOLS } from './connect.js';
8
9
  import { diffMenus } from './diff.js';
@@ -83,9 +84,15 @@ export async function main(argv) {
83
84
  const elicitation = (values.elicitation ?? 'decline');
84
85
  if (!ELICITATIONS.includes(elicitation))
85
86
  throw new UsageError('--elicitation must be decline or cancel');
87
+ if (values.lists !== undefined && sub !== 'snapshot')
88
+ throw new UsageError('--lists goes with snapshot.');
89
+ const lists = values.lists !== undefined ? values.lists.split(',').map((w) => w.trim()).filter(Boolean) : config.lists;
90
+ const badList = (lists ?? []).find((w) => !LIST_WORDS.includes(w));
91
+ if (badList)
92
+ throw new UsageError(`--lists takes ${LIST_WORDS.join(', ')}, comma-separated; not "${badList}"`);
86
93
  if (values.client !== undefined && sub !== 'snapshot')
87
94
  throw new UsageError('--client goes with snapshot.');
88
- if (values.client !== undefined && !(values.client in CLIENTS))
95
+ if (values.client !== undefined && !Object.hasOwn(CLIENTS, values.client))
89
96
  throw new UsageError(`--client must be one of ${CLIENT_NAMES.join(', ')}`);
90
97
  if (values.as !== undefined && sub !== 'snapshot')
91
98
  throw new UsageError('--as goes with snapshot: it lists the menu once per identity.');
@@ -306,11 +313,11 @@ export async function main(argv) {
306
313
  const routesPath = values.routes ?? config.routes;
307
314
  const routes = routesPath ? await loadRoutes(routesPath) : undefined;
308
315
  const client = values.client ?? config.client;
309
- const { menu, findings, cost } = await snapshot(target, { routes, timeoutMs, processes, identities, client, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
316
+ const { menu, findings, cost, notOffered } = await snapshot(target, { routes, timeoutMs, processes, identities, client, lists, catalog: values.catalog ? (config.catalog ?? true) : undefined, rules: config.rules, ignore: config.ignore, descriptionLimit: config.descriptionLimit, fullDescriptions: config.fullDescriptions });
310
317
  const outPath = values['no-write'] ? undefined : values.out ?? 'menu.json';
311
318
  if (outPath)
312
319
  await writeFile(outPath, JSON.stringify(menu, null, 2) + '\n');
313
- const output = formatSnapshot(menu, findings, format, outPath, cost);
320
+ const output = formatSnapshot(menu, findings, format, outPath, cost, notOffered);
314
321
  if (output)
315
322
  process.stdout.write(output + '\n');
316
323
  return findings.some((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[failOn]) ? 1 : 0;
package/dist/clients.d.ts CHANGED
@@ -14,7 +14,11 @@ export interface ClientProfile {
14
14
  */
15
15
  defers: Sourced<'all' | 'chosen' | 'none'>;
16
16
  /** What the model has of a deferred tool before it searches: its name, or nothing. */
17
- beforeSearch?: Sourced<'name' | 'nothing'>;
17
+ /**
18
+ * What the model has of a deferred tool before it searches: its name, nothing, or its
19
+ * name and description (OpenAI defers the parameter schema).
20
+ */
21
+ beforeSearch?: Sourced<'name' | 'nothing' | 'name-and-description'>;
18
22
  /** Where the client cuts a description: for a tool loaded up front, and one loaded through search. */
19
23
  descriptionCut?: Sourced<{
20
24
  upfront: number;
@@ -37,6 +41,8 @@ export interface ClientProfile {
37
41
  }
38
42
  export declare const CLIENTS: Record<string, ClientProfile>;
39
43
  export declare const CLIENT_NAMES: string[];
44
+ /** A client's profile by name: own keys only ("toString" names no client). */
45
+ export declare function profileOf(name: string | undefined): ClientProfile | undefined;
40
46
  /** The profile for a client name, or undefined for none given. Throws for an unknown name. */
41
47
  export declare function clientProfile(name: string | undefined): ClientProfile | undefined;
42
48
  /** Whether a tool name fits the client's API, and why not. */
package/dist/clients.js CHANGED
@@ -9,6 +9,7 @@ const CLAUDE_CODE_MCP = 'https://code.claude.com/docs/en/mcp';
9
9
  const CLAUDE_TOOL_SEARCH = 'https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool';
10
10
  const CLAUDE_DEFINE_TOOLS = 'https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools';
11
11
  const OPENAI_SPEC = 'https://github.com/openai/openai-openapi (openapi.yaml: FunctionToolParam, NamespaceToolParam, MCPTool)';
12
+ const OPENAI_TOOL_SEARCH = 'https://developers.openai.com/api/docs/guides/tools-tool-search';
12
13
  const READ = '2026-11-02';
13
14
  const claudeName = { value: { pattern: '^[a-zA-Z0-9_-]{1,128}$', max: 128, api: 'the Claude API' }, source: CLAUDE_DEFINE_TOOLS, read: READ };
14
15
  export const CLIENTS = {
@@ -42,16 +43,26 @@ export const CLIENTS = {
42
43
  label: "OpenAI's tool_search (Responses API)",
43
44
  // FunctionToolParam.defer_loading, MCPTool.defer_loading: per function, or per MCP server.
44
45
  defers: { value: 'chosen', source: OPENAI_SPEC, read: READ },
46
+ // "For an individual deferred function, the model still sees the function name and description,
47
+ // so in practice tool search is mostly deferring the parameter schema." For an MCP server or
48
+ // namespace, "the model sees only the namespace or server name and description at the beginning".
49
+ beforeSearch: { value: 'name-and-description', source: OPENAI_TOOL_SEARCH, read: '2026-11-03' },
50
+ // Not in the guide or the spec: how many tools a search returns, and which fields it matches on.
51
+ // So search/findable doesn't rank for OpenAI.
45
52
  // FunctionToolParam.name: maxLength 128, pattern ^[a-zA-Z0-9_-]+$.
46
53
  namePattern: { value: { pattern: '^[a-zA-Z0-9_-]+$', max: 128, api: "OpenAI's Responses API" }, source: OPENAI_SPEC, read: READ },
47
54
  },
48
55
  };
49
56
  export const CLIENT_NAMES = Object.keys(CLIENTS);
57
+ /** A client's profile by name: own keys only ("toString" names no client). */
58
+ export function profileOf(name) {
59
+ return name !== undefined && Object.hasOwn(CLIENTS, name) ? CLIENTS[name] : undefined;
60
+ }
50
61
  /** The profile for a client name, or undefined for none given. Throws for an unknown name. */
51
62
  export function clientProfile(name) {
52
63
  if (name === undefined)
53
64
  return undefined;
54
- const profile = CLIENTS[name];
65
+ const profile = profileOf(name);
55
66
  if (!profile)
56
67
  throw new Error(`unknown client "${name}": one of ${CLIENT_NAMES.join(', ')}`);
57
68
  return profile;
@@ -75,21 +86,33 @@ export function loadsUpfront(tool) {
75
86
  }
76
87
  /** What the menu costs under a client that defers tools: up front, and per tool a search loads. */
77
88
  export function clientCost(name, menu) {
78
- const profile = CLIENTS[name];
89
+ const profile = profileOf(name);
79
90
  if (!profile || profile.defers.value === 'none')
80
91
  return undefined;
81
92
  const loaded = profile.defers.value === 'all' ? menu.tools.filter(loadsUpfront) : [];
82
93
  const deferred = menu.tools.filter((t) => !loaded.includes(t));
83
- const perTool = deferred.length ? Math.round(deferred.reduce((n, t) => n + t.tokens, 0) / deferred.length) : 0;
84
- const largest = [...deferred].sort((a, b) => b.tokens - a.tokens)[0];
85
94
  const loadedTokens = loaded.reduce((n, t) => n + t.tokens, 0);
86
95
  const seen = profile.beforeSearch?.value;
87
- const upfront = seen === 'name' ? countTokens(deferred.map((t) => t.name).join('\n')) + loadedTokens : seen === 'nothing' ? loadedTokens : undefined;
96
+ // OpenAI keeps a deferred function's name and description up front: what a search adds is the rest.
97
+ const seenUpfront = (t) => countTokens(`${t.name}\n${t.description ?? ''}`);
98
+ const upfront = seen === 'name'
99
+ ? countTokens(deferred.map((t) => t.name).join('\n')) + loadedTokens
100
+ : seen === 'nothing'
101
+ ? loadedTokens
102
+ : seen === 'name-and-description'
103
+ ? deferred.reduce((n, t) => n + seenUpfront(t), 0) + loadedTokens
104
+ : undefined;
105
+ const onDemand = (t) => (seen === 'name-and-description' ? Math.max(0, t.tokens - seenUpfront(t)) : t.tokens);
88
106
  const basis = seen === 'name'
89
107
  ? `${profile.label} defers MCP tools and shows their names until a search loads one; the server's instructions load up front too and aren't counted here (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
90
108
  : seen === 'nothing'
91
109
  ? `with every tool deferred, the model sees none of them until a search loads one, and the docs advise keeping the 3–5 tools used most loaded (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
92
- : `${profile.label} defers per function or per MCP server; what the model sees before a search isn't in ${profile.defers.source}, so no up-front figure`;
110
+ : seen === 'name-and-description'
111
+ ? `deferred as functions, each tool's name and description stay up front and its schema loads on demand; deferred as one MCP server, the model sees only the server's name and description (set where the server is added) until a search loads its tools (${profile.beforeSearch.source}, read ${profile.beforeSearch.read})`
112
+ : `${profile.label} defers per function or per MCP server; what the model sees before a search isn't documented, so no up-front figure`;
113
+ const perTool = deferred.length ? Math.round(deferred.reduce((n, t) => n + onDemand(t), 0) / deferred.length) : 0;
114
+ const biggest = [...deferred].sort((a, b) => onDemand(b) - onDemand(a))[0];
115
+ const largest = biggest ? { name: biggest.name, tokens: onDemand(biggest) } : undefined;
93
116
  return {
94
117
  client: name,
95
118
  label: profile.label,
package/dist/config.d.ts CHANGED
@@ -26,6 +26,8 @@ export interface Config {
26
26
  headers?: Record<string, string>;
27
27
  env?: Record<string, string>;
28
28
  }>;
29
+ /** snapshot: which lists to read besides tools: ["prompts", "resources"]. --lists wins. */
30
+ lists?: string[];
29
31
  /** snapshot: the client to check the menu for (claude-code, claude-api-search, openai). --client wins. */
30
32
  client?: string;
31
33
  /** Server processes (stdio) or connections (HTTP) to compare, the main one included (default 2). */
package/dist/config.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { existsSync } from 'node:fs';
2
2
  import { readFile } from 'node:fs/promises';
3
3
  import { CLIENTS } from './clients.js';
4
+ import { LIST_WORDS } from './lists.js';
4
5
  import { CLIENT_LIMITS } from './rules/description.js';
5
6
  const DEFAULT_PATH = 'toolmenu.config.json';
6
7
  /** Optional: no config file is fine. */
@@ -24,13 +25,16 @@ export async function loadConfig(path) {
24
25
  throw new Error(`${file}: protocol must be auto, legacy or modern`);
25
26
  }
26
27
  const limit = config.descriptionLimit;
27
- if (limit !== undefined && !(typeof limit === 'number' && limit > 0) && !(typeof limit === 'string' && limit in CLIENT_LIMITS)) {
28
+ if (limit !== undefined && !(typeof limit === 'number' && limit > 0) && !(typeof limit === 'string' && Object.hasOwn(CLIENT_LIMITS, limit))) {
28
29
  throw new Error(`${file}: descriptionLimit must be a positive number or one of ${Object.keys(CLIENT_LIMITS).join(', ')}`);
29
30
  }
30
31
  if (config.processes !== undefined && !(Number.isInteger(config.processes) && config.processes >= 1)) {
31
32
  throw new Error(`${file}: processes must be a whole number, 1 or more`);
32
33
  }
33
- if (config.client !== undefined && !(typeof config.client === 'string' && config.client in CLIENTS)) {
34
+ if (config.lists !== undefined && !(Array.isArray(config.lists) && config.lists.every((l) => LIST_WORDS.includes(l)))) {
35
+ throw new Error(`${file}: lists must be a list of ${LIST_WORDS.join(', ')}`);
36
+ }
37
+ if (config.client !== undefined && !(typeof config.client === 'string' && Object.hasOwn(CLIENTS, config.client))) {
34
38
  throw new Error(`${file}: client must be one of ${Object.keys(CLIENTS).join(', ')}`);
35
39
  }
36
40
  if (config.identities !== undefined) {
package/dist/diff.js CHANGED
@@ -53,6 +53,17 @@ export const DIFF_RULES = {
53
53
  'diff/catalog-missing': { severity: 'info' },
54
54
  'diff/catalog-added': { severity: 'info' },
55
55
  'diff/catalog-queries': { severity: 'info' },
56
+ // snapshot --lists: prompts are called by name like tools, and resource templates are
57
+ // the URIs clients read through. Concrete resources are data (files come and go):
58
+ // counted, no bump. Only compared when both menus read the list.
59
+ 'diff/prompt-removed': { severity: 'error', class: 'breaking' },
60
+ 'diff/prompt-argument-required': { severity: 'error', class: 'breaking' },
61
+ 'diff/prompt-added': { severity: 'info', class: 'minor' },
62
+ 'diff/prompt-changed': { severity: 'info', class: 'notice' },
63
+ 'diff/resource-template-removed': { severity: 'error', class: 'breaking' },
64
+ 'diff/resource-template-added': { severity: 'info', class: 'minor' },
65
+ 'diff/resources': { severity: 'info', class: 'notice' },
66
+ 'diff/lists-unread': { severity: 'info' },
56
67
  };
57
68
  /**
58
69
  * In fixes: the release a breaking change should ship in. Resolved once the
@@ -135,6 +146,7 @@ export function diffMenus(before, after, options = {}) {
135
146
  });
136
147
  }
137
148
  raw.push(...compareCatalogs(before.catalog, after.catalog, ignored));
149
+ raw.push(...compareLists(before, after));
138
150
  // Ignored tools leave the token counts and the budget too.
139
151
  const tokens = tokenChange(oldTools, newTools);
140
152
  if (options.tokenBudget !== undefined && tokens.after > options.tokenBudget) {
@@ -1220,6 +1232,84 @@ function expandRefs(schema) {
1220
1232
  return { schema, expanded: false };
1221
1233
  }
1222
1234
  }
1235
+ /** The arguments a prompt requires. */
1236
+ function requiredArguments(p) {
1237
+ return (Array.isArray(p.arguments) ? p.arguments : []).filter((a) => a.required === true).map((a) => String(a.name));
1238
+ }
1239
+ /**
1240
+ * snapshot --lists: prompts, resource templates and resources between two menus.
1241
+ * A list only one menu read isn't compared (everything would read as added or removed).
1242
+ */
1243
+ function compareLists(before, after) {
1244
+ const out = [];
1245
+ const unread = [];
1246
+ const pair = (key, label) => {
1247
+ const a = before[key];
1248
+ const b = after[key];
1249
+ if (!a && !b)
1250
+ return undefined;
1251
+ if (!a || !b) {
1252
+ unread.push(`${label} (${a ? 'the old' : 'the new'} menu has them, the ${a ? 'new' : 'old'} one wasn't read with --lists)`);
1253
+ return undefined;
1254
+ }
1255
+ return [a, b];
1256
+ };
1257
+ const prompts = pair('prompts', 'prompts');
1258
+ if (prompts) {
1259
+ const [a, b] = prompts;
1260
+ const oldBy = new Map(a.map((p) => [String(p.name), p]));
1261
+ const newBy = new Map(b.map((p) => [String(p.name), p]));
1262
+ for (const [name] of oldBy) {
1263
+ if (!newBy.has(name))
1264
+ out.push({ rule: 'diff/prompt-removed', message: `Prompt ${code(name)} was removed. Users and clients that invoke it by name (a slash command, a saved workflow) now get an error.`, fix: `Keep ${code(name)} for one release, or ${BREAKING_RELEASE}.` });
1265
+ }
1266
+ for (const [name, p] of newBy) {
1267
+ const old = oldBy.get(name);
1268
+ if (!old) {
1269
+ out.push({ rule: 'diff/prompt-added', message: `Prompt ${code(name)} is new.` });
1270
+ continue;
1271
+ }
1272
+ const required = requiredArguments(p).filter((r) => !requiredArguments(old).includes(r));
1273
+ if (required.length) {
1274
+ out.push({ rule: 'diff/prompt-argument-required', message: `Prompt ${code(name)} now requires ${required.map(code).join(', ')}. Invocations that don't pass ${required.length === 1 ? 'it' : 'them'} now fail.`, fix: `Make ${required.length === 1 ? 'it' : 'them'} optional, or ${BREAKING_RELEASE}.` });
1275
+ }
1276
+ else if (JSON.stringify(old) !== JSON.stringify(p)) {
1277
+ out.push({ rule: 'diff/prompt-changed', message: `Prompt ${code(name)} changed (its description or arguments), and nothing it requires.` });
1278
+ }
1279
+ }
1280
+ }
1281
+ const templates = pair('resourceTemplates', 'resource templates');
1282
+ if (templates) {
1283
+ const [a, b] = templates;
1284
+ const oldSet = new Set(a.map((t) => String(t.uriTemplate)));
1285
+ const newSet = new Set(b.map((t) => String(t.uriTemplate)));
1286
+ for (const t of oldSet)
1287
+ if (!newSet.has(t))
1288
+ out.push({ rule: 'diff/resource-template-removed', message: `Resource template ${code(t)} was removed. Clients that read resources through it now get an error.`, fix: `Keep ${code(t)} for one release, or ${BREAKING_RELEASE}.` });
1289
+ for (const t of newSet)
1290
+ if (!oldSet.has(t))
1291
+ out.push({ rule: 'diff/resource-template-added', message: `Resource template ${code(t)} is new.` });
1292
+ }
1293
+ const resources = pair('resources', 'resources');
1294
+ if (resources) {
1295
+ const [a, b] = resources;
1296
+ const oldSet = new Set(a.map((r) => String(r.uri)));
1297
+ const newSet = new Set(b.map((r) => String(r.uri)));
1298
+ const gone = [...oldSet].filter((u) => !newSet.has(u));
1299
+ const fresh = [...newSet].filter((u) => !oldSet.has(u));
1300
+ if (gone.length || fresh.length) {
1301
+ out.push({
1302
+ rule: 'diff/resources',
1303
+ message: `The resources list changed: ${[fresh.length ? `${fresh.length} new` : '', gone.length ? `${gone.length} gone` : ''].filter(Boolean).join(', ')}. Resources are often data that changes between runs; a resource clients rely on by URI going away is worth a look.`,
1304
+ detail: [...gone.slice(0, 5).map((u) => `gone: ${u}`), ...fresh.slice(0, 5).map((u) => `new: ${u}`), ...(gone.length + fresh.length > 10 ? ['…'] : [])],
1305
+ });
1306
+ }
1307
+ }
1308
+ if (unread.length) {
1309
+ out.push({ rule: 'diff/lists-unread', message: `Not compared: ${unread.join('; ')}.`, fix: 'Snapshot both releases with the same --lists to compare them.' });
1310
+ }
1311
+ return out;
1312
+ }
1223
1313
  /** What the operations are behind: the search tool or router by name, or "the command routers" as words. */
1224
1314
  function catalogSource(c) {
1225
1315
  return (c.routers?.length ?? 0) > 1 ? c.tool : code(c.tool);
package/dist/explain.d.ts CHANGED
@@ -124,3 +124,11 @@ export interface ExplainContext {
124
124
  * when there's nothing to add (a refusal for too many requests keeps its own path).
125
125
  */
126
126
  export declare function explain(error: unknown, trace: Trace, context: ExplainContext): unknown;
127
+ /**
128
+ * A proxy this machine sets that Node's built-in fetch ignores: it reads HTTPS_PROXY
129
+ * only with NODE_USE_ENV_PROXY=1 (Node 22.21 and later). Behind such a proxy, every
130
+ * host looks like it doesn't resolve.
131
+ */
132
+ export declare function ignoredProxy(env?: NodeJS.ProcessEnv, host?: string): string | undefined;
133
+ /** What to do about an ignored proxy, for this Node. */
134
+ export declare function proxyAdvice(proxy: string, version?: string): string;
package/dist/explain.js CHANGED
@@ -164,7 +164,10 @@ const HELP_ROW = /^[ \t]*(?:[a-z][\w.-]*(?: [a-z][\w-]*)?(?: [[<][^\]>]*[\]>])*|
164
164
  /** Help output, even when the "Usage:" line scrolled out of the stderr kept: three table rows or more. */
165
165
  const helpRows = (text) => text.split('\n').filter((l) => HELP_ROW.test(l)).length >= 3;
166
166
  // The subcommands that usually start the MCP server, most specific first.
167
- const SUBCOMMANDS = ['mcp start', 'mcp serve', 'server start', 'mcp', 'stdio', 'serve', 'server', 'start'];
167
+ const SUBCOMMANDS = ['mcp start', 'mcp serve', 'server start', 'mcp', 'stdio', 'serve', 'server', 'start', 'run'];
168
+ // A CLI that names its commands when it gets none: "Unknown command: undefined. Expected
169
+ // 'init' or 'run'." (@cloudflare/mcp-server-cloudflare 0.2.0).
170
+ const EXPECTED_COMMANDS = /\b(?:unknown|invalid|missing|no) (?:sub)?command\b[^\n]*?\bexpected:?\s+((?:["'`][a-z][\w-]*["'`](?:,?\s*(?:or\s+)?)?)+)/i;
168
171
  // An HTTP server's address in its log: "MCP server listening on http://localhost:3001/mcp",
169
172
  // "StreamableHTTP endpoint available at http://127.0.0.1:3333/mcp".
170
173
  const HTTP_URL = /\b(?:listening|available|running|serving|started)\b[^\n]{0,60}?(https?:\/\/[^\s"'<>]+)/gi;
@@ -202,6 +205,10 @@ function offeredSubcommand(text) {
202
205
  for (const m of text.matchAll(/\{([^{}\n]*)\}/g))
203
206
  for (const w of m[1].split(','))
204
207
  offered.add(w.trim());
208
+ const expected = EXPECTED_COMMANDS.exec(text);
209
+ if (expected)
210
+ for (const m of expected[1].matchAll(/["'`]([a-z][\w-]*)["'`]/g))
211
+ offered.add(m[1]);
205
212
  let inUsage = false;
206
213
  for (const line of text.split('\n')) {
207
214
  if (!line.trim()) {
@@ -236,7 +243,7 @@ export function startupHint(trace, command, { exited = true } = {}) {
236
243
  const where = url ?? `http://localhost:${port}/mcp`;
237
244
  return `The server started an HTTP server (${where}) instead of talking on its stdin and stdout. Start it in stdio mode (${flag ? `its output mentions ${flag}` : 'often --stdio or --transport stdio'}), or run toolmenu against the address while the server runs: toolmenu snapshot ${where}`;
238
245
  }
239
- if (exited && (USAGE.some((re) => re.test(text)) || helpRows(text))) {
246
+ if (exited && (USAGE.some((re) => re.test(text)) || helpRows(text) || EXPECTED_COMMANDS.test(text))) {
240
247
  const sub = offeredSubcommand(text);
241
248
  return `The command printed its usage and exited: it wants a subcommand or an argument it wasn't given. ${sub ? `Its usage lists “${sub}”: try ${command} ${sub}` : 'Its usage (above) or its docs say what starts the MCP server: add that after the command.'}`;
242
249
  }
@@ -460,6 +467,28 @@ function rejectedCredentials(stderrText) {
460
467
  return REJECTED.exec(stderrText)?.[0];
461
468
  }
462
469
  const REJECTED_NEXT = "Check the API key or token the server was given (--env, or its config): it's likely wrong, expired or for another account. This is a reading of the server's log, not certain: read its stderr above.";
470
+ /**
471
+ * A proxy this machine sets that Node's built-in fetch ignores: it reads HTTPS_PROXY
472
+ * only with NODE_USE_ENV_PROXY=1 (Node 22.21 and later). Behind such a proxy, every
473
+ * host looks like it doesn't resolve.
474
+ */
475
+ export function ignoredProxy(env = process.env, host) {
476
+ if (env.NODE_USE_ENV_PROXY === '1')
477
+ return undefined;
478
+ // A host NO_PROXY exempts goes direct either way: its DNS failure is its own.
479
+ const exempt = (env.NO_PROXY ?? env.no_proxy ?? '').split(',').map((h) => h.trim().replace(/^\*?\./, '').toLowerCase()).filter(Boolean);
480
+ if (host && exempt.some((h) => h === '*' || host.toLowerCase() === h || host.toLowerCase().endsWith(`.${h}`)))
481
+ return undefined;
482
+ return ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy'].find((k) => env[k]);
483
+ }
484
+ /** What to do about an ignored proxy, for this Node. */
485
+ export function proxyAdvice(proxy, version = process.versions.node) {
486
+ const [major, minor] = version.split('.').map(Number);
487
+ const supported = major > 22 || (major === 22 && minor >= 21);
488
+ return supported
489
+ ? `This machine sets ${proxy}, but Node's fetch only goes through it with NODE_USE_ENV_PROXY=1: rerun as NODE_USE_ENV_PROXY=1 toolmenu ….`
490
+ : `This machine sets ${proxy}, but Node's fetch doesn't go through it, and Node ${version} can't be told to: Node 22.21 or later reads it with NODE_USE_ENV_PROXY=1.`;
491
+ }
463
492
  function firstLine(text) {
464
493
  return clean(text.split('\n')[0], 300);
465
494
  }
@@ -477,9 +506,19 @@ function explainHttp(error, trace, context, target) {
477
506
  const innermost = chain.at(-1);
478
507
  // The network, before any HTTP answer.
479
508
  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
480
- return new ConnectError(code === 'ENOTFOUND' ? `Couldn't find ${host}: the name doesn't resolve (DNS: ENOTFOUND).` : `Couldn't look up ${host}: DNS failed for now (EAI_AGAIN).`, [['url', target.url], ['stage', first]], code === 'ENOTFOUND'
481
- ? "Check the host name for typos. If it's right, the server may have moved or shut down: look up its current URL in its docs or registry entry."
482
- : 'Check this machine\'s network and DNS, then retry.', stage, { cause: error });
509
+ const proxy = ignoredProxy(process.env, host);
510
+ return new ConnectError(code === 'ENOTFOUND' ? `Couldn't find ${host}: the name doesn't resolve (DNS: ENOTFOUND).` : `Couldn't look up ${host}: DNS failed for now (EAI_AGAIN).`, [['url', target.url], ['stage', first], ...(proxy ? [['proxy', `${proxy} is set, but Node's fetch doesn't use it`]] : [])], proxy
511
+ ? proxyAdvice(proxy)
512
+ : code === 'ENOTFOUND'
513
+ ? "Check the host name for typos. If it's right, the server may have moved or shut down: look up its current URL in its docs or registry entry."
514
+ : 'Check this machine\'s network and DNS, then retry.', stage, { cause: error });
515
+ }
516
+ // A proxy that won't open the tunnel (undici: "Proxy response (502) !== 200 when HTTP Tunneling").
517
+ const tunnel = chain.map((e) => /Proxy response \((\d+)\) !== 200 when HTTP Tunneling/.exec(e.message)).find(Boolean);
518
+ if (tunnel) {
519
+ return new ConnectError(`The proxy couldn't open a connection to ${host}: it answered the tunnel request with HTTP ${tunnel[1]}.`, [['url', target.url], ['stage', first]], tunnel[1] === '403' || tunnel[1] === '407'
520
+ ? `The proxy refused ${host}: check what HTTPS_PROXY's policy allows, or run from a machine that can reach it directly.`
521
+ : `The proxy couldn't reach ${host} (often: the host is down or doesn't answer). Check that the server is up, e.g. curl -I ${target.url}, then retry.`, stage, { cause: error });
483
522
  }
484
523
  if (code === 'ECONNREFUSED') {
485
524
  return new ConnectError(`Nothing is listening at ${host}:${port}: the connection was refused (ECONNREFUSED).`, [['url', target.url], ['stage', first]], `Start the server, or check the host and port${url.port ? '' : ` (no port in the URL means ${port})`}.`, stage, { cause: error });
@@ -1,4 +1,4 @@
1
- export type FailureClass = 'auth' | 'environment' | 'network' | 'not-found' | 'client' | 'invalid-arguments' | 'other';
1
+ export type FailureClass = 'auth' | 'payment' | 'environment' | 'network' | 'not-found' | 'client' | 'invalid-arguments' | 'other';
2
2
  /** Failures of the setup (credentials, this machine, the network), not of the server. */
3
3
  export declare const SETUP_FAILURES: Set<FailureClass>;
4
4
  /**
package/dist/failures.js CHANGED
@@ -5,7 +5,7 @@
5
5
  * as a finding.
6
6
  */
7
7
  /** Failures of the setup (credentials, this machine, the network), not of the server. */
8
- export const SETUP_FAILURES = new Set(['auth', 'environment', 'network', 'not-found', 'client']);
8
+ export const SETUP_FAILURES = new Set(['auth', 'payment', 'environment', 'network', 'not-found', 'client']);
9
9
  // A tool that asks the client for something toolmenu doesn't offer: "Cannot request
10
10
  // input 'roots' (roots/list): the request's client capabilities do not declare the
11
11
  // required capability" (server-everything's get-roots-list), sampling, elicitation.
@@ -22,6 +22,11 @@ const ENVIRONMENT = /could not find [^.]{0,40}executable|is not found at \/|\bno
22
22
  // Netlify" (Netlify), "The API key you provided was rejected" (Pinecone), "Admin
23
23
  // auth is missing", "Runtime credentials are missing" (securenow). Not a bare
24
24
  // "token": plenty of errors mention one.
25
+ // Hosted servers ask the user to sign in in their own words: "Sign in to Ideal (or create
26
+ // your creator account) to continue", "Connect your Novamris account to read its saved chart".
27
+ const SIGN_IN = /\bsign in to\b|\blog ?in to (?:continue|use)\b|\bconnect your [\w .'-]{1,40}? account\b/i;
28
+ // A paid tool: "Payment required: $0.50 over MPP" (a hosted server), HTTP 402, no credits left.
29
+ const PAYMENT = /\bpayment required\b|\b(?:HTTP|status(?: code)?) 402\b|\binsufficient (?:credits?|balance|funds)\b/i;
25
30
  const AUTH = /\b(?:auth|authentication|credentials?|api[ _-]?key|access token)\b (?:is |are )?missing\b|\bno (?:authentication|auth|credentials?|api[ _-]?keys?|access tokens?|auth tokens?) (?:was |were )?(?:found|provided|configured|set|given)\b|\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;
26
31
  const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH)\b|socket hang up|getaddrinfo|network error/i;
27
32
  // "Either 'page_id' OR both 'title' and 'space_key' must be provided" (Atlassian),
@@ -164,7 +169,9 @@ export function classifyFailure(text, options = {}) {
164
169
  return 'client';
165
170
  if (ENVIRONMENT.test(text))
166
171
  return 'environment';
167
- if (AUTH.test(text))
172
+ if (PAYMENT.test(text))
173
+ return 'payment';
174
+ if (AUTH.test(text) || SIGN_IN.test(text))
168
175
  return 'auth';
169
176
  if (NETWORK.test(text))
170
177
  return 'network';
@@ -176,6 +183,7 @@ export function classifyFailure(text, options = {}) {
176
183
  }
177
184
  export const FAILURE_LABELS = {
178
185
  auth: 'authentication',
186
+ payment: 'payment (a paid tool)',
179
187
  environment: 'something missing on this machine',
180
188
  network: 'the network',
181
189
  'not-found': 'a 404 on a call that named nothing (usually the account or site behind the credentials)',
@@ -194,6 +202,8 @@ export function setupFailureAdvice(classes, transport) {
194
202
  const steps = [];
195
203
  if (set.has('auth') || set.has('not-found'))
196
204
  steps.push(`If the errors are about credentials, rerun with real ones (${credentials}); a test account is enough.`);
205
+ if (set.has('payment'))
206
+ steps.push('If a tool asks for payment, it can\'t be checked without paying: leave it out of the scenario, or run with an account that has credit.');
197
207
  if (set.has('environment'))
198
208
  steps.push('If something is missing on this machine (a browser, a binary, a module), install it where the server runs, or run the server in its own container image.');
199
209
  if (set.has('client'))
package/dist/help.js CHANGED
@@ -19,6 +19,7 @@ const OPTIONS = {
19
19
  env: ['--env <K=V>', ['environment variable for a stdio server, repeatable. The server only', 'gets a minimal environment (PATH, HOME, ...) plus these']],
20
20
  protocol: ['--protocol <auto|legacy|modern>', ['which handshake to make (default: auto)', 'legacy: the 2025 handshake only; modern: 2026-07-28 only, an error if the server lacks it']],
21
21
  as: ['--as <name>[:<credential>]', ['list the menu as this identity too, repeatable: a header ("reader:Authorization:', 'Bearer ...") or env var ("admin:ROLE=admin") on top of --header/--env. The first', 'is the main one (its menu is saved); the others are compared with it']],
22
+ lists: ['--lists <kinds>', ['which lists to read and check, comma-separated: tools (always),', 'prompts, resources (resources/list and resources/templates/list).', 'Saved in the menu file beside the tools']],
22
23
  client: ['--client <name>', ['check the menu for one client, from its own docs: claude-code (tools deferred,', 'its description cut and search), claude-api-search (Claude API tool search)', 'or openai (Responses API tool_search): cost up front and per tool, names it refuses']],
23
24
  'no-auth': ['--no-auth', ["don't use a stored OAuth login (toolmenu auth login) for this server"]],
24
25
  timeout: ['--timeout <ms>', ['per-request timeout (default: 30000)']],
@@ -79,7 +80,7 @@ const HELP = {
79
80
  'reports what in the menu confuses agents or breaks prompt caches.',
80
81
  SERVER_NOTE,
81
82
  ],
82
- own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client'],
83
+ own: ['out', 'no-write', 'routes', 'catalog', 'as', 'client', 'lists'],
83
84
  shared: ['config', 'format', 'json', 'fail-on', 'header', 'env', 'no-auth', 'protocol', 'timeout', 'processes'],
84
85
  examples: [
85
86
  'toolmenu snapshot -- npx -y @modelcontextprotocol/server-memory',
@@ -0,0 +1,40 @@
1
+ import { type Connection } from './connect.js';
2
+ export declare const LIST_KINDS: readonly ['prompts', 'resources', 'resourceTemplates'];
3
+ export type ListKind = (typeof LIST_KINDS)[number];
4
+ /** The --lists words: `resources` reads both resources/list and resources/templates/list. */
5
+ export declare const LIST_WORDS: readonly ['tools', 'prompts', 'resources'];
6
+ /** Each list's JSON-RPC method, result key, the key that names an item, and its words. */
7
+ export declare const LIST_INFO: Record<ListKind, {
8
+ method: string;
9
+ key: string;
10
+ id: string;
11
+ one: string;
12
+ capability: 'prompts' | 'resources';
13
+ }>;
14
+ /** Pages read at most: a resources list can be a whole file tree. */
15
+ export declare const MAX_PAGES = 50;
16
+ export interface ListRead {
17
+ kind: ListKind;
18
+ items: Record<string, unknown>[];
19
+ /** Raw result pages, as received (spec/schema checks them). */
20
+ pages: Record<string, unknown>[];
21
+ listMeta: {
22
+ ttlMs?: number;
23
+ cacheScope?: string;
24
+ };
25
+ /** Stopped at MAX_PAGES. */
26
+ truncated?: boolean;
27
+ /** Why it couldn't be read. */
28
+ error?: string;
29
+ /** The JSON-RPC error code it failed with, when there was one (-32601: method not found). */
30
+ code?: number;
31
+ }
32
+ /** Read one list, page by page, as the server sends it. */
33
+ export declare function readList(connection: Connection, kind: ListKind, timeoutMs?: number): Promise<ListRead>;
34
+ /** The list kinds the --lists words ask for that the server declares a capability for, and the ones it doesn't. */
35
+ export declare function kindsToRead(words: string[], capabilities: Record<string, unknown>): {
36
+ read: ListKind[];
37
+ undeclared: ListKind[];
38
+ };
39
+ /** Two reads of one list: what changed between them, by item id and in order. */
40
+ export declare function listChanges(kind: ListKind, before: Record<string, unknown>[], after: Record<string, unknown>[]): string[];