squally-mcp 0.4.0 → 0.5.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  # squally-mcp
2
2
 
3
3
  A local [MCP](https://modelcontextprotocol.io) server that lets a coding agent
4
- read your [Squally](https://app.squally.dev) data: which CI runs happened, how
4
+ read your [Squally](https://app.squally.dev) data: which runs happened, how
5
5
  stable each test is, and why a particular test failed.
6
6
 
7
7
  It runs on your machine over stdio and talks to Squally's read API over HTTPS.
@@ -138,7 +138,7 @@ squally-mcp trusts your operating system's certificate store, like your browser
138
138
  | Tool | What it answers | Cost |
139
139
  |---|---|---|
140
140
  | `squally-list-projects` | Which projects exist. **Start here** — every other tool needs a `projectId` from it. | cheap |
141
- | `squally-find-run` | Which runs happened — latest, or by branch, commit SHA or status. Counters only. | cheap |
141
+ | `squally-find-run` | Which runs happened — latest, or by branch, commit SHA, status or source. Counters only. | cheap |
142
142
  | `squally-get-run` | One run with its per-test rows, across all shards. Which test is red. | cheap |
143
143
  | `squally-debug-failure` | Every attempt of one test in one run: error, stack, Copy-for-AI prompt. | cheap |
144
144
  | `squally-get-test-metrics` | One test's stability, flaky rate and failure rate over a period. | cheap — one test |
@@ -148,12 +148,26 @@ squally-mcp trusts your operating system's certificate store, like your browser
148
148
  For a single test use `squally-get-test-metrics`, not `squally-list-tests` —
149
149
  the tool descriptions say so, and the server repeats it in its instructions.
150
150
 
151
+ ### Runs
152
+
153
+ `squally-find-run` lists every run, CI and local alike; `source` (`all` by
154
+ default, `ci` or `local`) narrows it, and each run says whether it was
155
+ `local`. A run's `status` is the dashboard's word: `passed`, `failed`,
156
+ `cancelled`, `incomplete` (a shard timed out, was stopped by the monthly
157
+ result limit or never reported) or `running` - and `?status=` filters by
158
+ any of them. A cancelled run is `cancelled`; `cancellation` says how, when
159
+ and by whom. A sharded run is one row, its counters over all its shards with
160
+ every test once, and the tests a cancel cut off count nowhere.
161
+
151
162
  ### What the numbers mean
152
163
 
153
- The two test tools count **CI runs whose shards all finished** in the period
154
- (7, 14, 30 or 90 days; 30 by default), on every branch unless you name one. A
155
- sharded run counts once, placed in the period by its first shard's start; a
156
- run that was a mass failure as a whole is left out. Local runs count only
164
+ The two test tools count **finished CI runs** in the period (7, 14, 30 or 90
165
+ days; 30 by default), on every branch unless you name one. A run finishes when
166
+ all its shards have - or, once the run timeout has passed, with the results its
167
+ shards reported, like a cancelled run; a shard stopped by the monthly result
168
+ limit counts like one that timed out. A sharded run counts once, placed in the period
169
+ by its first shard's start; a run that was a mass failure as a whole is left
170
+ out. Local runs count only
157
171
  when you ask for them: `source` is `ci` (the default), `local` or `all`, and
158
172
  the response's `population` names which runs it counted. Per test:
159
173
 
@@ -24,18 +24,34 @@
24
24
  // THE SOURCE SINCE 0.4.0 (API 1.0.0-beta.8): CI runs by default; local runs
25
25
  // count only when the agent asks for them - they were never counted before.
26
26
  //
27
+ // THE RUN TIMEOUT (API 1.0.0-beta.10, since 0.5.0): a run whose shard died or
28
+ // never started counts once the run timeout has passed, with the shards that
29
+ // finished - "whose shards all finished" stopped being the whole rule.
30
+ //
31
+ // THE MONTHLY RESULT LIMIT (API 1.0.0-beta.11, since 0.5.0): a shard the limit
32
+ // stopped is treated like a timed-out one, so the sentence names it - and says
33
+ // "the results its shards reported", since such a shard did not finish.
34
+ //
35
+ // ONE RUN STATUS SINCE 0.5.0 (API 1.0.0-beta.14): a run's status is the
36
+ // dashboard's own word - passed, failed, cancelled, incomplete or running -
37
+ // and the `cancelled` boolean is gone (`cancellation` says how and when). Said
38
+ // here because a model that knew the old shape looks for a flag that no longer
39
+ // exists, or reads "cancelled" as an unknown value.
40
+ //
27
41
  // Exported as `squally-mcp/instructions` (package.json), so it stays a plain
28
42
  // constant - test/exports.test.js imports it through the package name.
29
43
  export const INSTRUCTIONS = [
30
44
  "Start with squally-list-projects; every other tool needs a projectId from it.",
31
45
  "For one test, use squally-get-test-metrics, not squally-list-tests.",
32
- "Test metrics count the CI runs of the period whose shards all finished - a sharded",
33
- "run counts once - without runs that were a mass failure as a whole; pass source=local",
34
- "or source=all to count local runs or both, and a run still in progress counts once",
35
- "all its shards have finished.",
46
+ "Test metrics count the finished CI runs of the period - a sharded run counts once -",
47
+ "without runs that were a mass failure as a whole; pass source=local or source=all",
48
+ "to count local runs or both. A run still in progress counts once all its shards have",
49
+ "finished, or once the run timeout has passed, with the results its shards reported -",
50
+ "also when a shard was stopped by the monthly result limit.",
36
51
  "stability = runs that passed on the",
37
52
  "first try / runs; flakyRate = runs that passed only after a retry / runs;",
38
53
  "failureRate = failed runs / runs. There is no verdict: the tools return numbers,",
39
54
  "and you judge them. If a test name is ambiguous, repeat with filePath from the",
40
- "error. Errors carry a code and an action; follow the action.",
55
+ "error. A run's status is passed, failed, cancelled, incomplete or running.",
56
+ "Errors carry a code and an action; follow the action.",
41
57
  ].join(" ");
@@ -3,7 +3,7 @@
3
3
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
4
4
  "info": {
5
5
  "title": "Squally Read API",
6
- "version": "1.0.0-beta.9",
6
+ "version": "1.0.0-beta.14",
7
7
  "description": "Read access to a Squally organization's test results, for scripts, CI jobs and AI agents.\n\n**Authentication.** Every request carries an organization read key as `Authorization: Bearer sqly_ro_…`. A read key is organization-wide (every project), created by an organization admin in Organization › Read keys, and expires after 30, 60, 90, 180 days as chosen at creation. There is no renewal: create a new key and revoke the old one. Project ingest keys (`sqly_…`) are refused with `wrong_key_type`.\n\n**Expiry warning.** From 7 days before a key expires, every authenticated response carries `Squally-Key-Expires-At` with the expiry instant (ISO-8601).\n\n**Rate limit.** Currently 60 requests per 60 seconds per key, counted per `Authorization` header - a read key has its own budget, shared with nothing else. Over the limit the edge answers 429 without a JSON body.\n\n**Retries.** 429: wait 60 seconds, then retry. The edge counts requests per key in 60-second windows and sends no Retry-After header. 5xx: retry with exponential backoff, starting at 1 second and capped at 30 seconds. 400, 401, 403, 404: never retry - the same request gets the same answer.\n\n**Plans.** The read API is part of the Standard and Pro plans. A key of an organization on Free is answered 403 `tier_too_low`; keys are not revoked on a downgrade and work again after an upgrade.\n\n**Errors.** Every error is `{\"error\": \"<sentence>\", \"code\": \"<slug>\"}`. The sentence may be reworded; the slug may not. An id that does not exist and an id that belongs to another organization get the same 404, byte for byte.\n\n**Test names in paths.** Test names are Playwright title paths and often contain `/`: URL-encode them, including `/` as `%2F`.\n\n**Sharded runs** are returned as one logical run: /runs lists one row per logical run, and the run routes answer for all shards whichever shard's id you pass.\n\n**Stability.** v1, beta. The API may change until the beta ends; every change is listed in the changelog (docs/openapi/CHANGELOG.md)."
8
8
  },
9
9
  "servers": [
@@ -337,7 +337,7 @@
337
337
  "get": {
338
338
  "operationId": "listRuns",
339
339
  "summary": "List runs",
340
- "description": "Runs in a period, newest first - one row per logical run (a sharded CI run is one row). Filter by branch, commit SHA prefix or outcome; page with the cursors. Cheap to moderate: one bounded scan.",
340
+ "description": "Runs in a period, newest first - one row per logical run (a sharded CI run is one row), placed in the period and ordered by the start of its first shard (since 1.0.0-beta.13). CI and local runs both, unless source narrows it. Filter by branch, commit SHA prefix, status or source; page with the cursors. Cheap to moderate: bounded by the period's runs.",
341
341
  "tags": [
342
342
  "Runs"
343
343
  ],
@@ -392,15 +392,33 @@
392
392
  "name": "status",
393
393
  "in": "query",
394
394
  "required": false,
395
- "description": "Only runs with this outcome. A cancelled run matches neither value - only the unfiltered list has it.",
395
+ "description": "Only runs with this status - the status field's values. A cancelled run matches cancelled only (since 1.0.0-beta.14; passed and failed were the only values before it, and a cancelled run matched neither).",
396
396
  "schema": {
397
397
  "type": "string",
398
398
  "enum": [
399
399
  "passed",
400
- "failed"
400
+ "failed",
401
+ "cancelled",
402
+ "incomplete",
403
+ "running"
401
404
  ]
402
405
  }
403
406
  },
407
+ {
408
+ "name": "source",
409
+ "in": "query",
410
+ "required": false,
411
+ "description": "Which runs are listed, by where they ran: all - every run (the default); ci - runs a shard reported a CI provider for; local - runs no shard did (each run's local field). Since 1.0.0-beta.14.",
412
+ "schema": {
413
+ "type": "string",
414
+ "enum": [
415
+ "ci",
416
+ "local",
417
+ "all"
418
+ ],
419
+ "default": "all"
420
+ }
421
+ },
404
422
  {
405
423
  "name": "perPage",
406
424
  "in": "query",
@@ -474,8 +492,8 @@
474
492
  "testedRevision": null,
475
493
  "pullRequestNumber": null,
476
494
  "status": "passed",
477
- "cancelled": false,
478
495
  "cancellation": null,
496
+ "local": false,
479
497
  "startedAt": "2026-09-24T07:31:12.000Z",
480
498
  "finishedAt": "2026-09-24T07:39:47.000Z",
481
499
  "durationMs": 515000,
@@ -499,8 +517,8 @@
499
517
  "testedRevision": "c4f7a1e9b3d5c8e2f0a6b4d9e1c7f3a5b8d2e0f6",
500
518
  "pullRequestNumber": 318,
501
519
  "status": "failed",
502
- "cancelled": false,
503
520
  "cancellation": null,
521
+ "local": false,
504
522
  "startedAt": "2026-09-23T16:05:40.000Z",
505
523
  "finishedAt": "2026-09-23T16:12:02.000Z",
506
524
  "durationMs": 382000,
@@ -520,13 +538,13 @@
520
538
  "commitSha": "5f1d9b3e7a2c6e0f8b4d2a9c7e1f5b3d8a6c0e4f",
521
539
  "testedRevision": null,
522
540
  "pullRequestNumber": 318,
523
- "status": "failed",
524
- "cancelled": true,
541
+ "status": "cancelled",
525
542
  "cancellation": {
526
543
  "source": "reporter",
527
544
  "at": "2026-09-23T15:58:31.000Z",
528
545
  "byUserId": null
529
546
  },
547
+ "local": false,
530
548
  "startedAt": "2026-09-23T15:55:02.000Z",
531
549
  "finishedAt": "2026-09-23T15:58:31.000Z",
532
550
  "durationMs": 209000,
@@ -831,8 +849,8 @@
831
849
  "pullRequestTitle": null,
832
850
  "ciProvider": "github-actions",
833
851
  "status": "passed",
834
- "cancelled": false,
835
852
  "cancellation": null,
853
+ "local": false,
836
854
  "startedAt": "2026-09-24T07:31:12.000Z",
837
855
  "finishedAt": "2026-09-24T07:39:47.000Z",
838
856
  "durationMs": 515000,
@@ -4589,19 +4607,15 @@
4589
4607
  ]
4590
4608
  },
4591
4609
  "status": {
4592
- "anyOf": [
4593
- {
4594
- "type": "string"
4595
- },
4596
- {
4597
- "type": "null"
4598
- }
4610
+ "type": "string",
4611
+ "enum": [
4612
+ "passed",
4613
+ "failed",
4614
+ "cancelled",
4615
+ "incomplete",
4616
+ "running"
4599
4617
  ],
4600
- "description": "passed | failed | running | incomplete - for a sharded run, the whole group's. Never \"cancelled\": a cancelled run keeps the outcome of what it reported, and says so in cancelled."
4601
- },
4602
- "cancelled": {
4603
- "type": "boolean",
4604
- "description": "True when the run was cancelled - for a sharded run, when any shard recorded a cancel. A cancelled run keeps its status (the outcome of what it reported before the stop) and never matches ?status=passed or ?status=failed."
4618
+ "description": "How the run ended, the dashboard's own word: cancelled - the run was cancelled (for a sharded run, any shard recorded a cancel; cancellation says how and when); incomplete - a shard timed out, was stopped by the monthly result limit or never reported; running - a shard is still running; failed - every shard finished and a test failed; passed - every shard finished and none failed. In that order: the first that applies. Since 1.0.0-beta.14 - before it, a cancelled run reported the outcome beneath the cancel and a cancelled boolean."
4605
4619
  },
4606
4620
  "cancellation": {
4607
4621
  "anyOf": [
@@ -4646,7 +4660,11 @@
4646
4660
  "type": "null"
4647
4661
  }
4648
4662
  ],
4649
- "description": "How and when the run was cancelled; null when it was not."
4663
+ "description": "How and when the run was cancelled; null when it was not - set exactly when status is cancelled."
4664
+ },
4665
+ "local": {
4666
+ "type": "boolean",
4667
+ "description": "No shard of the run reported a CI provider: a local run (since 1.0.0-beta.14). GET /runs lists both kinds unless source says otherwise."
4650
4668
  },
4651
4669
  "startedAt": {
4652
4670
  "type": "string",
@@ -4678,7 +4696,8 @@
4678
4696
  "type": "object",
4679
4697
  "properties": {
4680
4698
  "total": {
4681
- "type": "integer"
4699
+ "type": "integer",
4700
+ "description": "Tests in the run, every test once however many shards reported it - its final attempt across all of them decides (highest retry, then the lowest shard, then the first repetition). total = passed + failed + skipped + flaky. Since 1.0.0-beta.12; until then each shard's count was summed, so a test reported from two shards counted twice. In a cancelled run the tests the cancel interrupted - reported as skipped - count nowhere, so skipped there counts no test (since 1.0.0-beta.13); the run's tests list still has them."
4682
4701
  },
4683
4702
  "passed": {
4684
4703
  "type": "integer"
@@ -4740,8 +4759,8 @@
4740
4759
  "testedRevision",
4741
4760
  "pullRequestNumber",
4742
4761
  "status",
4743
- "cancelled",
4744
4762
  "cancellation",
4763
+ "local",
4745
4764
  "startedAt",
4746
4765
  "finishedAt",
4747
4766
  "durationMs",
@@ -4897,11 +4916,14 @@
4897
4916
  },
4898
4917
  "status": {
4899
4918
  "type": "string",
4900
- "description": "passed | failed | running | incomplete - the whole group's. Never \"cancelled\": a cancelled run keeps the outcome of what it reported, and says so in cancelled."
4901
- },
4902
- "cancelled": {
4903
- "type": "boolean",
4904
- "description": "True when the run was cancelled - for a sharded run, when any shard recorded a cancel. A cancelled run keeps its status (the outcome of what it reported before the stop) and never matches ?status=passed or ?status=failed."
4919
+ "enum": [
4920
+ "passed",
4921
+ "failed",
4922
+ "cancelled",
4923
+ "incomplete",
4924
+ "running"
4925
+ ],
4926
+ "description": "How the run ended, the dashboard's own word: cancelled - the run was cancelled (for a sharded run, any shard recorded a cancel; cancellation says how and when); incomplete - a shard timed out, was stopped by the monthly result limit or never reported; running - a shard is still running; failed - every shard finished and a test failed; passed - every shard finished and none failed. In that order: the first that applies. Since 1.0.0-beta.14 - before it, a cancelled run reported the outcome beneath the cancel and a cancelled boolean."
4905
4927
  },
4906
4928
  "cancellation": {
4907
4929
  "anyOf": [
@@ -4946,7 +4968,11 @@
4946
4968
  "type": "null"
4947
4969
  }
4948
4970
  ],
4949
- "description": "How and when the run was cancelled; null when it was not."
4971
+ "description": "How and when the run was cancelled; null when it was not - set exactly when status is cancelled."
4972
+ },
4973
+ "local": {
4974
+ "type": "boolean",
4975
+ "description": "No shard of the run reported a CI provider: a local run (since 1.0.0-beta.14). GET /runs lists both kinds unless source says otherwise."
4950
4976
  },
4951
4977
  "startedAt": {
4952
4978
  "type": "string",
@@ -5011,14 +5037,15 @@
5011
5037
  "type": "string"
5012
5038
  },
5013
5039
  "status": {
5014
- "anyOf": [
5015
- {
5016
- "type": "string"
5017
- },
5018
- {
5019
- "type": "null"
5020
- }
5021
- ]
5040
+ "type": "string",
5041
+ "enum": [
5042
+ "passed",
5043
+ "failed",
5044
+ "cancelled",
5045
+ "incomplete",
5046
+ "running"
5047
+ ],
5048
+ "description": "What this shard did, in the run status's words: cancelled when it recorded a cancel; else running or incomplete by its state; else failed when a test failed, passed otherwise. The shards panel's own rule (since 1.0.0-beta.14 - it was the shard's raw outcome, null until it finished)."
5022
5049
  }
5023
5050
  },
5024
5051
  "required": [
@@ -5053,8 +5080,8 @@
5053
5080
  "pullRequestTitle",
5054
5081
  "ciProvider",
5055
5082
  "status",
5056
- "cancelled",
5057
5083
  "cancellation",
5084
+ "local",
5058
5085
  "startedAt",
5059
5086
  "finishedAt",
5060
5087
  "durationMs",
@@ -5065,7 +5092,8 @@
5065
5092
  "type": "object",
5066
5093
  "properties": {
5067
5094
  "total": {
5068
- "type": "integer"
5095
+ "type": "integer",
5096
+ "description": "Tests in the run, every test once however many shards reported it - its final attempt across all of them decides (highest retry, then the lowest shard, then the first repetition). total = passed + failed + skipped + flaky. Since 1.0.0-beta.12; until then each shard's count was summed, so a test reported from two shards counted twice. In a cancelled run the tests the cancel interrupted - reported as skipped - count nowhere, so skipped there counts no test (since 1.0.0-beta.13); the run's tests list still has them."
5069
5097
  },
5070
5098
  "passed": {
5071
5099
  "type": "integer"
@@ -5111,7 +5139,8 @@
5111
5139
  "type": "string"
5112
5140
  },
5113
5141
  "attempts": {
5114
- "type": "integer"
5142
+ "type": "integer",
5143
+ "description": "Every attempt of the test in the run, across all its shards (since 1.0.0-beta.12; per shard before)."
5115
5144
  },
5116
5145
  "durationMs": {
5117
5146
  "anyOf": [
@@ -5202,7 +5231,8 @@
5202
5231
  {
5203
5232
  "type": "null"
5204
5233
  }
5205
- ]
5234
+ ],
5235
+ "description": "The shard the test's final attempt ran in; null for an unsharded run. One row per test since 1.0.0-beta.12 - a test reported from two shards was one row per shard before."
5206
5236
  }
5207
5237
  },
5208
5238
  "required": [
@@ -5472,7 +5502,8 @@
5472
5502
  {
5473
5503
  "type": "null"
5474
5504
  }
5475
- ]
5505
+ ],
5506
+ "description": "The shard the test's final attempt ran in; null for an unsharded run. One row per test since 1.0.0-beta.12 - a test reported from two shards was one row per shard before."
5476
5507
  }
5477
5508
  },
