toolmenu 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +84 -23
  2. package/dist/args.d.ts +31 -5
  3. package/dist/args.js +91 -14
  4. package/dist/auth.d.ts +4 -2
  5. package/dist/auth.js +59 -21
  6. package/dist/auto.d.ts +80 -6
  7. package/dist/auto.js +255 -19
  8. package/dist/breakdown.d.ts +2 -0
  9. package/dist/breakdown.js +64 -19
  10. package/dist/catalog.d.ts +87 -10
  11. package/dist/catalog.js +415 -58
  12. package/dist/cli.js +170 -185
  13. package/dist/close.d.ts +8 -0
  14. package/dist/close.js +18 -0
  15. package/dist/config.d.ts +7 -1
  16. package/dist/config.js +17 -0
  17. package/dist/connect.d.ts +14 -0
  18. package/dist/connect.js +150 -16
  19. package/dist/diff.d.ts +23 -1
  20. package/dist/diff.js +574 -120
  21. package/dist/difference.d.ts +2 -0
  22. package/dist/difference.js +13 -12
  23. package/dist/explain.d.ts +113 -0
  24. package/dist/explain.js +461 -0
  25. package/dist/failures.d.ts +15 -0
  26. package/dist/failures.js +59 -2
  27. package/dist/help.d.ts +11 -0
  28. package/dist/help.js +205 -0
  29. package/dist/history.d.ts +13 -0
  30. package/dist/history.js +86 -6
  31. package/dist/init.d.ts +93 -2
  32. package/dist/init.js +508 -21
  33. package/dist/menu.js +10 -2
  34. package/dist/options.d.ts +141 -0
  35. package/dist/options.js +50 -0
  36. package/dist/report.d.ts +2 -2
  37. package/dist/report.js +305 -101
  38. package/dist/rules/description.d.ts +7 -2
  39. package/dist/rules/description.js +86 -42
  40. package/dist/rules/determinism.d.ts +4 -1
  41. package/dist/rules/determinism.js +175 -11
  42. package/dist/rules/gated.d.ts +7 -0
  43. package/dist/rules/gated.js +77 -0
  44. package/dist/rules/ids.d.ts +1 -1
  45. package/dist/rules/ids.js +9 -4
  46. package/dist/rules/index.d.ts +6 -0
  47. package/dist/rules/index.js +18 -6
  48. package/dist/rules/naming.d.ts +1 -1
  49. package/dist/rules/naming.js +91 -21
  50. package/dist/rules/rule.d.ts +25 -0
  51. package/dist/rules/rule.js +25 -1
  52. package/dist/rules/spec.d.ts +6 -0
  53. package/dist/rules/spec.js +56 -9
  54. package/dist/rules/write.d.ts +1 -1
  55. package/dist/rules/write.js +64 -14
  56. package/dist/session.d.ts +34 -9
  57. package/dist/session.js +525 -94
  58. package/dist/snapshot.d.ts +8 -2
  59. package/dist/snapshot.js +33 -2
  60. package/dist/types.d.ts +21 -0
  61. package/dist/words.d.ts +5 -0
  62. package/dist/words.js +14 -0
  63. package/package.json +2 -2
package/dist/auto.d.ts CHANGED
@@ -1,28 +1,102 @@
1
1
  import { type Scenario } from './session.js';
2
- import type { Menu } from './types.js';
2
+ import type { Menu, MenuTool } from './types.js';
3
+ /** A value the user gave: `raw` is the text as typed on the command line, when it was typed. */
4
+ export interface GivenValue {
5
+ /** The text as typed, for fitValue: `42` for a string parameter is "42". */
6
+ raw?: string;
7
+ value: unknown;
8
+ /** A values file's map grouped by tool: each field with its own text. */
9
+ fields?: Record<string, GivenValue>;
10
+ }
3
11
  export interface AutoOptions {
4
12
  /** Also call read-only tools marked openWorldHint: true (web search, fetch, scraping). */
5
13
  openWorld?: boolean;
6
14
  /** At most this many calls (default 20). */
7
15
  maxCalls?: number;
16
+ /**
17
+ * Only the calls: no list first, no repeat of the first call at the end. For
18
+ * tools that appear mid-session, planned into a session already running.
19
+ */
20
+ callsOnly?: boolean;
21
+ /**
22
+ * Values for required parameters, by name (`repo_path`) or for one tool
23
+ * (`get_issue.issue_key`). Used before anything is synthesized.
24
+ */
25
+ values?: Record<string, GivenValue>;
26
+ /**
27
+ * Tools the user says only read, although the server doesn't mark them
28
+ * readOnlyHint. Exact names: a pattern would also cover tools a later release
29
+ * adds, which nobody has looked at. A tool marked or named as a write is still
30
+ * never called.
31
+ */
32
+ assumeReadOnly?: string[];
8
33
  }
