@tellagen/mcp-server 0.5.1 → 0.6.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 (74) hide show
  1. package/README.md +29 -3
  2. package/SKILL.md +40 -3
  3. package/contracts/mcp-protocol.json +13 -1
  4. package/contracts/runbooks/manifest.json +20 -10
  5. package/contracts/runbooks/v2/client-protocol.json +59 -2
  6. package/contracts/runbooks/v2/client-writes.guidance.json +16 -1
  7. package/contracts/runbooks/v2/fixtures/timeline-event-blocks-rejected.json +15 -1
  8. package/contracts/runbooks/v2/investigation-window.guidance.json +45 -0
  9. package/contracts/runbooks/v2/question-checks.guidance.json +49 -0
  10. package/contracts/runbooks/v2/timeline-event-blocks.schema.json +62 -1
  11. package/contracts/tellagen-runbook-contracts.json +3 -3
  12. package/dist/cli/doctor.d.ts +19 -0
  13. package/dist/cli/doctor.js +212 -0
  14. package/dist/cli/doctor.js.map +1 -0
  15. package/dist/cli/main.js +5 -0
  16. package/dist/cli/main.js.map +1 -1
  17. package/dist/diagnosis-structure.d.ts +103 -78
  18. package/dist/diagnosis-structure.js +62 -7
  19. package/dist/diagnosis-structure.js.map +1 -1
  20. package/dist/doctor/checks.d.ts +42 -0
  21. package/dist/doctor/checks.js +175 -0
  22. package/dist/doctor/checks.js.map +1 -0
  23. package/dist/doctor/config-files.d.ts +49 -0
  24. package/dist/doctor/config-files.js +121 -0
  25. package/dist/doctor/config-files.js.map +1 -0
  26. package/dist/doctor/toml.d.ts +13 -0
  27. package/dist/doctor/toml.js +205 -0
  28. package/dist/doctor/toml.js.map +1 -0
  29. package/dist/figures.d.ts +407 -83
  30. package/dist/figures.js +297 -5
  31. package/dist/figures.js.map +1 -1
  32. package/dist/index.js +1 -1
  33. package/dist/index.js.map +1 -1
  34. package/dist/k8s-safety.d.ts +42 -0
  35. package/dist/k8s-safety.js +33 -0
  36. package/dist/k8s-safety.js.map +1 -0
  37. package/dist/log-lines.d.ts +118 -0
  38. package/dist/log-lines.js +534 -0
  39. package/dist/log-lines.js.map +1 -0
  40. package/dist/redact.d.ts +21 -0
  41. package/dist/redact.js +212 -5
  42. package/dist/redact.js.map +1 -1
  43. package/dist/run-window.d.ts +59 -0
  44. package/dist/run-window.js +141 -0
  45. package/dist/run-window.js.map +1 -0
  46. package/dist/server.d.ts +1 -1
  47. package/dist/server.js +1 -1
  48. package/dist/tool-report.d.ts +2 -0
  49. package/dist/tool-report.js +3 -0
  50. package/dist/tool-report.js.map +1 -0
  51. package/dist/tools/catalog.js +1 -0
  52. package/dist/tools/catalog.js.map +1 -1
  53. package/dist/tools/diagnostics.js +85 -2
  54. package/dist/tools/diagnostics.js.map +1 -1
  55. package/dist/tools/figures.d.ts +2 -2
  56. package/dist/tools/figures.js +29 -7
  57. package/dist/tools/figures.js.map +1 -1
  58. package/dist/tools/findings.d.ts +8 -0
  59. package/dist/tools/findings.js +63 -2
  60. package/dist/tools/findings.js.map +1 -1
  61. package/dist/tools/investigations.d.ts +1 -1
  62. package/dist/tools/investigations.js +43 -4
  63. package/dist/tools/investigations.js.map +1 -1
  64. package/dist/tools/postmortem-runbooks.d.ts +20 -20
  65. package/dist/tools/source-links.d.ts +7 -0
  66. package/dist/tools/source-links.js +32 -5
  67. package/dist/tools/source-links.js.map +1 -1
  68. package/dist/tools/timeline.js +13 -2
  69. package/dist/tools/timeline.js.map +1 -1
  70. package/dist/version.d.ts +2 -2
  71. package/dist/version.js +3 -1
  72. package/dist/version.js.map +1 -1
  73. package/package.json +1 -1
  74. package/server.json +1 -1
package/README.md CHANGED
@@ -97,6 +97,24 @@ After a restart of the client, ask it to continue. `tellagen_resume` picks the r
97
97
 
98
98
  In **Settings > Local diagnosis**, under **For admins**, **Check MCP tools** gives a prompt with a `diagnostic_session_id` such as `diag_abc123`. That is a tool check, not a run: the client turns on the `settings` toolset, runs safe read-only checks and calls `tellagen_report_diagnostic_tools`.
99
99
 