5478
5509
  "required": [
@@ -5552,7 +5583,7 @@
5552
5583
  "local_groups_finished_not_mass_failure",
5553
5584
  "all_groups_finished_not_mass_failure"
5554
5585
  ],
5555
- "description": "Which runs every number counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - without runs that were a mass failure as a whole (at least 20 tests, over 80% of them failed). Every branch unless the branch parameter names one. Runs that have not finished are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.8; before it, ci_groups_finished_not_mass_failure was the only value, and since 1.0.0-beta.6 - it was ci_completed_not_excluded, which counted every completed shard on its own)."
5586
+ "description": "Which runs every number counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - without runs that were a mass failure as a whole (at least 20 tests, over 80% of them failed). Every branch unless the branch parameter names one. A run finishes when all its shards have, or - once it is overdue by the project's run timeout, counted from its latest shard's start - when every shard that started has completed, timed out or been stopped by the monthly result limit; such a run counts like a cancelled one, with the results its shards reported (since 1.0.0-beta.10; the monthly result limit since 1.0.0-beta.11). Runs still running are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.8; before it, ci_groups_finished_not_mass_failure was the only value, and since 1.0.0-beta.6 - it was ci_completed_not_excluded, which counted every completed shard on its own)."
5556
5587
  },
5557
5588
  "days": {
5558
5589
  "type": "integer",
@@ -5857,7 +5888,7 @@
5857
5888
  "local_groups_finished_not_mass_failure",
5858
5889
  "all_groups_finished_not_mass_failure"
5859
5890
  ],
