toolmenu 0.20.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 +1 -0
- package/dist/auto.js +9 -3
- package/dist/catalog.js +4 -0
- package/dist/explain.d.ts +8 -0
- package/dist/explain.js +44 -5
- package/dist/failures.d.ts +1 -1
- package/dist/failures.js +12 -2
- package/dist/rules/index.js +2 -1
- package/dist/rules/lists.js +1 -1
- package/dist/rules/write.d.ts +7 -0
- package/dist/rules/write.js +41 -7
- package/dist/words.d.ts +6 -0
- package/dist/words.js +9 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -399,6 +399,7 @@ server, or from the spec itself. If a rule can't point to one, it doesn't ship.
|
|
|
399
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) |
|
|
400
400
|
| `write/unannotated` | warn | Tools named like writes (`delete_`, `send_`…) with no annotations, as one summary grouped by the annotation each name suggests |
|
|
401
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) |
|
|
402
403
|
| `write/no-dry-run` | info | Destructive tools with no dry-run parameter or preview tool, as one summary |
|
|
403
404
|
| `spec/discover` | info | The server only speaks the 2025 protocol, so 2026-07-28 rules are skipped |
|
|
404
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 |
|
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
|
-
|
|
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 =
|
|
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/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
|
-
|
|
481
|
-
|
|
482
|
-
|
|
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 });
|
package/dist/failures.d.ts
CHANGED
|
@@ -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 (
|
|
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/rules/index.js
CHANGED
|
@@ -8,7 +8,7 @@ import { handleLifetime } from './handles.js';
|
|
|
8
8
|
import { authVariance, cacheScopePublic } from './identities.js';
|
|
9
9
|
import { route, sharedWord, vagueId } from './naming.js';
|
|
10
10
|
import { cacheHints, deprecated, discover, duplicateName, schema, serverInfo, toolsCapability } from './spec.js';
|
|
11
|
-
import { noDryRun, unannotated } from './write.js';
|
|
11
|
+
import { noDryRun, readOnlyMismatch, unannotated } from './write.js';
|
|
12
12
|
import { gated } from './gated.js';
|
|
13
13
|
import { xMcpHeader } from './headers.js';
|
|
14
14
|
import { schemaRef } from './refs.js';
|
|
@@ -32,6 +32,7 @@ export const MENU_RULES = [
|
|
|
32
32
|
lateInstruction,
|
|
33
33
|
noDryRun,
|
|
34
34
|
unannotated,
|
|
35
|
+
readOnlyMismatch,
|
|
35
36
|
schema,
|
|
36
37
|
xMcpHeader,
|
|
37
38
|
schemaRef,
|
package/dist/rules/lists.js
CHANGED
|
@@ -47,7 +47,7 @@ export const listSchema = {
|
|
|
47
47
|
if (r.first.error) {
|
|
48
48
|
const said = r.first.error.replace(/[.\s]+$/, '');
|
|
49
49
|
const failure = classifyFailure(r.first.error, { code: r.first.code });
|
|
50
|
-
if (r.first.code === -32601 || /method not found/i.test(r.first.error)) {
|
|
50
|
+
if (r.first.code === -32601 || /method not (?:found|supported|implemented)/i.test(r.first.error)) {
|
|
51
51
|
// A server that declares resources but answers one of their methods with Method not found.
|
|
52
52
|
findings.push({
|
|
53
53
|
severity: 'info',
|
package/dist/rules/write.d.ts
CHANGED
|
@@ -1,3 +1,10 @@
|
|
|
1
1
|
import { type Rule } from './rule.js';
|
|
2
2
|
export declare const unannotated: Rule;
|
|
3
|
+
/**
|
|
4
|
+
* readOnlyHint: true on a tool whose name says it writes (create_, delete_, send_…).
|
|
5
|
+
* The spec's readOnlyHint means "the tool does not modify its environment", and
|
|
6
|
+
* clients and agents act on it: run it without asking, retry it, call it to explore.
|
|
7
|
+
* Seen on a hosted server: create_my_ideal_account, marked read-only.
|
|
8
|
+
*/
|
|
9
|
+
export declare const readOnlyMismatch: Rule;
|
|
3
10
|
export declare const noDryRun: Rule;
|
package/dist/rules/write.js
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
|
-
import { WRITE_VERBS,
|
|
1
|
+
import { WRITE_VERBS, commonWords, leadingVerb, nouns, words } from '../words.js';
|
|
2
2
|
import { count, kept, names } from './rule.js';
|
|
3
3
|
const DRY_RUN_PARAMS = /^(dry[_-]?run|preview|validate[_-]?only|simulate|plan|what[_-]?if)$/i;
|
|
4
4
|
const PREVIEW_WORDS = new Set(['preview', 'validate', 'plan', 'simulate', 'dry']);
|
|
5
5
|
/** Write verbs that only add something; the others delete or overwrite. A guess from the name. */
|
|
6
6
|
const ADDITIVE_VERBS = new Set(['create', 'add', 'insert', 'send', 'post', 'publish', 'submit', 'upload', 'assign', 'invite', 'approve']);
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
/**
|
|
8
|
+
* Named like a write: the name leads with a write verb, after a prefix most of the
|
|
9
|
+
* menu's tools share. Not a verb further in: percent_change computes a change, and
|
|
10
|
+
* score_status_update scores one (both seen on scanned servers).
|
|
11
|
+
*/
|
|
12
|
+
function isWriteByName(tool, common = new Set()) {
|
|
13
|
+
return WRITE_VERBS.has(leadingVerb(tool.name, common) ?? '');
|
|
9
14
|
}
|
|
10
15
|
function hasAnnotations(tool) {
|
|
11
16
|
return !!tool.annotations && Object.keys(tool.annotations).length > 0;
|
|
@@ -17,10 +22,11 @@ export const unannotated = {
|
|
|
17
22
|
lesson: '02',
|
|
18
23
|
summary: 'Tools that look like writes carry annotations',
|
|
19
24
|
run(ctx) {
|
|
20
|
-
const
|
|
25
|
+
const common = commonWords(ctx.menu.tools.map((t) => t.name));
|
|
26
|
+
const bare = kept(ctx.menu.tools, ctx).filter((t) => isWriteByName(t, common) && !hasAnnotations(t));
|
|
21
27
|
if (bare.length === 0)
|
|
22
28
|
return [];
|
|
23
|
-
const additive = (t) => ADDITIVE_VERBS.has(
|
|
29
|
+
const additive = (t) => ADDITIVE_VERBS.has(leadingVerb(t.name, common));
|
|
24
30
|
// One finding, not one per tool: the same gap in 53 tools is one thing to fix.
|
|
25
31
|
if (bare.length === 1) {
|
|
26
32
|
const [tool] = bare;
|
|
@@ -29,12 +35,12 @@ export const unannotated = {
|
|
|
29
35
|
{
|
|
30
36
|
tool: tool.name,
|
|
31
37
|
confidence: 'unsure',
|
|
32
|
-
message: `${tool.name} is named like a write ("${
|
|
38
|
+
message: `${tool.name} is named like a write ("${leadingVerb(tool.name, common)}") and has no annotations. ${WHY}`,
|
|
33
39
|
fix: `Add annotations: { readOnlyHint: false, destructiveHint: ${!adds} } to ${tool.name} (${adds ? 'true if it can also delete or overwrite' : 'false if it only adds'}), or { readOnlyHint: true } if it changes nothing.`,
|
|
34
40
|
},
|
|
35
41
|
];
|
|
36
42
|
}
|
|
37
|
-
const verbs = [...new Set(bare.map((t) => `${
|
|
43
|
+
const verbs = [...new Set(bare.map((t) => `${leadingVerb(t.name, common)}…`))];
|
|
38
44
|
const overwrites = bare.filter((t) => !additive(t)).map((t) => t.name);
|
|
39
45
|
const adds = bare.filter(additive).map((t) => t.name);
|
|
40
46
|
return [
|
|
@@ -50,6 +56,34 @@ export const unannotated = {
|
|
|
50
56
|
];
|
|
51
57
|
},
|
|
52
58
|
};
|
|
59
|
+
/**
|
|
60
|
+
* readOnlyHint: true on a tool whose name says it writes (create_, delete_, send_…).
|
|
61
|
+
* The spec's readOnlyHint means "the tool does not modify its environment", and
|
|
62
|
+
* clients and agents act on it: run it without asking, retry it, call it to explore.
|
|
63
|
+
* Seen on a hosted server: create_my_ideal_account, marked read-only.
|
|
64
|
+
*/
|
|
65
|
+
export const readOnlyMismatch = {
|
|
66
|
+
id: 'write/read-only-mismatch',
|
|
67
|
+
severity: 'warn',
|
|
68
|
+
summary: 'Tools marked read-only whose names say they write',
|
|
69
|
+
run(ctx) {
|
|
70
|
+
const common = commonWords(ctx.menu.tools.map((t) => t.name));
|
|
71
|
+
const lead = (t) => leadingVerb(t.name, common);
|
|
72
|
+
const odd = kept(ctx.menu.tools, ctx).filter((t) => t.annotations?.readOnlyHint === true && WRITE_VERBS.has(lead(t) ?? ''));
|
|
73
|
+
if (!odd.length)
|
|
74
|
+
return [];
|
|
75
|
+
const one = odd.length === 1;
|
|
76
|
+
return [
|
|
77
|
+
{
|
|
78
|
+
...(one ? { tool: odd[0].name } : {}),
|
|
79
|
+
confidence: 'unsure',
|
|
80
|
+
message: `${one ? `${odd[0].name} is` : `${count(odd.length, 'tool')} are`} marked readOnlyHint: true but named like ${one ? 'a write' : 'writes'} (${names([...new Set(odd.map((t) => `${lead(t)}…`))], 6)}). readOnlyHint says a tool doesn't change anything, and clients act on it: one may run ${one ? 'it' : 'them'} without asking the user, or call ${one ? 'it' : 'them'} just to look. If ${one ? 'it changes' : 'they change'} anything, even state on the server, the hint is wrong.`,
|
|
81
|
+
...(one ? {} : { detail: [odd.map((t) => t.name).join(', ')] }),
|
|
82
|
+
fix: `Where the tool changes anything, set readOnlyHint: false (and destructiveHint to whether it deletes or overwrites); where it truly only reads, a name without the write verb says so to agents too.`,
|
|
83
|
+
},
|
|
84
|
+
];
|
|
85
|
+
},
|
|
86
|
+
};
|
|
53
87
|
export const noDryRun = {
|
|
54
88
|
id: 'write/no-dry-run',
|
|
55
89
|
severity: 'info',
|
package/dist/words.d.ts
CHANGED
|
@@ -15,5 +15,11 @@ export declare function article(word: string): 'a' | 'an';
|
|
|
15
15
|
export declare function commonWords(names: string[]): Set<string>;
|
|
16
16
|
/** The tool's verb: the first word that is one, skipping prefixes like `API-`. */
|
|
17
17
|
export declare function verbOf(name: string): string | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* The verb a name leads with, after any prefix most of the menu's tools share
|
|
20
|
+
* (copilot_studio_clear_read_cache → clear): the verb of what the tool does, not one
|
|
21
|
+
* in its object (score_status_update scores; "update" is what it scores).
|
|
22
|
+
*/
|
|
23
|
+
export declare function leadingVerb(name: string, common?: Set<string>): string | undefined;
|
|
18
24
|
/** The nouns in a tool name, singular: `list_team_audits` → team, audit. */
|
|
19
25
|
export declare function nouns(name: string): string[];
|
package/dist/words.js
CHANGED
|
@@ -68,6 +68,15 @@ export function commonWords(names) {
|
|
|
68
68
|
export function verbOf(name) {
|
|
69
69
|
return words(name).find((w) => VERBS.has(w));
|
|
70
70
|
}
|
|
71
|
+
/**
|
|
72
|
+
* The verb a name leads with, after any prefix most of the menu's tools share
|
|
73
|
+
* (copilot_studio_clear_read_cache → clear): the verb of what the tool does, not one
|
|
74
|
+
* in its object (score_status_update scores; "update" is what it scores).
|
|
75
|
+
*/
|
|
76
|
+
export function leadingVerb(name, common = new Set()) {
|
|
77
|
+
const first = words(name).find((w) => !common.has(w));
|
|
78
|
+
return first !== undefined && VERBS.has(first) ? first : undefined;
|
|
79
|
+
}
|
|
71
80
|
/** The nouns in a tool name, singular: `list_team_audits` → team, audit. */
|
|
72
81
|
export function nouns(name) {
|
|
73
82
|
return words(name)
|
package/package.json
CHANGED