@tellagen/mcp-server 0.5.1 → 0.7.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 (123) hide show
  1. package/README.md +53 -3
  2. package/SKILL.md +143 -19
  3. package/contracts/mcp-protocol.json +64 -3
  4. package/contracts/runbooks/manifest.json +24 -14
  5. package/contracts/runbooks/v2/client-protocol.json +65 -2
  6. package/contracts/runbooks/v2/client-writes.guidance.json +16 -1
  7. package/contracts/runbooks/v2/fixtures/filesystem-pressure.json +22 -31
  8. package/contracts/runbooks/v2/fixtures/timeline-event-blocks-rejected.json +15 -1
  9. package/contracts/runbooks/v2/investigation-window.guidance.json +45 -0
  10. package/contracts/runbooks/v2/question-checks.guidance.json +49 -0
  11. package/contracts/runbooks/v2/result-summary.guidance.json +53 -5
  12. package/contracts/runbooks/v2/timeline-event-blocks.schema.json +66 -3
  13. package/contracts/tellagen-runbook-contracts.json +3 -3
  14. package/dist/active-run.d.ts +6 -0
  15. package/dist/active-run.js +14 -0
  16. package/dist/active-run.js.map +1 -1
  17. package/dist/cli/doctor.d.ts +19 -0
  18. package/dist/cli/doctor.js +179 -0
  19. package/dist/cli/doctor.js.map +1 -0
  20. package/dist/cli/kubernetes.d.ts +47 -0
  21. package/dist/cli/kubernetes.js +369 -0
  22. package/dist/cli/kubernetes.js.map +1 -0
  23. package/dist/cli/main.js +10 -0
  24. package/dist/cli/main.js.map +1 -1
  25. package/dist/diagnosis-structure.d.ts +380 -102
  26. package/dist/diagnosis-structure.js +334 -14
  27. package/dist/diagnosis-structure.js.map +1 -1
  28. package/dist/doctor/checks.d.ts +42 -0
  29. package/dist/doctor/checks.js +181 -0
  30. package/dist/doctor/checks.js.map +1 -0
  31. package/dist/doctor/config-files.d.ts +49 -0
  32. package/dist/doctor/config-files.js +121 -0
  33. package/dist/doctor/config-files.js.map +1 -0
  34. package/dist/doctor/k8s-read-only.d.ts +16 -0
  35. package/dist/doctor/k8s-read-only.js +89 -0
  36. package/dist/doctor/k8s-read-only.js.map +1 -0
  37. package/dist/doctor/real-fs.d.ts +3 -0
  38. package/dist/doctor/real-fs.js +36 -0
  39. package/dist/doctor/real-fs.js.map +1 -0
  40. package/dist/doctor/toml.d.ts +13 -0
  41. package/dist/doctor/toml.js +205 -0
  42. package/dist/doctor/toml.js.map +1 -0
  43. package/dist/figures.d.ts +520 -101
  44. package/dist/figures.js +341 -7
  45. package/dist/figures.js.map +1 -1
  46. package/dist/heartbeat.d.ts +3 -0
  47. package/dist/heartbeat.js +32 -1
  48. package/dist/heartbeat.js.map +1 -1
  49. package/dist/index.js +1 -1
  50. package/dist/index.js.map +1 -1
  51. package/dist/k8s-safety.d.ts +42 -0
  52. package/dist/k8s-safety.js +33 -0
  53. package/dist/k8s-safety.js.map +1 -0
  54. package/dist/listen-config.d.ts +5 -5
  55. package/dist/listen-probe.d.ts +14 -1
  56. package/dist/listen-probe.js +83 -5
  57. package/dist/listen-probe.js.map +1 -1
  58. package/dist/listen-settings.d.ts +8 -0
  59. package/dist/listen-settings.js +29 -0
  60. package/dist/listen-settings.js.map +1 -1
  61. package/dist/listener.d.ts +11 -0
  62. package/dist/listener.js +60 -16
  63. package/dist/listener.js.map +1 -1
  64. package/dist/log-lines.d.ts +118 -0
  65. package/dist/log-lines.js +534 -0
  66. package/dist/log-lines.js.map +1 -0
  67. package/dist/redact.d.ts +21 -0
  68. package/dist/redact.js +212 -5
  69. package/dist/redact.js.map +1 -1
  70. package/dist/run-events.js +13 -1
  71. package/dist/run-events.js.map +1 -1
  72. package/dist/run-requests.d.ts +16 -0
  73. package/dist/run-requests.js +56 -0
  74. package/dist/run-requests.js.map +1 -0
  75. package/dist/run-window.d.ts +59 -0
  76. package/dist/run-window.js +141 -0
  77. package/dist/run-window.js.map +1 -0
  78. package/dist/server.d.ts +1 -1
  79. package/dist/server.js +11 -9
  80. package/dist/server.js.map +1 -1
  81. package/dist/session.d.ts +37 -0
  82. package/dist/session.js +59 -0
  83. package/dist/session.js.map +1 -1
  84. package/dist/tool-report.d.ts +2 -0
  85. package/dist/tool-report.js +3 -0
  86. package/dist/tool-report.js.map +1 -0
  87. package/dist/tools/amendments.d.ts +13 -0
  88. package/dist/tools/amendments.js +206 -0
  89. package/dist/tools/amendments.js.map +1 -0
  90. package/dist/tools/catalog.js +4 -0
  91. package/dist/tools/catalog.js.map +1 -1
  92. package/dist/tools/diagnostics.js +131 -3
  93. package/dist/tools/diagnostics.js.map +1 -1
  94. package/dist/tools/figures.d.ts +2 -2
  95. package/dist/tools/figures.js +37 -9
  96. package/dist/tools/figures.js.map +1 -1
  97. package/dist/tools/findings.d.ts +136 -0
  98. package/dist/tools/findings.js +68 -7
  99. package/dist/tools/findings.js.map +1 -1
  100. package/dist/tools/index.js +4 -0
  101. package/dist/tools/index.js.map +1 -1
  102. package/dist/tools/investigations.d.ts +3223 -5
  103. package/dist/tools/investigations.js +202 -50
  104. package/dist/tools/investigations.js.map +1 -1
  105. package/dist/tools/next.d.ts +16 -0
  106. package/dist/tools/next.js +49 -1
  107. package/dist/tools/next.js.map +1 -1
  108. package/dist/tools/postmortem-runbooks.d.ts +20 -20
  109. package/dist/tools/requests.d.ts +3 -0
  110. package/dist/tools/requests.js +62 -0
  111. package/dist/tools/requests.js.map +1 -0
  112. package/dist/tools/resume.js +14 -1
  113. package/dist/tools/resume.js.map +1 -1
  114. package/dist/tools/source-links.d.ts +7 -0
  115. package/dist/tools/source-links.js +32 -5
  116. package/dist/tools/source-links.js.map +1 -1
  117. package/dist/tools/timeline.js +24 -2
  118. package/dist/tools/timeline.js.map +1 -1
  119. package/dist/version.d.ts +4 -2
  120. package/dist/version.js +6 -1
  121. package/dist/version.js.map +1 -1
  122. package/package.json +1 -1
  123. package/server.json +1 -1