100
+ To recheck from the client with no prompt to copy, ask it to run `tellagen_report_available_sources`: it posts the tools the client can reach (`grafana`, `kubernetes`, `github`, `docs`, `local_host`, each found or not found) to Tellagen, and the tools table in Settings shows them for that client. For Kubernetes the client also runs four `kubectl auth can-i` tests (create pods, delete pods, create `pods/exec`, get secrets) and reports them as checks. The tests read access rules and change nothing. They say what the Kubernetes identity could do, not what a model will do: a session that is not listened has no guard on its commands, so Tellagen never calls such a session read-only.
101
+
102
+ ### Find out why a tool is not found
103
+
104
+ ```
105
+ npx @tellagen/mcp-server doctor [--client claude-code|claude-desktop|codex|cursor] [--tool grafana|kubernetes|github|docs] [--fix] [--report]
106
+ ```
107
+
108
+ `doctor` is for a person to run. It reads the MCP config files of the AI clients on this computer, only because you ran it: Claude Code (`~/.claude.json`, and `.mcp.json` of the current folder), Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`, or the Windows and Linux place), Codex (`~/.codex/config.toml`) and Cursor (`~/.cursor/mcp.json`). It never writes them. For each server that is Grafana, Kubernetes, GitHub or documentation, it checks and says in one sentence what to do:
109
+
110
+ - `command_resolves`: the command can be started. Claude Desktop and Cursor start servers from a shorter PATH than a terminal (`/usr/bin:/bin:/usr/sbin:/sbin` plus the `PATH` of the entry's `env`), so `uvx` that works in your terminal can fail there. The doctor then names the full path to use. Claude Code and Codex use the PATH of your terminal.
111
+ - `env_present`: the settings the tool needs are in the entry (names only; a value is never printed or sent).
112
+ - `health`: for Grafana, `GRAFANA_URL` answers `/api/health`. No token is sent.
113
+
114
+ `--fix` prints a corrected entry and stops; it changes nothing. `--report` posts the result to Tellagen, only names and statuses in fixed words (no path, value, argument or file text), under the client's name, so the Settings table can show why a tool is not found. It reports only problems, never a tool as found.
115
+
116
+ The doctor cannot see a running session. It reads config files, so the model check (Recheck in Settings, or `/tellagen:check-tools`) is still the truth for a session. It does not test what a Kubernetes identity can change. The exit code is 1 when it found a problem.
117
+
100
118
  ### If something is not set up
101
119
 
102
120
  The server always starts, so the client shows it as connected. What a tool call answers when it cannot work:
@@ -111,7 +129,7 @@ The server asks Tellagen once, right after the MCP handshake, whether the key wo
111
129
 
112
130
  ## Tools
113
131
 
114
- The server offers 50 tools, all with the prefix `tellagen_`, in five toolsets. A tool that reads never changes anything. A person, not an API key, accepts or rejects a root cause in Tellagen: no tool can do it.
132
+ The server offers 51 tools, all with the prefix `tellagen_`, in five toolsets. A tool that reads never changes anything. A person, not an API key, accepts or rejects a root cause in Tellagen: no tool can do it.
115
133
 
116
134
  ### Toolsets
117
135
 
@@ -211,6 +229,7 @@ Setup checks and run inspection.
211
229
  | `tellagen_probe_datasource` | reads | Check the local setup of a datasource before you query it |
212
230
  | `tellagen_get_diagnostic_session` | reads | Read an MCP diagnostic session (a `diag_*` ID) |
213
231
  | `tellagen_report_diagnostic_tools` | adds | Report which MCP tools are visible and usable |
232
+ | `tellagen_report_available_sources` | adds | Report which data sources this client can reach, with no check ID, so the tools table in Settings updates (also `/tellagen:check-tools` in the plugin) |
214
233
  | `tellagen_list_trace_steps` | reads | List the steps already posted, to avoid repeating work when you resume |
215
234
  | `tellagen_list_runbooks` | reads | List the runbooks that matched a run |
216
235
  | `tellagen_list_investigation_runbook_waivers` | reads | List the checks a responder waived |
@@ -231,6 +250,7 @@ Setup checks and run inspection.
231
250
  | `logout` | Remove the key from this computer (`--all` for every workspace). It does not sign the client out on the server |
232
251
  | `status` | Show the sign-in. `--line` prints one sentence for a client hook, or nothing when all is well; `--json` for a script |
233
252
  | `listen` | Take the diagnosis runs that wait for you and run each with Claude Code, with no window |
253
+ | `doctor` | Find why a client cannot see a tool, from the config files of the clients on this computer. Reads only; `--fix` prints a corrected entry, `--report` sends names and statuses |
234
254
  | `trace-hook` | Record one tool call of a client hook as a step of the open run |
235
255
 
236
256
  (`listen-guard` and `listen-wrap` are internal: the listener starts Claude Code through them.)
@@ -410,14 +430,18 @@ The headline claim (`conclusion.sentence` of `result_summary`) states one cause
410
430
 
411
431
  ### Capability negotiation
412
432
 
413
- At pickup the MCP server advertises, in `protocol_capabilities`, the runbook v2 bundle plus three optional capabilities. Tellagen lists the ones it accepts in the top-level `server_capabilities` of the pickup (and of `tellagen_get_incident_context`), for example `["diagnosis_structure_v1", "diagnosis_changes_v1", "run_images_v1"]`.
433
+ At pickup the MCP server advertises, in `protocol_capabilities`, the runbook v2 bundle plus the optional capabilities. Tellagen lists the ones it accepts in the top-level `server_capabilities` of the pickup (and of `tellagen_get_incident_context`), for example `["diagnosis_structure_v1", "diagnosis_changes_v1", "run_images_v1"]`.
414
434
 
415
435
  | Capability | The MCP sends | Effect on Tellagen |
416
436
  | --- | --- | --- |
417
437
  | `diagnosis_structure_v1` | evidence ref `links`, `command`, `datasource`; `causal_paths` with `finding_ids`, `figure`, `links`; `ruled_out`, `coverage`, `unknowns`; trace `outcome` and `cause_key`; live causes | a confirmed or likely diagnosis without `causal_paths` is a hard error; every other check is a warning |
418
438
  | `diagnosis_changes_v1` | `change_refs`, and the `ci_run`, `deployment` and `release` link kinds | enables the warning `regression_source_missing` |
439
+ | `investigation_window_v1` | (nothing extra) it reads `request.context.window` and puts it at the top of the pickup answer as `mcp_window`; it sends `window_suggestion` with a result when the signal lies outside the window | the pickup carries the window of the run; completion checks the suggestion and warns with `evidence_outside_window` |
440
+ | `question_checks_v1` | `checks` (one to three `{source, question}` yes or no checks) on a gap finding | a person answers each check with yes, no or not sure; a blocking gap with no checks gets the warning `blocking_gap_without_checks` |
419
441
  | `run_images_v1` | (nothing extra) it reads screenshots with `tellagen_get_context_attachment` | the web says the client reads images; without it the responder is told the agent gets each caption and a link |
420
442
 
443
+ A server-only capability, `log_lines_v1`, means Tellagen takes a `log_lines` figure. `tellagen_build_figure` builds one from the result of a Loki query (see Figures) only when the run lists it, and refuses with a clear message otherwise. The timeline tools and `tellagen_complete_investigation` leave a `log_lines` block or step figure out for a run that does not list it, and the tool result carries an `mcp_notice`. Likewise `question_checks_v1` is listed by Tellagen at pickup: without it `checks` are left off a gap finding and the result says so.
444
+
421
445
  One more capability is the server's alone: Tellagen lists `diff_lines_v1` in `server_capabilities` when a diff figure may carry unchanged lines (`op: "context"`) and line numbers (`old_no`, `new_no`). The MCP does not advertise it. Without it, a diff goes out with only its `+` and `-` lines and no numbers (an older Tellagen would drop the whole figure), and the tool result carries an `mcp_notice`. `tellagen_build_figure` takes the `run_id` for this check; the timeline tools go by the latest pickup of the process.
422
446
 
423
447
  Likewise Tellagen lists `figure_extras_v1` when a `stats` figure may carry a `title` and more than four items, and a `run_history` figure may carry `runs_not_shown`. Without it the MCP cuts a stats figure to its first four items and drops the title and `runs_not_shown`, and the tool result carries an `mcp_notice`; `tellagen_build_figure` says so in `notes`. `tellagen_build_figure` takes the `run_id` for this check, and the timeline tools and `tellagen_complete_investigation` apply it to the figures they send.
@@ -466,7 +490,9 @@ Each ref needs one of `ref`, `sha`, `title` or `links`; the MCP refuses an unkno
466
490
  | `run_history` | yes | yes | 2 to 30 runs oldest first, `runs_not_shown` (how many runs of a longer history were left out; with `figure_extras_v1` only), 4 marks, a span; the builder also takes the GitHub Actions run list (`github_runs`) and places marks by sha |
467
491
  | `diff` | yes | yes | `path`, `ref`, `additions`, `deletions`, 1 to 6 hunks and 12 changed lines in all (a short change is sent whole, each removed line next to its replacement); with `diff_lines_v1` also unchanged lines and line numbers; the builder also takes a unified `patch` and `select_hunks` |
468
492
 
469
- A step figure is at most 16 KB. The builder never sets `example` (demo data). The tool listing shows the four newer types by type only to keep it small; their fields are in `resource://tellagen/figure-guide`, and the tool checks them in full when it runs. A Tellagen that does not know a figure type yet answers a timeline block with `400 invalid_block`, and drops a step figure with the completion warning `figure_invalid`.
493
+ | `log_lines` | yes | yes | needs `log_lines_v1`. 0 to 8 lines `{time, level, text, fields, relation, note}` (text 500, up to 6 fields, note 160), `matched` of `scanned` and a `source` range (`query`, `datasource`, `from`, `to`); matched 0 needs `scanned` and the range. The builder reads a Loki result (`streams`, or `entries`), keeps the 8 lines that show the event first, reads each level from a label, JSON, logfmt or a leading word, and marks lines you name as `matches_event`, `context` or `unrelated`. The range defaults to the run window |
494
+
495
+ A step figure is at most 16 KB (48 KB for `log_lines`). The builder never sets `example` (demo data). The tool listing shows the five newer types by type only to keep it small; their fields are in `resource://tellagen/figure-guide`, and the tool checks them in full when it runs. A Tellagen that does not know a figure type yet answers a timeline block with `400 invalid_block`, and drops a step figure with the completion warning `figure_invalid`.
470
496
 