9
- export type SkipReason = 'not read-only' | 'open world' | 'needs values' | 'over the call budget';
34
+ export type SkipReason = 'not read-only' | 'unmarked' | 'open world' | 'needs values' | 'over the call budget' | 'over the per-unlock budget';
10
35
  export interface AutoPlan {
11
36
  scenario: Scenario;
12
37
  called: string[];
38
+ /** Called on the user's word (--assume-read-only): the server doesn't mark them readOnlyHint. */
39
+ assumed: string[];
40
+ /** Called with at least one value the user gave. */
41
+ withValues: string[];
13
42
  skipped: {
14
43
  tool: string;
15
44
  reason: SkipReason;
16
45
  missing?: string[];
46
+ why?: string;
47
+ }[];
48
+ /** --value and --assume-read-only entries that did nothing, and why. */
49
+ ignored: {
50
+ input: string;
51
+ why: string;
17
52
  }[];
53
+ /** Calls counted against --max-calls (unlocks aren't). */
54
+ spent: number;
55
+ /** Unlock calls the plan makes, one per value (not the repeat): each gets its own budget for the tools it brings. */
56
+ unlockValues: number;
18
57
  }
58
+ /** What a session report shows about an --auto plan. */
59
+ export type AutoSummary = Pick<AutoPlan, 'called' | 'skipped'> & Partial<Pick<AutoPlan, 'assumed' | 'withValues' | 'ignored'>> & {
60
+ maxCalls?: number;
61
+ maxCallsPerUnlock?: number;
62
+ /** Guessed unlocks whose first value changed nothing, and how many calls to them were left out. */
63
+ stopped?: {
64
+ tool: string;
65
+ calls: number;
66
+ }[];
67
+ };
68
+ /** Marked or named as a write: never called on the user's word. Says why, or undefined. */
69
+ export declare function writeSign(tool: MenuTool): string | undefined;
19
70
  /**
20
71
  * A scenario built from the menu, no hand-written steps: every read-only tool
21
- * whose required arguments the schema can fill, cheapest first (no arguments,
22
- * then lists and searches, then single lookups, then the rest), then the first
23
- * call again, which should change nothing. Never a tool that isn't marked
24
- * readOnlyHint, whatever allow_writes says.
72
+ * whose required arguments the user's values and the schema can fill, cheapest
73
+ * first (no arguments, then lists and searches, then single lookups, then the
74
+ * rest), then the first call again, which should change nothing. Never a tool that
75
+ * isn't marked readOnlyHint, whatever allow_writes says, unless the user named it
76
+ * in assumeReadOnly and nothing marks or names it as a write.
25
77
  */
26
78
  export declare function autoScenario(menu: Menu, options?: AutoOptions): AutoPlan;
79
+ /** `name=value` from --value: JSON when it parses (numbers, true, lists), the text otherwise. */
80
+ export declare function parseValueFlag(text: string): [string, GivenValue];
81
+ /** A values file: a YAML or JSON map, keys as in --value (`repo_path`, `get_issue.issue_key`). */
82
+ export declare function loadValuesFile(path: string): Promise<Record<string, GivenValue>>;
83
+ /** --assume-read-only a,b --assume-read-only c: exact names, no patterns. */
84
+ export declare function parseAssumeReadOnly(flags: string[]): string[];
85
+ /** Parameters the skipped tools need, most needed first, with how many tools each fills. */
86
+ export declare function neededValues(skipped: AutoPlan['skipped']): {
87
+ param: string;
88
+ tools: string[];
89
+ }[];
90
+ /**
91
+ * The one flag or two that would let --auto call more, as a next step: values for
92
+ * the parameters most tools need, the unmarked tools to vouch for, --open-world.
93
+ * Undefined when nothing was left out that a flag can reach.
94
+ */
95
+ export declare function autoNextStep(auto: AutoSummary): string | undefined;
96
+ /**
97
+ * What --auto called and what it left out, each with the flag that reaches it: the
98
+ * header line of a session report, then one line per reason.
99
+ */
100
+ export declare function autoSummary(auto: AutoSummary): string[];
27
101
  /** The plan as a scenario file, to commit and run again with --scenario. */
28
102
  export declare function scenarioYaml(plan: AutoPlan, serverName?: string): string;
package/dist/auto.js CHANGED
@@ -1,16 +1,49 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { isMap, isNode, isScalar, parseDocument } from 'yaml';
1
3
  import { synthesizeArgs } from './args.js';
2
4
  import { MAX_UNLOCKS, unlockers } from './session.js';