@@ -1,6 +1,6 @@
1
1
  {
2
- "contract_version": "2026-11-12.4",
3
- "bundle_sha256": "be6b865611486f0643b93475e12f5aa110baeedb2b40e8e1c577f5af90951e70",
2
+ "contract_version": "2026-11-17.1",
3
+ "bundle_sha256": "f0c6dbed0bd3e716de808f5cf42553def829864a0c26cb40f3c85cae7ec3fd3e",
4
4
  "bundle_digest_algorithm": "sha256(sorted(path + NUL + file_sha256 + LF))",
5
5
  "files": [
6
6
  {
@@ -10,13 +10,13 @@
10
10
  },
11
11
  {
12
12
  "path": "v2/client-protocol.json",
13
- "sha256": "7e56204abb9244224da34e16f7a03ab9a98ec011ee6818238a0070445b5e2124",
14
- "bytes": 26452
13
+ "sha256": "280e08fe0455bfec03a466328a1a02f54d6988921b940b627b5bab256070d7bd",
14
+ "bytes": 28149
15
15
  },
16
16
  {
17
17
  "path": "v2/client-writes.guidance.json",
18
- "sha256": "21308777a7e2df31becfaf0d30d15d34d15209c82a74d5ce722412de9641b6a0",
19
- "bytes": 5623
18
+ "sha256": "cb6edb75eec86edc9bdd4705d2bff12636cd03c659689b71a8ecc58e72be418c",
19
+ "bytes": 7796
20
20
  },
21
21
  {
22
22
  "path": "v2/compiled-plan.schema.json",
@@ -25,8 +25,8 @@
25
25
  },
26
26
  {
27
27
  "path": "v2/fixtures/filesystem-pressure.json",
28
- "sha256": "8c7b92f5dc4b68e94d20459ff33089f93d41bf5b8b876c76ce28f5d4a5fb48af",
29
- "bytes": 8804
28
+ "sha256": "093860c63b91dcb0528c87c769d03e2cc4aa88edcd444a4d305acd86a93c2c11",
29
+ "bytes": 8632
30
30
  },
31
31
  {
32
32
  "path": "v2/fixtures/grafana-error-rate-plan.json",
@@ -40,18 +40,28 @@
40
40
  },
41
41
  {
42
42
  "path": "v2/fixtures/timeline-event-blocks-rejected.json",
43
- "sha256": "180918b71679e3155584167c8869d216e82938570ac49a15633692215c4b3999",
44
- "bytes": 5829
43
+ "sha256": "21886fb5e1d785c5782ca48a4c358e3285992827d3b5e0d98dc5015f6233f8a1",
44
+ "bytes": 6459
45
45
  },
46
46
  {
47
47
  "path": "v2/fixtures/timeline-event-with-blocks.json",
48
48
  "sha256": "944f8fcaaaacd81c2f2b0d42bd5e3baa32c26c33ce04d71a0187968158d2a7fe",
49
49
  "bytes": 3361
50
50
  },
51
+ {
52
+ "path": "v2/investigation-window.guidance.json",
53
+ "sha256": "72a3709e76fe7881d151886b73367d7683fa929a3af129b2a5b790ec0829acd9",
54
+ "bytes": 2915
55
+ },
56
+ {
57
+ "path": "v2/question-checks.guidance.json",
58
+ "sha256": "af5bfbd8cccdcf33defa7b9071a326fe58b3ef819a79d13b6e0058adc9b4f929",
59
+ "bytes": 3919
60
+ },
51
61
  {
52
62
  "path": "v2/result-summary.guidance.json",
53
- "sha256": "8d9372a00de80e4326205e0fbdb50269005dffc8f54ad594ec259ea03071cde4",
54
- "bytes": 2418
63
+ "sha256": "3d0f2a7d1b451efdfad41f42d946107e41c4b1ea1d6ba520932adcf500d9d854",
64
+ "bytes": 6087
55
65
  },
56
66
  {
57
67
  "path": "v2/runbook-definition.schema.json",
@@ -60,8 +70,8 @@
60
70
  },
61
71
  {
62
72
  "path": "v2/timeline-event-blocks.schema.json",
63
- "sha256": "8c47e3f39cbdbbcafe69215b07af763ce110a561f01491da8bdc0db968f2c76f",
64
- "bytes": 26585
73
+ "sha256": "ff84b0b9ebb6a97b123c1c318548af31a74fcf95cc28a452edeeb2027b34df98",
74
+ "bytes": 31536
65
75
  }
66
76
  ]
67
77
  }