5860
- "description": "Which runs every number counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - without runs that were a mass failure as a whole (at least 20 tests, over 80% of them failed). Every branch unless the branch parameter names one. Runs that have not finished are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.8; before it, ci_groups_finished_not_mass_failure was the only value, and since 1.0.0-beta.6 - it was ci_completed_not_excluded, which counted every completed shard on its own)."
5891
+ "description": "Which runs every number counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - without runs that were a mass failure as a whole (at least 20 tests, over 80% of them failed). Every branch unless the branch parameter names one. A run finishes when all its shards have, or - once it is overdue by the project's run timeout, counted from its latest shard's start - when every shard that started has completed, timed out or been stopped by the monthly result limit; such a run counts like a cancelled one, with the results its shards reported (since 1.0.0-beta.10; the monthly result limit since 1.0.0-beta.11). Runs still running are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.8; before it, ci_groups_finished_not_mass_failure was the only value, and since 1.0.0-beta.6 - it was ci_completed_not_excluded, which counted every completed shard on its own)."
5861
5892
  },
5862
5893
  "days": {
5863
5894
  "type": "integer",
@@ -6165,7 +6196,7 @@
6165
6196
  },
6166
6197
  "counted": {
6167
6198
  "type": "boolean",
6168
- "description": "Whether the run is in the metrics' population (see population on the metrics endpoints): a run of the source parameter's kind - CI by default - whose shards all finished, not a mass failure, and the test not just skipped by a cancellation (since 1.0.0-beta.6; the source since 1.0.0-beta.8)."
6199
+ "description": "Whether the run is in the metrics' population (see population on the metrics endpoints): a run of the source parameter's kind - CI by default - that finished (all its shards, or overdue with every shard that started completed, timed out or stopped by the monthly result limit - since 1.0.0-beta.10, the limit since 1.0.0-beta.11), not a mass failure, and the test not just skipped by a cancellation (since 1.0.0-beta.6; the source since 1.0.0-beta.8)."
6169
6200
  },