471
497
  ## Run context: screenshots, links and the parent run
472
498
 
package/SKILL.md CHANGED
@@ -16,6 +16,15 @@ Do these five things before you call `tellagen_complete_investigation`:
16
16
 
17
17
  When Tellagen answers `completed: false` with `repairs`, nothing was changed. Each repair has a `code`, the `field` path (or a runbook check id), what is `missing` and one `example` of a valid value that is never a value you sent. Fix every repair, then call `tellagen_complete_investigation` again with the same arguments.
18
18
 
19
+ ## The time window of the run
20
+
21
+ When Tellagen lists `investigation_window_v1` (this server always advertises it at pickup), the pickup bundle has `request.context.window`, and the server puts a `mcp_window` note at the top of the answer. It has a `from`, a `to` (left out for an open incident, which means until the run ends), a `basis` and a `baseline_from`. The window is stored when the run is created, so it does not change while you work.
22
+
23
+ - **Search for the cause inside the window.** Every query that looks for what went wrong uses a range between `from` and `to`. `tellagen_build_source_link` and `tellagen_build_figure` (a `log_lines` figure) use the window as their range when you send none, and tell you so in `range` and `notes`. If your query ran over another range, send `from` and `to`.
24
+ - **Use the baseline only for counts.** The baseline is the stretch before `from`. Read it 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.
25
+ - **When the signal starts outside the window, do not search outside it.** Send `window_suggestion` `{from, to, reason}` with `tellagen_complete_investigation` (it is a field of `result_summary`), and say so in a finding. The reason has at most 200 characters and names the first signal you found, for example: The first 502s are at 22:14, 2 hours before the window starts. `to` is left out for an incident that is still open. A window is at most 30 days. A person applies the suggestion; it never changes your run, and it never sets or proposes a root cause.
26
+ - Tellagen warns with `evidence_outside_window` when a cited source has a range that reaches outside the window and its baseline together. A count over the baseline does not warn.
27
+
19
28
  ## A lead from a past incident