@@ -2,13 +2,18 @@
2
2
  "format": 1,
3
3
  "about": "What Tellagen offers to a diagnosis client: capabilities, headers, error codes and the fields of each route a client calls. A test builds this file from the request and response types; refresh it with UPDATE_CLIENT_PROTOCOL=1 (see handlers/client_protocol_contract_test.go). The MCP server compares it with what it sends and relies on.",
4
4
  "server_capabilities": [
5
+ "action_answer_v1",
5
6
  "cause_lead_v1",
6
7
  "client_heartbeat_v1",
7
8
  "completion_repairs_v1",
9
+ "coverage_not_needed_v1",
8
10
  "diagnosis_changes_v1",
9
11
  "diagnosis_structure_v1",
10
12
  "diff_lines_v1",
11
13
  "figure_extras_v1",
14
+ "figure_limits_v1",
15
+ "log_lines_v1",
16
+ "question_checks_v1",
12
17
  "recorded_steps_v1",
13
18
  "responder_notes_v1",
14
19
  "run_images_v1"
@@ -21,10 +26,13 @@
21
26
  "finding_roles_v2",
22
27
  "gap_findings_v2",
23
28
  "guidance_default_v1",
29
+ "investigation_window_v1",
30
+ "question_checks_v1",
24
31
  "responder_notes_v1",
25
32
  "run_images_v1",
26
33
  "runbook_plan_v2",
27
34
  "strict_fields_v1",
35
+ "tool_check_v1",
28
36
  "trace_check_id_v2"
29
37
  ],
30
38
  "client_headers": [
@@ -39,9 +47,11 @@
39
47
  "client_upgrade_required",
40
48
  "denied",
41
49
  "expired",
50
+ "finding_checks_invalid",
42
51
  "invalid_device_code",
43
52
  "invalid_field_type",
44
53
  "invalid_idempotency_key",
54
+ "invalid_window",
45
55
  "investigation_completion_blocked",
46
56
  "investigation_executor_conflict",
47
57
  "investigation_run_ended",
@@ -147,6 +157,9 @@
147
157
  "method": "POST",
148
158
  "path": "/api/v1/incidents/{id}/findings",
149
159
  "request_fields": [
160
+ "checks",
161
+ "checks.question",
162
+ "checks.source",
150
163
  "claim",
151
164
  "confidence",
152
165
  "confidence_reason",
@@ -186,6 +199,8 @@
186
199
  ],
187
200
  "response_fields": [
188
201
  "finding",
202
+ "finding.answers",
203
+ "finding.checks",
189
204
  "finding.claim",
190
205
  "finding.confidence",
191
206
  "finding.confidence_reason",
@@ -234,6 +249,12 @@
234
249
  "proxy_id",
235
250
  "question",
236
251
  "question_finding_id",
252
+ "window",
253
+ "window.baseline_days",
254
+ "window.from",
255
+ "window.from_expr",
256
+ "window.to",
257
+ "window.to_expr",
237
258
  "without_grafana"
238
259
  ],
239
260
  "response_fields": [
@@ -291,7 +312,8 @@
291
312
  "run.question_finding_id",
292
313
  "run.result_summary",
293
314
  "run.started_at",
294
- "run.status"
315
+ "run.status",
316
+ "run.window"
295
317
  ]
296
318
  },
297
319
  {
@@ -578,7 +600,11 @@
578
600
  "runs.requested_by",
579
601
  "runs.requested_by_me",
580
602
  "runs.run_id",
581
- "runs.screenshot_count"
603
+ "runs.screenshot_count",
604
+ "tool_check",
605
+ "tool_check.client",
606
+ "tool_check.expires_at",
607
+ "tool_check.id"
582
608
  ]
583
609
  },
584
610
  {
@@ -589,6 +615,7 @@
589
615
  "failure_reason",
590
616
  "mitigation_state",
591
617
  "result_summary",
618
+ "result_summary.answer",
592
619
  "result_summary.assessment",
593
620
  "result_summary.causal_paths",
594
621
  "result_summary.change_refs",
@@ -607,6 +634,7 @@
607
634
  "result_summary.signals_checked",
608
635
  "result_summary.takeaways",
609
636
  "result_summary.unknowns",
637
+ "result_summary.window_suggestion",
610
638
  "status"
611
639
  ],