6170
6201
  "branch": {
6171
6202
  "anyOf": [
@@ -6285,7 +6316,7 @@
6285
6316
  "local_groups_finished",
6286
6317
  "all_groups_finished"
6287
6318
  ],
6288
- "description": "Which runs every error figure counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - runs that were a mass failure as a whole included (see massFailureRunCount). Runs that have not finished are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.9)."
6319
+ "description": "Which runs every error figure counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - runs that were a mass failure as a whole included (see massFailureRunCount). A run finishes when all its shards have, or - once it is overdue by the project's run timeout, counted from its latest shard's start - when every shard that started has completed, timed out or been stopped by the monthly result limit; such a run counts like a cancelled one, with the results its shards reported (since 1.0.0-beta.10; the monthly result limit since 1.0.0-beta.11). Runs still running are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.9)."
6289
6320
  },
6290
6321
  "window": {
6291
6322
  "type": "object",
@@ -6424,7 +6455,7 @@
6424
6455
  },
6425
6456
  "unfinishedRuns": {
6426
6457
  "type": "integer",
6427
- "description": "Runs of the source in the window that have not finished - a shard still running, timed out or never reported. In no figure (since 1.0.0-beta.9)."
6458
+ "description": "Runs of the source in the window that have not finished - a shard still running, or one timed out, stopped by the monthly result limit or never reported while the run is not yet overdue (an overdue one is finished and counted since 1.0.0-beta.10; a limit-stopped one since 1.0.0-beta.11). In no figure (since 1.0.0-beta.9)."
6428
6459
  }