20
29
 
21
30
  When Tellagen finds a past incident that looks like this one and whose cause a person accepted, the pickup bundle has `request.context.suspected_cause_hints` (and the server adds `mcp_cause_lead`). Each hint has the past incident (`source_incident_id`, `source_title`), the accepted `cause_claim`, optionally the `fix`, the runbook step that supported it and `reasons` (`same_alert`, `same_service`, `same_cause`, `similar_words`, `linked`).
@@ -37,7 +46,7 @@ A client hook (`npx @tellagen/mcp-server trace-hook`) can record each Grafana or
37
46
 
38
47
  Tellagen is an incident investigation platform. Your role is to act as an on-call AI investigator: read incidents, gather evidence from observability and source control systems, post structured findings, and promote key findings to the incident timeline so human responders see them in the war room.
39
48
 
40
- ## Tools available (50 total)
49
+ ## Tools available (51 total)
41
50
 
42
51
  The tools are in five toolsets. `diagnosis` and `incidents` are listed at the start. Call `tellagen_enable_toolset` with `timeline`, `postmortem`, `settings` or `all` to list the others: the timeline readers and editors and `tellagen_promote_finding` are in `timeline`, the postmortem tools in `postmortem`, and the datasource probe, the tool check tools, `tellagen_list_trace_steps`, `tellagen_list_runbooks`, `tellagen_list_investigation_runbook_waivers` and `tellagen_update_investigation_scope` in `settings`.
43
52
 
@@ -112,13 +121,14 @@ The run ID is optional on every run tool. After `tellagen_pick_up_investigation`
112
121
  | `tellagen_get_service` | GET | Read one service and its metadata |
113
122
  | `tellagen_probe_datasource` | GET | Probe a registered metadata-only datasource using local credentials without returning secrets |
114
123
  | `tellagen_build_source_link` | GET | Turn a Grafana, GitHub (commit, compare, pull request, Actions run or job, release) or Kubernetes reference into `links[]` (or a copyable `command`) for an evidence ref; calls only the Tellagen API |
115
- | `tellagen_build_figure` | — | Turn numbers you read from a tool result into a figure Tellagen draws (stats, compare, trend, table, checks, changes, range_overlap, histogram, run_history, diff) and check it against Tellagen's limits; no network call. Read `resource://tellagen/figure-guide` |
124
+ | `tellagen_build_figure` | — | Turn numbers you read from a tool result into a figure Tellagen draws (stats, compare, trend, table, checks, changes, range_overlap, histogram, run_history, diff, log_lines) and check it against Tellagen's limits; no network call. Read `resource://tellagen/figure-guide` |
116
125
 
117
126
  ### MCP diagnostics
118
127
  | Tool | Method | What it does |
119
128
  |------|--------|-------------|
120
129
  | `tellagen_get_diagnostic_session` | GET | Read a `diag_*` MCP diagnostic session created from Settings → Local diagnosis (For admins, Check MCP tools) |
121
130
  | `tellagen_report_diagnostic_tools` | POST | Post sanitized MCP tool availability and access reports for a diagnostic session |