612
640
  "response_fields": [
@@ -641,6 +669,7 @@
641
669
  "pickup.parent",
642
670
  "ready",
643
671
  "repairs",
672
+ "repairs.advice",
644
673
  "repairs.code",
645
674
  "repairs.example",
646
675
  "repairs.field",
@@ -678,6 +707,7 @@
678
707
  "run.result_summary",
679
708
  "run.started_at",
680
709
  "run.status",
710
+ "run.window",
681
711
  "run_state",
682
712
  "warnings",
683
713
  "warnings.code",
@@ -721,6 +751,7 @@
721
751
  "incident.last_event_at",
722
752
  "incident.last_event_summary",
723
753
  "incident.meet_url",
754
+ "incident.origin",
724
755
  "incident.postmortem_summary",
725
756
  "incident.recovered_at",
726
757
  "incident.regions",
@@ -787,9 +818,11 @@
787
818
  "run.result_summary",
788
819
  "run.started_at",
789
820
  "run.status",
821
+ "run.window",
790
822
  "server_capabilities",
791
823
  "source_bases",
792
824
  "source_bases.base_url",
825
+ "source_bases.datasources",
793
826
  "source_bases.kind",
794
827
  "source_bases.name",
795
828
  "source_bases.network",
@@ -847,6 +880,7 @@
847
880
  "incident.last_event_at",
848
881
  "incident.last_event_summary",
849
882
  "incident.meet_url",
883
+ "incident.origin",
850
884
  "incident.postmortem_summary",
851
885
  "incident.recovered_at",
852
886
  "incident.regions",
@@ -913,14 +947,43 @@
913
947
  "run.result_summary",
914
948
  "run.started_at",
915
949
  "run.status",
950
+ "run.window",
916
951
  "server_capabilities",
917
952
  "source_bases",
918
953
  "source_bases.base_url",
954
+ "source_bases.datasources",
919
955
  "source_bases.kind",
920
956
  "source_bases.name",
921
957
  "source_bases.network",
922
958
  "source_bases.repositories"
923
959
  ]
960
+ },
961
+ {
962
+ "method": "POST",
963
+ "path": "/api/v1/settings/agent/tool-report",
964
+ "request_fields": [
965
+ "available_sources",
966
+ "available_sources.access_status",
967
+ "available_sources.detail",
968
+ "available_sources.key",
969
+ "available_sources.state",
970
+ "kubernetes_checks",
971
+ "kubernetes_checks.id",
972
+ "kubernetes_checks.status",
973
+ "kubernetes_checks.summary",
974
+ "kubernetes_read_only_tools",
975
+ "profile_id"
976
+ ],
977
+ "response_fields": [
978
+ "accepted_sources",
979
+ "accepted_sources.detail",
980
+ "accepted_sources.key",
981
+ "accepted_sources.state",
982
+ "client",
983
+ "ignored_sources",
984
+ "profile_id",
985
+ "recorded_at"
986
+ ]
924
987
  }
925
988
  ]
926
989
  }
@@ -22,7 +22,10 @@
22
22
  "Send an Idempotency-Key header (or the idempotency_key field) with every finding. Use one new key for one finding, for example a UUID, and send the same key when you repeat the request after a timeout. The repeat answers 200 with the first finding and the header Idempotent-Replayed: true, and creates nothing.",
23
23
  "A cause upsert is safe to repeat: the cause key in the path is its identity. A trace step is safe to repeat by its step_id. A create of a run with an id you chose is safe to repeat: when the run exists and you made it in the same incident, the answer is 200 with that run.",
24
24
  "A value of the wrong type answers 400 invalid_field_type with field set to the path of the value, for example result_summary.causal_paths[0].steps[1].finding_ids, and a message that says which type the field wants. Correct that field and send the request again.",
25
- "With strict_fields_v1 a body with a field the route does not know answers 400 unknown_field. field is the first path and details.fields lists up to 20 of them. Remove or rename those fields. Without the capability unknown fields are dropped with no message, as before."
25
+ "With strict_fields_v1 a body with a field the route does not know answers 400 unknown_field. field is the first path and details.fields lists up to 20 of them. Remove or rename those fields. Without the capability unknown fields are dropped with no message, as before.",
26
+ "A log or metric proof gets a Grafana Explore link from the data source, the query and the range. Give every Loki or Prometheus evidence ref a datasource with the name of the data source it came from. A ref with a query and no datasource gets the warning log_evidence_without_link, because no link can be built, and a link you send yourself must point at the workspace's own Grafana.",
27
+ "A step or finding that says a search found nothing (0 lines, no errors, no matches) must say in what range and out of how many lines. Without both it gets the warning silence_without_scope. Send a log_lines figure with matched 0, scanned and the range in source.from and source.to, or write the range and the scanned count in the result summary of the evidence.",
28
+ "Do not quote as the key line of a finding a line you marked unrelated in a log_lines figure. A finding whose result_sample is such a line gets the warning key_quote_unrelated. Quote a line that matches the event, or mark the line context or matches_event if it does."
26
29
  ],
