squally-mcp 0.1.3 → 0.2.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 +84 -10
- package/dist/api.js +17 -2
- package/dist/instructions.js +18 -7
- package/dist/openapi/v1.json +979 -273
- package/dist/openapi.d.ts +14 -8
- package/dist/openapi.js +22 -9
- package/dist/result.d.ts +12 -0
- package/dist/result.js +26 -0
- package/dist/tools.d.ts +6 -3
- package/dist/tools.js +21 -15
- package/dist/validate.js +6 -0
- package/package.json +1 -1
package/dist/openapi.d.ts
CHANGED
|
@@ -32,28 +32,34 @@ export declare function parseDocument(text: string): OpenApiDocument;
|
|
|
32
32
|
export declare function loadDocument(): OpenApiDocument;
|
|
33
33
|
export declare function operationFor(operationId: string): OpenApiOperation;
|
|
34
34
|
/**
|
|
35
|
-
* Parameters of
|
|
35
|
+
* Parameters of an operation that its tool does NOT offer - a deliberate
|
|
36
36
|
* deviation from the OpenAPI document, like PARAMETER_DESCRIPTIONS above.
|
|
37
37
|
*
|
|
38
38
|
* QUIETER TOOLS (25.09., 0.1.3). Every property of an inputSchema sits in the
|
|
39
39
|
* model's context on every turn, and a parameter on offer is a parameter the
|
|
40
|
-
* model spends a decision on. These
|
|
40
|
+
* model spends a decision on. These answer no question an agent asks:
|
|
41
41
|
*
|
|
42
42
|
* perPage the page size is FIXED at the API's default, 10 rows, for
|
|
43
|
-
* squally-find-run
|
|
44
|
-
*
|
|
45
|
-
* `cursor` (runs) and `page` (flaky tests, errors) are kept.
|
|
43
|
+
* squally-find-run and squally-list-errors. "More" stays one
|
|
44
|
+
* call away: `cursor` (runs) and `page` (errors) are kept.
|
|
46
45
|
* direction paging back towards newer runs is a person's gesture; an agent
|
|
47
46
|
* that wants the newest runs calls again without a cursor.
|
|
48
47
|
*
|
|
48
|
+
* PER OPERATION SINCE 0.2.0, where it was one set for every tool: listTests
|
|
49
|
+
* KEEPS perPage (1-100, default 50) - asked for by name in the 0.2.0 brief,
|
|
50
|
+
* and the one list whose rows an agent may want many of at once, to rank the
|
|
51
|
+
* whole suite in one answer rather than ten rows at a time.
|
|
52
|
+
*
|
|
49
53
|
* Left out of the input schema AND the validator (src/validate.ts), so an
|
|
50
54
|
* agent that sends one is told it made the argument up, and none is ever
|
|
51
|
-
* forwarded. test/drift.test.js checks that
|
|
55
|
+
* forwarded. test/drift.test.js checks that each is still optional upstream
|
|
52
56
|
* and that the default page size is still 10 - the moment either stops being
|
|
53
57
|
* true, this deviation stops being harmless.
|
|
54
58
|
*/
|
|
55
|
-
export declare const OMITTED_PARAMETERS: ReadonlySet<string
|
|
56
|
-
/** The parameters
|
|
59
|
+
export declare const OMITTED_PARAMETERS: ReadonlyMap<string, ReadonlySet<string>>;
|
|
60
|
+
/** The parameters `operation`'s tool leaves out - empty for most. */
|
|
61
|
+
export declare function omittedParameters(operation: OpenApiOperation): ReadonlySet<string>;
|
|
62
|
+
/** The parameters a tool offers: the operation's, minus its OMITTED_PARAMETERS. */
|
|
57
63
|
export declare function toolParameters(operation: OpenApiOperation): OpenApiParameter[];
|
|
58
64
|
/**
|
|
59
65
|
* The operation's parameters as one JSON Schema object.
|
package/dist/openapi.js
CHANGED
|
@@ -112,30 +112,43 @@ const PARAMETER_DESCRIPTIONS = {
|
|
|
112
112
|
"Without a cursor the newest runs come first.",
|
|
113
113
|
};
|
|
114
114
|
/**
|
|
115
|
-
* Parameters of
|
|
115
|
+
* Parameters of an operation that its tool does NOT offer - a deliberate
|
|
116
116
|
* deviation from the OpenAPI document, like PARAMETER_DESCRIPTIONS above.
|
|
117
117
|
*
|
|
118
118
|
* QUIETER TOOLS (25.09., 0.1.3). Every property of an inputSchema sits in the
|
|
119
119
|
* model's context on every turn, and a parameter on offer is a parameter the
|
|
120
|
-
* model spends a decision on. These
|
|
120
|
+
* model spends a decision on. These answer no question an agent asks:
|
|
121
121
|
*
|
|
122
122
|
* perPage the page size is FIXED at the API's default, 10 rows, for
|
|
123
|
-
* squally-find-run
|
|
124
|
-
*
|
|
125
|
-
* `cursor` (runs) and `page` (flaky tests, errors) are kept.
|
|
123
|
+
* squally-find-run and squally-list-errors. "More" stays one
|
|
124
|
+
* call away: `cursor` (runs) and `page` (errors) are kept.
|
|
126
125
|
* direction paging back towards newer runs is a person's gesture; an agent
|
|
127
126
|
* that wants the newest runs calls again without a cursor.
|
|
128
127
|
*
|
|
128
|
+
* PER OPERATION SINCE 0.2.0, where it was one set for every tool: listTests
|
|
129
|
+
* KEEPS perPage (1-100, default 50) - asked for by name in the 0.2.0 brief,
|
|
130
|
+
* and the one list whose rows an agent may want many of at once, to rank the
|
|
131
|
+
* whole suite in one answer rather than ten rows at a time.
|
|
132
|
+
*
|
|
129
133
|
* Left out of the input schema AND the validator (src/validate.ts), so an
|
|
130
134
|
* agent that sends one is told it made the argument up, and none is ever
|
|
131
|
-
* forwarded. test/drift.test.js checks that
|
|
135
|
+
* forwarded. test/drift.test.js checks that each is still optional upstream
|
|
132
136
|
* and that the default page size is still 10 - the moment either stops being
|
|
133
137
|
* true, this deviation stops being harmless.
|
|
134
138
|
*/
|
|
135
|
-
export const OMITTED_PARAMETERS = new
|
|
136
|
-
|
|
139
|
+
export const OMITTED_PARAMETERS = new Map([
|
|
140
|
+
["listRuns", new Set(["perPage", "direction"])],
|
|
141
|
+
["listErrors", new Set(["perPage"])],
|
|
142
|
+
]);
|
|
143
|
+
const NOTHING_OMITTED = new Set();
|
|
144
|
+
/** The parameters `operation`'s tool leaves out - empty for most. */
|
|
145
|
+
export function omittedParameters(operation) {
|
|
146
|
+
return OMITTED_PARAMETERS.get(operation.operationId) ?? NOTHING_OMITTED;
|
|
147
|
+
}
|
|
148
|
+
/** The parameters a tool offers: the operation's, minus its OMITTED_PARAMETERS. */
|
|
137
149
|
export function toolParameters(operation) {
|
|
138
|
-
|
|
150
|
+
const omitted = omittedParameters(operation);
|
|
151
|
+
return operation.parameters.filter((parameter) => !omitted.has(parameter.name));
|
|
139
152
|
}
|
|
140
153
|
/**
|
|
141
154
|
* The operation's parameters as one JSON Schema object.
|
package/dist/result.d.ts
CHANGED
|
@@ -13,6 +13,18 @@ export declare const RATE_LIMITED_TEXT = "Rate limited - wait 60 seconds, then r
|
|
|
13
13
|
*/
|
|
14
14
|
export declare function expiryLine(isoDate: string): string;
|
|
15
15
|
export declare function successResult(data: unknown, keyExpiresAt: string | null): CallToolResult;
|
|
16
|
+
/**
|
|
17
|
+
* The files an ambiguous_test answer names, as the filePath values to retry
|
|
18
|
+
* with - or null when the sentence does not have the expected shape.
|
|
19
|
+
*
|
|
20
|
+
* WHY PARSE A SENTENCE the document says "may be reworded": the files exist
|
|
21
|
+
* nowhere else in the answer, and the sentence names them in HTTP terms
|
|
22
|
+
* ("Pass ?filePath= with one of: tests/a.spec.ts, (no file).") - where
|
|
23
|
+
* "(no file)" is a placeholder the model must NOT copy: the argument for a
|
|
24
|
+
* test with no file is the empty string. A reworded sentence only costs this
|
|
25
|
+
* extra line; the sentence itself is always shown verbatim above it.
|
|
26
|
+
*/
|
|
27
|
+
export declare function ambiguousFilePaths(message: string): string[] | null;
|
|
16
28
|
export declare function failureResult(failure: ApiFailure, errorCodes: Map<string, ErrorCode>): CallToolResult;
|
|
17
29
|
/**
|
|
18
30
|
* WITH THE CAUSES: "fetch failed" alone names no reason; error.cause says
|
package/dist/result.js
CHANGED
|
@@ -30,6 +30,27 @@ export function successResult(data, keyExpiresAt) {
|
|
|
30
30
|
structuredContent: data,
|
|
31
31
|
};
|
|
32
32
|
}
|
|
33
|
+
/**
|
|
34
|
+
* The files an ambiguous_test answer names, as the filePath values to retry
|
|
35
|
+
* with - or null when the sentence does not have the expected shape.
|
|
36
|
+
*
|
|
37
|
+
* WHY PARSE A SENTENCE the document says "may be reworded": the files exist
|
|
38
|
+
* nowhere else in the answer, and the sentence names them in HTTP terms
|
|
39
|
+
* ("Pass ?filePath= with one of: tests/a.spec.ts, (no file).") - where
|
|
40
|
+
* "(no file)" is a placeholder the model must NOT copy: the argument for a
|
|
41
|
+
* test with no file is the empty string. A reworded sentence only costs this
|
|
42
|
+
* extra line; the sentence itself is always shown verbatim above it.
|
|
43
|
+
*/
|
|
44
|
+
export function ambiguousFilePaths(message) {
|
|
45
|
+
const listed = /one of: (.+)\.$/.exec(message.trim())?.[1];
|
|
46
|
+
if (!listed)
|
|
47
|
+
return null;
|
|
48
|
+
return listed.split(", ").map((file) => (file === "(no file)" ? "" : file));
|
|
49
|
+
}
|
|
50
|
+
function filePathLine(paths) {
|
|
51
|
+
const quoted = paths.map((path) => path === "" ? `"" (the test with no file)` : JSON.stringify(path));
|
|
52
|
+
return `Retry with filePath set to exactly one of: ${quoted.join(", ")}`;
|
|
53
|
+
}
|
|
33
54
|
export function failureResult(failure, errorCodes) {
|
|
34
55
|
if (failure.status === 429) {
|
|
35
56
|
return { content: [text(RATE_LIMITED_TEXT)], isError: true };
|
|
@@ -39,6 +60,11 @@ export function failureResult(failure, errorCodes) {
|
|
|
39
60
|
lines.push(failure.message ?? `The Squally API answered HTTP ${failure.status}.`);
|
|
40
61
|
if (failure.code)
|
|
41
62
|
lines.push(`Error code: ${failure.code}`);
|
|
63
|
+
if (failure.code === "ambiguous_test" && failure.message) {
|
|
64
|
+
const paths = ambiguousFilePaths(failure.message);
|
|
65
|
+
if (paths && paths.length > 0)
|
|
66
|
+
lines.push(filePathLine(paths));
|
|
67
|
+
}
|
|
42
68
|
if (known) {
|
|
43
69
|
lines.push(`What to do: ${known.action}`);
|
|
44
70
|
}
|
package/dist/tools.d.ts
CHANGED
|
@@ -18,9 +18,12 @@ export type ToolDefinition = {
|
|
|
18
18
|
*/
|
|
19
19
|
answers: string;
|
|
20
20
|
/**
|
|
21
|
-
* FOR PEOPLE: "expensive"
|
|
22
|
-
* is "cheap".
|
|
23
|
-
*
|
|
21
|
+
* FOR PEOPLE: "expensive" was the one engine pass (§4.2.2), everything else
|
|
22
|
+
* is "cheap". Since 0.2.0 no tool is expensive - the engine is gone, and the
|
|
23
|
+
* tests list is paged in the database. The value stays in the type for the
|
|
24
|
+
* consumers of `squally-mcp/tools` (the docs), which render both. The model
|
|
25
|
+
* learns the cost from `description` and the server instructions, not from
|
|
26
|
+
* this.
|
|
24
27
|
*/
|
|
25
28
|
cost: "cheap" | "expensive";
|
|
26
29
|
};
|
package/dist/tools.js
CHANGED
|
@@ -49,24 +49,30 @@ export const TOOLS = [
|
|
|
49
49
|
cost: "cheap",
|
|
50
50
|
},
|
|
51
51
|
{
|
|
52
|
-
name: "squally-get-test-
|
|
53
|
-
title: "Get
|
|
54
|
-
operationId: "
|
|
55
|
-
description: "
|
|
56
|
-
"
|
|
57
|
-
"
|
|
58
|
-
|
|
52
|
+
name: "squally-get-test-metrics",
|
|
53
|
+
title: "Get one test's metrics",
|
|
54
|
+
operationId: "getTestMetrics",
|
|
55
|
+
description: "One test's numbers over a period: runs, stability (runs that passed on the first try " +
|
|
56
|
+
"/ runs), flakyRate (runs that passed only after a retry / runs), failureRate (failed " +
|
|
57
|
+
"runs / runs), time lost to retries and failures, its last 20 runs and the branches it " +
|
|
58
|
+
"ran on. Counts completed CI runs of the period, without runs where most of the suite " +
|
|
59
|
+
"failed at once; local runs never count. There is no verdict - the tool returns the " +
|
|
60
|
+
"numbers and you judge them. runs = 0 with null rates is a valid answer: no completed " +
|
|
61
|
+
"CI run of this test in the period. Cheap; for one test use this, not squally-list-tests.",
|
|
62
|
+
answers: "One test's stability, flaky rate and failure rate over a period.",
|
|
59
63
|
cost: "cheap",
|
|
60
64
|
},
|
|
61
65
|
{
|
|
62
|
-
name: "squally-list-
|
|
63
|
-
title: "List
|
|
64
|
-
operationId: "
|
|
65
|
-
description: "
|
|
66
|
-
"
|
|
67
|
-
"
|
|
68
|
-
|
|
69
|
-
|
|
66
|
+
name: "squally-list-tests",
|
|
67
|
+
title: "List tests",
|
|
68
|
+
operationId: "listTests",
|
|
69
|
+
description: "Every test with a completed CI run in the period, with the same numbers per test as " +
|
|
70
|
+
"squally-get-test-metrics - runs, stability, flakyRate, failureRate, time lost - ranked " +
|
|
71
|
+
"worst first by the chosen sort (default: lowest stability). There is no verdict and no " +
|
|
72
|
+
"status - the tool labels no test; you judge the numbers. Moderate - two queries over " +
|
|
73
|
+
"the period, paged; for a single test use squally-get-test-metrics.",
|
|
74
|
+
answers: "Every test with a CI run in the period, ranked by stability, flaky rate or failures.",
|
|
75
|
+
cost: "cheap",
|
|
70
76
|
},
|
|
71
77
|
{
|
|
72
78
|
name: "squally-list-errors",
|
package/dist/validate.js
CHANGED
|
@@ -41,8 +41,14 @@ function integerSchema(schema) {
|
|
|
41
41
|
}
|
|
42
42
|
let out = z.number().int();
|
|
43
43
|
const minimum = schema["minimum"];
|
|
44
|
+
const maximum = schema["maximum"];
|
|
44
45
|
if (typeof minimum === "number")
|
|
45
46
|
out = out.min(minimum);
|
|
47
|
+
// Read since 0.2.0: squally-list-tests' perPage is the first parameter with
|
|
48
|
+
// an upper bound (1-100). Unread, perPage=500 would pass here and come back
|
|
49
|
+
// from the API as a 400 about a value the model never saw refused.
|
|
50
|
+
if (typeof maximum === "number")
|
|
51
|
+
out = out.max(maximum);
|
|
46
52
|
return out;
|
|
47
53
|
}
|
|
48
54
|
function forParameter(schema) {
|