toolmenu 0.16.0 → 0.17.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.
- package/README.md +9 -2
- package/dist/auth.js +2 -1
- package/dist/auto.js +33 -2
- package/dist/breakdown.js +3 -31
- package/dist/catalog.d.ts +1 -1
- package/dist/catalog.js +4 -3
- package/dist/cli.js +42 -6
- package/dist/config.d.ts +9 -0
- package/dist/config.js +11 -0
- package/dist/connect.d.ts +1 -0
- package/dist/connect.js +46 -16
- package/dist/diff.js +51 -13
- package/dist/explain.d.ts +9 -4
- package/dist/explain.js +90 -25
- package/dist/failures.js +5 -4
- package/dist/help.js +2 -1
- package/dist/mrtr.d.ts +27 -6
- package/dist/mrtr.js +116 -37
- package/dist/options.d.ts +4 -0
- package/dist/options.js +1 -0
- package/dist/probe.d.ts +8 -0
- package/dist/probe.js +9 -1
- package/dist/report.js +2 -1
- package/dist/rules/gated.js +5 -5
- package/dist/rules/handles.d.ts +12 -0
- package/dist/rules/handles.js +88 -0
- package/dist/rules/headers.js +4 -4
- package/dist/rules/identities.d.ts +23 -0
- package/dist/rules/identities.js +84 -0
- package/dist/rules/index.js +5 -0
- package/dist/rules/refs.js +10 -78
- package/dist/rules/rule.d.ts +2 -0
- package/dist/rules/search.js +3 -2
- package/dist/rules/spec.js +2 -1
- package/dist/schema-ref.d.ts +35 -0
- package/dist/schema-ref.js +178 -0
- package/dist/search.d.ts +8 -0
- package/dist/search.js +4 -1
- package/dist/session.d.ts +17 -0
- package/dist/session.js +156 -66
- package/dist/snapshot.d.ts +10 -1
- package/dist/snapshot.js +20 -3
- package/package.json +1 -1
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { singular, words } from '../words.js';
|
|
2
|
+
import { kept, names } from './rule.js';
|
|
3
|
+
/*
|
|
4
|
+
* Server-minted handles (2026-07-28, SEP-2567). With protocol sessions gone, a
|
|
5
|
+
* server that keeps state across calls hands out a handle as an ordinary tool
|
|
6
|
+
* result (`basket_id`) and takes it back as an argument. The spec asks for the
|
|
7
|
+
* handle's retention "in the creation tool's description" ("baskets expire after
|
|
8
|
+
* 24 hours of inactivity"), so a model knows when to make a new one.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Kinds that are server state for a while, never a lasting record: a session, a
|
|
12
|
+
* basket or cart, a checkout, a lease or lock, or something called a handle.
|
|
13
|
+
* Not drafts, runs, jobs or tasks: in real menus those are as often records that
|
|
14
|
+
* stay (an email draft, a CI run, a planner task).
|
|
15
|
+
*/
|
|
16
|
+
const HANDLE_KINDS = new Set(['session', 'basket', 'cart', 'checkout', 'handle', 'lease', 'lock']);
|
|
17
|
+
const CREATE = new Set(['create', 'start', 'open', 'new', 'begin', 'init', 'initialize', 'acquire']);
|
|
18
|
+
/** How a handle parameter ends: session_id, sessionHandle, cart_token, or the kind alone. */
|
|
19
|
+
const HANDLE_SUFFIX = new Set(['id', 'ids', 'uuid', 'handle', 'token', 'key', 'ref']);
|
|
20
|
+
/**
|
|
21
|
+
* Words that say how long a handle lasts, or that it lasts: "expires", "TTL",
|
|
22
|
+
* "valid for 24 hours", "after 30 minutes of inactivity", "kept until closed",
|
|
23
|
+
* "never expires".
|
|
24
|
+
*/
|
|
25
|
+
const LIFETIME = /\bexpir(?:e|es|ed|y|ing|ation)\b|\bttl\b|\btime[- ]to[- ]live\b|\bvalid (?:for|until)\b|\blasts?\b|\binactiv|\bidle\b|\btime(?:s|d)? ?out\b|\bretain|\bretention\b|\bkept (?:for|until)\b|\b(?:deleted|discarded|cleared|purged|removed) (?:after|when|on)\b|\bpersist|\bindefinite|\bnever expire|\buntil (?:it is |you )?(?:closed?|ended?|deleted?|released?)\b|\b\d+\s*(?:s|sec|seconds?|m|min|minutes?|h|hrs?|hours?|d|days?)\b/i;
|
|
26
|
+
/** The handle kind a tool creates, from its name: start_session → session, create-shopping-cart → cart. */
|
|
27
|
+
function createdKind(tool) {
|
|
28
|
+
const w = words(tool.name).map(singular);
|
|
29
|
+
if (!w.length || !CREATE.has(w[0]))
|
|
30
|
+
return undefined;
|
|
31
|
+
return w.slice(1).find((x) => HANDLE_KINDS.has(x));
|
|
32
|
+
}
|
|
33
|
+
/** The handle kinds some tool in the menu creates. */
|
|
34
|
+
export function createdKinds(tools) {
|
|
35
|
+
return new Set(tools.map(createdKind).filter((k) => !!k));
|
|
36
|
+
}
|
|
37
|
+
/** Parameters of a tool that take a handle of this kind: session_id, cartToken, `session`. */
|
|
38
|
+
export function handleParams(tool, kind) {
|
|
39
|
+
return Object.keys(tool.inputSchema?.properties ?? {}).filter((p) => {
|
|
40
|
+
const w = words(p).map(singular);
|
|
41
|
+
if (w.length === 1)
|
|
42
|
+
return w[0] === kind;
|
|
43
|
+
return w.at(-2) === kind && HANDLE_SUFFIX.has(w.at(-1));
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
/** Text a creation tool gives about what it returns: its description, and its output schema's descriptions. */
|
|
47
|
+
function ownText(tool) {
|
|
48
|
+
const out = [tool.description ?? ''];
|
|
49
|
+
const walk = (s, depth) => {
|
|
50
|
+
if (!s || depth > 4)
|
|
51
|
+
return;
|
|
52
|
+
if (typeof s.description === 'string')
|
|
53
|
+
out.push(s.description);
|
|
54
|
+
for (const child of Object.values(s.properties ?? {}))
|
|
55
|
+
walk(child, depth + 1);
|
|
56
|
+
};
|
|
57
|
+
walk(tool.outputSchema, 0);
|
|
58
|
+
return out.join('\n');
|
|
59
|
+
}
|
|
60
|
+
export const handleLifetime = {
|
|
61
|
+
id: 'ids/handle-lifetime',
|
|
62
|
+
severity: 'info',
|
|
63
|
+
since: '2026-07-28',
|
|
64
|
+
summary: "A tool that creates a handle should say how long it lasts",
|
|
65
|
+
run(ctx) {
|
|
66
|
+
const findings = [];
|
|
67
|
+
for (const tool of kept(ctx.menu.tools, ctx)) {
|
|
68
|
+
const kind = createdKind(tool);
|
|
69
|
+
if (!kind)
|
|
70
|
+
continue;
|
|
71
|
+
// A handle is passed back: some other tool takes it. Otherwise it's not a handle the model keeps.
|
|
72
|
+
const users = ctx.menu.tools.filter((t) => t.name !== tool.name && handleParams(t, kind).length);
|
|
73
|
+
if (!users.length)
|
|
74
|
+
continue;
|
|
75
|
+
if (LIFETIME.test(ownText(tool)))
|
|
76
|
+
continue;
|
|
77
|
+
const takers = users.map((t) => `${t.name}.${handleParams(t, kind)[0]}`);
|
|
78
|
+
findings.push({
|
|
79
|
+
tool: tool.name,
|
|
80
|
+
confidence: 'unsure',
|
|
81
|
+
message: `${tool.name} creates a ${kind} that ${takers.length === 1 ? takers[0] : `${takers.length} tools`} take${takers.length === 1 ? 's' : ''} back, but its description doesn't say how long the ${kind} lasts. 2026-07-28 asks for a handle's retention in the creation tool's description, so a model can tell an expired ${kind} from a wrong one and knows when to make a new one.`,
|
|
82
|
+
...(takers.length > 1 ? { detail: [`Taken by ${names(takers, 8)}.`] } : {}),
|
|
83
|
+
fix: `Say in ${tool.name}'s description how long a ${kind} lasts ("${kind}s expire after 30 minutes of inactivity", or "a ${kind} lasts until it is closed"), and return a tool error that says so for an expired or unknown one.`,
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
return findings;
|
|
87
|
+
},
|
|
88
|
+
};
|
package/dist/rules/headers.js
CHANGED
|
@@ -51,13 +51,13 @@ export function headerFaults(tool) {
|
|
|
51
51
|
if (typeof type !== 'string') {
|
|
52
52
|
fault(type === undefined ? 'the parameter has no "type"; it must be string, integer or boolean' : `the parameter's type is ${JSON.stringify(type)}; it must be one of string, integer or boolean, not a list`);
|
|
53
53
|
}
|
|
54
|
-
else if (type
|
|
55
|
-
fault('the parameter is a number; the spec allows only string, integer or boolean (the official SDK client accepts number for now, other clients may not)', false);
|
|
56
|
-
}
|
|
57
|
-
else if (!PRIMITIVE.has(type)) {
|
|
54
|
+
else if (type !== 'number' && !PRIMITIVE.has(type)) {
|
|
58
55
|
fault(`the parameter is ${type === 'array' || type === 'object' ? 'an' : 'a'} ${type}; it must be string, integer or boolean`);
|
|
59
56
|
}
|
|
60
57
|
else {
|
|
58
|
+
// number takes part in the uniqueness check too: the SDK client registers it.
|
|
59
|
+
if (type === 'number')
|
|
60
|
+
fault('the parameter is a number; the spec allows only string, integer or boolean (the official SDK client accepts number for now, other clients may not)', false);
|
|
61
61
|
const prior = seen.get(raw.toLowerCase());
|
|
62
62
|
if (prior !== undefined)
|
|
63
63
|
fault(`"${raw}" is already used by ${prior}; header names must differ ignoring case`);
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { MenuTool } from '../types.js';
|
|
2
|
+
import { type Rule } from './rule.js';
|
|
3
|
+
/** One identity's menu, as snapshot listed it: the first is the main one, whose menu is saved. */
|
|
4
|
+
export interface IdentityMenu {
|
|
5
|
+
name: string;
|
|
6
|
+
tools?: MenuTool[];
|
|
7
|
+
tokens?: number;
|
|
8
|
+
cacheScope?: unknown;
|
|
9
|
+
/** Why it couldn't be listed (bad credentials, a refused connection). */
|
|
10
|
+
error?: string;
|
|
11
|
+
}
|
|
12
|
+
/** What one identity's menu adds and lacks against the main one, and its token total. */
|
|
13
|
+
export interface IdentityDifference {
|
|
14
|
+
name: string;
|
|
15
|
+
adds: string[];
|
|
16
|
+
lacks: string[];
|
|
17
|
+
/** Tools both list whose definitions differ (a description or schema per role). */
|
|
18
|
+
changed: string[];
|
|
19
|
+
tokens: number;
|
|
20
|
+
}
|
|
21
|
+
export declare function identityDifferences(identities: IdentityMenu[]): IdentityDifference[];
|
|
22
|
+
export declare const authVariance: Rule;
|
|
23
|
+
export declare const cacheScopePublic: Rule;
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { count, names, num } from './rule.js';
|
|
2
|
+
export function identityDifferences(identities) {
|
|
3
|
+
const [main, ...others] = identities;
|
|
4
|
+
if (!main?.tools)
|
|
5
|
+
return [];
|
|
6
|
+
const mine = new Map(main.tools.map((t) => [t.name, JSON.stringify({ d: t.description, i: t.inputSchema, o: t.outputSchema, a: t.annotations })]));
|
|
7
|
+
return others
|
|
8
|
+
.filter((o) => o.tools)
|
|
9
|
+
.map((o) => {
|
|
10
|
+
const theirs = new Map(o.tools.map((t) => [t.name, JSON.stringify({ d: t.description, i: t.inputSchema, o: t.outputSchema, a: t.annotations })]));
|
|
11
|
+
return {
|
|
12
|
+
name: o.name,
|
|
13
|
+
adds: [...theirs.keys()].filter((n) => !mine.has(n)),
|
|
14
|
+
lacks: [...mine.keys()].filter((n) => !theirs.has(n)),
|
|
15
|
+
changed: [...theirs].filter(([n, def]) => mine.has(n) && mine.get(n) !== def).map(([n]) => n),
|
|
16
|
+
tokens: o.tokens ?? 0,
|
|
17
|
+
};
|
|
18
|
+
});
|
|
19
|
+
}
|
|
20
|
+
const differs = (d) => d.adds.length + d.lacks.length + d.changed.length > 0;
|
|
21
|
+
function describe(d, main) {
|
|
22
|
+
const parts = [
|
|
23
|
+
d.adds.length ? `adds ${names(d.adds, 6)}` : '',
|
|
24
|
+
d.lacks.length ? `lacks ${names(d.lacks, 6)}` : '',
|
|
25
|
+
d.changed.length ? `${count(d.changed.length, 'tool')} defined differently (${names(d.changed, 4)})` : '',
|
|
26
|
+
].filter(Boolean);
|
|
27
|
+
const delta = d.tokens - (main.tokens ?? 0);
|
|
28
|
+
return `${d.name}: ${parts.join('; ')} (${num(d.tokens)} tokens, ${delta >= 0 ? '+' : ''}${num(delta)} against ${main.name})`;
|
|
29
|
+
}
|
|
30
|
+
export const authVariance = {
|
|
31
|
+
id: 'menu/auth-variance',
|
|
32
|
+
severity: 'info',
|
|
33
|
+
summary: 'The menu differs between identities (allowed; says what differs)',
|
|
34
|
+
run(ctx) {
|
|
35
|
+
const identities = ctx.identities ?? [];
|
|
36
|
+
if (identities.length < 2)
|
|
37
|
+
return [];
|
|
38
|
+
const [main] = identities;
|
|
39
|
+
const findings = [];
|
|
40
|
+
const diffs = identityDifferences(identities);
|
|
41
|
+
const varying = diffs.filter(differs);
|
|
42
|
+
if (varying.length) {
|
|
43
|
+
findings.push({
|
|
44
|
+
message: `The menu differs by identity: ${varying.length === diffs.length && diffs.length === 1 ? `${varying[0].name} sees a different tool set than ${main.name}` : `${count(varying.length, 'identity', 'identities')} of ${num(diffs.length)} see a different tool set than ${main.name}`}. Allowed (the tool set may vary by authorization); each sees only its own, so a baseline of ${main.name}'s menu doesn't cover the others.`,
|
|
45
|
+
detail: varying.map((d) => describe(d, main)),
|
|
46
|
+
fix: `Keep a baseline per identity you care about: the first --as is the menu saved, so snapshot --as ${varying[0].name}:… --as ${main.name}:… --out menu.${varying[0].name}.json, and diff each one.`,
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
const failed = identities.filter((i) => i.error);
|
|
50
|
+
if (failed.length) {
|
|
51
|
+
findings.push({
|
|
52
|
+
message: failed.length === 1
|
|
53
|
+
? `${failed[0].name} couldn't be listed, so its menu is not compared (${failed[0].error.replace(/[.\s]+$/, '')}).`
|
|
54
|
+
: `${names(failed.map((i) => i.name))} couldn't be listed, so their menus are not compared.`,
|
|
55
|
+
...(failed.length > 1 ? { detail: failed.map((i) => `${i.name}: ${i.error.replace(/[.\s]+$/, '')}`) } : {}),
|
|
56
|
+
fix: 'Check the credentials given with --as for that identity.',
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
return findings;
|
|
60
|
+
},
|
|
61
|
+
};
|
|
62
|
+
export const cacheScopePublic = {
|
|
63
|
+
id: 'spec/cache-scope-public',
|
|
64
|
+
severity: 'warn',
|
|
65
|
+
since: '2026-07-28',
|
|
66
|
+
summary: 'A list marked cacheScope "public" that differs by identity',
|
|
67
|
+
run(ctx) {
|
|
68
|
+
const identities = ctx.identities ?? [];
|
|
69
|
+
const varying = identityDifferences(identities).filter(differs);
|
|
70
|
+
if (!varying.length)
|
|
71
|
+
return [];
|
|
72
|
+
const listed = identities.filter((i) => i.tools);
|
|
73
|
+
const publicOnes = listed.filter((i) => i.cacheScope === 'public').map((i) => i.name);
|
|
74
|
+
if (!publicOnes.length)
|
|
75
|
+
return [];
|
|
76
|
+
return [
|
|
77
|
+
{
|
|
78
|
+
message: `tools/list says cacheScope: "public"${publicOnes.length < listed.length ? ` (for ${names(publicOnes)})` : ''}, but the tool set differs by identity. Public lets shared caches serve one caller's list to another, across authorization contexts: a client can be shown tools its credentials can't use, or miss ones they can.`,
|
|
79
|
+
detail: varying.map((d) => describe(d, identities[0])),
|
|
80
|
+
fix: 'Set cacheScope: "private" on tools/list when the tools depend on who is asking.',
|
|
81
|
+
},
|
|
82
|
+
];
|
|
83
|
+
},
|
|
84
|
+
};
|
package/dist/rules/index.js
CHANGED
|
@@ -2,6 +2,8 @@ import { SEVERITY_RANK } from '../types.js';
|
|
|
2
2
|
import { buried, cut, lateInstruction } from './description.js';
|
|
3
3
|
import { connectionVariance, hostSpecific, nondeterministic, processVariance } from './determinism.js';
|
|
4
4
|
import { authoredIds } from './ids.js';
|
|
5
|
+
import { handleLifetime } from './handles.js';
|
|
6
|
+
import { authVariance, cacheScopePublic } from './identities.js';
|
|
5
7
|
import { route, sharedWord, vagueId } from './naming.js';
|
|
6
8
|
import { cacheHints, deprecated, discover, duplicateName, schema, serverInfo, toolsCapability } from './spec.js';
|
|
7
9
|
import { noDryRun, unannotated } from './write.js';
|
|
@@ -21,6 +23,7 @@ export const MENU_RULES = [
|
|
|
21
23
|
route,
|
|
22
24
|
findable,
|
|
23
25
|
authoredIds,
|
|
26
|
+
handleLifetime,
|
|
24
27
|
buried,
|
|
25
28
|
cut,
|
|
26
29
|
lateInstruction,
|
|
@@ -33,6 +36,8 @@ export const MENU_RULES = [
|
|
|
33
36
|
discover,
|
|
34
37
|
deprecated,
|
|
35
38
|
cacheHints,
|
|
39
|
+
authVariance,
|
|
40
|
+
cacheScopePublic,
|
|
36
41
|
serverInfo,
|
|
37
42
|
];
|
|
38
43
|
/**
|
package/dist/rules/refs.js
CHANGED
|
@@ -1,86 +1,18 @@
|
|
|
1
|
+
import { indexSchema, isNetworkRef } from '../schema-ref.js';
|
|
1
2
|
import { count, names } from './rule.js';
|
|
2
|
-
/** JSON Pointer within the schema: `#/$defs/A`, `#/properties/a/items`. */
|
|
3
|
-
function pointer(root, ref) {
|
|
4
|
-
if (ref === '#' || ref === '#/')
|
|
5
|
-
return true;
|
|
6
|
-
let node = root;
|
|
7
|
-
for (const raw of ref.slice(2).split('/')) {
|
|
8
|
-
const part = decodeURIComponent(raw).replace(/~1/g, '/').replace(/~0/g, '~');
|
|
9
|
-
if (Array.isArray(node) && /^\d+$/.test(part) && Number(part) < node.length)
|
|
10
|
-
node = node[Number(part)];
|
|
11
|
-
else if (node && typeof node === 'object' && part in node)
|
|
12
|
-
node = node[part];
|
|
13
|
-
else
|
|
14
|
-
return false;
|
|
15
|
-
}
|
|
16
|
-
return true;
|
|
17
|
-
}
|
|
18
|
-
/** Every $id and $anchor in a schema, for refs that name them. */
|
|
19
|
-
function targets(node, ids, anchors, depth = 0) {
|
|
20
|
-
if (!node || typeof node !== 'object' || depth > 64)
|
|
21
|
-
return;
|
|
22
|
-
if (Array.isArray(node)) {
|
|
23
|
-
for (const v of node)
|
|
24
|
-
targets(v, ids, anchors, depth + 1);
|
|
25
|
-
return;
|
|
26
|
-
}
|
|
27
|
-
const s = node;
|
|
28
|
-
if (typeof s.$id === 'string')
|
|
29
|
-
ids.add(s.$id.replace(/#$/, ''));
|
|
30
|
-
if (typeof s.$anchor === 'string')
|
|
31
|
-
anchors.add(s.$anchor);
|
|
32
|
-
if (typeof s.$dynamicAnchor === 'string')
|
|
33
|
-
anchors.add(s.$dynamicAnchor);
|
|
34
|
-
for (const [k, v] of Object.entries(s))
|
|
35
|
-
if (k !== 'enum' && k !== 'const' && k !== 'default' && k !== 'examples')
|
|
36
|
-
targets(v, ids, anchors, depth + 1);
|
|
37
|
-
}
|
|
38
3
|
/** Every $ref in one schema that a client can't resolve from the schema itself. */
|
|
39
4
|
export function unresolvedRefs(schema, where) {
|
|
40
5
|
if (!schema || typeof schema !== 'object')
|
|
41
6
|
return [];
|
|
42
|
-
const
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
return;
|
|
52
|
-
}
|
|
53
|
-
const s = node;
|
|
54
|
-
for (const key of ['$ref', '$dynamicRef']) {
|
|
55
|
-
const ref = s[key];
|
|
56
|
-
if (typeof ref !== 'string')
|
|
57
|
-
continue;
|
|
58
|
-
const at = path.length ? path.join('.') : 'the schema root';
|
|
59
|
-
if (ref.startsWith('#/') || ref === '#') {
|
|
60
|
-
if (!pointer(schema, ref))
|
|
61
|
-
out.push({ where, path: at, ref, kind: 'missing' });
|
|
62
|
-
}
|
|
63
|
-
else if (ref.startsWith('#')) {
|
|
64
|
-
if (!anchors.has(ref.slice(1)))
|
|
65
|
-
out.push({ where, path: at, ref, kind: 'missing' });
|
|
66
|
-
}
|
|
67
|
-
else {
|
|
68
|
-
// A ref to a schema's own $id (or a fragment of it) resolves locally.
|
|
69
|
-
const [base, fragment] = ref.split('#');
|
|
70
|
-
const local = [...ids].some((id) => id === base || id.endsWith(`/${base}`));
|
|
71
|
-
if (local && (!fragment || fragment.startsWith('/') || anchors.has(fragment)))
|
|
72
|
-
continue;
|
|
73
|
-
out.push({ where, path: at, ref, kind: /^https?:\/\//i.test(ref) ? 'network' : 'missing' });
|
|
74
|
-
}
|
|
75
|
-
}
|
|
76
|
-
for (const [k, v] of Object.entries(s)) {
|
|
77
|
-
if (k === 'enum' || k === 'const' || k === 'default' || k === 'examples')
|
|
78
|
-
continue;
|
|
79
|
-
visit(v, k === 'properties' ? path : [...path, k === 'items' || k.startsWith('$') || /^(any|one|all)Of$|^not$|^if$|^then$|^else$|Properties$/.test(k) ? `<${k}>` : k], depth + 1);
|
|
80
|
-
}
|
|
81
|
-
};
|
|
82
|
-
visit(schema, [], 0);
|
|
83
|
-
return out;
|
|
7
|
+
const index = indexSchema(schema);
|
|
8
|
+
return index.refs
|
|
9
|
+
.filter((r) => !index.resolve(r.ref, r.base))
|
|
10
|
+
.map((r) => ({
|
|
11
|
+
where,
|
|
12
|
+
path: r.path.length ? r.path.join('.') : 'the schema root',
|
|
13
|
+
ref: r.ref,
|
|
14
|
+
kind: isNetworkRef(r.ref, r.base) ? 'network' : 'missing',
|
|
15
|
+
}));
|
|
84
16
|
}
|
|
85
17
|
export function refFaults(tool) {
|
|
86
18
|
return [...unresolvedRefs(tool.inputSchema, 'inputSchema'), ...unresolvedRefs(tool.outputSchema, 'outputSchema')];
|
package/dist/rules/rule.d.ts
CHANGED
|
@@ -26,6 +26,8 @@ export interface RuleContext {
|
|
|
26
26
|
};
|
|
27
27
|
/** How this run reached the server, as the command line ends: `-- node server.js` or the URL. For next steps. */
|
|
28
28
|
server?: string;
|
|
29
|
+
/** snapshot --as: each identity's menu, the main one first (menu/auth-variance, spec/cache-scope-public). */
|
|
30
|
+
identities?: import('./identities.js').IdentityMenu[];
|
|
29
31
|
/** Where clients are assumed to cut tool descriptions (description/buried). */
|
|
30
32
|
descriptionLimit?: number | string;
|
|
31
33
|
/** Tools (names or globs) the client sends uncut, so description/buried skips them. */
|
package/dist/rules/search.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { buildIndex, placeOf, SEARCH_LIMIT } from '../search.js';
|
|
1
|
+
import { buildIndex, placeIn, placeOf, SEARCH_LIMIT } from '../search.js';
|
|
2
2
|
import { commonWords, VERBS, words } from '../words.js';
|
|
3
3
|
import { clip, count, kept, names, num } from './rule.js';
|
|
4
4
|
/**
|
|
@@ -51,8 +51,9 @@ export const findable = {
|
|
|
51
51
|
// routes.yml: a route's tools should be in what a search for it returns.
|
|
52
52
|
for (const [keyword, expectation] of Object.entries(ctx.routes ?? {})) {
|
|
53
53
|
const present = (expectation.must_match ?? []).filter((n) => tools.some((t) => t.name === n));
|
|
54
|
+
const ranked = present.length ? index.rank(keyword) : [];
|
|
54
55
|
const lost = present
|
|
55
|
-
.map((n) => ({ n, ...
|
|
56
|
+
.map((n) => ({ n, ...placeIn(ranked, n) }))
|
|
56
57
|
.filter((r) => r.place === undefined || r.place > SEARCH_LIMIT);
|
|
57
58
|
for (const r of lost) {
|
|
58
59
|
findings.push({
|
package/dist/rules/spec.js
CHANGED
|
@@ -167,7 +167,8 @@ export const cacheHints = {
|
|
|
167
167
|
fix: 'If the tool set is stable, set a positive ttlMs on tools/list (3600000 is an hour).',
|
|
168
168
|
});
|
|
169
169
|
}
|
|
170
|
-
|
|
170
|
+
// With --as identities, spec/cache-scope-public answers this with evidence instead.
|
|
171
|
+
if (meta.cacheScope === 'public' && ctx.usedAuth && (ctx.identities?.length ?? 0) < 2) {
|
|
171
172
|
findings.push({
|
|
172
173
|
message: 'tools/list says cacheScope: "public" on a server that took credentials. Public lets shared caches serve the list to other callers, across authorization contexts. Fine only if the tool set never depends on who is asking.',
|
|
173
174
|
fix: 'If tools depend on the caller\'s account or scopes, set cacheScope: "private" on tools/list.',
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/** Each subschema of a schema node, with the step that reaches it: `{ key: 'properties', name: 'a' }`. */
|
|
2
|
+
export declare function children(node: Record<string, unknown>): {
|
|
3
|
+
key: string;
|
|
4
|
+
name?: string;
|
|
5
|
+
index?: number;
|
|
6
|
+
value: unknown;
|
|
7
|
+
}[];
|
|
8
|
+
/** What a ref points to: the value (an object, or a boolean schema such as `true`), and the top-level $defs entry it belongs to. */
|
|
9
|
+
export interface Target {
|
|
10
|
+
value: unknown;
|
|
11
|
+
entry?: string;
|
|
12
|
+
}
|
|
13
|
+
export interface SchemaIndex {
|
|
14
|
+
/** What a ref written inside a resource with base `base` points to; undefined when nothing in the schema matches. */
|
|
15
|
+
resolve(ref: string, base: string): Target | undefined;
|
|
16
|
+
/** Every $ref and $dynamicRef in the schema, with where it's written and the resource base it's resolved against. */
|
|
17
|
+
refs: {
|
|
18
|
+
ref: string;
|
|
19
|
+
base: string;
|
|
20
|
+
path: string[];
|
|
21
|
+
node: object;
|
|
22
|
+
}[];
|
|
23
|
+
/** The top-level $defs/definitions entry (`$defs/A`) a node belongs to, if any. */
|
|
24
|
+
entryOf(node: object): string | undefined;
|
|
25
|
+
}
|
|
26
|
+
/** Index one schema: its resources, anchors and references. */
|
|
27
|
+
export declare function indexSchema(schema: unknown): SchemaIndex;
|
|
28
|
+
/**
|
|
29
|
+
* Is the ref a network URI, which clients must not fetch? A fragment-only ref
|
|
30
|
+
* ("#/$defs/Typo", "#anchor") points into the schema it's written in, whatever that
|
|
31
|
+
* schema's $id: when it doesn't resolve, it's missing, not remote.
|
|
32
|
+
*/
|
|
33
|
+
export declare function isNetworkRef(ref: string, base: string): boolean;
|
|
34
|
+
/** Which top-level $defs/definitions entries a schema uses, following refs from outside them and then from the entries used. */
|
|
35
|
+
export declare function usedEntries(schema: unknown): Set<string>;
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* $ref resolution inside one JSON Schema, the way a client that must not fetch
|
|
3
|
+
* anything resolves it (2026-07-28, SEP-2106): JSON Pointers, $anchor and
|
|
4
|
+
* $dynamicAnchor, draft-07 plain-name $id ("#node"), and embedded resources
|
|
5
|
+
* named by $id, each pointer resolved inside the resource it's written in.
|
|
6
|
+
* Shared by spec/ref (does it resolve?) and the token breakdown (which $defs
|
|
7
|
+
* entries are used?), so the two always agree.
|
|
8
|
+
*/
|
|
9
|
+
/** Keywords whose value is one schema. */
|
|
10
|
+
const ONE = ['items', 'additionalItems', 'additionalProperties', 'unevaluatedProperties', 'unevaluatedItems', 'propertyNames', 'contains', 'not', 'if', 'then', 'else', 'contentSchema'];
|
|
11
|
+
/** Keywords whose value is a list of schemas (draft-07 `items` can be one too). */
|
|
12
|
+
const LIST = ['allOf', 'anyOf', 'oneOf', 'prefixItems', 'items'];
|
|
13
|
+
/** Keywords whose value maps names to schemas (draft-07 `dependencies` maps to a schema or a list of names; only the schemas count). */
|
|
14
|
+
const MAP = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas', 'dependencies'];
|
|
15
|
+
/** Each subschema of a schema node, with the step that reaches it: `{ key: 'properties', name: 'a' }`. */
|
|
16
|
+
export function children(node) {
|
|
17
|
+
const out = [];
|
|
18
|
+
for (const key of ONE) {
|
|
19
|
+
const v = node[key];
|
|
20
|
+
if (v && typeof v === 'object' && !Array.isArray(v))
|
|
21
|
+
out.push({ key, value: v });
|
|
22
|
+
}
|
|
23
|
+
for (const key of LIST) {
|
|
24
|
+
const v = node[key];
|
|
25
|
+
if (Array.isArray(v))
|
|
26
|
+
v.forEach((value, index) => out.push({ key, index, value }));
|
|
27
|
+
}
|
|
28
|
+
for (const key of MAP) {
|
|
29
|
+
const v = node[key];
|
|
30
|
+
if (v && typeof v === 'object' && !Array.isArray(v)) {
|
|
31
|
+
for (const [name, value] of Object.entries(v))
|
|
32
|
+
if (value && typeof value === 'object' && !Array.isArray(value))
|
|
33
|
+
out.push({ key, name, value });
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
return out;
|
|
37
|
+
}
|
|
38
|
+
/** A percent-escape that doesn't decode is kept as written, never thrown. */
|
|
39
|
+
function decode(part) {
|
|
40
|
+
let text = part;
|
|
41
|
+
try {
|
|
42
|
+
text = decodeURIComponent(part);
|
|
43
|
+
}
|
|
44
|
+
catch {
|
|
45
|
+
// keep it raw
|
|
46
|
+
}
|
|
47
|
+
return text.replace(/~1/g, '/').replace(/~0/g, '~');
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* A schema with no absolute $id still has a base: relative $ids and refs join
|
|
51
|
+
* against it ("dir/a.json" then "b.json" is "dir/b.json"), and it is never a
|
|
52
|
+
* network address. Its spelling never leaves this file.
|
|
53
|
+
*/
|
|
54
|
+
const LOCAL = 'toolmenu-schema:/';
|
|
55
|
+
const ABSOLUTE = /^[a-z][a-z0-9+.-]*:/i;
|
|
56
|
+
/** `base` + `ref` the way a URI resolves, normalized (case of scheme and host, dot segments), so two spellings of one URI match. */
|
|
57
|
+
function join(base, ref) {
|
|
58
|
+
try {
|
|
59
|
+
return new URL(ref, ABSOLUTE.test(base) ? base : LOCAL).href;
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
return ref;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
const strip = (uri) => uri.replace(/#$/, '');
|
|
66
|
+
/** Index one schema: its resources, anchors and references. */
|
|
67
|
+
export function indexSchema(schema) {
|
|
68
|
+
const resources = new Map();
|
|
69
|
+
const anchors = new Map();
|
|
70
|
+
const refs = [];
|
|
71
|
+
const entries = new Map();
|
|
72
|
+
const root = (schema && typeof schema === 'object' ? schema : {});
|
|
73
|
+
const rootBase = LOCAL;
|
|
74
|
+
const walk = (node, base, path, entry, depth) => {
|
|
75
|
+
if (!node || typeof node !== 'object' || Array.isArray(node) || depth > 64)
|
|
76
|
+
return;
|
|
77
|
+
const s = node;
|
|
78
|
+
if (entry)
|
|
79
|
+
entries.set(s, entry);
|
|
80
|
+
let here = base;
|
|
81
|
+
if (depth === 0)
|
|
82
|
+
resources.set(base, s);
|
|
83
|
+
if (typeof s.$id === 'string') {
|
|
84
|
+
// "#node" (draft-07 plain name), "a.json" or "a.json#node" (draft-06/07: a resource and a name for it).
|
|
85
|
+
const hash = s.$id.indexOf('#');
|
|
86
|
+
const uri = hash < 0 ? s.$id : s.$id.slice(0, hash);
|
|
87
|
+
const name = hash < 0 ? '' : s.$id.slice(hash + 1);
|
|
88
|
+
if (uri) {
|
|
89
|
+
here = strip(join(base, uri));
|
|
90
|
+
resources.set(here, s);
|
|
91
|
+
}
|
|
92
|
+
if (name && !name.startsWith('/'))
|
|
93
|
+
anchors.set(`${here}#${name}`, s);
|
|
94
|
+
}
|
|
95
|
+
for (const key of ['$anchor', '$dynamicAnchor'])
|
|
96
|
+
if (typeof s[key] === 'string')
|
|
97
|
+
anchors.set(`${here}#${s[key]}`, s);
|
|
98
|
+
for (const key of ['$ref', '$dynamicRef'])
|
|
99
|
+
if (typeof s[key] === 'string')
|
|
100
|
+
refs.push({ ref: s[key], base: here, path, node: s });
|
|
101
|
+
for (const c of children(s)) {
|
|
102
|
+
const step = c.key === 'properties' ? c.name : c.name !== undefined ? `<${c.key}>.${c.name}` : c.index !== undefined ? `<${c.key}>.${c.index}` : `<${c.key}>`;
|
|
103
|
+
const owner = entry ?? (depth === 0 && (c.key === '$defs' || c.key === 'definitions') ? `${c.key}/${c.name}` : undefined);
|
|
104
|
+
walk(c.value, here, [...path, step], owner, depth + 1);
|
|
105
|
+
}
|
|
106
|
+
};
|
|
107
|
+
walk(root, rootBase, [], undefined, 0);
|
|
108
|
+
const pointer = (resource, fragment) => {
|
|
109
|
+
if (fragment === '' || fragment === '/')
|
|
110
|
+
return { value: resource, entry: entries.get(resource) };
|
|
111
|
+
const parts = fragment.slice(1).split('/').map(decode);
|
|
112
|
+
let node = resource;
|
|
113
|
+
for (const part of parts) {
|
|
114
|
+
if (Array.isArray(node) && /^\d+$/.test(part) && Number(part) < node.length)
|
|
115
|
+
node = node[Number(part)];
|
|
116
|
+
else if (node && typeof node === 'object' && Object.prototype.hasOwnProperty.call(node, part))
|
|
117
|
+
node = node[part];
|
|
118
|
+
else
|
|
119
|
+
return undefined;
|
|
120
|
+
}
|
|
121
|
+
// The entry comes from where the pointer goes: a path under the root's $defs, the
|
|
122
|
+
// entry the resource itself sits in, or the node's own. Not only the node's: a
|
|
123
|
+
// boolean schema ($defs: { Any: true }) or an object inside a list the walk doesn't
|
|
124
|
+
// enter (an entry's `examples`) is still inside its entry.
|
|
125
|
+
const entry = (resource === root && (parts[0] === '$defs' || parts[0] === 'definitions') && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : undefined) ??
|
|
126
|
+
entries.get(resource) ??
|
|
127
|
+
(node && typeof node === 'object' ? entries.get(node) : undefined);
|
|
128
|
+
return { value: node, ...(entry ? { entry } : {}) };
|
|
129
|
+
};
|
|
130
|
+
return {
|
|
131
|
+
refs,
|
|
132
|
+
entryOf: (node) => entries.get(node),
|
|
133
|
+
resolve(ref, base) {
|
|
134
|
+
// The resource from the URI part, joined and normalized; the fragment as written
|
|
135
|
+
// (the URL parser would re-encode it). A pointer is split into segments before
|
|
136
|
+
// any is decoded: "~1" is a "/" inside one segment.
|
|
137
|
+
const hash = ref.indexOf('#');
|
|
138
|
+
const uri = hash < 0 ? ref : ref.slice(0, hash);
|
|
139
|
+
const where = uri ? strip(join(base, uri)) : base;
|
|
140
|
+
const fragment = hash < 0 ? '' : ref.slice(hash + 1);
|
|
141
|
+
const resource = resources.get(where);
|
|
142
|
+
if (!resource)
|
|
143
|
+
return undefined;
|
|
144
|
+
if (fragment === '' || fragment.startsWith('/'))
|
|
145
|
+
return pointer(resource, fragment);
|
|
146
|
+
const anchored = anchors.get(`${where}#${decode(fragment)}`);
|
|
147
|
+
return anchored ? { value: anchored, ...(entries.get(anchored) ? { entry: entries.get(anchored) } : {}) } : undefined;
|
|
148
|
+
},
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Is the ref a network URI, which clients must not fetch? A fragment-only ref
|
|
153
|
+
* ("#/$defs/Typo", "#anchor") points into the schema it's written in, whatever that
|
|
154
|
+
* schema's $id: when it doesn't resolve, it's missing, not remote.
|
|
155
|
+
*/
|
|
156
|
+
export function isNetworkRef(ref, base) {
|
|
157
|
+
if (ref === '' || ref.startsWith('#'))
|
|
158
|
+
return false;
|
|
159
|
+
return /^https?:\/\//i.test(join(base, ref));
|
|
160
|
+
}
|
|
161
|
+
/** Which top-level $defs/definitions entries a schema uses, following refs from outside them and then from the entries used. */
|
|
162
|
+
export function usedEntries(schema) {
|
|
163
|
+
const index = indexSchema(schema);
|
|
164
|
+
const used = new Set();
|
|
165
|
+
const queue = index.refs.filter((r) => !index.entryOf(r.node));
|
|
166
|
+
while (queue.length) {
|
|
167
|
+
const r = queue.pop();
|
|
168
|
+
const entry = index.resolve(r.ref, r.base)?.entry;
|
|
169
|
+
if (!entry || used.has(entry))
|
|
170
|
+
continue;
|
|
171
|
+
used.add(entry);
|
|
172
|
+
// Every ref written inside the entry now counts too ($ref and $dynamicRef on one node alike).
|
|
173
|
+
for (const inner of index.refs)
|
|
174
|
+
if (index.entryOf(inner.node) === entry)
|
|
175
|
+
queue.push(inner);
|
|
176
|
+
}
|
|
177
|
+
return used;
|
|
178
|
+
}
|
package/dist/search.d.ts
CHANGED
|
@@ -22,3 +22,11 @@ export declare function placeOf(index: SearchIndex, query: string, tool: string)
|
|
|
22
22
|
place?: number;
|
|
23
23
|
ahead: string[];
|
|
24
24
|
};
|
|
25
|
+
/** placeOf on a ranking already made: one ranking per query, however many tools are looked up in it. */
|
|
26
|
+
export declare function placeIn(ranked: {
|
|
27
|
+
tool: string;
|
|
28
|
+
score: number;
|
|
29
|
+
}[], tool: string): {
|
|
30
|
+
place?: number;
|
|
31
|
+
ahead: string[];
|
|
32
|
+
};
|
package/dist/search.js
CHANGED
|
@@ -77,7 +77,10 @@ export function buildIndex(tools) {
|
|
|
77
77
|
* coin flip. Undefined when the query matches nothing in the tool.
|
|
78
78
|
*/
|
|
79
79
|
export function placeOf(index, query, tool) {
|
|
80
|
-
|
|
80
|
+
return placeIn(index.rank(query), tool);
|
|
81
|
+
}
|
|
82
|
+
/** placeOf on a ranking already made: one ranking per query, however many tools are looked up in it. */
|
|
83
|
+
export function placeIn(ranked, tool) {
|
|
81
84
|
const mine = ranked.find((r) => r.tool === tool);
|
|
82
85
|
if (!mine)
|
|
83
86
|
return { ahead: ranked.slice(0, SEARCH_LIMIT).map((r) => r.tool) };
|
package/dist/session.d.ts
CHANGED
|
@@ -15,6 +15,12 @@ export type Step = {
|
|
|
15
15
|
* alone. If its first such call changes nothing, the rest aren't made.
|
|
16
16
|
*/
|
|
17
17
|
tentative?: boolean;
|
|
18
|
+
/**
|
|
19
|
+
* --auto only (2026-07-28): called with a handle that can't exist, to see what
|
|
20
|
+
* the model gets back. A tool error is the right answer; a JSON-RPC error is
|
|
21
|
+
* session/handle-error.
|
|
22
|
+
*/
|
|
23
|
+
probe?: import('./rules/handles.js').HandleProbe;
|
|
18
24
|
} | {
|
|
19
25
|
kind: 'wait_for';
|
|
20
26
|
event: 'tools_list_changed';
|
|
@@ -126,6 +132,17 @@ export declare function changeFindings(before: MenuTool[], after: MenuTool[], ch
|
|
|
126
132
|
export declare function scopeOf(changes: ToolChange[], next: MenuTool[], probe: MenuTool[], transport: Target['kind'], baseline?: MenuTool[]): Scope;
|
|
127
133
|
export declare function mergeRepeats(raw: Raw[]): Raw[];
|
|
128
134
|
export type { Era };
|
|
135
|
+
/**
|
|
136
|
+
* An unlock that surely unlocks tools: it says so (name or description), or its
|
|
137
|
+
* parameter is named for tool sets outright (toolsets). One that only has an enum of domains, and
|
|
138
|
+
* doesn't say it unlocks anything, may be data: session --auto still tries it once,
|
|
139
|
+
* but menu/gated and session/unlock-coverage don't charge it.
|
|
140
|
+
*/
|
|
141
|
+
export declare function definite(u: {
|
|
142
|
+
claims: boolean;
|
|
143
|
+
param?: string;
|
|
144
|
+
tool?: MenuTool;
|
|
145
|
+
}): boolean;
|
|
129
146
|
interface Unlocker {
|
|
130
147
|
tool: MenuTool;
|
|
131
148
|
score: number;
|