27
30
  "x-examples": {
28
31
  "recorded_step": {
@@ -37,6 +40,18 @@
37
40
  },
38
41
  "field_error": {
39
42
  "good": {"code": "invalid_field_type", "field": "result_summary.causal_paths[0].steps[1].finding_ids", "message": "result_summary.causal_paths[0].steps[1].finding_ids: expected an array, got a string"}
43
+ },
44
+ "log_evidence_link": {
45
+ "good": {"source": "grafana-loki", "datasource": "Loki", "query": "{app=\"slack-bot\"} |= \"reply sent\"", "result_summary": "0 of 2,313 lines from 2026-11-14T00:26:02Z to 2026-11-14T01:26:02Z"},
46
+ "bad": {"source": "grafana-loki", "query": "{app=\"slack-bot\"} |= \"reply sent\"", "result_summary": "No lines"}
47
+ },
48
+ "silence_scope": {
49
+ "good": {"type": "log_lines", "title": "Replies after the ack", "matched": 0, "scanned": 2313, "source": {"kind": "loki", "datasource": "Loki", "query": "{app=\"slack-bot\"} |= \"reply sent\"", "from": "2026-11-14T00:26:02Z", "to": "2026-11-14T01:26:02Z"}, "event_at": "2026-11-14T00:26:02Z"},
50
+ "bad": {"claim": "The bot never replied.", "result_summary": "0 lines"}
51
+ },
52
+ "key_quote": {
53
+ "good": {"claim": "The leader task failed 4 minutes after the ack.", "result_sample": "00:30:12 leader task failed company=402"},
54
+ "bad": {"claim": "The leader task failed after the ack.", "result_sample": "00:26:02 leader task failed company=578", "note": "the same run marked this line unrelated: company 578, 11 hours after the event"}
40
55
  }
41
56
  }
42
57
  }
@@ -19,17 +19,6 @@
19
19
  "capabilities": ["repos:read"],
20
20
  "required": true,
21
21
  "on_unavailable": {"action": "record_gap"}
22
- },
23
- {
24
- "id": "host-filesystem",
25
- "source_key": "local_host",
26
- "capabilities": [
27
- "host:filesystem_inventory",
28
- "host:path_mount_mapping",
29
- "host:filesystem_consumers"
30
- ],
31
- "required": true,
32
- "on_unavailable": {"action": "record_gap"}
33
22
  }
34
23
  ],
35
24
  "entry_check_ids": ["identify-alert-filesystem"],
@@ -82,44 +71,46 @@
82
71
  },
83
72
  {
84
73
  "id": "map-runtime-filesystems",
85
- "intent": "Map the alerted filesystem and every suspected service storage path to runtime host, device, and mountpoint identities",
86
- "source_requirement_id": "host-filesystem",
74
+ "intent": "Map the alerted filesystem and every suspected service storage path to host, device, and mountpoint identities with the node-exporter filesystem series",
75
+ "source_requirement_id": "filesystem-metrics",
87
76
  "safety": "read_only",
88
77
  "invocation": {
89
78
  "kind": "query",
90
- "capability": "host:path_mount_mapping",
91
- "template": "Use the reviewed bounded host evidence wrapper to map root, monitoring, and container storage paths to host, device, mountpoint, and filesystem identities. Compare candidates only with explicit resource identity keys.",
92
- "parameters": {},
93
- "bounds": {"lookback": "5m", "step": "5m", "max_points": 1}
79
+ "capability": "prometheus:query",
80
+ "template": "node_filesystem_size_bytes{fstype=~\"ext4|xfs\"}",
81
+ "parameters": {
82
+ "time_range": {"type": "time_range", "source": "incident.time_range", "target": "request.range"}
83
+ },
84
+ "bounds": {"lookback": "30m", "step": "5m", "max_points": 6}
94
85
  },
95
86
  "evidence_contract": {
96
- "kind": "command_output",
97
- "required_fields": ["artifact", "query", "resource_identity", "join_basis", "result_summary"]
87
+ "kind": "timeseries",
88
+ "required_fields": ["artifact", "query", "time_range", "resource_identity", "join_basis", "result_summary"]
98
89
  },
99
- "confirms_when": "The suspected consumer maps to the same host, device, and mountpoint as the alert, with the join keys recorded",
100
- "falsifies_when": "The suspected consumer explicitly maps to a different device or mountpoint on the alerting host",
90
+ "confirms_when": "The suspected consumer's storage path maps to the same host, device, and mountpoint as the alert, with the join keys recorded",
91
+ "falsifies_when": "The documented storage path of the suspected consumer maps to a different device or mountpoint on the alerting host",
101
92
  "on_confirm": ["find-alerted-filesystem-consumers"],
102
93
  "on_falsify": ["find-alerted-filesystem-consumers"],
103
94
  "on_error": {"action": "record_gap"}
104
95
  },
105
96
  {
106
97
  "id": "find-alerted-filesystem-consumers",
107
- "intent": "Identify bounded top-level consumers on the alerted filesystem without crossing mount boundaries",
108
- "source_requirement_id": "host-filesystem",
98
+ "intent": "Identify the documented consumers of the alerted filesystem from the infrastructure documentation. Tellagen does not read the host itself, so a consumer the documentation does not name stays a gap finding",
99
+ "source_requirement_id": "infrastructure-docs",
109
100
  "safety": "read_only",
110
101
  "invocation": {
111
102
  "kind": "query",
112
- "capability": "host:filesystem_consumers",
113
- "template": "Use the reviewed bounded host evidence wrapper to list top-level consumers on the alerted filesystem only. Do not follow other mounts and do not read file contents, configuration, environment, or credentials.",
103
+ "capability": "repos:read",
104
+ "template": "Read the configured infrastructure repository for the services, volumes, and storage paths that sit on the alerted host and mountpoint. Return the documented consumers with their paths. Do not read credentials, configuration values, or environment files.",
114
105
  "parameters": {},
115
106
  "bounds": {"lookback": "5m", "step": "5m", "max_points": 1}
116
107
  },
117
108
  "evidence_contract": {
118
- "kind": "command_output",
119
- "required_fields": ["artifact", "query", "resource_identity", "result_sample", "result_summary"]
109
+ "kind": "document",
110
+ "required_fields": ["artifact", "query", "result_summary"]
120
111
  },
121
- "confirms_when": "One or more bounded consumers on the alerted filesystem account for material usage and are identified by path and bytes",
122
- "falsifies_when": "No inspected consumer on the alerted filesystem accounts for material usage within the bounded evidence",
112
+ "confirms_when": "The documentation names one or more consumers whose storage is on the alerted filesystem",
113
+ "falsifies_when": "The documentation shows that no documented consumer stores data on the alerted filesystem",
123
114
  "on_confirm": ["verify-filesystem-headroom"],
124
115
  "on_falsify": ["verify-filesystem-headroom"],
125
116
  "on_error": {"action": "record_gap"}
@@ -150,13 +141,13 @@
150
141
  }
