toolmenu 0.11.0 → 0.12.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.
@@ -1,6 +1,52 @@
1
1
  export type FailureClass = 'auth' | 'environment' | 'network' | 'not-found' | '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
+ /**
5
+ * A refusal for too many requests, in a server's or an upstream API's words: "Too many
6
+ * requests, please try again later." (express-rate-limit), "API rate limit exceeded"
7
+ * (GitHub), "Request failed with status code 429" (axios). Not a bare "429" or
8
+ * "rateLimit": "Order 429 not found", "rateLimit must be a positive number".
9
+ */
10
+ export declare const RATE_LIMITED: RegExp;
11
+ /** The HTTP status a transport refused a request with: the SDK's SdkHttpError carries it, its SSE transport says "(HTTP 429)". */
12
+ export declare function httpStatus(error: unknown): number | undefined;
13
+ /** A thrown error that is a refusal for too many requests: a 429 from the transport, or the words for one. */
14
+ export declare function tooMany(error: unknown): boolean;
15
+ /**
16
+ * How long to wait before each retry of a refused request: a per-minute limit clears
17
+ * within them. TOOLMENU_RATE_LIMIT_WAITS_MS ("100,200") sets others, for the CLI's
18
+ * tests; a value that isn't a list of milliseconds keeps these, so a typo can't turn
19
+ * the waiting off.
20
+ */
21
+ export declare const RATE_LIMIT_WAITS_MS: number[];
22
+ /** What to do about a rate limit toolmenu couldn't wait out. */
23
+ 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
+ /** Quoted words that end a sentence: “Rate limit exceeded”. but “Try again later.” (no second period). */
25
+ export declare function quotedSentence(words: string): string;
26
+ /** Why a check was skipped, as a clause: "rate-limited, and still after waiting 0.3 s (“…”)", or the server's words. */
27
+ export declare function whyNot(error: unknown, waitedMs: number): string;
28
+ /** A wait, for a message: "0.3 s", "62 s". */
29
+ export declare function waitedFor(ms: number): string;
30
+ export declare function waitsFrom(value: string | undefined): number[] | undefined;
31
+ /**
32
+ * What the server said, from an error: the JSON-RPC error's message when the
33
+ * transport quotes the response body ("Error POSTing to endpoint: {"jsonrpc":…}"),
34
+ * without that prefix; the first line, at most `max` characters.
35
+ */
36
+ export declare function serverWords(error: unknown, max?: number): string;
37
+ /**
38
+ * Send a request, and again after each wait while it's refused for being too many.
39
+ * `error` and `result` say whether a thrown error or a result is such a refusal and
40
+ * safe to send again; `waited` adds up the time spent waiting.
41
+ */
42
+ export declare function patiently<T>(request: () => Promise<T>, options?: {
43
+ waits?: number[];
44
+ error?: (e: unknown) => boolean;
45
+ result?: (r: T) => boolean;
46
+ waited?: {
47
+ ms: number;
48
+ };
49
+ }): Promise<T>;
4
50
  /**
5
51
  * Classify a failed call. `code` is the JSON-RPC error code when the call threw.
6
52
  * `hadArguments`: a 404 on a call that named nothing (no arguments) means the
package/dist/failures.js CHANGED
@@ -18,6 +18,92 @@ const NETWORK = /\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTU
18
18
  // "**Input Error**" (Sentry), JSON-RPC's invalid params.
19
19
  const INVALID_ARGUMENTS = /invalid (params|parameters|arguments|input)|input error|validation (error|failed)|must be provided|is required\b|\beither\b[^.]{0,80}\bor\b[^.]{0,80}\b(must|required)/i;
20
20
  const NOT_FOUND = /\b404\b|not found/i;
21
+ /**
22
+ * A refusal for too many requests, in a server's or an upstream API's words: "Too many
23
+ * requests, please try again later." (express-rate-limit), "API rate limit exceeded"
24
+ * (GitHub), "Request failed with status code 429" (axios). Not a bare "429" or
25
+ * "rateLimit": "Order 429 not found", "rateLimit must be a positive number".
26
+ */
27
+ export const RATE_LIMITED = /too many requests|rate[ _-]?limit(?:ed\b|s?[ _-](?:exceeded|reached|hit)\b)|exceeded (?:the |your )?rate[ _-]?limit|(?:status(?: code)?|HTTP) 429\b|\b429 too many/i;
28
+ /** The HTTP status a transport refused a request with: the SDK's SdkHttpError carries it, its SSE transport says "(HTTP 429)". */
29
+ export function httpStatus(error) {
30
+ const status = error?.status;
31
+ if (typeof status === 'number')
32
+ return status;
33
+ const m = /\(HTTP (\d{3})\)/.exec(error instanceof Error ? error.message : String(error));
34
+ return m ? Number(m[1]) : undefined;
35
+ }
36
+ /** A thrown error that is a refusal for too many requests: a 429 from the transport, or the words for one. */
37
+ export function tooMany(error) {
38
+ return httpStatus(error) === 429 || RATE_LIMITED.test(error instanceof Error ? error.message : String(error));
39
+ }
40
+ /**
41
+ * How long to wait before each retry of a refused request: a per-minute limit clears
42
+ * within them. TOOLMENU_RATE_LIMIT_WAITS_MS ("100,200") sets others, for the CLI's
43
+ * tests; a value that isn't a list of milliseconds keeps these, so a typo can't turn
44
+ * the waiting off.
45
+ */
46
+ export const RATE_LIMIT_WAITS_MS = waitsFrom(process.env.TOOLMENU_RATE_LIMIT_WAITS_MS) ?? [2000, 4000, 8000, 16_000, 32_000];
47
+ /** What to do about a rate limit toolmenu couldn't wait out. */
48
+ 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
+ /** Quoted words that end a sentence: “Rate limit exceeded”. but “Try again later.” (no second period). */
50
+ export function quotedSentence(words) {
51
+ return `“${words}”${/[.!?…]$/.test(words) ? '' : '.'}`;
52
+ }
53
+ /** Why a check was skipped, as a clause: "rate-limited, and still after waiting 0.3 s (“…”)", or the server's words. */
54
+ export function whyNot(error, waitedMs) {
55
+ return tooMany(error) ? `rate-limited, and still after waiting ${waitedFor(waitedMs)} (“${serverWords(error)}”)` : serverWords(error, 200);
56
+ }
57
+ /** A wait, for a message: "0.3 s", "62 s". */
58
+ export function waitedFor(ms) {
59
+ return `${ms < 10_000 ? Math.round(ms / 100) / 10 : Math.round(ms / 1000)} s`;
60
+ }
61
+ export function waitsFrom(value) {
62
+ const parts = value?.split(',').map((p) => p.trim());
63
+ if (!parts?.length || !parts.every((p) => /^\d+$/.test(p)))
64
+ return undefined;
65
+ return parts.map(Number);
66
+ }
67
+ /**
68
+ * What the server said, from an error: the JSON-RPC error's message when the
69
+ * transport quotes the response body ("Error POSTing to endpoint: {"jsonrpc":…}"),
70
+ * without that prefix; the first line, at most `max` characters.
71
+ */
72
+ export function serverWords(error, max = 100) {
73
+ let text = (error instanceof Error ? error.message : String(error)).split('\n')[0].replace(/^.*?endpoint(?: \(HTTP \d{3}\))?:\s*/i, '').trim();
74
+ const quoted = /"message"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(text)?.[1];
75
+ if (quoted !== undefined) {
76
+ try {
77
+ text = JSON.parse(`"${quoted}"`);
78
+ }
79
+ catch {
80
+ text = quoted;
81
+ }
82
+ }
83
+ return text.length > max ? `${text.slice(0, max - 1)}…` : text;
84
+ }
85
+ /**
86
+ * Send a request, and again after each wait while it's refused for being too many.
87
+ * `error` and `result` say whether a thrown error or a result is such a refusal and
88
+ * safe to send again; `waited` adds up the time spent waiting.
89
+ */
90
+ export async function patiently(request, options = {}) {
91
+ const waits = options.waits ?? RATE_LIMIT_WAITS_MS;
92
+ for (let attempt = 0;; attempt++) {
93
+ try {
94
+ const r = await request();
95
+ if (attempt >= waits.length || !options.result?.(r))
96
+ return r;
97
+ }
98
+ catch (error) {
99
+ if (attempt >= waits.length || !options.error?.(error))
100
+ throw error;
101
+ }
102
+ await new Promise((resolve) => setTimeout(resolve, waits[attempt]));
103
+ if (options.waited)
104
+ options.waited.ms += waits[attempt];
105
+ }
106
+ }
21
107
  /**
22
108
  * Classify a failed call. `code` is the JSON-RPC error code when the call threw.
23
109
  * `hadArguments`: a 404 on a call that named nothing (no arguments) means the
package/dist/init.d.ts CHANGED
@@ -7,8 +7,13 @@ export interface Project {
7
7
  }
8
8
  /** What the repository in `dir` looks like, and how CI gets it ready to run. */