6429
6460
  },
6430
6461
  "required": [
@@ -6462,7 +6493,7 @@
6462
6493
  "local_groups_finished",
6463
6494
  "all_groups_finished"
6464
6495
  ],
6465
- "description": "Which runs every error figure counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - runs that were a mass failure as a whole included (see massFailureRunCount). Runs that have not finished are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.9)."
6496
+ "description": "Which runs every error figure counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - runs that were a mass failure as a whole included (see massFailureRunCount). A run finishes when all its shards have, or - once it is overdue by the project's run timeout, counted from its latest shard's start - when every shard that started has completed, timed out or been stopped by the monthly result limit; such a run counts like a cancelled one, with the results its shards reported (since 1.0.0-beta.10; the monthly result limit since 1.0.0-beta.11). Runs still running are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.9)."
6466
6497
  },
6467
6498
  "window": {
6468
6499
  "type": "object",
@@ -6770,15 +6801,14 @@
6770
6801
  ]
6771
6802
  },
6772
6803
  "status": {
6773
- "anyOf": [
6774
- {
6775
- "type": "string"
6776
- },
6777
- {
6778
- "type": "null"
6779
- }
6804
+ "type": "string",
6805
+ "enum": [
6806
+ "passed",
6807
+ "failed",
6808
+ "cancelled",
6809
+ "incomplete"
6780
6810
  ],
6781
- "description": "The run's status over all its shards: passed or failed."
6811
+ "description": "The run's status over all its shards, as GET /runs reports it - a finished run, so never running: passed, failed, cancelled, or incomplete for a run finished by the run timeout - a shard timed out, was stopped by the monthly result limit or never reported (incomplete since 1.0.0-beta.10, the limit since 1.0.0-beta.11; cancelled since 1.0.0-beta.14 - before it, a cancelled run reported the outcome beneath the cancel)."
6782
6812
  },
6783
6813
  "startedAt": {
6784
6814
  "type": "string",
@@ -6843,11 +6873,11 @@
6843
6873
  },
6844
6874
  "runsInWindow": {
6845
6875
  "type": "integer",
6846
- "description": "Finished runs of the source in the window on branchScope (see the source parameter and testMetrics.population), each counted once however many shards it had, by the start of its first shard; mass-failure and cancelled runs included. The runs windowStability is counted over."
6876
+ "description": "Finished runs of the source in the window on branchScope (see the source parameter and testMetrics.population), each counted once however many shards it had, by the start of its first shard; mass-failure, cancelled and incomplete runs included (incomplete - finished by the run timeout - since 1.0.0-beta.10). The runs windowStability is counted over."
6847
6877
  },
6848
6878
  "unfinishedRuns": {
6849
6879
  "type": "integer",
6850
- "description": "Runs of the source in the window on branchScope that have not finished - a shard still running, timed out or never reported. In no other figure (since 1.0.0-beta.7; of the source since 1.0.0-beta.8)."
6880
+ "description": "Runs of the source in the window on branchScope that have not finished - a shard still running, or one timed out, stopped by the monthly result limit or never reported while the run is not yet overdue (an overdue one is finished and counted since 1.0.0-beta.10; a limit-stopped one since 1.0.0-beta.11). In no other figure (since 1.0.0-beta.7; of the source since 1.0.0-beta.8)."
6851
6881
  },
6852
6882
  "suiteSize": {
6853
6883
  "type": "integer",
@@ -6921,7 +6951,7 @@
6921
6951
  "local_groups_finished_not_mass_failure",
6922
6952
  "all_groups_finished_not_mass_failure"
6923
6953
  ],
6924
- "description": "Which runs every number counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - without runs that were a mass failure as a whole (at least 20 tests, over 80% of them failed). Every branch unless the branch parameter names one. Runs that have not finished are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.8; before it, ci_groups_finished_not_mass_failure was the only value, and since 1.0.0-beta.6 - it was ci_completed_not_excluded, which counted every completed shard on its own)."
6954
+ "description": "Which runs every number counts: runs whose shards all finished, each counted once however many shards it ran in, placed in the period by the start of their first shard - without runs that were a mass failure as a whole (at least 20 tests, over 80% of them failed). Every branch unless the branch parameter names one. A run finishes when all its shards have, or - once it is overdue by the project's run timeout, counted from its latest shard's start - when every shard that started has completed, timed out or been stopped by the monthly result limit; such a run counts like a cancelled one, with the results its shards reported (since 1.0.0-beta.10; the monthly result limit since 1.0.0-beta.11). Runs still running are not counted. The prefix names the source parameter: ci_ - CI runs (a shard reported a CI provider), the default; local_ - runs no shard reported a CI provider for; all_ - both (since 1.0.0-beta.8; before it, ci_groups_finished_not_mass_failure was the only value, and since 1.0.0-beta.6 - it was ci_completed_not_excluded, which counted every completed shard on its own)."
6925
6955
  },