151
142
  ],
152
143
  "escalation": {
153
- "when": "Runtime topology is unavailable, resource identities do not match, or no bounded consumer explains the alert",
144
+ "when": "Runtime topology is unavailable, resource identities do not match, or no documented consumer explains the alert. Post a gap finding that says the host was not inspected",
154
145
  "target": "infrastructure owner and incident commander"
155
146
  },
156
147
  "remediation": {
157
148
  "mode": "suggest_only",
158
149
  "proposed_steps": [
159
- "Ask the infrastructure owner to review evidence-linked consumers on the alerted filesystem and approve a reversible cleanup target.",
150
+ "Ask the infrastructure owner to inspect the alerted filesystem on the host and approve a reversible cleanup target.",
160
151
  "Treat service storage or WAL failures on a different filesystem as a separate remediation task with its own owner and verification."
161
152
  ],
162
153
  "approval_required": true,
@@ -5,7 +5,7 @@
5
5
  "name": "unknown block type",
6
6
  "blocks": [{"type": "heatmap", "cells": [[1, 2], [3, 4]]}],
7
7
  "field": "blocks[0].type",
8
- "message": "unknown block type \"heatmap\" (use stats, compare, trend, table, checks, changes, range_overlap, histogram, run_history or diff)"
8
+ "message": "unknown block type \"heatmap\" (use stats, compare, trend, table, checks, changes, range_overlap, histogram, run_history, diff or log_lines)"
9
9
  },
10
10
  {
11
11
  "name": "a number sent as text",
@@ -110,6 +110,20 @@
110
110
  "blocks": [{"type": "range_overlap", "min": 0, "max": 100, "rows": [{"label": "a", "from": 10, "to": 20}, {"label": "b", "from": 50, "to": 150}]}],
111
111
  "field": "blocks[0].rows[1].to",
112
112
  "message": "must be within min and max (0 to 100)"
113
+ },
114
+ {
115
+ "name": "log lines with no result and no scope",
116
+ "blocks": [{"type": "log_lines", "matched": 0}],
117
+ "field": "blocks[0].scanned",
118
+ "message": "is required when matched is 0, so the empty result says how much was searched"
119
+ },
120
+ {
121
+ "name": "log lines with more lines than matches",
122
+ "blocks": [{"type": "log_lines", "matched": 1, "lines": [
123
+ {"time": "2026-11-14T00:26:02Z", "level": "error", "text": "a"}, {"time": "2026-11-14T00:26:03Z", "level": "error", "text": "b"}
124
+ ]}],
125
+ "field": "blocks[0].lines",
126
+ "message": "has 2 lines but matched is 1"
113
127
  }
114
128
  ]
115
129
  }