3
- import { COLLECTION_VERBS, LOOKUP_VERBS, verbOf } from './words.js';
5
+ import { COLLECTION_VERBS, LOOKUP_VERBS, verbOf, WRITE_VERBS } from './words.js';
6
+ /** Marked or named as a write: never called on the user's word. Says why, or undefined. */
7
+ export function writeSign(tool) {
8
+ const a = tool.annotations ?? {};
9
+ if (a.readOnlyHint === false)
10
+ return 'the server marks it readOnlyHint: false';
11
+ if (a.destructiveHint === true)
12
+ return 'the server marks it destructiveHint: true';
13
+ const verb = verbOf(tool.name);
14
+ if (verb && WRITE_VERBS.has(verb))
15
+ return `its name starts with "${verb}", a write`;
16
+ return undefined;
17
+ }
4
18
  /**
5
19
  * A scenario built from the menu, no hand-written steps: every read-only tool
6
- * whose required arguments the schema can fill, cheapest first (no arguments,
7
- * then lists and searches, then single lookups, then the rest), then the first
8
- * call again, which should change nothing. Never a tool that isn't marked
9
- * readOnlyHint, whatever allow_writes says.
20
+ * whose required arguments the user's values and the schema can fill, cheapest
21
+ * first (no arguments, then lists and searches, then single lookups, then the
22
+ * rest), then the first call again, which should change nothing. Never a tool that
23
+ * isn't marked readOnlyHint, whatever allow_writes says, unless the user named it
24
+ * in assumeReadOnly and nothing marks or names it as a write.
10
25
  */