6926
6956
  "days": {
6927
6957
  "type": "integer",
@@ -7045,7 +7075,7 @@
7045
7075
  "durationMs"
7046
7076
  ]
7047
7077
  },
7048
- "description": "The last 30 finished runs of the source on branchScope, whatever the window, oldest first - one point per run, passed counting first-try passes, durationMs from its first shard's start to its last shard's finish. Cancelled runs are left out."
7078
+ "description": "The last 30 finished runs of the source on branchScope, whatever the window, oldest first - one point per run, passed counting first-try passes, durationMs from its first shard's start to its last shard's finish. Cancelled and incomplete runs are left out (incomplete since 1.0.0-beta.10)."
7049
7079
  }
7050
7080
  },
7051
7081
  "required": [
package/dist/tools.js CHANGED
@@ -23,10 +23,12 @@ export const TOOLS = [
23
23
  name: "squally-find-run",
24
24
  title: "Find runs",
25
25
  operationId: "listRuns",
26
- description: "Finds CI runs of a project - the latest, or filtered by branch, commit SHA or status. " +
27
- "One row per logical run: a sharded run is collapsed into a single entry. Returns summary " +
26
+ description: "Finds runs of a project, CI and local alike - the latest, or filtered by branch, commit SHA, " +
27
+ "status or source (all by default; ci or local narrows it, and each run says local). Status " +
28
+ "is passed, failed, cancelled, incomplete or running. One row per logical run: a sharded run " +
29
+ "is collapsed into a single entry, its counters over all its shards. Returns summary " +
28
30
  "counters only; use squally-get-run for the per-test rows.",
29
- answers: "Which runs happened — latest, or by branch, commit SHA or status. Counters only.",
31
+ answers: "Which runs happened — latest, or by branch, commit SHA, status or source. Counters only.",
30
32
  cost: "cheap",
31
33
  },
32
34
  {
@@ -34,7 +36,8 @@ export const TOOLS = [
34
36
  title: "Get one run",
35
37
  operationId: "getRun",
36
38
  description: "One run with its per-test result rows, across every shard. Use this to find out which " +
37
- "test is red in a run; the run list carries only the counters.",
39
+ "test is red in a run; the run list carries only the counters. Its status is cancelled " +
40
+ "for a cancelled run (cancellation says how and when), and local says it ran without CI.",
38
41
  answers: "One run with its per-test rows, across all shards. Which test is red.",
39
42
  cost: "cheap",
40
43
  },
@@ -56,11 +59,13 @@ export const TOOLS = [
56
59
  "/ runs), flakyRate (runs that passed only after a retry / runs), failureRate (failed " +
57
60
  "runs / runs), time lost to retries and failures, its last 20 runs (each with the run " +
58
61
  "id squally-find-run gives; runs it skipped included, as result \"skipped\" - shown, " +
59
- "never counted in runs or any rate) and the branches it ran on. Counts the CI runs of " +
60
- "the period whose shards all finished - a sharded run counts once, by its first " +
61
- "shard's start - without runs that were a mass failure as a whole; source=local or " +
62
- "source=all counts local runs or both instead (population names which), and a run " +
63
- "still in progress counts once all its shards have finished. There " +
62
+ "never counted in runs or any rate) and the branches it ran on. Counts the finished " +
63
+ "CI runs of the period - a sharded run counts once, by its first shard's start - " +
64
+ "without runs that were a mass failure as a whole; source=local or source=all counts " +
65
+ "local runs or both instead (population names which). A run still in progress counts " +
66
+ "once all its shards have finished, or once the run timeout has passed, with the " +
67
+ "results its shards reported - also when a shard was stopped by the monthly result " +
68
+ "limit. There " +
64
69
  "is no verdict - the tool returns the numbers and you judge them. runs = 0 " +
65
70
  "with null rates is a valid answer: no counted CI run of this test in the period. " +
66
71
  "Cheap; for one test use this, not squally-list-tests.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "squally-mcp",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Local MCP server for Squally — read-only access to your Playwright test runs, flaky tests and failures.",
5
5
  "license": "MIT",
6
6
  "author": "Squally",