131
+ | `tellagen_report_available_sources` | POST | Tell Tellagen which data sources this client can reach, with no `diag_` ID and no run (the tools table in Settings updates for this client) |
122
132
 
123
133
  ## MCP diagnostic lifecycle
124
134
 
@@ -144,6 +154,20 @@ Report statuses:
144
154
 
145
155
  Never include secrets, tokens, cookies, kubeconfig contents, local filesystem paths, or raw provider response bodies in diagnostic reports. Keep `checks[].summary` short and sanitized.
146
156
 
157
+ ### Kubernetes safety check
158
+
159
+ When the tool is kubernetes, add this step. With the same kubeconfig and context the Kubernetes MCP server uses, run four `kubectl auth can-i` tests: `create pods`, `delete pods`, `create pods/exec` and `get secrets`. Print no output and no names. Report each as a check with a stable id: `k8s_can_create_pods`, `k8s_can_delete_pods`, `k8s_can_exec`, `k8s_can_read_secrets`. The status is `ok` when the answer is no, `failed` when it is yes, and `warning` or `not_checked` when the command could not run. The commands read access rules and change nothing. Keep the summary to one sentence.
160
+
161
+ The result says what the identity could do, not what a model will do. A session that is not listened has no guard on its commands, so never call it read-only. A pickup sends only found or not_found, so it cannot carry this check.
162
+
163
+ ### Recheck from the client
164
+
165
+ For a recheck with no `diag_` ID, call `tellagen_enable_toolset` with `settings`, look at the MCP servers and shell tools you have, map them to `grafana`, `kubernetes`, `github`, `docs` and `local_host`, and call `tellagen_report_available_sources` with each as `found` or `not_found` (and `kubernetes_checks` when you ran the safety check). For each tool that is not found, say in one sentence why this client cannot see it. Never print tokens, paths or raw output.
166
+
167
+ ### Find out why a tool is not found (a person runs it)
168
+
169
+ `npx @tellagen/mcp-server doctor [--client claude-code|claude-desktop|codex|cursor] [--tool grafana|kubernetes|github|docs] [--fix] [--report]` reads the MCP config files of the clients on this computer (only because the person ran it), checks that each Grafana, Kubernetes, GitHub or documentation server can be started from the PATH that client uses, has its settings (names only) and, for Grafana, answers `/api/health` with no token. It prints one sentence for each problem. `--fix` prints a corrected entry and stops. `--report` posts names and statuses to Tellagen. It cannot see a running session: the model check above is still the truth for a session.
170
+
147
171
  ## Investigation lifecycle
148
172
 
149
173
  Every investigation follows this sequence. Do not skip steps.
@@ -339,6 +363,9 @@ Optional:
339
363
  | `evidence_refs` | array | Sources consulted (see below) |
340
364
  | `role` | enum | `confirms`, `supports`, `contradicts`, or `gap`. Send `contradicts` on a `negative` finding and `gap` on a `gap` finding. Without a role Tellagen stores `supports` |
341
365
  | `screenshots` | array | Standalone screenshots for this finding |
366
+ | `checks` | array | A `gap` finding only: one to three yes or no checks, each `{source, question}` (see below). Sent only when Tellagen lists `question_checks_v1` |
367
+
368
+ **A blocking gap is a few yes or no checks.** When a gap blocks the diagnosis, keep `claim` as the one question and add one to three `checks`. Each check is one yes or no question that ends with a question mark (at most 200 characters, never two questions joined by "and"), and `source` names the place where the person looks (at most 120 characters), for example Slack or the Tellagen workspace. Ask only what you could not check yourself; what you already checked goes in `evidence_summary`. Do not ask a person to judge a theory: a check is a fact they can read off a page in a minute. A person answers yes, no or not sure to each check, and while your run is working the answers reach you as a responder note. Treat not sure as no information, never as a yes or a no. Good: claim "Can the Tellagen bot post in Slack channel C0A8FBWB199?" with the checks {"source": "Slack", "question": "Is the Tellagen bot a member of channel C0A8FBWB199?"} and {"source": "Tellagen workspace", "question": "Is that channel linked to an incident of company 5?"}. Bad: one claim that asks whether the channel is linked and the bot is a member, and a check with no source. A check can never set or propose a root cause. Against a Tellagen without `question_checks_v1` the MCP leaves `checks` out and says so in `mcp_notice`.
342
369
 
343
370
  ### Evidence refs
344
371
 