11
26
  export function autoScenario(menu, options = {}) {
12
27
  const maxCalls = options.maxCalls ?? 20;
13
28
  const skipped = [];
29
+ const ignored = [];
30
+ const byName = new Map(menu.tools.map((t) => [t.name, t]));
31
+ // --assume-read-only: exact names, and never a write.
32
+ const assumed = new Set();
33
+ for (const name of options.assumeReadOnly ?? []) {
34
+ const tool = byName.get(name);
35
+ if (!tool)
36
+ ignored.push({ input: `--assume-read-only ${name}`, why: 'no tool by that name in the menu' });
37
+ else if (tool.annotations?.readOnlyHint === true)
38
+ ignored.push({ input: `--assume-read-only ${name}`, why: 'the server already marks it readOnlyHint: true' });
39
+ else if (writeSign(tool))
40
+ ignored.push({ input: `--assume-read-only ${name}`, why: `not called: ${writeSign(tool)}` });
41
+ else
42
+ assumed.add(name);
43
+ }
44
+ const readOnly = (t) => t.annotations?.readOnlyHint === true || assumed.has(t.name);
45
+ const { perTool, ignored: unusedValues } = resolveValues(menu, options.values ?? {});
46
+ ignored.push(...unusedValues);
14
47
  const candidates = [];
15
48
  // Read-only unlocks with every value in an enum: each value, outside the call
16
49
  // budget, so the tools behind every toolset are seen (GitHub: 19 toolsets).
@@ -19,17 +52,17 @@ export function autoScenario(menu, options = {}) {
19
52
  // server whose every tool calls an outside service marks its unlock that way too,
20
53
  // and --auto then tested nothing.
21
54
  const unlocks = unlockers(menu.tools).filter((u) => {
22
- const a = u.tool.annotations ?? {};
23
55
  const required = u.tool.inputSchema?.required ?? [];
24
- return u.param && u.values.length && a.readOnlyHint === true && required.every((p) => p === u.param);
56
+ return u.param && u.values.length && readOnly(u.tool) && required.every((p) => p === u.param);
25
57
  });
26
58
  const unlocking = new Set(unlocks.map((u) => u.tool.name));
27
59
  for (const tool of menu.tools) {
28
60
  if (unlocking.has(tool.name))
29
61
  continue;
30
62
  const a = tool.annotations ?? {};
31
- if (a.readOnlyHint !== true) {
32
- skipped.push({ tool: tool.name, reason: 'not read-only' });
63
+ if (!readOnly(tool)) {
64
+ const write = writeSign(tool);
65
+ skipped.push(write || a.readOnlyHint !== undefined ? { tool: tool.name, reason: 'not read-only', ...(write ? { why: write } : {}) } : { tool: tool.name, reason: 'unmarked' });
33
66
  continue;
34
67
  }
35
68
  // readOnlyHint is the server's own claim, and a read-only search still spends
@@ -41,31 +74,155 @@ export function autoScenario(menu, options = {}) {
41
74
  skipped.push({ tool: tool.name, reason: 'open world' });
42
75
  continue;
43
76
  }
44
- const filled = synthesizeArgs(tool.inputSchema);
77
+ const filled = synthesizeArgs(tool.inputSchema, perTool.get(tool.name));
45
78
  if (!filled.ok) {
46
79
  skipped.push({ tool: tool.name, reason: 'needs values', missing: filled.missing });
47
80
  continue;
48
81
  }
49
- candidates.push({ tool, args: filled.args, rank: rank(tool, filled.args) });
82
+ candidates.push({ tool, args: filled.args, rank: rank(tool, filled.args), valued: Object.values(filled.sources).includes('value') });
50
83
  }
51
84
  candidates.sort((x, y) => x.rank - y.rank);
52
85
  const chosen = candidates.slice(0, maxCalls);
53
86
  for (const c of candidates.slice(maxCalls))
54
87
  skipped.push({ tool: c.tool.name, reason: 'over the call budget' });
55
- const steps = [{ kind: 'list' }];
88
+ const steps = options.callsOnly ? [] : [{ kind: 'list' }];
56
89
  for (const c of chosen)
57
90
  steps.push({ kind: 'call', tool: c.tool.name, args: c.args });
58
91
  for (const u of unlocks) {
59
92
  const array = u.tool.inputSchema?.properties?.[u.param]?.type === 'array';
60
93
  const values = u.values.slice(0, MAX_UNLOCKS);
94
+ // Guessed from its schema alone (nothing says it unlocks tools): if the first
95
+ // value changes nothing, the session doesn't spend a call on every other one.
96
+ const tentative = u.claims ? {} : { tentative: true };
61
97
  for (const v of values)
62
- steps.push({ kind: 'call', tool: u.tool.name, args: { [u.param]: array ? [v] : v } });
98
+ steps.push({ kind: 'call', tool: u.tool.name, args: { [u.param]: array ? [v] : v }, ...tentative });
63
99
  // The same unlock again should change nothing, as in the --init starter.
64
- steps.push({ kind: 'call', tool: u.tool.name, args: { [u.param]: array ? [values[0]] : values[0] } });
100
+ steps.push({ kind: 'call', tool: u.tool.name, args: { [u.param]: array ? [values[0]] : values[0] }, ...tentative });
65
101
  }
66
- if (chosen.length)
102
+ if (chosen.length && !options.callsOnly)
67
103
  steps.push({ kind: 'call', tool: chosen[0].tool.name, args: chosen[0].args });
68
- return { scenario: { allowWrites: false, steps }, called: [...chosen.map((c) => c.tool.name), ...unlocks.map((u) => u.tool.name)], skipped };
104
+ const called = [...chosen.map((c) => c.tool.name), ...unlocks.map((u) => u.tool.name)];
105
+ return {
106
+ scenario: { allowWrites: false, steps, ...(assumed.size ? { assumeReadOnly: [...assumed] } : {}) },
107
+ called,
108
+ assumed: called.filter((n) => assumed.has(n)),
109
+ withValues: chosen.filter((c) => c.valued).map((c) => c.tool.name),
110
+ skipped,
111
+ ignored,
112
+ spent: chosen.length,
113
+ unlockValues: unlocks.reduce((n, u) => n + Math.min(u.values.length, MAX_UNLOCKS), 0),
114
+ };
115
+ }
116
+ /**
117
+ * The user's values, per tool. `param` fills that required parameter wherever a
118
+ * tool has it; `tool.param` fills it, required or not, on that tool only (and
119
+ * wins over a by-name value). A value no tool takes is reported, not dropped.
120
+ */
121
+ function resolveValues(menu, values) {
122
+ const perTool = new Map();
123
+ const ignored = [];
124
+ const set = (tool, param, v) => perTool.set(tool, { ...perTool.get(tool), [param]: v });
125
+ const byName = new Map(menu.tools.map((t) => [t.name, t]));
126
+ const targeted = [];
127
+ for (const [key, v] of Object.entries(values)) {
128
+ // A values file can group by tool: `get_issue: { issue_key: ABC-1 }`.
129
+ if (byName.has(key) && v.raw === undefined && v.value && typeof v.value === 'object' && !Array.isArray(v.value)) {
130
+ for (const [param, pv] of Object.entries(v.value)) {
131
+ if (!byName.get(key).inputSchema?.properties?.[param])
132
+ ignored.push({ input: `${key}.${param}`, why: `${key} has no parameter ${param}` });
133
+ else
134
+ targeted.push([key, param, v.fields?.[param] ?? { value: pv, ...(typeof pv === 'string' ? { raw: pv } : {}) }]);
135
+ }
136
+ continue;
137
+ }
138
+ const dot = key.lastIndexOf('.');
139
+ const toolName = dot > 0 ? key.slice(0, dot) : '';
140
+ if (toolName && byName.has(toolName)) {
141
+ const param = key.slice(dot + 1);
142
+ if (!byName.get(toolName).inputSchema?.properties?.[param])
143
+ ignored.push({ input: `--value ${key}`, why: `${toolName} has no parameter ${param}` });
144
+ else
145
+ targeted.push([toolName, param, v]);
146
+ continue;
147
+ }
148
+ const takers = menu.tools.filter((t) => (t.inputSchema?.required ?? []).includes(key));
149
+ if (takers.length) {
150
+ for (const t of takers)
151
+ set(t.name, key, v);
152
+ continue;
153
+ }
154
+ const optional = menu.tools.filter((t) => t.inputSchema?.properties?.[key]).map((t) => t.name);
155
+ ignored.push({
156
+ input: `--value ${key}`,
157
+ why: optional.length
158
+ ? `no tool requires ${key}; to pass it where it's optional, name the tool (--value ${optional[0]}.${key}=…)`
159
+ : toolName
160
+ ? `no tool named ${toolName}, and no parameter named ${key}`
161
+ : `no tool takes a parameter named ${key}`,
162
+ });
163
+ }
164
+ for (const [tool, param, v] of targeted)
165
+ set(tool, param, v);
166
+ return { perTool, ignored };
167
+ }
168
+ /** `name=value` from --value: JSON when it parses (numbers, true, lists), the text otherwise. */
169
+ export function parseValueFlag(text) {
170
+ const eq = text.indexOf('=');
171
+ if (eq <= 0)
172
+ throw new Error(`--value ${text}: expected name=value or tool.name=value (e.g. --value repo_path=/src/app)`);
173
+ const key = text.slice(0, eq).trim();
174
+ const raw = text.slice(eq + 1);
175
+ let value = raw;
176
+ try {
177
+ value = JSON.parse(raw);
178
+ }
179
+ catch {
180
+ // plain text
181
+ }
182
+ return [key, { raw, value }];
183
+ }
184
+ /** A values file: a YAML or JSON map, keys as in --value (`repo_path`, `get_issue.issue_key`). */
185
+ export async function loadValuesFile(path) {
186
+ let doc;
187
+ try {
188
+ doc = parseDocument(await readFile(path, 'utf8'));
189
+ if (doc.errors.length)
190
+ throw doc.errors[0];
191
+ }
192
+ catch (error) {
193
+ throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`);
194
+ }
195
+ if (!isMap(doc.contents))
196
+ throw new Error(`${path}: expected a map of parameter names to values (repo_path: /src/app)`);
197
+ const data = doc.toJS();
198
+ const out = {};
199
+ for (const pair of doc.contents.items) {
200
+ const key = String(isScalar(pair.key) ? pair.key.value : pair.key);
201
+ // Grouped per tool (`get_issue: { issue_key: ABC-1 }`) is sorted out against the menu.
202
+ const fields = isMap(pair.value)
203
+ ? Object.fromEntries(pair.value.items.map((p) => [String(isScalar(p.key) ? p.key.value : p.key), given(p.value)]))
204
+ : undefined;
205
+ out[key] = { ...given(pair.value, data[key]), ...(fields ? { fields } : {}) };
206
+ }
207
+ return out;
208
+ }
209
+ /**
210
+ * One value from a values file, with the text a scalar was written as: YAML reads
211
+ * `42` as a number and `02134` as 2134, but for a string parameter the user meant
212
+ * the text, as with --value.
213
+ */
214
+ function given(node, value = isNode(node) ? node.toJSON() : node) {
215
+ const raw = isScalar(node) ? (node.source ?? (typeof node.value === 'string' ? node.value : undefined)) : undefined;
216
+ return { value, ...(raw !== undefined ? { raw } : {}) };
217
+ }
218
+ /** --assume-read-only a,b --assume-read-only c: exact names, no patterns. */
219
+ export function parseAssumeReadOnly(flags) {
220
+ const names = flags.flatMap((f) => f.split(',')).map((s) => s.trim()).filter(Boolean);
221
+ const pattern = names.find((n) => /[*?[\]]/.test(n));
222
+ if (pattern) {
223
+ throw new Error(`--assume-read-only takes exact tool names, not patterns (${pattern}): a pattern would also cover tools a later release adds, which nobody has checked. List the tools.`);
224
+ }
225
+ return [...new Set(names)];
69
226
  }
70
227
  function rank(tool, args) {
71
228
  if (Object.keys(args).length === 0)
@@ -77,14 +234,91 @@ function rank(tool, args) {
77
234
  return 2;
78
235
  return 3;
79
236
  }
237
+ /** Parameters the skipped tools need, most needed first, with how many tools each fills. */
238
+ export function neededValues(skipped) {
239
+ const by = new Map();
240
+ for (const s of skipped)
241
+ if (s.reason === 'needs values')
242
+ for (const m of s.missing ?? [])
243
+ by.set(m, [...(by.get(m) ?? []), s.tool]);
244
+ return [...by].map(([param, tools]) => ({ param, tools })).sort((a, b) => b.tools.length - a.tools.length || a.param.localeCompare(b.param));
245
+ }
246
+ /**
247
+ * The one flag or two that would let --auto call more, as a next step: values for
248
+ * the parameters most tools need, the unmarked tools to vouch for, --open-world.
249
+ * Undefined when nothing was left out that a flag can reach.
250
+ */
251
+ export function autoNextStep(auto) {
252
+ const needs = neededValues(auto.skipped);
253
+ const unmarked = auto.skipped.filter((s) => s.reason === 'unmarked').map((s) => s.tool);
254
+ const openWorld = auto.skipped.filter((s) => s.reason === 'open world').length;
255
+ const parts = [];
256
+ if (needs.length) {
257
+ const top = needs.slice(0, 3).map((n) => `--value ${n.param}=…`).join(' ');
258
+ parts.push(needs.length > 3 ? `${top} (or --save-scenario auto.yml and fill in the other ${needs.length - 3})` : top);
259
+ }
260
+ if (unmarked.length)
261
+ parts.push(`--assume-read-only ${list(unmarked, 4, ',')} for the ones that only read`);
262
+ if (openWorld)
263
+ parts.push('--open-world (may cost API credits)');
264
+ return parts.length ? `Rerun with ${parts.join('; or ')}.` : undefined;
265
+ }
266
+ function list(names, max, sep = ', ') {
267
+ return names.slice(0, max).join(sep) + (names.length > max ? `${sep === ',' ? ',' : sep}…` : '');
268
+ }
269
+ /**
270
+ * What --auto called and what it left out, each with the flag that reaches it: the
271
+ * header line of a session report, then one line per reason.
272
+ */
273
+ export function autoSummary(auto) {
274
+ const n = auto.called.length;
275
+ const extras = [
276
+ auto.withValues?.length ? `${auto.withValues.length} with your --value` : '',
277
+ auto.assumed?.length ? `${auto.assumed.length} on your word, not marked read-only: ${list(auto.assumed, 6)}` : '',
278
+ ].filter(Boolean);
279
+ const lines = [`auto: called ${n} tool${n === 1 ? '' : 's'}${extras.length ? ` (${extras.join('; ')})` : ''}`];
280
+ const skip = (reason) => auto.skipped.filter((s) => s.reason === reason);
281
+ const rows = [];
282
+ const needs = skip('needs values');
283
+ if (needs.length) {
284
+ const params = neededValues(auto.skipped);
285
+ const shown = params.slice(0, 4).map((p) => `--value ${p.param}=… (${p.tools.length})`);
286
+ rows.push(`${needs.length} ${needs.length === 1 ? 'needs' : 'need'} values the schema doesn't give → ${shown.join(', ')}${params.length > 4 ? `, and ${params.length - 4} more (--save-scenario lists them)` : ''}`);
287
+ }
288
+ const unmarked = skip('unmarked');
289
+ if (unmarked.length)
290
+ rows.push(`${unmarked.length} not marked read-only → --assume-read-only ${list(unmarked.map((s) => s.tool), 4, ',')} if they only read`);
291
+ const writes = skip('not read-only');
292
+ if (writes.length)
293
+ rows.push(`${writes.length} marked or named as writes (never called)`);
294
+ const openWorld = skip('open world');
295
+ if (openWorld.length)
296
+ rows.push(`${openWorld.length} marked openWorldHint → --open-world (may cost API credits)`);
297
+ const over = skip('over the call budget');
298
+ // Unlocks run outside the budget, so called.length would overshoot.
299
+ if (over.length)
300
+ rows.push(`${over.length} over the call budget → --max-calls ${(auto.maxCalls ?? 20) + over.length}`);
301
+ const overUnlock = skip('over the per-unlock budget');
302
+ if (overUnlock.length)
303
+ rows.push(`${overUnlock.length} over the per-unlock budget → --max-calls-per-unlock ${(auto.maxCallsPerUnlock ?? 5) + overUnlock.length}`);
304
+ rows.forEach((r, i) => lines.push(`${i === 0 ? 'not called: ' : ' '}${r}`));
305
+ for (const x of auto.stopped ?? [])
306
+ lines.push(`stopped: ${x.tool}: its first value changed nothing and it doesn't say it unlocks tools, so the other ${x.calls} call${x.calls === 1 ? ' was' : 's were'} left out (a scenario can still make them)`);
307
+ for (const x of auto.ignored ?? [])
308
+ lines.push(`ignored: ${x.input}: ${x.why}`);
309
+ return lines;
310
+ }
80
311
  /** The plan as a scenario file, to commit and run again with --scenario. */
81
312
  export function scenarioYaml(plan, serverName) {
82
313
  const lines = [
83
314
  `# Written by \`toolmenu session --auto\`${serverName ? ` for ${serverName}` : ''}: every read-only tool whose`,
84
- '# required arguments the schema could fill. Edit freely.',
315
+ '# required arguments your values and the schema could fill. Edit freely.',
85
316
  'allow_writes: false',
86
- 'steps:',
87
317
  ];
318
+ if (plan.assumed.length) {
319
+ lines.push('# Not marked readOnlyHint by the server; called because you said they only read:', `assume_read_only: [${plan.assumed.map((n) => JSON.stringify(n)).join(', ')}]`);
320
+ }
321
+ lines.push('steps:');
88
322
  for (const step of plan.scenario.steps) {
89
323
  if (step.kind === 'list')
90
324
  lines.push(' - list');
@@ -96,9 +330,11 @@ export function scenarioYaml(plan, serverName) {
96
330
  }
97
331
  const needs = plan.skipped.filter((s) => s.reason === 'needs values');
98
332
  if (needs.length) {
99
- lines.push('', ' # Read-only tools that need values the schema doesn\'t give:');
333
+ lines.push('', ' # Read-only tools that need values the schema doesn\'t give. Fill in the TODOs and uncomment:');
100
334
  for (const s of needs.slice(0, 15))
101
335
  lines.push(` # - call: ${s.tool}`, ` # args: { ${s.missing.map((m) => `${m}: TODO`).join(', ')} }`);
336
+ if (needs.length > 15)
337
+ lines.push(` # …and ${needs.length - 15} more: ${needs.slice(15).map((s) => s.tool).join(', ')}`);
102
338
  }
103
339
  return lines.join('\n') + '\n';
104
340
  }
@@ -55,3 +55,5 @@ export interface Repeated {
55
55
  export declare function breakdown(menu: Menu): Breakdown;
56
56
  /** The breakdown as report lines, or none for a menu too small to need one. */
57
57
  export declare function breakdownLines(b: Breakdown, tools: number): string[];
58
+ /** The breakdown for a PR comment: a fold, the biggest tools as a table, the waste as a list. */
59
+ export declare function breakdownMarkdown(b: Breakdown, tools: number): string[];
package/dist/breakdown.js CHANGED
@@ -145,32 +145,77 @@ function enumValues(schema) {
145
145
  return schema.items.enum;
146
146
  return [];
147
147
  }
148
- /** The breakdown as report lines, or none for a menu too small to need one. */
149
- export function breakdownLines(b, tools) {
150
- const n = (x) => `~${x.toLocaleString('en-US')}`;
151
- const repeated = b.repeated.map((r) => {
152
- const inside = r.within > 1 ? `${r.tools === 1 ? '' : ', '}×${r.within} inside ${r.withinTool}${r.saving > 0 ? `: a $defs entry there could save ${n(r.saving)}` : ''}` : '';
153
- if (r.tools === 1)
154
- return ` repeated: one ${n(r.tokens)}-token block ×${r.count} in ${r.withinTool} (${r.where.map((w) => w.slice(r.withinTool.length + 1)).join(', ')}${r.count > r.where.length ? ', …' : ''})${r.saving > 0 ? `: a $defs entry could save ${n(r.saving)}` : ''}`;
155
- return ` repeated: ${r.param} (${n(r.tokens)}) in ${r.tools} tools, ${n(r.total)} in all${inside}`;
156
- });
157
- const pct = (x) => `${Math.round(x * 100)}%`;
148
+ const tok = (x) => `~${x.toLocaleString('en-US')}`;
149
+ const pct = (x) => `${Math.round(x * 100)}%`;
150
+ const list = (names, total) => `${names.join(', ')}${total > names.length ? ', …' : ''}`;
151
+ /** A tool's schema can't refer to another tool's: said once, after the repeated blocks that span tools. */
152
+ const ACROSS_TOOLS = "A tool's schema can't $ref another tool's, so a block shared across tools is paid once per tool: only a smaller block saves tokens there.";
153
+ function items(b, tools) {
158
154
  const u = b.unusedDefs;
159
155
  const unused = u.tokens
160
- ? [` unused $defs: ${n(u.tokens)} tokens${b.total ? ` (${pct(u.tokens / b.total)} of the menu)` : ''} in ${u.tools} tool${u.tools === 1 ? '' : 's'} (${u.examples.join(', ')}${u.tools > u.examples.length ? ', …' : ''}): definitions nothing in the tool refers to`]
156
+ ? [{
157
+ kind: 'unused',
158
+ text: `unused $defs: ${tok(u.tokens)} tokens${b.total ? ` (${pct(u.tokens / b.total)} of the menu)` : ''} in ${u.tools} tool${u.tools === 1 ? '' : 's'} (${list(u.examples, u.tools)})`,
159
+ why: 'Definitions nothing in their tool refers to: sent with every conversation, read by no one.',
160
+ fix: "Remove the unreferenced $defs entries from each tool's inputSchema.",
161
+ }]
161
162
  : [];
163
+ // Two different blocks under the same name ("form") are told apart by where the first one is.
164
+ const label = (r) => (b.repeated.filter((x) => x.tools > 1 && x.param === r.param).length > 1 && r.where[0] ? `${r.param} at ${r.where[0]}` : r.param);
165
+ const repeated = b.repeated.map((r) => {
166
+ if (r.tools === 1) {
167
+ const places = list(r.where.map((w) => w.slice(r.withinTool.length + 1)), r.count);
168
+ return { kind: 'repeated', text: `repeated: one ${tok(r.tokens)}-token block ×${r.count} in ${r.withinTool} (${places})${r.saving > 0 ? `: a $defs entry could save ${tok(r.saving)}` : ''}`, ...(r.saving > 0 ? { fix: `Move the block into ${r.withinTool}'s $defs once and $ref it.` } : {}) };
169
+ }
170
+ const inside = r.within > 1 ? `, ×${r.within} inside ${r.withinTool}${r.saving > 0 ? `: a $defs entry there could save ${tok(r.saving)}` : ''}` : '';
171
+ return { kind: 'repeated', text: `repeated: ${label(r)} (${tok(r.tokens)} tokens) in ${r.tools} tools, ${tok(r.total)} in all${inside}` };
172
+ });
162
173
  // A small menu gets no breakdown, but waste inside one tool is worth a line anyway.
163
174
  if (tools < 5) {
164
175
  const within = [...unused, ...repeated.filter((_, i) => b.repeated[i].within > 1)];
165
- return within.length ? ['Where the tokens go (estimate):', ...within] : [];
176
+ return within.length ? { title: 'Where the tokens go (estimate):', items: within } : undefined;
166
177
  }
167
178
  const topShare = b.top.reduce((s, t) => s + t.share, 0);
168
- const lines = [`Where the tokens go (estimate): the top ${b.top.length} tools are ${pct(topShare)} of the menu`];
169
- for (const t of b.top)
170
- lines.push(` ${pct(t.share).padStart(4)} ${t.name} ${n(t.tokens)} (description ${n(t.description)}, schema ${n(t.schema)})`);
171
- lines.push(...unused);
172
- for (const e of b.enums)
173
- lines.push(` enum: ${e.tool}.${e.param} has ${e.values} values, ${n(e.tokens)} tokens`);
174
- lines.push(...repeated);
179
+ const width = Math.min(40, Math.max(...b.top.map((t) => t.name.length)));
180
+ const top = b.top.map((t) => ({ kind: 'top', text: `${pct(t.share).padStart(4)} ${t.name.padEnd(width)} ${tok(t.tokens).padStart(7)} tokens (description ${tok(t.description)}, schema ${tok(t.schema)})` }));
181
+ const enums = b.enums.map((e) => ({ kind: 'enum', text: `enum: ${e.tool}.${e.param} has ${e.values} values, ${tok(e.tokens)} tokens` }));
182
+ const note = b.repeated.some((r) => r.tools > 1) ? [{ kind: 'note', text: ACROSS_TOOLS }] : [];
183
+ return { title: `Where the tokens go (estimate): the top ${b.top.length} tools are ${pct(topShare)} of the menu`, items: [...top, ...unused, ...enums, ...repeated, ...note] };
184
+ }
185
+ /** The breakdown as report lines, or none for a menu too small to need one. */
186
+ export function breakdownLines(b, tools) {
187
+ const found = items(b, tools);
188
+ if (!found)
189
+ return [];
190
+ const lines = [found.title];
191
+ for (const item of found.items) {
192
+ lines.push(item.kind === 'note' ? ` (${item.text})` : ` ${item.text}`);
193
+ if (item.why)
194
+ lines.push(` ${item.why}`);
195
+ if (item.fix)
196
+ lines.push(` → Next: ${item.fix}`);
197
+ }
198
+ return lines;
199
+ }
200
+ /** The breakdown for a PR comment: a fold, the biggest tools as a table, the waste as a list. */
201
+ export function breakdownMarkdown(b, tools) {
202
+ const found = items(b, tools);
203
+ if (!found)
204
+ return [];
205
+ const cell = (t) => t.replace(/\|/g, '\\|');
206
+ const code = (t) => t.replace(/\$defs/g, '`$defs`');
207
+ const lines = ['', `<details><summary>${found.title}</summary>`, ''];
208
+ if (tools >= 5) {
209
+ lines.push('| Share | Tool | Tokens | Description | Schema |', '|---:|---|---:|---:|---:|');
210
+ for (const t of b.top)
211
+ lines.push(`| ${pct(t.share)} | \`${cell(t.name)}\` | ${tok(t.tokens)} | ${tok(t.description)} | ${tok(t.schema)} |`);
212
+ lines.push('');
213
+ }
214
+ for (const item of found.items.filter((i) => i.kind !== 'top' && i.kind !== 'note')) {
215
+ lines.push(`- ${code(item.text)}${item.why ? `. ${code(item.why)}` : ''}${item.fix ? `<br>**→ Next:** ${code(item.fix)}` : ''}`);
216
+ }
217
+ for (const item of found.items.filter((i) => i.kind === 'note'))
218
+ lines.push('', `_${code(item.text)}_`);
219
+ lines.push('', '</details>');
175
220
  return lines;
176
221
  }