9
9
  export declare function detectProject(dir: string): Project;
10
- /** An env var whose value is a credential: goes into the workflow as a secret, never as a value. */
11
- export declare function looksSecret(key: string): boolean;
10
+ /**
11
+ * The repository secret an env var's value goes into. Every value is a secret: a
12
+ * name doesn't say whether its value is a credential (DATABASE_URL, SENTRY_DSN and
13
+ * GITHUB_PAT carry one, and no pattern on names catches them all). GitHub keeps
14
+ * GITHUB_* for itself (secrets.GITHUB_TOKEN is the job's own token), so those get a prefix.
15
+ */
16
+ export declare function envSecretName(key: string): string;
12
17
  export interface WorkflowOptions {
13
18
  target: Target;
14
19
  project: Project;
@@ -16,7 +21,7 @@ export interface WorkflowOptions {
16
21
  session?: boolean;
17
22
  baseline?: string;
18
23
  }
19
- /** The workflow file, as text. Credentials appear only as ${{ secrets.NAME }}. */
24
+ /** The workflow file, as text. Env and header values appear only as ${{ secrets.NAME }}. */
20
25
  export declare function workflowYaml(opts: WorkflowOptions): string;
21
26
  /** The secret names the workflow refers to, to tell the user what to add. */
22
27
  export declare function secretsNeeded(target: Target): string[];
package/dist/init.js CHANGED
@@ -29,8 +29,9 @@ export function detectProject(dir) {
29
29
  const uv = has('uv.lock');
30
30
  return {
31
31
  kind: 'python',
32
+ // setup-uv has no floating major tag (v10): only full versions resolve.
32
33
  setup: uv
33
- ? ['- uses: astral-sh/setup-uv@v10', '- run: uv sync']
34
+ ? ['- uses: astral-sh/setup-uv@v10.2.0', '- run: uv sync']
34
35
  : ['- uses: actions/setup-python@v7', " with: { python-version: '3.12' }", `- run: pip install ${has('pyproject.toml') ? '.' : '-r requirements.txt'}`],
35
36
  };
36
37
  }
@@ -40,11 +41,17 @@ export function detectProject(dir) {
40
41
  return { kind: 'rust', setup: ['- run: cargo build --release'] };
41
42
  return { kind: 'unknown', setup: ['# TODO: install and build your server here'] };
42
43
  }
43
- /** An env var whose value is a credential: goes into the workflow as a secret, never as a value. */
44
- export function looksSecret(key) {
45
- return /token|secret|password|passwd|api[_-]?key|(^|_)key$|credential|auth/i.test(key);
44
+ /**
45
+ * The repository secret an env var's value goes into. Every value is a secret: a
46
+ * name doesn't say whether its value is a credential (DATABASE_URL, SENTRY_DSN and
47
+ * GITHUB_PAT carry one, and no pattern on names catches them all). GitHub keeps
48
+ * GITHUB_* for itself (secrets.GITHUB_TOKEN is the job's own token), so those get a prefix.
49
+ */
50
+ export function envSecretName(key) {
51
+ const name = key.toUpperCase().replace(/[^A-Z0-9_]+/g, '_');
52
+ return /^(GITHUB_|[0-9])/.test(name) ? `MCP_${name}` : name;
46
53
  }
47
- /** The workflow file, as text. Credentials appear only as ${{ secrets.NAME }}. */
54
+ /** The workflow file, as text. Env and header values appear only as ${{ secrets.NAME }}. */
48
55
  export function workflowYaml(opts) {
49
56
  const t = opts.target;
50
57
  const lines = [
@@ -71,7 +78,7 @@ export function workflowYaml(opts) {
71
78
  if (env.length) {
72
79
  lines.push(' env: |');
73
80
  for (const k of env)
74
- lines.push(` ${k}=${looksSecret(k) ? `\${{ secrets.${k} }}` : t.env[k]}`);
81
+ lines.push(` ${k}=\${{ secrets.${envSecretName(k)} }}`);
75
82
  }
76
83
  }
77
84
  else {
@@ -91,7 +98,7 @@ export function workflowYaml(opts) {
91
98
  /** The secret names the workflow refers to, to tell the user what to add. */
92
99
  export function secretsNeeded(target) {
93
100
  if (target.kind === 'stdio')
94
- return Object.keys(target.env ?? {}).filter(looksSecret);
101
+ return Object.keys(target.env ?? {}).map(envSecretName);
95
102
  return Object.keys(target.headers ?? {}).map(secretName);
96
103
  }
97
104
  function secretName(header) {
package/dist/probe.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { type Target } from './connect.js';
1
+ import { type Connection, type Target } from './connect.js';
2
2
  import type { Probe } from './rules/determinism.js';
3
3
  import type { Menu, MenuTool } from './types.js';
4
4
  /**
@@ -16,12 +16,24 @@ export declare const PROBE_SEED = "1";
16
16
  export declare function seeded(target: Target, seed: string): Target;
17
17
  /** A command that starts the server in a container: the seed (and --env) don't reach it unless passed through. */
18
18
  export declare function isContainerWrapper(target: Target): boolean;
19
+ /**
20
+ * A connection still refused for being too many requests after the waits, said as
21
+ * that and what to do about it, not as the transport's error. Anything else as is.
22
+ */
23
+ export declare function refusedForTooMany(error: unknown, waitedMs: number): unknown;
24
+ /** connect, with a refusal for being too many waited out (connecting is read-only). */
25
+ export declare function connectPatiently(target: Target, options?: {
26
+ timeoutMs?: number;
27
+ waits?: number[];
28
+ }): Promise<Connection>;
19
29
  /** The menu a fresh process (stdio) or connection (HTTP) serves: connect, list once, close. */
20
- export declare function probeMenu(target: Target, timeoutMs: number): Promise<Menu>;
30
+ export declare function probeMenu(target: Target, timeoutMs: number, waits?: number[], waited?: {
31
+ ms: number;
32
+ }): Promise<Menu>;
21
33
  /**
22
34
  * Menus from `processes - 1` fresh processes (stdio) or connections (HTTP), to
23
35
  * compare with the main one. stdio probes run with a different hash seed each. An
24
36
  * HTTP probe that differs is retried once: a rolling deploy can serve two
25
37
  * versions for a moment.
26
38
  */
27
- export declare function probeVariance(target: Target, main: MenuTool[], processes: number, timeoutMs: number): Promise<Probe[]>;
39
+ export declare function probeVariance(target: Target, main: MenuTool[], processes: number, timeoutMs: number, waits?: number[]): Promise<Probe[]>;
package/dist/probe.js CHANGED
@@ -2,6 +2,7 @@ import { basename } from 'node:path';
2
2
  import { connect, listTools } from './connect.js';
3
3
  import { compareMenus } from './compare.js';
4
4
  import { buildMenu } from './menu.js';
5
+ import { patiently, quotedSentence, RATE_LIMIT_ADVICE, serverWords, tooMany, waitedFor, whyNot } from './failures.js';
5
6
  /**
6
7
  * The hash seed of the process whose menu toolmenu saves and compares. Python
7
8
  * orders sets of strings by a per-process random seed; pinning it makes a Python
@@ -23,35 +24,58 @@ export function seeded(target, seed) {
23
24
  export function isContainerWrapper(target) {
24
25
  return target.kind === 'stdio' && /^(docker|podman|nerdctl)(\.exe)?$/.test(basename(target.command));
25
26
  }
26
- /** The menu a fresh process (stdio) or connection (HTTP) serves: connect, list once, close. */
27
- export async function probeMenu(target, timeoutMs) {
28
- const c = await connect(target, { timeoutMs });
27
+ /**
28
+ * A connection still refused for being too many requests after the waits, said as
29
+ * that and what to do about it, not as the transport's error. Anything else as is.
30
+ */
31
+ export function refusedForTooMany(error, waitedMs) {
32
+ if (!tooMany(error))
33
+ return error;
34
+ return new Error(`Rate-limited while connecting, and still after waiting ${waitedFor(waitedMs)}: ${quotedSentence(serverWords(error))} ${RATE_LIMIT_ADVICE}`);
35
+ }
36
+ /** connect, with a refusal for being too many waited out (connecting is read-only). */
37
+ export async function connectPatiently(target, options = {}) {
38
+ const waited = { ms: 0 };
29
39
  try {
30
- const list = await listTools(c, { timeoutMs });
31
- return buildMenu(list.tools, { name: c.server.name, version: c.server.version, protocolVersion: c.protocolVersion, era: c.era });
40
+ return await patiently(() => connect(target, { timeoutMs: options.timeoutMs }), { waits: options.waits, error: tooMany, waited });
32
41
  }
33
- finally {
34
- await c.close().catch(() => { });
42
+ catch (error) {
43
+ throw refusedForTooMany(error, waited.ms);
35
44
  }
36
45
  }
46
+ /** The menu a fresh process (stdio) or connection (HTTP) serves: connect, list once, close. */
47
+ export async function probeMenu(target, timeoutMs, waits, waited) {
48
+ // Read-only: a refusal for being too many is waited out and the probe sent again.
49
+ return patiently(async () => {
50
+ const c = await connect(target, { timeoutMs });
51
+ try {
52
+ const list = await listTools(c, { timeoutMs });
53
+ return buildMenu(list.tools, { name: c.server.name, version: c.server.version, protocolVersion: c.protocolVersion, era: c.era });
54
+ }
55
+ finally {
56
+ await c.close().catch(() => { });
57
+ }
58
+ }, { waits, error: tooMany, waited });
59
+ }
37
60
  /**
38
61
  * Menus from `processes - 1` fresh processes (stdio) or connections (HTTP), to
39
62
  * compare with the main one. stdio probes run with a different hash seed each. An
40
63
  * HTTP probe that differs is retried once: a rolling deploy can serve two
41
64
  * versions for a moment.
42
65
  */
43
- export async function probeVariance(target, main, processes, timeoutMs) {
66
+ export async function probeVariance(target, main, processes, timeoutMs, waits) {
44
67
  const probes = [];
45
68
  for (let i = 0; i < processes - 1; i++) {
46
69
  const seed = String(Number(PROBE_SEED) + i);
70
+ const waited = { ms: 0 };
47
71
  try {
48
- let tools = (await probeMenu(seeded(target, seed), timeoutMs)).tools;
72
+ let tools = (await probeMenu(seeded(target, seed), timeoutMs, waits, waited)).tools;
49
73
  if (target.kind === 'http' && compareMenus(main, tools).length)
50
- tools = (await probeMenu(target, timeoutMs)).tools;
74
+ tools = (await probeMenu(target, timeoutMs, waits, waited)).tools;
51
75
  probes.push({ tools });
52
76
  }
53
77
  catch (error) {
54
- probes.push({ error: error instanceof Error ? error.message : String(error) });
78
+ probes.push({ error: tooMany(error) ? whyNot(error, waited.ms) : error instanceof Error ? error.message : String(error) });
55
79
  }
56
80
  }
57
81
  return probes;
@@ -51,10 +51,13 @@ export function instructions(text, otherTools) {
51
51
  // Naming another tool alongside use/call/instead is an instruction too:
52
52
  // "call render_html first", "use get_progress_table instead", and the
53
53
  // contrast "(get_a and get_b don't answer this)".
54
+ // The whole name only: a tool called `search` isn't named by "research".
55
+ const nameChar = /[\w-]/;
54
56
  for (const name of otherTools) {
55
57
  let at = text.indexOf(name);
56
58
  while (at !== -1) {
57
- if (/\b(use|call|instead|prefer|first|rather than|don'?t|doesn'?t|do not|does not|isn'?t|aren'?t|won'?t|unlike)\b/i.test(sentenceAround(text, at)))
59
+ const whole = !nameChar.test(text[at - 1] ?? '') && !nameChar.test(text[at + name.length] ?? '');
60
+ if (whole && /\b(use|call|instead|prefer|first|rather than|don'?t|doesn'?t|do not|does not|isn'?t|aren'?t|won'?t|unlike)\b/i.test(sentenceAround(text, at)))
58
61
  found.set(at, name);
59
62
  at = text.indexOf(name, at + name.length);
60
63
  }
@@ -1,5 +1,6 @@
1
1
  import { compareMenus } from '../compare.js';
2
2
  import { describeToolDifference } from '../difference.js';
3
+ import { serverWords } from '../failures.js';
3
4
  const LABELS = {
4
5
  added: 'tool added',
5
6
  removed: 'tool removed',
@@ -87,7 +88,7 @@ function varianceRule(id, transport) {
87
88
  const out = [];
88
89
  for (const probe of ctx.probes) {
89
90
  if (probe.error) {
90
- out.push({ severity: 'info', message: `Couldn't ${transport === 'stdio' ? 'start a second server process' : 'open a second connection'} to compare menus, so this wasn't checked: ${probe.error.split('\n')[0]}` });
91
+ out.push({ severity: 'info', message: `Couldn't ${transport === 'stdio' ? 'start a second server process' : 'open a second connection'} to compare menus, so this wasn't checked: ${serverWords(probe.error, 200)}` });
91
92
  continue;
92
93
  }
93
94
  const f = varianceFinding(ctx.menu.tools, probe.tools ?? [], { transport, modern: ctx.era === 'modern', wrapper: !!ctx.wrapper });
@@ -3,10 +3,11 @@ import { buried, cut } from './description.js';
3
3
  import { connectionVariance, nondeterministic, processVariance } from './determinism.js';
4
4
  import { authoredIds } from './ids.js';
5
5
  import { route, sharedWord, vagueId } from './naming.js';
6
- import { cacheHints, deprecated, discover, schema } from './spec.js';
6
+ import { cacheHints, deprecated, discover, duplicateName, schema, toolsCapability } from './spec.js';
7
7
  import { noDryRun, unannotated } from './write.js';
8
8
  export const MENU_RULES = [
9
9
  nondeterministic,
10
+ duplicateName,
10
11
  processVariance,
11
12
  connectionVariance,
12
13
  vagueId,
@@ -18,6 +19,7 @@ export const MENU_RULES = [
18
19
  noDryRun,
19
20
  unannotated,
20
21
  schema,
22
+ toolsCapability,
21
23
  discover,
22
24
  deprecated,
23
25
  cacheHints,
@@ -1,5 +1,7 @@
1
1
  import type { Rule } from './rule.js';
2
2
  export declare const schema: Rule;
3
+ export declare const toolsCapability: Rule;
4
+ export declare const duplicateName: Rule;
3
5
  export declare const discover: Rule;
4
6
  export declare const deprecated: Rule;
5
7
  export declare const cacheHints: Rule;
@@ -53,6 +53,35 @@ export const schema = {
53
53
  return findings;
54
54
  },
55
55
  };
56
+ export const toolsCapability = {
57
+ id: 'spec/tools-capability',
58
+ severity: 'error',
59
+ summary: 'The server declares the tools capability',
60
+ run(ctx) {
61
+ if ('tools' in ctx.capabilities)
62
+ return [];
63
+ return [
64
+ {
65
+ message: `The server doesn't declare the tools capability, so clients don't ask for its tools: the official MCP SDK client returns an empty list without sending tools/list${ctx.menu.tools.length ? '' : ', and that is the menu toolmenu got'}. Declare "tools": {} in the server's capabilities.`,
66
+ },
67
+ ];
68
+ },
69
+ };
70
+ export const duplicateName = {
71
+ id: 'menu/duplicate-name',
72
+ severity: 'error',
73
+ summary: 'Every tool in the menu has its own name',
74
+ run(ctx) {
75
+ const positions = new Map();
76
+ ctx.menu.tools.forEach((t, i) => positions.set(t.name, [...(positions.get(t.name) ?? []), i]));
77
+ return [...positions]
78
+ .filter(([, at]) => at.length > 1)
79
+ .map(([name, at]) => ({
80
+ tool: name,
81
+ message: `${at.length} tools are named ${name} (positions ${at.join(', ')}). A call names the tool, so only one of them can be reached; clients may keep either, or reject the whole list (Claude's API refuses duplicate tool names).`,
82
+ }));
83
+ },
84
+ };
56
85
  export const discover = {
57
86
  id: 'spec/discover',
58
87
  severity: 'info',
package/dist/semver.js CHANGED
@@ -1,5 +1,5 @@
1
1
  export function parseSemver(version) {
2
- const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?/.exec(version ?? '');
2
+ const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version ?? '');
3
3
  return m ? { nums: [Number(m[1]), Number(m[2]), Number(m[3])], ...(m[4] ? { pre: m[4] } : {}) } : undefined;
4
4
  }
5
5
  /** Calendar versions (2026.8.31) promise nothing about compatibility. */
package/dist/session.d.ts CHANGED
@@ -74,6 +74,15 @@ export interface SessionOptions {
74
74
  scenarioName?: string;
75
75
  /** Server processes (stdio) or connections (HTTP) to compare before the first step, the main one included (default 2). */
76
76
  processes?: number;
77
+ /** The union menu is kept as a baseline (--union-out): an unlock never called then leaves tools out of it. */
78
+ unionOut?: boolean;
79
+ /** session --auto: what the plan called and skipped, so a run that called nothing isn't a clean one. */
80
+ auto?: {
81
+ called: string[];
82
+ skipped: import('./auto.js').AutoPlan['skipped'];
83
+ };
84
+ /** Waits before retrying a request refused for being too many (default 2, 4, 8, 16, 32 s: a per-minute limit clears within them). */
85
+ rateLimitWaitsMs?: number[];
77
86
  }
78
87
  type Raw = Omit<Finding, 'severity'> & {
79
88
  severity: Severity;
@@ -85,9 +94,11 @@ export declare function changeFindings(before: MenuTool[], after: MenuTool[], ch
85
94
  /**
86
95
  * Does a fresh connection see this step's changes? All of them: the server's tool
87
96
  * set changed. None: the change belongs to this connection (or, on stdio, this
88
- * process). Reorders alone can't tell, and a mix is unclear.
97
+ * process). Reorders alone can't tell, and a mix is unclear. So can't a step that
98
+ * takes the menu back to the session's `baseline` while fresh ones still serve it:
99
+ * a fresh process starts there anyway (an unlock undone reads as "seen" by it).
89
100
  */
90
- export declare function scopeOf(changes: ToolChange[], next: MenuTool[], probe: MenuTool[], transport: Target['kind']): Scope;
101
+ export declare function scopeOf(changes: ToolChange[], next: MenuTool[], probe: MenuTool[], transport: Target['kind'], baseline?: MenuTool[]): Scope;
91
102
  export type { Era };
92
103
  interface Unlocker {
93
104
  tool: MenuTool;
@@ -103,4 +114,32 @@ interface Unlocker {
103
114
  */
104
115
  export declare function clip(text: string, max: number): string;
105
116
  export declare function unlockers(tools: MenuTool[]): Unlocker[];
106
- export declare function starterScenario(menu: Menu): string;
117
+ /**
118
+ * Unlocks whose values the schema doesn't give (no enum), each with a read-only
119
+ * lister that should: no required arguments, a lookup verb, and a noun in common
120
+ * with the unlock (toolception: enable_toolset { name } ← list_toolsets).
121
+ */
122
+ export declare function unlockListers(tools: MenuTool[]): {
123
+ unlock: string;
124
+ lister: string;
125
+ }[];
126
+ /**
127
+ * The values a listing offers, from its JSON (structuredContent, or text that
128
+ * starts with JSON): the first list of strings, or of objects with a key, id,
129
+ * slug or name, each item's own field first (toolception's `key: "quotes"`, not
130
+ * the display name "Quotes" nested under it).
131
+ */
132
+ export declare function valuesFromListing(result: {
133
+ structuredContent?: unknown;
134
+ content?: unknown;
135
+ }): string[];
136
+ /** At most this many values of one unlock in a scenario; the rest are named in a comment. */
137
+ export declare const MAX_UNLOCKS = 50;
138
+ export interface StarterOptions {
139
+ /**
140
+ * Values for unlocks whose schema has no enum, by tool name: read from the
141
+ * server's own listing (toolception's list_toolsets), see unlockListers.
142
+ */
143
+ values?: Record<string, unknown[]>;
144
+ }
145
+ export declare function starterScenario(menu: Menu, options?: StarterOptions): string;