@@ -518,9 +545,10 @@ Tellagen accepts any text. A headline over 15 words gets the warning `headline_t
518
545
  | Two to four ranges that meet | `range_overlap` | `rows` of `{label, from, to}` in one `unit`; optional `min` and `max`. Tellagen computes the overlap; never send it |
519
546
  | A distribution before and after | `histogram` | `edges` (3 to 61, increasing) and one count per bucket in `before` and `after`. The builder takes Prometheus cumulative `le` buckets as `buckets`. Tellagen computes the percentiles; never send them |
520
547
  | CI builds, jobs or deploys in order | `run_history` | `runs` oldest first (2 to 30) with `ref` and `result`, `marks` for the regression and the fix between two neighbouring runs. The builder takes the GitHub Actions run list as `github_runs` |
548
+ | The log lines that prove it, or the proof that there are none | `log_lines` | Needs `log_lines_v1`. Built from a Loki result: at most 8 `lines` (time, level, text, up to 6 fields, a `relation`), `matched` of `scanned`, and the `source` range. See "Log lines" below |
521
549
  | The lines that broke or fixed it | `diff` | `path`, `ref`, `additions` and `deletions` of the whole change, every changed line of a change up to 12 lines (at most 6 hunks) in `hunks`, each removed line next to the line that replaced it. The builder takes a file's `patch` |
522
550
 
523
- `table` and `changes` are timeline blocks only, never a step figure. Every number comes from a tool result you can cite. If you do not have the number, leave the `figure` out. A figure is at most 16 KB. Put the unit in `unit`, not in the number. Never set `example`: that flag is for demo data. A Tellagen that does not know a figure type yet drops the figure and says so in `warnings` (`figure_invalid`).
551
+ `table` and `changes` are timeline blocks only, never a step figure. Every number comes from a tool result you can cite. If you do not have the number, leave the `figure` out. A figure is at most 16 KB (48 KB for a `log_lines` figure). Put the unit in `unit`, not in the number. Never set `example`: that flag is for demo data. A Tellagen that does not know a figure type yet drops the figure and says so in `warnings` (`figure_invalid`).
524
552
 
525
553
  **Ruled out: `ruled_out`** (up to 5). `{label, explanation, finding_ids, links, confidence_percent}` for each cause you checked and excluded, taken from your `negative` findings.
526
554
 
@@ -612,6 +640,12 @@ Build each one with `tellagen_build_figure` (placement `step_figure`, or `timeli
612
640
 
613
641
  **`stats`: the few numbers that matter.** Aim for four or fewer: the first four are tiles in one row, so put the total first and give a tone only to the exception. A source name belongs in a source chip, not in a caption. When `server_capabilities` in the pickup lists `figure_extras_v1` you may add a `title` of up to 80 characters that names the tiles (for example "Tests of the run") and send up to eight items; items five to eight are drawn as plain rows. From a test summary, put the total first, then passed, failed and skipped. Without `figure_extras_v1` the MCP drops the title and every item after the fourth and says so in `mcp_notice`, because an older Tellagen drops a figure that carries them. Pass the `run_id` to `tellagen_build_figure`.
614
642
 
