@tellagen/mcp-server 0.1.3 → 0.4.1
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 +208 -12
- package/SKILL.md +395 -15
- package/contracts/runbooks/manifest.json +47 -0
- package/contracts/runbooks/v1/fixtures/global-runbook.json +7 -0
- package/contracts/runbooks/v1/runbook-definition.schema.json +25 -0
- package/contracts/runbooks/v2/compiled-plan.schema.json +40 -0
- package/contracts/runbooks/v2/fixtures/filesystem-pressure.json +181 -0
- package/contracts/runbooks/v2/fixtures/grafana-error-rate-plan.json +50 -0
- package/contracts/runbooks/v2/fixtures/grafana-error-rate.json +58 -0
- package/contracts/runbooks/v2/fixtures/timeline-event-blocks-rejected.json +90 -0
- package/contracts/runbooks/v2/fixtures/timeline-event-with-blocks.json +61 -0
- package/contracts/runbooks/v2/runbook-definition.schema.json +377 -0
- package/contracts/runbooks/v2/timeline-event-blocks.schema.json +480 -0
- package/contracts/tellagen-runbook-contracts.json +8 -0
- package/dist/auth.d.ts +2 -1
- package/dist/auth.js +2 -1
- package/dist/auth.js.map +1 -1
- package/dist/client.d.ts +20 -0
- package/dist/client.js +81 -12
- package/dist/client.js.map +1 -1
- package/dist/diagnosis-structure.d.ts +1416 -0
- package/dist/diagnosis-structure.js +656 -0
- package/dist/diagnosis-structure.js.map +1 -0
- package/dist/errors.d.ts +2 -1
- package/dist/errors.js +4 -1
- package/dist/errors.js.map +1 -1
- package/dist/figures.d.ts +2336 -0
- package/dist/figures.js +1288 -0
- package/dist/figures.js.map +1 -0
- package/dist/image-info.d.ts +14 -0
- package/dist/image-info.js +65 -0
- package/dist/image-info.js.map +1 -0
- package/dist/index.js +2 -6
- package/dist/index.js.map +1 -1
- package/dist/server.js +66 -7
- package/dist/server.js.map +1 -1
- package/dist/source-links.d.ts +101 -0
- package/dist/source-links.js +374 -0
- package/dist/source-links.js.map +1 -0
- package/dist/start.d.ts +11 -0
- package/dist/start.js +14 -0
- package/dist/start.js.map +1 -0
- package/dist/tools/attachments.d.ts +19 -0
- package/dist/tools/attachments.js +177 -0
- package/dist/tools/attachments.js.map +1 -0
- package/dist/tools/causes.d.ts +50 -0
- package/dist/tools/causes.js +97 -0
- package/dist/tools/causes.js.map +1 -0
- package/dist/tools/datasources.d.ts +3 -0
- package/dist/tools/datasources.js +325 -0
- package/dist/tools/datasources.js.map +1 -0
- package/dist/tools/diagnostics.d.ts +3 -0
- package/dist/tools/diagnostics.js +113 -0
- package/dist/tools/diagnostics.js.map +1 -0
- package/dist/tools/figures.d.ts +8 -0
- package/dist/tools/figures.js +209 -0
- package/dist/tools/figures.js.map +1 -0
- package/dist/tools/findings.js +85 -7
- package/dist/tools/findings.js.map +1 -1
- package/dist/tools/incidents.js +44 -4
- package/dist/tools/incidents.js.map +1 -1
- package/dist/tools/index.js +14 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/investigations.js +546 -21
- package/dist/tools/investigations.js.map +1 -1
- package/dist/tools/postmortem-runbooks.d.ts +786 -0
- package/dist/tools/postmortem-runbooks.js +330 -0
- package/dist/tools/postmortem-runbooks.js.map +1 -0
- package/dist/tools/source-links.d.ts +47 -0
- package/dist/tools/source-links.js +302 -0
- package/dist/tools/source-links.js.map +1 -0
- package/dist/tools/timeline.js +178 -13
- package/dist/tools/timeline.js.map +1 -1
- package/dist/version.d.ts +2 -0
- package/dist/version.js +12 -0
- package/dist/version.js.map +1 -0
- package/package.json +3 -2
- package/server.json +15 -1
|
@@ -0,0 +1,656 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Diagnosis structure (diagnosis_structure_v1).
|
|
3
|
+
*
|
|
4
|
+
* A newer Tellagen backend accepts richer evidence refs (links, command,
|
|
5
|
+
* datasource), a causal chain with finding ids and a figure per step, ruled
|
|
6
|
+
* out / coverage / unknowns, and a trace step outcome. An older backend
|
|
7
|
+
* decodes request bodies leniently and silently drops fields it does not know,
|
|
8
|
+
* so the agent could not tell. The rule is therefore:
|
|
9
|
+
*
|
|
10
|
+
* - the MCP always advertises the capability in `protocol_capabilities`
|
|
11
|
+
* (src/version.ts), and
|
|
12
|
+
* - it sends the new fields only for a run whose pickup / context response
|
|
13
|
+
* lists the capability in the top-level `server_capabilities`.
|
|
14
|
+
*
|
|
15
|
+
* Zod objects below are not strict, so every new field needs an explicit
|
|
16
|
+
* entry or it is stripped before the request leaves.
|
|
17
|
+
*/
|
|
18
|
+
import { z } from "zod";
|
|
19
|
+
import { checksBlockSchema, diffBlockSchema, figureRuleIssues, histogramBlockSchema, MAX_STEP_FIGURE_BYTES, rangeOverlapBlockSchema, runHistoryBlockSchema, } from "./figures.js";
|
|
20
|
+
export const DIAGNOSIS_STRUCTURE_CAPABILITY = "diagnosis_structure_v1";
|
|
21
|
+
/** change_refs on the result and the ci_run, deployment and release link kinds. */
|
|
22
|
+
export const DIAGNOSIS_CHANGES_CAPABILITY = "diagnosis_changes_v1";
|
|
23
|
+
/** The client reads a run's screenshots with tellagen_get_context_attachment. */
|
|
24
|
+
export const RUN_IMAGES_CAPABILITY = "run_images_v1";
|
|
25
|
+
/* ------------------------------------------------------------------ */
|
|
26
|
+
/* Capability negotiation */
|
|
27
|
+
/* ------------------------------------------------------------------ */
|
|
28
|
+
const capabilityByClient = new WeakMap();
|
|
29
|
+
function capabilityMap(client) {
|
|
30
|
+
let map = capabilityByClient.get(client);
|
|
31
|
+
if (!map) {
|
|
32
|
+
map = new Map();
|
|
33
|
+
capabilityByClient.set(client, map);
|
|
34
|
+
}
|
|
35
|
+
return map;
|
|
36
|
+
}
|
|
37
|
+
function isRecord(value) {
|
|
38
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Remembers the capabilities the backend that answered a pickup or context
|
|
42
|
+
* call for `runId` advertises. A missing `server_capabilities` is a definite
|
|
43
|
+
* "none": the backend predates the field.
|
|
44
|
+
*/
|
|
45
|
+
export function rememberServerCapabilities(client, runId, response) {
|
|
46
|
+
if (!isRecord(response))
|
|
47
|
+
return;
|
|
48
|
+
const list = response.server_capabilities;
|
|
49
|
+
const advertised = new Set(Array.isArray(list) ? list.filter((item) => typeof item === "string") : []);
|
|
50
|
+
capabilityMap(client).set(runId, advertised);
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Whether the backend accepts a capability for this run. Uses what pickup or
|
|
54
|
+
* context told us in this process; otherwise reads the run context once (a
|
|
55
|
+
* resumed run picked up by another process). A failed lookup counts as "not
|
|
56
|
+
* supported" for this call and is retried on the next one.
|
|
57
|
+
*/
|
|
58
|
+
export async function supportsCapability(client, runId, capability) {
|
|
59
|
+
const map = capabilityMap(client);
|
|
60
|
+
const known = map.get(runId);
|
|
61
|
+
if (known !== undefined)
|
|
62
|
+
return known.has(capability);
|
|
63
|
+
try {
|
|
64
|
+
const context = await client.get(`/api/v1/investigations/${encodeURIComponent(runId)}/context`);
|
|
65
|
+
rememberServerCapabilities(client, runId, context);
|
|
66
|
+
return map.get(runId)?.has(capability) ?? false;
|
|
67
|
+
}
|
|
68
|
+
catch {
|
|
69
|
+
return false;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
/** Whether the backend accepts the diagnosis structure for this run. */
|
|
73
|
+
export async function supportsDiagnosisStructure(client, runId) {
|
|
74
|
+
return supportsCapability(client, runId, DIAGNOSIS_STRUCTURE_CAPABILITY);
|
|
75
|
+
}
|
|
76
|
+
/** Whether the backend accepts change_refs and the change link kinds for this run. */
|
|
77
|
+
export async function supportsDiagnosisChanges(client, runId) {
|
|
78
|
+
return supportsCapability(client, runId, DIAGNOSIS_CHANGES_CAPABILITY);
|
|
79
|
+
}
|
|
80
|
+
/* ------------------------------------------------------------------ */
|
|
81
|
+
/* Evidence ref additions */
|
|
82
|
+
/* ------------------------------------------------------------------ */
|
|
83
|
+
/** Link kinds a backend without diagnosis_changes_v1 does not know. */
|
|
84
|
+
export const CHANGE_LINK_KINDS = ["ci_run", "deployment", "release"];
|
|
85
|
+
export const EVIDENCE_LINK_KINDS = [
|
|
86
|
+
"explore",
|
|
87
|
+
"panel",
|
|
88
|
+
"diff",
|
|
89
|
+
"commit",
|
|
90
|
+
"pr",
|
|
91
|
+
"logs",
|
|
92
|
+
"trace",
|
|
93
|
+
...CHANGE_LINK_KINDS,
|
|
94
|
+
];
|
|
95
|
+
export const evidenceLinkSchema = z.object({
|
|
96
|
+
kind: z
|
|
97
|
+
.enum(EVIDENCE_LINK_KINDS)
|
|
98
|
+
.describe("What the link opens: explore, panel, diff, commit, pr, logs, trace, ci_run (a CI run or job page), deployment or release"),
|
|
99
|
+
label: z
|
|
100
|
+
.string()
|
|
101
|
+
.trim()
|
|
102
|
+
.min(1)
|
|
103
|
+
.max(60)
|
|
104
|
+
.describe("Short text for the link, up to 60 characters"),
|
|
105
|
+
url: z
|
|
106
|
+
.string()
|
|
107
|
+
.trim()
|
|
108
|
+
.min(1)
|
|
109
|
+
.max(2048)
|
|
110
|
+
.refine((value) => {
|
|
111
|
+
try {
|
|
112
|
+
const protocol = new URL(value).protocol;
|
|
113
|
+
return protocol === "http:" || protocol === "https:";
|
|
114
|
+
}
|
|
115
|
+
catch {
|
|
116
|
+
return false;
|
|
117
|
+
}
|
|
118
|
+
}, { message: "must be an http or https address" })
|
|
119
|
+
.describe("http or https address, without credentials"),
|
|
120
|
+
});
|
|
121
|
+
export const evidenceLinksSchema = z
|
|
122
|
+
.array(evidenceLinkSchema)
|
|
123
|
+
.max(4)
|
|
124
|
+
.describe("Clickable sources for this evidence, at most 4. Build Grafana and GitHub links with tellagen_build_source_link and copy its links[] here unchanged. Leave it out when you have no real address.");
|
|
125
|
+
/** Fields added to every evidence ref by diagnosis_structure_v1. */
|
|
126
|
+
export const evidenceRefStructureShape = {
|
|
127
|
+
links: evidenceLinksSchema.optional(),
|
|
128
|
+
command: z
|
|
129
|
+
.string()
|
|
130
|
+
.max(1000)
|
|
131
|
+
.optional()
|
|
132
|
+
.describe("A copyable, read-only command that reproduces this evidence (for example a kubectl get or logs command), up to 1000 characters. Use it for Kubernetes and other local sources that have no browser link. Never include credentials; Tellagen redacts them and drops a longer command."),
|
|
133
|
+
datasource: z
|
|
134
|
+
.string()
|
|
135
|
+
.max(120)
|
|
136
|
+
.optional()
|
|
137
|
+
.describe("Name of the data source the evidence came from (for example the Grafana data source name or uid)"),
|
|
138
|
+
};
|
|
139
|
+
const EVIDENCE_REF_STRUCTURE_FIELDS = ["links", "command", "datasource"];
|
|
140
|
+
/* ------------------------------------------------------------------ */
|
|
141
|
+
/* Step figure: one timeline block of a figure type */
|
|
142
|
+
/* ------------------------------------------------------------------ */
|
|
143
|
+
const control = /[\u0000-\u001f\u007f]/;
|
|
144
|
+
function line(min, max) {
|
|
145
|
+
return z
|
|
146
|
+
.string()
|
|
147
|
+
.trim()
|
|
148
|
+
.min(min)
|
|
149
|
+
.max(max)
|
|
150
|
+
.refine((value) => !control.test(value), {
|
|
151
|
+
message: "must be one line without control characters",
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
const blockNumber = z.number().finite().min(-1e12).max(1e12);
|
|
155
|
+
const positiveBlockNumber = z.number().finite().gt(0).max(1e12);
|
|
156
|
+
const blockCommon = {
|
|
157
|
+
slot: z.literal("summary").optional(),
|
|
158
|
+
anchor: line(0, 80).optional(),
|
|
159
|
+
postmortem: z.boolean().optional(),
|
|
160
|
+
};
|
|
161
|
+
const blockThreshold = z
|
|
162
|
+
.object({ value: blockNumber, label: line(0, 80).optional() })
|
|
163
|
+
.strict();
|
|
164
|
+
const statsFigure = z
|
|
165
|
+
.object({
|
|
166
|
+
type: z.literal("stats"),
|
|
167
|
+
...blockCommon,
|
|
168
|
+
items: z
|
|
169
|
+
.array(z
|
|
170
|
+
.object({
|
|
171
|
+
label: line(1, 48),
|
|
172
|
+
value: line(1, 32),
|
|
173
|
+
caption: line(0, 64).optional(),
|
|
174
|
+
tone: z.enum(["good", "warn", "bad", "neutral"]).optional(),
|
|
175
|
+
})
|
|
176
|
+
.strict())
|
|
177
|
+
.min(1)
|
|
178
|
+
.max(4),
|
|
179
|
+
})
|
|
180
|
+
.strict();
|
|
181
|
+
const compareFigure = z
|
|
182
|
+
.object({
|
|
183
|
+
type: z.literal("compare"),
|
|
184
|
+
...blockCommon,
|
|
185
|
+
title: line(0, 80).optional(),
|
|
186
|
+
metric: line(0, 32).optional(),
|
|
187
|
+
unit: line(0, 12).optional(),
|
|
188
|
+
better: z.enum(["lower", "higher"]).optional(),
|
|
189
|
+
delta: z.enum(["rel", "abs"]).optional(),
|
|
190
|
+
max: positiveBlockNumber.optional(),
|
|
191
|
+
threshold: blockThreshold.optional(),
|
|
192
|
+
rows: z
|
|
193
|
+
.array(z
|
|
194
|
+
.object({
|
|
195
|
+
label: line(1, 80),
|
|
196
|
+
mono: z.boolean().optional(),
|
|
197
|
+
before: blockNumber,
|
|
198
|
+
after: blockNumber,
|
|
199
|
+
details: z
|
|
200
|
+
.array(z
|
|
201
|
+
.object({
|
|
202
|
+
label: line(1, 32),
|
|
203
|
+
before: line(1, 32),
|
|
204
|
+
after: line(1, 32),
|
|
205
|
+
})
|
|
206
|
+
.strict())
|
|
207
|
+
.max(3)
|
|
208
|
+
.optional(),
|
|
209
|
+
})
|
|
210
|
+
.strict())
|
|
211
|
+
.min(1)
|
|
212
|
+
.max(8),
|
|
213
|
+
})
|
|
214
|
+
.strict();
|
|
215
|
+
const trendFigure = z
|
|
216
|
+
.object({
|
|
217
|
+
type: z.literal("trend"),
|
|
218
|
+
...blockCommon,
|
|
219
|
+
title: line(0, 80).optional(),
|
|
220
|
+
unit: line(0, 12).optional(),
|
|
221
|
+
series: z.array(blockNumber).min(2).max(500),
|
|
222
|
+
start: z.string().datetime({ offset: true }).optional(),
|
|
223
|
+
step_seconds: z.number().int().min(1).max(86400).optional(),
|
|
224
|
+
max: positiveBlockNumber.optional(),
|
|
225
|
+
threshold: blockThreshold.optional(),
|
|
226
|
+
marks: z
|
|
227
|
+
.array(z
|
|
228
|
+
.object({ i: z.number().int().min(0), label: line(1, 48) })
|
|
229
|
+
.strict())
|
|
230
|
+
.max(3)
|
|
231
|
+
.optional(),
|
|
232
|
+
source: z
|
|
233
|
+
.object({
|
|
234
|
+
kind: line(0, 80).optional(),
|
|
235
|
+
datasource: line(0, 80).optional(),
|
|
236
|
+
// Only source.query may hold line breaks.
|
|
237
|
+
query: z.string().max(2000).optional(),
|
|
238
|
+
from: line(0, 80).optional(),
|
|
239
|
+
to: line(0, 80).optional(),
|
|
240
|
+
step: line(0, 80).optional(),
|
|
241
|
+
artifact_id: line(0, 80).optional(),
|
|
242
|
+
})
|
|
243
|
+
.strict()
|
|
244
|
+
.optional(),
|
|
245
|
+
})
|
|
246
|
+
.strict();
|
|
247
|
+
/** Same size cap as the backend: canonical block JSON, 16 KB. */
|
|
248
|
+
export const MAX_FIGURE_BYTES = MAX_STEP_FIGURE_BYTES;
|
|
249
|
+
/** Figure types the tool listing shows by type only; they are checked in full below. */
|
|
250
|
+
const LISTED_BY_TYPE = ["checks", "range_overlap", "histogram", "run_history", "diff"];
|
|
251
|
+
const fullListedByType = z.discriminatedUnion("type", [
|
|
252
|
+
checksBlockSchema.extend(blockCommon),
|
|
253
|
+
rangeOverlapBlockSchema.extend(blockCommon),
|
|
254
|
+
histogramBlockSchema.extend(blockCommon),
|
|
255
|
+
runHistoryBlockSchema.extend(blockCommon),
|
|
256
|
+
diffBlockSchema.extend(blockCommon),
|
|
257
|
+
]);
|
|
258
|
+
export const stepFigureSchema = z
|
|
259
|
+
.discriminatedUnion("type", [
|
|
260
|
+
statsFigure,
|
|
261
|
+
compareFigure,
|
|
262
|
+
trendFigure,
|
|
263
|
+
// The listing stays small: these carry only their type there, and the
|
|
264
|
+
// refinement below checks every field before the request leaves.
|
|
265
|
+
z
|
|
266
|
+
.object({ type: z.enum(LISTED_BY_TYPE) })
|
|
267
|
+
.passthrough()
|
|
268
|
+
.describe("checks, range_overlap, histogram, run_history or diff: build it with tellagen_build_figure"),
|
|
269
|
+
])
|
|
270
|
+
.superRefine((figure, ctx) => {
|
|
271
|
+
if (LISTED_BY_TYPE.includes(figure.type)) {
|
|
272
|
+
const full = fullListedByType.safeParse(figure);
|
|
273
|
+
if (!full.success) {
|
|
274
|
+
for (const issue of full.error.issues) {
|
|
275
|
+
ctx.addIssue({ code: z.ZodIssueCode.custom, path: issue.path, message: issue.message });
|
|
276
|
+
}
|
|
277
|
+
return;
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
if (figure.slot !== undefined && figure.anchor !== undefined) {
|
|
281
|
+
ctx.addIssue({
|
|
282
|
+
code: z.ZodIssueCode.custom,
|
|
283
|
+
path: ["anchor"],
|
|
284
|
+
message: "send slot or anchor, not both",
|
|
285
|
+
});
|
|
286
|
+
}
|
|
287
|
+
if (figure.type === "trend") {
|
|
288
|
+
if ((figure.start === undefined) !== (figure.step_seconds === undefined)) {
|
|
289
|
+
ctx.addIssue({
|
|
290
|
+
code: z.ZodIssueCode.custom,
|
|
291
|
+
path: [figure.start === undefined ? "start" : "step_seconds"],
|
|
292
|
+
message: "send start and step_seconds together",
|
|
293
|
+
});
|
|
294
|
+
}
|
|
295
|
+
figure.marks?.forEach((mark, index) => {
|
|
296
|
+
if (mark.i >= figure.series.length) {
|
|
297
|
+
ctx.addIssue({
|
|
298
|
+
code: z.ZodIssueCode.custom,
|
|
299
|
+
path: ["marks", index, "i"],
|
|
300
|
+
message: `must be a point index from 0 to ${figure.series.length - 1}`,
|
|
301
|
+
});
|
|
302
|
+
}
|
|
303
|
+
});
|
|
304
|
+
}
|
|
305
|
+
for (const issue of figureRuleIssues(figure)) {
|
|
306
|
+
ctx.addIssue({ code: z.ZodIssueCode.custom, path: issue.path, message: issue.message });
|
|
307
|
+
}
|
|
308
|
+
const bytes = new TextEncoder().encode(JSON.stringify(figure)).length;
|
|
309
|
+
if (bytes > MAX_FIGURE_BYTES) {
|
|
310
|
+
ctx.addIssue({
|
|
311
|
+
code: z.ZodIssueCode.custom,
|
|
312
|
+
message: `figure is ${bytes} bytes; the limit is ${MAX_FIGURE_BYTES}. Reduce a trend to at most 500 points, or send fewer runs or rows`,
|
|
313
|
+
});
|
|
314
|
+
}
|
|
315
|
+
})
|
|
316
|
+
.describe("ONE timeline block object that shows the step's key numbers, validated like a timeline event block. compare = a before and after with an optional threshold; trend = a series over time (give source with the query that produced it); stats = 2 to 4 key numbers; checks = pass or fail per check; range_overlap = two to four ranges that meet; histogram = bucket counts before and after; run_history = CI or deploy runs oldest first with the regression and fix marks; diff = up to 12 changed lines of the change. Build it with tellagen_build_figure (placement step_figure). Never invent a number: every value must come from a tool result.");
|
|
317
|
+
/* ------------------------------------------------------------------ */
|
|
318
|
+
/* Result summary additions */
|
|
319
|
+
/* ------------------------------------------------------------------ */
|
|
320
|
+
const findingIdsSchema = z
|
|
321
|
+
.array(z.number().int().positive())
|
|
322
|
+
.max(12)
|
|
323
|
+
.describe("Numeric ids of this run's findings that prove it, as returned by tellagen_post_finding (up to 12)");
|
|
324
|
+
export const stepStructureShape = {
|
|
325
|
+
finding_ids: findingIdsSchema.optional(),
|
|
326
|
+
figure: stepFigureSchema.optional(),
|
|
327
|
+
links: evidenceLinksSchema.optional(),
|
|
328
|
+
};
|
|
329
|
+
export const ruledOutSchema = z.object({
|
|
330
|
+
id: line(0, 64).optional(),
|
|
331
|
+
label: line(1, 200).describe("The cause that was ruled out, in a few words"),
|
|
332
|
+
explanation: z
|
|
333
|
+
.string()
|
|
334
|
+
.max(600)
|
|
335
|
+
.optional()
|
|
336
|
+
.describe("Why the evidence rules it out"),
|
|
337
|
+
finding_ids: findingIdsSchema.optional(),
|
|
338
|
+
links: evidenceLinksSchema.optional(),
|
|
339
|
+
confidence_percent: z.number().int().min(0).max(100).optional(),
|
|
340
|
+
});
|
|
341
|
+
export const coverageEntrySchema = z.object({
|
|
342
|
+
id: line(0, 64).optional(),
|
|
343
|
+
source: line(1, 80).describe("The data source, for example Grafana, GitHub or Kubernetes"),
|
|
344
|
+
state: z
|
|
345
|
+
.enum(["checked", "gap", "not_configured"])
|
|
346
|
+
.describe("checked = read and used; gap = configured but could not be read or satisfied; not_configured = no such source in this workspace"),
|
|
347
|
+
summary: z.string().max(600).optional(),
|
|
348
|
+
links: evidenceLinksSchema.optional(),
|
|
349
|
+
step_ids: z
|
|
350
|
+
.array(z.string().min(1).max(64))
|
|
351
|
+
.max(12)
|
|
352
|
+
.optional()
|
|
353
|
+
.describe("Ids of the causal_paths steps this source proved"),
|
|
354
|
+
integration_id: z.string().max(64).optional(),
|
|
355
|
+
finding_ids: findingIdsSchema.optional(),
|
|
356
|
+
});
|
|
357
|
+
export const unknownSchema = z.object({
|
|
358
|
+
id: line(0, 64).optional(),
|
|
359
|
+
label: line(1, 200).describe("What could not be established"),
|
|
360
|
+
why: z.string().max(600).optional().describe("Why it is unknown"),
|
|
361
|
+
finding_ids: findingIdsSchema.optional(),
|
|
362
|
+
});
|
|
363
|
+
/* ------------------------------------------------------------------ */
|
|
364
|
+
/* Change refs (diagnosis_changes_v1) */
|
|
365
|
+
/* ------------------------------------------------------------------ */
|
|
366
|
+
export const CHANGE_ROLES = [
|
|
367
|
+
"regression_source",
|
|
368
|
+
"fix",
|
|
369
|
+
"rollback",
|
|
370
|
+
"last_good",
|
|
371
|
+
"first_bad",
|
|
372
|
+
"verified_by",
|
|
373
|
+
"context",
|
|
374
|
+
];
|
|
375
|
+
export const CHANGE_KINDS = [
|
|
376
|
+
"commit",
|
|
377
|
+
"pull_request",
|
|
378
|
+
"deployment",
|
|
379
|
+
"release",
|
|
380
|
+
"ci_run",
|
|
381
|
+
"config_change",
|
|
382
|
+
];
|
|
383
|
+
export const CHANGE_RESULTS = ["success", "failure", "cancelled", "skipped", "pending", "unknown"];
|
|
384
|
+
export const CHANGE_STATES = ["open", "merged", "closed", "reverted", "deployed", "rolled_back"];
|
|
385
|
+
/** The backend keeps at most this many change refs. */
|
|
386
|
+
export const MAX_CHANGE_REFS = 6;
|
|
387
|
+
export const changeRefSchema = z
|
|
388
|
+
.object({
|
|
389
|
+
id: line(0, 64).optional().describe("Your id for the change; Tellagen derives change-N when it is missing or used twice"),
|
|
390
|
+
role: z
|
|
391
|
+
.enum(CHANGE_ROLES)
|
|
392
|
+
.describe("regression_source = the commit or pull request that introduced the failure; first_bad = the first failed run or deploy; last_good = the last good one before it; fix = the change that fixed it; rollback = a rollback that removed the change; verified_by = a run after the fix, with its result; context = a related change that is not the cause"),
|
|
393
|
+
kind: z.enum(CHANGE_KINDS).describe("commit, pull_request, deployment, release, ci_run or config_change"),
|
|
394
|
+
title: line(0, 200).optional().describe("One line: the commit subject, pull request title or run name"),
|
|
395
|
+
repo: z
|
|
396
|
+
.string()
|
|
397
|
+
.trim()
|
|
398
|
+
.max(200)
|
|
399
|
+
.regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/, "must be owner/name")
|
|
400
|
+
.optional()
|
|
401
|
+
.describe("GitHub repository as owner/name; with ref or sha Tellagen builds the link"),
|
|
402
|
+
ref: line(0, 120)
|
|
403
|
+
.optional()
|
|
404
|
+
.describe("The pull request number, release tag, CI run id, branch or deployment id"),
|
|
405
|
+
sha: z
|
|
406
|
+
.string()
|
|
407
|
+
.trim()
|
|
408
|
+
.regex(/^[0-9a-fA-F]{7,64}$/, "must be 7 to 64 hex characters")
|
|
409
|
+
.optional()
|
|
410
|
+
.describe("The commit sha"),
|
|
411
|
+
occurred_at: z
|
|
412
|
+
.string()
|
|
413
|
+
.datetime({ offset: true })
|
|
414
|
+
.optional()
|
|
415
|
+
.describe("When it merged, deployed or ran (RFC 3339)"),
|
|
416
|
+
author: line(0, 120).optional(),
|
|
417
|
+
result: z
|
|
418
|
+
.enum(CHANGE_RESULTS)
|
|
419
|
+
.optional()
|
|
420
|
+
.describe("How a CI run or deployment ended. A fact; a green run never confirms the cause by itself."),
|
|
421
|
+
state: z.enum(CHANGE_STATES).optional(),
|
|
422
|
+
verification: z.enum(["confirmed", "likely", "unknown"]).optional(),
|
|
423
|
+
confidence_percent: z.number().int().min(0).max(100).optional(),
|
|
424
|
+
step_ids: z
|
|
425
|
+
.array(z.string().min(1).max(64))
|
|
426
|
+
.max(12)
|
|
427
|
+
.optional()
|
|
428
|
+
.describe("Ids of the causal_paths steps this change belongs to"),
|
|
429
|
+
finding_ids: findingIdsSchema.optional(),
|
|
430
|
+
links: evidenceLinksSchema.optional(),
|
|
431
|
+
})
|
|
432
|
+
.refine((change) => Boolean(change.ref?.trim() || change.sha?.trim() || change.title?.trim() || change.links?.length), { message: "a change ref needs ref, sha, title or links" });
|
|
433
|
+
export const resultChangeShape = {
|
|
434
|
+
change_refs: z
|
|
435
|
+
.array(changeRefSchema)
|
|
436
|
+
.max(MAX_CHANGE_REFS)
|
|
437
|
+
.optional()
|
|
438
|
+
.describe("The changes tied to the incident, at most 6: the regression_source that introduced it, first_bad and last_good runs or deploys, the fix, and one verified_by ci_run per run after the fix with its result. Give each a link (tellagen_build_source_link) or repo with ref or sha, and finding_ids or step_ids. Needs diagnosis_changes_v1."),
|
|
439
|
+
};
|
|
440
|
+
export const resultStructureShape = {
|
|
441
|
+
ruled_out: z
|
|
442
|
+
.array(ruledOutSchema)
|
|
443
|
+
.max(5)
|
|
444
|
+
.optional()
|
|
445
|
+
.describe("Causes the run checked and ruled out, at most 5. One entry per negative finding that matters."),
|
|
446
|
+
coverage: z
|
|
447
|
+
.array(coverageEntrySchema)
|
|
448
|
+
.max(8)
|
|
449
|
+
.optional()
|
|
450
|
+
.describe("One entry per data source the run used or could not use, at most 8. Use state gap for a source that could not be read."),
|
|
451
|
+
unknowns: z
|
|
452
|
+
.array(unknownSchema)
|
|
453
|
+
.max(5)
|
|
454
|
+
.optional()
|
|
455
|
+
.describe("What the run could not establish, at most 5"),
|
|
456
|
+
};
|
|
457
|
+
/* ------------------------------------------------------------------ */
|
|
458
|
+
/* Trace step additions */
|
|
459
|
+
/* ------------------------------------------------------------------ */
|
|
460
|
+
export const TRACE_OUTCOMES = [
|
|
461
|
+
"supports",
|
|
462
|
+
"rules_out",
|
|
463
|
+
"nothing_notable",
|
|
464
|
+
"inconclusive",
|
|
465
|
+
"unavailable",
|
|
466
|
+
];
|
|
467
|
+
export const traceStructureShape = {
|
|
468
|
+
outcome: z
|
|
469
|
+
.enum(TRACE_OUTCOMES)
|
|
470
|
+
.optional()
|
|
471
|
+
.describe("What this finished check did to the cause it tested: supports, rules_out, nothing_notable, inconclusive, or unavailable (the source could not be read). Send it with status done or error."),
|
|
472
|
+
cause_key: z
|
|
473
|
+
.string()
|
|
474
|
+
.trim()
|
|
475
|
+
.min(1)
|
|
476
|
+
.max(64)
|
|
477
|
+
.optional()
|
|
478
|
+
.describe("Your short key for the cause this check belongs to (for example deploy-4412); reuse it on every check of that cause"),
|
|
479
|
+
};
|
|
480
|
+
function stripEvidenceRefs(refs, path, removed) {
|
|
481
|
+
if (!Array.isArray(refs))
|
|
482
|
+
return refs;
|
|
483
|
+
return refs.map((ref, index) => {
|
|
484
|
+
if (!isRecord(ref))
|
|
485
|
+
return ref;
|
|
486
|
+
const next = { ...ref };
|
|
487
|
+
for (const field of EVIDENCE_REF_STRUCTURE_FIELDS) {
|
|
488
|
+
if (field in next) {
|
|
489
|
+
delete next[field];
|
|
490
|
+
removed.push(`${path}[${index}].${field}`);
|
|
491
|
+
}
|
|
492
|
+
}
|
|
493
|
+
return next;
|
|
494
|
+
});
|
|
495
|
+
}
|
|
496
|
+
/** An evidence ref list without links, command and datasource. */
|
|
497
|
+
export function stripFindingEvidenceStructure(refs) {
|
|
498
|
+
const removed = [];
|
|
499
|
+
return { refs: stripEvidenceRefs(refs, "evidence_refs", removed), removed };
|
|
500
|
+
}
|
|
501
|
+
/** A result summary without any diagnosis_structure_v1 field. */
|
|
502
|
+
export function stripResultStructure(summary) {
|
|
503
|
+
const removed = [];
|
|
504
|
+
if (!isRecord(summary))
|
|
505
|
+
return { summary, removed };
|
|
506
|
+
const next = { ...summary };
|
|
507
|
+
if (Array.isArray(next.causal_paths)) {
|
|
508
|
+
next.causal_paths = next.causal_paths.map((path, pathIndex) => {
|
|
509
|
+
if (!isRecord(path) || !Array.isArray(path.steps))
|
|
510
|
+
return path;
|
|
511
|
+
return {
|
|
512
|
+
...path,
|
|
513
|
+
steps: path.steps.map((step, stepIndex) => {
|
|
514
|
+
if (!isRecord(step))
|
|
515
|
+
return step;
|
|
516
|
+
const at = `causal_paths[${pathIndex}].steps[${stepIndex}]`;
|
|
517
|
+
const copy = { ...step };
|
|
518
|
+
for (const field of ["finding_ids", "figure", "links"]) {
|
|
519
|
+
if (field in copy) {
|
|
520
|
+
delete copy[field];
|
|
521
|
+
removed.push(`${at}.${field}`);
|
|
522
|
+
}
|
|
523
|
+
}
|
|
524
|
+
if ("evidence_refs" in copy) {
|
|
525
|
+
copy.evidence_refs = stripEvidenceRefs(copy.evidence_refs, `${at}.evidence_refs`, removed);
|
|
526
|
+
}
|
|
527
|
+
return copy;
|
|
528
|
+
}),
|
|
529
|
+
};
|
|
530
|
+
});
|
|
531
|
+
}
|
|
532
|
+
if (Array.isArray(next.recommended_actions)) {
|
|
533
|
+
next.recommended_actions = next.recommended_actions.map((action, index) => {
|
|
534
|
+
if (!isRecord(action) || !("evidence_refs" in action))
|
|
535
|
+
return action;
|
|
536
|
+
return {
|
|
537
|
+
...action,
|
|
538
|
+
evidence_refs: stripEvidenceRefs(action.evidence_refs, `recommended_actions[${index}].evidence_refs`, removed),
|
|
539
|
+
};
|
|
540
|
+
});
|
|
541
|
+
}
|
|
542
|
+
if (isRecord(next.question_verification) &&
|
|
543
|
+
"evidence_refs" in next.question_verification) {
|
|
544
|
+
next.question_verification = {
|
|
545
|
+
...next.question_verification,
|
|
546
|
+
evidence_refs: stripEvidenceRefs(next.question_verification.evidence_refs, "question_verification.evidence_refs", removed),
|
|
547
|
+
};
|
|
548
|
+
}
|
|
549
|
+
for (const field of ["ruled_out", "coverage", "unknowns"]) {
|
|
550
|
+
if (field in next) {
|
|
551
|
+
delete next[field];
|
|
552
|
+
removed.push(field);
|
|
553
|
+
}
|
|
554
|
+
}
|
|
555
|
+
return { summary: next, removed };
|
|
556
|
+
}
|
|
557
|
+
/** The trace body without outcome and cause_key. */
|
|
558
|
+
export function stripTraceStructure(body) {
|
|
559
|
+
const next = { ...body };
|
|
560
|
+
const removed = [];
|
|
561
|
+
for (const field of ["outcome", "cause_key"]) {
|
|
562
|
+
if (field in next) {
|
|
563
|
+
delete next[field];
|
|
564
|
+
removed.push(field);
|
|
565
|
+
}
|
|
566
|
+
}
|
|
567
|
+
return { body: next, removed };
|
|
568
|
+
}
|
|
569
|
+
const CHANGE_LINK_KIND_SET = new Set(CHANGE_LINK_KINDS);
|
|
570
|
+
/** A copy of value without links of the change kinds, at any depth. */
|
|
571
|
+
function dropChangeLinks(value, path, removed) {
|
|
572
|
+
if (Array.isArray(value)) {
|
|
573
|
+
return value.map((item, index) => dropChangeLinks(item, `${path}[${index}]`, removed));
|
|
574
|
+
}
|
|
575
|
+
if (!isRecord(value))
|
|
576
|
+
return value;
|
|
577
|
+
const next = {};
|
|
578
|
+
for (const [key, child] of Object.entries(value)) {
|
|
579
|
+
const at = path ? `${path}.${key}` : key;
|
|
580
|
+
if (key === "links" && Array.isArray(child)) {
|
|
581
|
+
next[key] = child.filter((link, index) => {
|
|
582
|
+
if (isRecord(link) && typeof link.kind === "string" && CHANGE_LINK_KIND_SET.has(link.kind)) {
|
|
583
|
+
removed.push(`${at}[${index}]`);
|
|
584
|
+
return false;
|
|
585
|
+
}
|
|
586
|
+
return true;
|
|
587
|
+
});
|
|
588
|
+
continue;
|
|
589
|
+
}
|
|
590
|
+
next[key] = dropChangeLinks(child, at, removed);
|
|
591
|
+
}
|
|
592
|
+
return next;
|
|
593
|
+
}
|
|
594
|
+
/** A result summary without change_refs and without ci_run, deployment and release links. */
|
|
595
|
+
export function stripResultChanges(summary) {
|
|
596
|
+
const removed = [];
|
|
597
|
+
if (!isRecord(summary))
|
|
598
|
+
return { summary, removed };
|
|
599
|
+
const rest = { ...summary };
|
|
600
|
+
if ("change_refs" in rest) {
|
|
601
|
+
delete rest.change_refs;
|
|
602
|
+
removed.push("change_refs");
|
|
603
|
+
}
|
|
604
|
+
return { summary: dropChangeLinks(rest, "", removed), removed };
|
|
605
|
+
}
|
|
606
|
+
/** Evidence refs without ci_run, deployment and release links. */
|
|
607
|
+
export function stripFindingChangeLinks(refs) {
|
|
608
|
+
const removed = [];
|
|
609
|
+
return { refs: dropChangeLinks(refs, "evidence_refs", removed), removed };
|
|
610
|
+
}
|
|
611
|
+
/** The sentence the tool adds when it dropped fields for an older backend. */
|
|
612
|
+
export function unsupportedNotice(removed, capability = DIAGNOSIS_STRUCTURE_CAPABILITY) {
|
|
613
|
+
const shown = removed.slice(0, 6).join(", ");
|
|
614
|
+
const more = removed.length > 6 ? `, and ${removed.length - 6} more` : "";
|
|
615
|
+
const feature = capability === DIAGNOSIS_CHANGES_CAPABILITY
|
|
616
|
+
? "change refs and ci_run, deployment and release links"
|
|
617
|
+
: "the diagnosis structure";
|
|
618
|
+
return `This Tellagen backend does not advertise ${capability} for this run, so ${shown}${more} were not sent. Update Tellagen to use ${feature}; the rest of the call went through.`;
|
|
619
|
+
}
|
|
620
|
+
const WARNING_ADVICE = {
|
|
621
|
+
no_causal_path: "send causal_paths with 2 to 4 steps",
|
|
622
|
+
step_without_proof: "cite finding_ids from tellagen_post_finding on each step",
|
|
623
|
+
finding_ids_dropped: "use numeric ids that tellagen_post_finding returned for this run",
|
|
624
|
+
step_ids_dropped: "coverage step_ids must be ids of causal_paths steps",
|
|
625
|
+
evidence_without_link: "evidence refs have no link: call tellagen_build_source_link or add a command",
|
|
626
|
+
links_dropped: "links must be http(s) addresses, at most 4 per ref, labels up to 60 characters",
|
|
627
|
+
commands_dropped: "keep command under 1000 characters",
|
|
628
|
+
figure_invalid: "fix the figure to match a stats, compare, trend, checks, range_overlap, histogram, run_history or diff block (tellagen_build_figure checks it)",
|
|
629
|
+
structure_truncated: "keep ruled_out to 5, coverage to 8 and unknowns to 5",
|
|
630
|
+
negative_not_ruled_out: "add a ruled_out entry for each negative finding that matters",
|
|
631
|
+
gap_without_coverage: "add a coverage entry with state gap for each gap finding",
|
|
632
|
+
single_source_high_confidence: "confirm the cause from a second source or lower the confidence",
|
|
633
|
+
change_without_link: "give each change ref a link, or repo with ref or sha so Tellagen can build one",
|
|
634
|
+
change_without_proof: "cite finding_ids or step_ids on each change ref",
|
|
635
|
+
regression_source_missing: "add the change that introduced it as a change ref with role regression_source, or say in unknowns why it is not known",
|
|
636
|
+
change_refs_dropped: "use a known role and kind, give each ref a ref, sha, title or link, and send at most 6",
|
|
637
|
+
};
|
|
638
|
+
/**
|
|
639
|
+
* One line the agent can act on, from the backend's warnings. The warnings
|
|
640
|
+
* themselves stay verbatim in the response; this only groups them by code.
|
|
641
|
+
*/
|
|
642
|
+
export function summarizeWarnings(warnings) {
|
|
643
|
+
if (!Array.isArray(warnings) || warnings.length === 0)
|
|
644
|
+
return undefined;
|
|
645
|
+
const counts = new Map();
|
|
646
|
+
for (const warning of warnings) {
|
|
647
|
+
const code = isRecord(warning) && typeof warning.code === "string" ? warning.code : "warning";
|
|
648
|
+
counts.set(code, (counts.get(code) ?? 0) + 1);
|
|
649
|
+
}
|
|
650
|
+
const parts = [...counts.entries()].map(([code, count]) => {
|
|
651
|
+
const advice = WARNING_ADVICE[code];
|
|
652
|
+
return advice ? `${count} ${code} (${advice})` : `${count} ${code}`;
|
|
653
|
+
});
|
|
654
|
+
return `${warnings.length} warning${warnings.length === 1 ? "" : "s"}: ${parts.join("; ")}. The run is already complete, so name anything you could not fix in your report and apply the fixes on the next run.`;
|
|
655
|
+
}
|
|
656
|
+
//# sourceMappingURL=diagnosis-structure.js.map
|