@@ -0,0 +1,45 @@
1
+ {
2
+ "title": "Investigation pickup: the time window of the run",
3
+ "description": "How to use context.window in the pickup request. The server adds it when the client advertised investigation_window_v1 in protocol_capabilities. The window was stored when the run was created, so it does not change while the run works. The field is left out for a client without the capability and for a run made before windows. The same field is in GET /api/v1/investigations/{id}/context.",
4
+ "x-capability": "investigation_window_v1",
5
+ "x-fields": {
6
+ "from": "Start of the window, an RFC 3339 time.",
7
+ "to": "End of the window. Left out means until the run ends: the incident is still open, so use now.",
8
+ "basis": "Where the window came from: first_signal_moment or first_signal_ongoing (Tellagen proposed it from the incident), person (a person set it) or follow_up (copied from the run this one corrects).",
9
+ "baseline_from": "Start of the baseline, which ends where the window starts. Left out means the run has no baseline.",
10
+ "first_signal_at": "When the first signal of the incident came in. Left out when none is known."
11
+ },
12
+ "x-time-text": "A time with no zone in a request, such as 2026-11-14 00:11, is read as UTC. Send RFC 3339 times to be exact.",
13
+ "x-limits": {
14
+ "window_max_days": 30,
15
+ "default_window_max_hours": 24,
16
+ "baseline_default_days": 7,
17
+ "suggestion_reason_max_chars": 200
18
+ },
19
+ "x-baseline-days": [0, 1, 7, 30],
20
+ "x-guidance": [
21
+ "Search for the cause inside the window: every query that looks for what went wrong uses a range between from and to.",
22
+ "Use the baseline only to learn whether a number is normal, for example the error count of the same hour on earlier days. Never look for the cause in it.",
23
+ "When the signal starts before from or after to, do not search outside the window. Send window_suggestion with the result and say so in a finding. window_suggestion is {from, to, reason}: the same limits as a window, a reason of at most 200 characters, and to may be left out for an open incident.",
24
+ "The server warns evidence_outside_window when a cited source has a time range that reaches outside the window and its baseline together. It is advice, not an error. A count over the baseline does not trigger it.",
25
+ "A window never sets or proposes a root cause. A person accepts a root cause."
26
+ ],
27
+ "x-examples": {
28
+ "window": {
29
+ "from": "2026-11-14T00:11:00Z",
30
+ "to": "2026-11-14T01:26:00Z",
31
+ "basis": "first_signal_ongoing",
32
+ "baseline_from": "2026-11-07T00:11:00Z",
33
+ "first_signal_at": "2026-11-14T00:41:00Z"
34
+ },
35
+ "good_suggestion": {
36
+ "from": "2026-11-13T22:00:00Z",
37
+ "to": "2026-11-14T01:26:00Z",
38
+ "reason": "The first 502s are at 22:14, 2 hours before the window starts."
39
+ },
40
+ "bad_suggestion": {
41
+ "from": "2026-10-01T00:00:00Z",
42
+ "reason": "I want more data."
43
+ }
44
+ }
45
+ }
@@ -0,0 +1,49 @@
1
+ {
2
+ "title": "Blocking question as yes or no checks",
3
+ "description": "How to write a gap finding that blocks the diagnosis so that a person can answer it in a few seconds. The server lists question_checks_v1 in server_capabilities at pickup when it accepts checks. A client sends checks only then, and advertises question_checks_v1 in protocol_capabilities to be held to the rule: a blocking gap with no checks gets the completion warning blocking_gap_without_checks, which is advice and never an error. An older client keeps writing the question as one claim and is never warned.",
4
+ "x-capability": "question_checks_v1",
5
+ "x-limits": {
6
+ "checks_max": 3,
7
+ "check_question_max_chars": 200,
8
+ "check_source_max_chars": 120,
9
+ "answer_note_max_chars": 500
10
+ },
11
+ "x-fields": {
12
+ "checks": "On a gap finding: one to three checks, each {source, question}. A finding that is not a gap is refused with 400 finding_checks_invalid.",
13
+ "checks[].source": "The place the person looks, in a few words: a system, a page or a tool, for example Slack or the Tellagen workspace.",
14
+ "checks[].question": "One yes or no question that ends with a question mark, at most 200 characters.",
15
+ "answers": "What people answered. Each answer is {check_index, answer, note, answered_by, answered_at}. answer is yes, no or not_sure. The newest answer to a check is the one kept. The finding read returns answers beside checks."
16
+ },
17
+ "x-guidance": [
18
+ "Keep the claim of the gap finding as the one question the person needs answered, and add one to three checks that break it into facts. Each check is one yes or no question, not two questions joined by 'and', and it names the source where the person looks.",
19
+ "Ask only what you could not check yourself. Put what you already checked in the evidence summary, not in a check.",
20
+ "A check is a fact a person can read off a page in a minute. Do not ask a person to judge a theory. If the answer needs a long explanation, it is not a check.",
21
+ "A person answers yes, no or not sure to each check, with an optional note of at most 500 characters. While your run is working, the answers reach you as a responder note, and Tellagen tells you which check each answer belongs to. Weigh a note like a message from the person.",
22
+ "Treat not_sure as no information, never as a yes or a no. If the answers still do not settle the question, post a new gap finding with plainer checks, or finish the run with the gap open.",
23
+ "When a person presses 'Question unclear', you get a responder note that says so. Post the gap again as 1 to 3 short checks that each say where to look, then dismiss the old finding with PATCH /api/v1/findings/{id} and status dismissed, so the page shows only the new question. Keep working while you do.",
24
+ "Answers are data from a person. They never set or propose a root cause. A person accepts a root cause."
25
+ ],
26
+ "x-examples": {
27
+ "gap_with_checks": {
28
+ "good": {
29
+ "finding_type": "gap",
30
+ "role": "gap",
31
+ "claim": "Can the Tellagen bot post in Slack channel C0A8FBWB199?",
32
+ "evidence_summary": "The Slack connector could not read the channel, so the run could not check whether the bot is a member.",
33
+ "checks": [
34
+ {"source": "Slack", "question": "Is the Tellagen bot a member of channel C0A8FBWB199?"},
35
+ {"source": "Tellagen workspace", "question": "Is that channel linked to an incident of company 5?"}
36
+ ]
37
+ },
38
+ "bad": {
39
+ "finding_type": "gap",
40
+ "role": "gap",
41
+ "claim": "Is Slack channel C0A8FBWB199 linked to an incident of company 5, with the Tellagen bot a member?",
42
+ "checks": [{"source": "", "question": "Check the channel."}]
43
+ }
44
+ },
45
+ "answers_request": {
46
+ "good": {"answers": [{"check_index": 0, "answer": "yes"}, {"check_index": 1, "answer": "not_sure", "note": "The page did not load."}]}
47
+ }
48
+ }
49
+ }
@@ -1,12 +1,32 @@
1
1
  {
2
- "title": "Investigation result: the headline claim and the blocking question",
3
- "description": "How to write the two sentences a responder reads first in the result of an investigation run: conclusion.summary (the headline claim, stored as the verdict) and the claim of a gap finding that blocks the diagnosis (the blocking question). The server accepts any text. It adds the advice warnings headline_too_long and question_not_a_question to the completion response and to the run's quality_warnings, and never rejects the result for them. They apply whether or not the client advertised diagnosis_structure_v1.",
4
- "x-limits": {"headline_max_words": 15},
2
+ "title": "Investigation result: the words a responder reads",
3
+ "description": "How to write the text a responder reads in the result of an investigation run: the headline claim (conclusion.summary, stored as the verdict), the answer line, the blocking question and every claim, summary, action and explanation. The server accepts any text. It adds the advice warnings headline_too_long, question_not_a_question, text_too_long, filler_phrase and raw_id_in_text (and coverage_not_needed_without_reason) to the completion response and to the run's quality_warnings, and never rejects the result for them. A dry run (completion_repairs_v1) lists each text warning as a repair with advice true: ready stays true, because the run would complete as it is. They apply whether or not the client advertised diagnosis_structure_v1.",
4
+ "x-limits": {
5
+ "headline_max_words": 15,
6
+ "answer_max_words": 15,
7
+ "step_claim_max_words": 20,
8
+ "finding_claim_max_words": 20,
9
+ "finding_evidence_summary_max_words": 60,
10
+ "action_title_max_words": 12,
11
+ "action_summary_max_words": 20,
12
+ "ruled_out_explanation_max_words": 30,
13
+ "coverage_summary_max_words": 20,
14
+ "unknown_label_max_words": 12,
15
+ "customer_impact_label_max_words": 15
16
+ },
5
17
  "x-guidance": [
6
18
  "The headline claim states one cause in at most 15 words. Name what broke and why, in plain words. Put the detail, the numbers and the other possible causes in findings, causal_paths and ruled_out, not in the headline.",
7
19
  "A blocking question is a gap finding that a person has to answer before the diagnosis can be trusted. Write its claim as one real question that ends with a question mark and that a person with access to the system can answer with a fact. Do not write it as a statement about what is unknown.",
8
20
  "Ask one thing in a blocking question. If you have two questions, post two gap findings. Put what you already checked in the evidence summary, not in the question.",
9
- "If the headline is over 15 words, completion answers with the warning headline_too_long and keeps the result. If a blocking question does not end with a question mark, completion answers with question_not_a_question and keeps the result. Fix the sentence and send the result again when you can; the run is not failed either way."
21
+ "If the headline is over 15 words, completion answers with the warning headline_too_long and keeps the result. If a blocking question does not end with a question mark, completion answers with question_not_a_question and keeps the result. Fix the sentence and send the result again when you can; the run is not failed either way.",
22
+ "Keep every sentence short. The limits in words are: answer 15, claim of a causal step 20, claim of a finding 20, evidence summary of a finding 60 (three sentences at most), action title 12, action summary 20, ruled-out explanation 30, coverage summary or reason 20, unknown label 12, customer impact label 15. A text over its limit completes with the warning text_too_long, which names the path, the count and the limit; the page folds it behind Show more.",
23
+ "Do not repeat a rule of this protocol in your text. The page shows who decides.",
24
+ "The phrases in x-banned-phrase-openers are filler only at the start of a sentence: a sentence that opens with Based on the is flagged, a fact that says the threshold is based on the p99 latency is not.",
25
+ "A finding states a fact. Do not write in the first person; a source you did not read is a coverage entry, not a sentence.",
26
+ "Do not put a raw id in a sentence: a number of 9 digits or more, such as a run or job number, or a hex string of 12 characters or more. Put the id in links and name the thing in words. A short commit id of 7 characters or a pull request number such as #421 is fine. A long number followed by a unit word, such as 107374182400 bytes, is a measurement and is fine. The warning is raw_id_in_text.",
27
+ "When the run's question asks what to do, write result_summary.answer: one plain sentence of at most 15 words that answers it directly. Leave it out when the run had no question beyond the default. When an action changes a file, add a diff figure of the exact lines to the action (recommended_actions[].figure). Both need the server capability action_answer_v1.",
28
+ "A source you skipped on purpose is a coverage entry in state not_needed with a reason of at most 20 words (coverage_not_needed_v1). It is not checked, and it is not a gap. Never send checked for a source nobody read.",
29
+ "In a compare figure, never put a limit or a budget in before. Give the row its own limit instead (figure_limits_v1): the row then reads after against limit and needs no before."
10
30
  ],
11
31
  "x-examples": {
12
32
  "headline": {
@@ -16,6 +36,34 @@
16
36
  "blocking_question": {
17
37
  "good": "Did the 14:02 deploy of the billing service lower the retry limit?",
18
38
  "bad": "Whether the retry limit was lowered by the 14:02 deploy of the billing service could not be established from the available data and needs to be confirmed by someone with access to the deploy history."
39
+ },
40
+ "answer": {
41
+ "good": "Keep the P1 alert for master. Stop paging for pull requests.",
42
+ "bad": "Based on the investigation, I recommend that the team considers whether the alert should be moved to a lower priority or removed."
43
+ },
44
+ "finding_evidence_summary": {
45
+ "good": "The pool reached 100 of 100 connections at 14:02. Errors began 40 seconds later. The pool recovered after the restart at 14:20.",
46
+ "bad": "Run 43852571837 failed. I could not find a written paging policy. This is a proposal. A person decides."
19
47
  }
20
- }
48
+ },
49
+ "x-banned-phrases": [
50
+ "This is a proposal. A person decides.",
51
+ "A person decides",
52
+ "Only a person can",
53
+ "Based on the",
54
+ "It is likely that",
55
+ "It is worth noting",
56
+ "Please note",
57
+ "I could not find",
58
+ "I did not",
59
+ "in the data I read",
60
+ "Not queried on purpose",
61
+ "Investigation complete"
62
+ ],
63
+ "x-banned-phrase-openers": [
64
+ "Based on the",
65
+ "It is likely that",
66
+ "It is worth noting",
67
+ "Please note"
68
+ ]
21
69
  }