643
+ **`log_lines`: the log lines that prove it, or the proof that there are none.** Use it for log evidence instead of a `stats` tile: the reader reads the lines themselves. It needs `log_lines_v1` in `server_capabilities` (pass the `run_id`; without it the builder refuses and says to use a `checks` figure and the finding instead). Run the Loki query inside the run window and send the whole result to `tellagen_build_figure` as `streams` (the Loki result as returned, or its whole response body) or as `entries` (`[{timestamp, line, labels}]`), with `query`, `datasource`, `from` and `to`.
644
+ - The builder keeps at most 8 lines, the ones that show the event first, then the lines you marked `unrelated`, then the rest with errors first. It reads each level from a stream label, from the JSON or logfmt of the line, or from a word at its start. The text stays as logged; only colour codes and secrets are removed, line breaks become a mark and a text over 500 characters is cut. It never writes a line you did not read in the result.
645
+ - `matched` is how many lines the query matched in the range. It defaults to the lines you sent, so send `matched` when the query had a limit; the builder works out `lines_not_shown`. `scanned` is how many lines the query looked at (`query_loki_stats` returns it). Set `event_at` to the moment of the event.
646
+ - **Mark what is not proof.** List terms that show the event in `match` (those lines become `matches_event`). Mark a line of another tenant, company or request as `unrelated`, with a note that says why, in `marks`: `{"field": {"key": "company_id", "value": "578"}, "relation": "unrelated", "note": "Company 578, 11 hours after the event"}`, or `{"contains": "...", ...}`. A line that looks like proof and is not is the one to mark, never to leave out. **Never use the text of an unrelated line as the quote of a finding.**
647
+ - **A query that found nothing is proof only with its range.** Send `streams` as an empty list, `scanned` and the range (`from` and `to`): 0 of 2,313 lines from 00:26 to 01:26 says something; an empty list with no range does not.
648
+
615
649
  **`run_history`: which build broke and which fixed it.** Send the output of `gh run list` (or the GitHub Actions run list) as `github_runs`. The builder maps each run: `#<run number>` as the ref, the head sha, the start time, the event, the run page, and the conclusion as the result (`cancelled` stays `cancelled`; `timed_out` and `startup_failure` count as `failure`). A run that is skipped, neutral, stale or action_required has no result: leave it out. Runs are put oldest first; send 2 to 30. Add `job` (the failing job's name, from `gh run view <run id> --json jobs`) to the failing runs. If the history has more than 30 runs, send the 30 that matter (the runs around the break and the fix, oldest first) and set `runs_not_shown` to how many you left out; the strip then says "N more runs not shown." (`figure_extras_v1` only, otherwise the MCP drops it). Add up to 4 `marks`: `change_ref` is `regression` or `fix`, with the `sha` of the change (the mark goes before the first run built from it) or `between` with the refs of the two neighbouring runs. Set `repo` to `owner/name` so each run links to its page, and an optional `span` such as `{"from": "#4151", "to": "#4163", "label": "E2E Tests failed"}`.
616
650
 
617
651
  ```json
@@ -849,6 +883,9 @@ Then immediately start investigating it.
849
883
  - **Stopping at a failed link.** If `tellagen_build_source_link` fails, send a read-only `command` and the `datasource` on the evidence ref.
850
884
  - **Proofs with no source.** An evidence ref for Grafana or GitHub with no `links`, or a Kubernetes check with no `command`, shows "No source link" to responders. Call `tellagen_build_source_link`; do not paste a hand-built address.
851
885
  - **Citing keys instead of ids.** `finding_ids` are the numeric ids `tellagen_post_finding` returned. Keys, claims or titles are dropped.
886
+ - **Searching outside the window.** Look for the cause between the window's `from` and `to`. Use the baseline only for counts. When the signal starts outside, send `window_suggestion`.
887
+ - **A compound blocking question.** Write a blocking gap as one to three yes or no `checks`, each naming its source, never one question joined with "and".
888
+ - **A stats tile for log evidence.** Prefer a `log_lines` figure: it shows the lines. Quote only a line that is not marked `unrelated`.
852
889
  - **Inventing a figure.** A figure with a number you did not read from a tool result is worse than no figure.
853
890
  - **A chain with one step per finding.** Keep the chain to 2 to 4 steps that tell the story; put the rest in the evidence ledger as context findings.
854
891
  - **Hiding gaps.** A source you could not read belongs in `coverage` with state `gap` and in a `gap` finding, not in silence.
@@ -9,6 +9,8 @@
9
9
  "finding_roles_v2",
10
10
  "gap_findings_v2",
11
11
  "guidance_default_v1",
12
+ "investigation_window_v1",
13
+ "question_checks_v1",
12
14
  "responder_notes_v1",
13
15
  "run_images_v1",
14
16
  "runbook_plan_v2",
@@ -22,6 +24,8 @@
22
24
  "diagnosis_structure_v1",
23
25
  "diff_lines_v1",
24
26
  "figure_extras_v1",
27
+ "log_lines_v1",
28
+ "question_checks_v1",
25
29
  "recorded_steps_v1",
26
30
  "run_images_v1"
27
31
  ],
@@ -147,9 +151,17 @@
147
151
  {
148
152
  "method": "POST",
149
153
  "path": "/api/v1/incidents/{id}/findings",
150
- "request_fields": ["investigation_run_id", "finding_type", "claim", "evidence_summary", "confidence", "confidence_reason", "evidence_refs"],
154
+ "request_fields": ["investigation_run_id", "finding_type", "claim", "evidence_summary", "confidence", "confidence_reason", "evidence_refs", "checks", "checks.source", "checks.question"],
151
155
  "response_fields": [],
152
156
  "error_codes": ["run_taken_over", "investigation_run_ended"]
157
+ },
158
+ {
159
+ "method": "POST",
160
+ "path": "/api/v1/settings/agent/tool-report",
161
+ "since_bundle": "2026-11-15.1",
162
+ "request_fields": ["available_sources", "profile_id"],
163
+ "response_fields": ["accepted_sources", "ignored_sources"],
164
+ "error_codes": []
153
165
  }
154
166
  ]
155
167
  }
@@ -1,6 +1,6 @@
1
1
  {
2
- "contract_version": "2026-11-12.4",
3
- "bundle_sha256": "be6b865611486f0643b93475e12f5aa110baeedb2b40e8e1c577f5af90951e70",
2
+ "contract_version": "2026-11-15.2",
3
+ "bundle_sha256": "2b938382ff9164ec69435795c60c7a56d5dd13e61dc5bdd7e7cf67461b47df61",
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": "65fd7731653370816489c6ffea7925a765e01440cd14d4a72042a649b06c5d7e",
14
+ "bytes": 27974
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",
@@ -40,14 +40,24 @@
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
63
  "sha256": "8d9372a00de80e4326205e0fbdb50269005dffc8f54ad594ec259ea03071cde4",
@@ -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": "3026b10055809bd0dd7aa219e2b89a07190822e1d27861d6cc1eb839478261ec",
74
+ "bytes": 31084
65
75
  }
66
76
  ]
67
77
  }
@@ -9,6 +9,8 @@
9
9
  "diagnosis_structure_v1",
10
10
  "diff_lines_v1",
11
11
  "figure_extras_v1",
12
+ "log_lines_v1",
13
+ "question_checks_v1",
12
14
  "recorded_steps_v1",
13
15
  "responder_notes_v1",
14
16
  "run_images_v1"
@@ -21,10 +23,13 @@
21
23
  "finding_roles_v2",
22
24
  "gap_findings_v2",
23
25
  "guidance_default_v1",
26
+ "investigation_window_v1",
27
+ "question_checks_v1",
24
28
  "responder_notes_v1",
25
29
  "run_images_v1",
26
30
  "runbook_plan_v2",
27
31
  "strict_fields_v1",
32
+ "tool_check_v1",
28
33
  "trace_check_id_v2"
29
34
  ],
30
35
  "client_headers": [
@@ -39,9 +44,11 @@
39
44
  "client_upgrade_required",
40
45
  "denied",
41
46
  "expired",
47
+ "finding_checks_invalid",
42
48
  "invalid_device_code",
43
49
  "invalid_field_type",
44
50
  "invalid_idempotency_key",
51
+ "invalid_window",
45
52
  "investigation_completion_blocked",
46
53
  "investigation_executor_conflict",
47
54
  "investigation_run_ended",
@@ -147,6 +154,9 @@
147
154
  "method": "POST",
148
155
  "path": "/api/v1/incidents/{id}/findings",
149
156
  "request_fields": [
157
+ "checks",
158
+ "checks.question",
159
+ "checks.source",
150
160
  "claim",
151
161
  "confidence",
152
162
  "confidence_reason",
@@ -186,6 +196,8 @@
186
196
  ],
187
197
  "response_fields": [
188
198
  "finding",
199
+ "finding.answers",
200
+ "finding.checks",
189
201
  "finding.claim",
190
202
  "finding.confidence",
191
203
  "finding.confidence_reason",
@@ -234,6 +246,12 @@
234
246
  "proxy_id",
235
247
  "question",
236
248
  "question_finding_id",
249
+ "window",
250
+ "window.baseline_days",
251
+ "window.from",
252
+ "window.from_expr",
253
+ "window.to",
254
+ "window.to_expr",
237
255
  "without_grafana"
238
256
  ],
239
257
  "response_fields": [
@@ -291,7 +309,8 @@
291
309
  "run.question_finding_id",
292
310
  "run.result_summary",
293
311
  "run.started_at",
294
- "run.status"
312
+ "run.status",
313
+ "run.window"
295
314
  ]
296
315
  },
297
316
  {
@@ -578,7 +597,11 @@
578
597
  "runs.requested_by",
579
598
  "runs.requested_by_me",
580
599
  "runs.run_id",
581
- "runs.screenshot_count"
600
+ "runs.screenshot_count",
601
+ "tool_check",
602
+ "tool_check.client",
603
+ "tool_check.expires_at",
604
+ "tool_check.id"
582
605
  ]
583
606
  },
584
607
  {
@@ -607,6 +630,7 @@
607
630
  "result_summary.signals_checked",
608
631
  "result_summary.takeaways",
609
632
  "result_summary.unknowns",
633
+ "result_summary.window_suggestion",
610
634
  "status"
611
635
  ],
612
636
  "response_fields": [
@@ -678,6 +702,7 @@
678
702
  "run.result_summary",
679
703
  "run.started_at",
680
704
  "run.status",
705
+ "run.window",
681
706
  "run_state",
682
707
  "warnings",
683
708
  "warnings.code",
@@ -721,6 +746,7 @@
721
746
  "incident.last_event_at",
722
747
  "incident.last_event_summary",
723
748
  "incident.meet_url",
749
+ "incident.origin",
724
750
  "incident.postmortem_summary",
725
751
  "incident.recovered_at",
726
752
  "incident.regions",
@@ -787,9 +813,11 @@
787
813
  "run.result_summary",
788
814
  "run.started_at",
789
815
  "run.status",
816
+ "run.window",
790
817
  "server_capabilities",
791
818
  "source_bases",
792
819
  "source_bases.base_url",
820
+ "source_bases.datasources",
793
821
  "source_bases.kind",
794
822
  "source_bases.name",
795
823
  "source_bases.network",
@@ -847,6 +875,7 @@
847
875
  "incident.last_event_at",
848
876
  "incident.last_event_summary",
849
877
  "incident.meet_url",
878
+ "incident.origin",
850
879
  "incident.postmortem_summary",
851
880
  "incident.recovered_at",
852
881
  "incident.regions",
@@ -913,14 +942,42 @@
913
942
  "run.result_summary",
914
943
  "run.started_at",
915
944
  "run.status",
945
+ "run.window",
916
946
  "server_capabilities",
917
947
  "source_bases",
918
948
  "source_bases.base_url",
949
+ "source_bases.datasources",
919
950
  "source_bases.kind",
920
951
  "source_bases.name",
921
952
  "source_bases.network",
922
953
  "source_bases.repositories"
923
954
  ]
955
+ },
956
+ {
957
+ "method": "POST",
958
+ "path": "/api/v1/settings/agent/tool-report",
959
+ "request_fields": [
960
+ "available_sources",
961
+ "available_sources.access_status",
962
+ "available_sources.detail",
963
+ "available_sources.key",
964
+ "available_sources.state",
965
+ "kubernetes_checks",
966
+ "kubernetes_checks.id",
967
+ "kubernetes_checks.status",
968
+ "kubernetes_checks.summary",
969
+ "profile_id"
970
+ ],
971
+ "response_fields": [
972
+ "accepted_sources",
973
+ "accepted_sources.detail",
974
+ "accepted_sources.key",
975
+ "accepted_sources.state",
976
+ "client",
977
+ "ignored_sources",
978
+ "profile_id",
979
+ "recorded_at"
980
+ ]
924
981
  }
925
982
  ]
926
983
  }
@@ -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
  }
@@ -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
+ }