@tellagen/mcp-server 0.4.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +335 -102
- package/SKILL.md +183 -27
- package/contracts/mcp-protocol.json +155 -0
- package/contracts/runbooks/manifest.json +26 -6
- package/contracts/runbooks/v2/cause-lead.guidance.json +37 -0
- package/contracts/runbooks/v2/client-protocol.json +926 -0
- package/contracts/runbooks/v2/client-writes.guidance.json +42 -0
- package/contracts/runbooks/v2/fixtures/timeline-event-blocks-rejected.json +30 -5
- package/contracts/runbooks/v2/result-summary.guidance.json +21 -0
- package/contracts/runbooks/v2/timeline-event-blocks.schema.json +18 -11
- package/contracts/tellagen-runbook-contracts.json +4 -4
- package/dist/active-run.d.ts +29 -0
- package/dist/active-run.js +67 -0
- package/dist/active-run.js.map +1 -0
- package/dist/bootstrap.d.ts +20 -0
- package/dist/bootstrap.js +29 -0
- package/dist/bootstrap.js.map +1 -0
- package/dist/cause-lead.d.ts +25 -0
- package/dist/cause-lead.js +145 -0
- package/dist/cause-lead.js.map +1 -0
- package/dist/cli/auth.d.ts +22 -0
- package/dist/cli/auth.js +207 -0
- package/dist/cli/auth.js.map +1 -0
- package/dist/cli/io.d.ts +16 -0
- package/dist/cli/io.js +53 -0
- package/dist/cli/io.js.map +1 -0
- package/dist/cli/listen-guard.d.ts +12 -0
- package/dist/cli/listen-guard.js +50 -0
- package/dist/cli/listen-guard.js.map +1 -0
- package/dist/cli/listen.d.ts +28 -0
- package/dist/cli/listen.js +205 -0
- package/dist/cli/listen.js.map +1 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +53 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/cli/trace-hook.d.ts +23 -0
- package/dist/cli/trace-hook.js +99 -0
- package/dist/cli/trace-hook.js.map +1 -0
- package/dist/client.d.ts +92 -6
- package/dist/client.js +300 -23
- package/dist/client.js.map +1 -1
- package/dist/config.d.ts +17 -0
- package/dist/config.js +38 -0
- package/dist/config.js.map +1 -0
- package/dist/credentials.d.ts +120 -0
- package/dist/credentials.js +363 -0
- package/dist/credentials.js.map +1 -0
- package/dist/diagnosis-structure.d.ts +207 -147
- package/dist/diagnosis-structure.js +143 -2
- package/dist/diagnosis-structure.js.map +1 -1
- package/dist/diff-figure.d.ts +56 -0
- package/dist/diff-figure.js +276 -0
- package/dist/diff-figure.js.map +1 -0
- package/dist/errors.d.ts +21 -0
- package/dist/errors.js +60 -0
- package/dist/errors.js.map +1 -1
- package/dist/figures.d.ts +281 -201
- package/dist/figures.js +189 -47
- package/dist/figures.js.map +1 -1
- package/dist/guide-resources.d.ts +28 -0
- package/dist/guide-resources.js +81 -0
- package/dist/guide-resources.js.map +1 -0
- package/dist/heartbeat.d.ts +24 -0
- package/dist/heartbeat.js +94 -0
- package/dist/heartbeat.js.map +1 -0
- package/dist/home.d.ts +8 -0
- package/dist/home.js +14 -0
- package/dist/home.js.map +1 -0
- package/dist/identity.d.ts +32 -0
- package/dist/identity.js +83 -0
- package/dist/identity.js.map +1 -0
- package/dist/index.js +46 -14
- package/dist/index.js.map +1 -1
- package/dist/listen-config.d.ts +67 -0
- package/dist/listen-config.js +83 -0
- package/dist/listen-config.js.map +1 -0
- package/dist/listen-probe.d.ts +57 -0
- package/dist/listen-probe.js +158 -0
- package/dist/listen-probe.js.map +1 -0
- package/dist/listen-rules.d.ts +88 -0
- package/dist/listen-rules.js +252 -0
- package/dist/listen-rules.js.map +1 -0
- package/dist/listen-settings.d.ts +18 -0
- package/dist/listen-settings.js +50 -0
- package/dist/listen-settings.js.map +1 -0
- package/dist/listen-wrap.d.ts +21 -0
- package/dist/listen-wrap.js +52 -0
- package/dist/listen-wrap.js.map +1 -0
- package/dist/listener.d.ts +195 -0
- package/dist/listener.js +600 -0
- package/dist/listener.js.map +1 -0
- package/dist/open-run.d.ts +2 -0
- package/dist/open-run.js +5 -0
- package/dist/open-run.js.map +1 -0
- package/dist/prompts.d.ts +12 -0
- package/dist/prompts.js +37 -0
- package/dist/prompts.js.map +1 -0
- package/dist/redact.d.ts +13 -0
- package/dist/redact.js +76 -0
- package/dist/redact.js.map +1 -0
- package/dist/run-events.d.ts +54 -0
- package/dist/run-events.js +210 -0
- package/dist/run-events.js.map +1 -0
- package/dist/run-state.d.ts +184 -0
- package/dist/run-state.js +207 -0
- package/dist/run-state.js.map +1 -0
- package/dist/server.d.ts +22 -2
- package/dist/server.js +137 -29
- package/dist/server.js.map +1 -1
- package/dist/session.d.ts +86 -0
- package/dist/session.js +155 -0
- package/dist/session.js.map +1 -0
- package/dist/shell-rules.d.ts +49 -0
- package/dist/shell-rules.js +335 -0
- package/dist/shell-rules.js.map +1 -0
- package/dist/signin-index.d.ts +164 -0
- package/dist/signin-index.js +116 -0
- package/dist/signin-index.js.map +1 -0
- package/dist/signin.d.ts +169 -0
- package/dist/signin.js +541 -0
- package/dist/signin.js.map +1 -0
- package/dist/start.d.ts +7 -6
- package/dist/start.js +14 -7
- package/dist/start.js.map +1 -1
- package/dist/tools/catalog.d.ts +44 -0
- package/dist/tools/catalog.js +105 -0
- package/dist/tools/catalog.js.map +1 -0
- package/dist/tools/causes.d.ts +6 -6
- package/dist/tools/causes.js +4 -5
- package/dist/tools/causes.js.map +1 -1
- package/dist/tools/context.js +5 -5
- package/dist/tools/context.js.map +1 -1
- package/dist/tools/datasources.js +1 -1
- package/dist/tools/datasources.js.map +1 -1
- package/dist/tools/diagnostics.js +2 -2
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/figures.d.ts +3 -2
- package/dist/tools/figures.js +38 -13
- package/dist/tools/figures.js.map +1 -1
- package/dist/tools/findings.d.ts +28 -0
- package/dist/tools/findings.js +88 -24
- package/dist/tools/findings.js.map +1 -1
- package/dist/tools/incidents.js +5 -5
- package/dist/tools/incidents.js.map +1 -1
- package/dist/tools/index.d.ts +19 -2
- package/dist/tools/index.js +115 -14
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/investigations.d.ts +54 -0
- package/dist/tools/investigations.js +370 -69
- package/dist/tools/investigations.js.map +1 -1
- package/dist/tools/next.d.ts +20 -0
- package/dist/tools/next.js +136 -0
- package/dist/tools/next.js.map +1 -0
- package/dist/tools/postmortem-runbooks.d.ts +52 -52
- package/dist/tools/postmortem-runbooks.js +3 -10
- package/dist/tools/postmortem-runbooks.js.map +1 -1
- package/dist/tools/resume.d.ts +5 -0
- package/dist/tools/resume.js +136 -0
- package/dist/tools/resume.js.map +1 -0
- package/dist/tools/signin.d.ts +12 -0
- package/dist/tools/signin.js +54 -0
- package/dist/tools/signin.js.map +1 -0
- package/dist/tools/source-links.js +5 -3
- package/dist/tools/source-links.js.map +1 -1
- package/dist/tools/timeline.js +57 -11
- package/dist/tools/timeline.js.map +1 -1
- package/dist/trace-record.d.ts +36 -0
- package/dist/trace-record.js +283 -0
- package/dist/trace-record.js.map +1 -0
- package/dist/version.d.ts +10 -2
- package/dist/version.js +20 -1
- package/dist/version.js.map +1 -1
- package/package.json +23 -3
- package/server.json +5 -5
- package/contracts/runbooks/v1/fixtures/global-runbook.json +0 -7
- package/contracts/runbooks/v1/runbook-definition.schema.json +0 -25
- package/dist/auth.d.ts +0 -7
- package/dist/auth.js +0 -19
- package/dist/auth.js.map +0 -1
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
-
import { formatError } from "../errors.js";
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
2
|
+
import { formatError, TellagenAPIError } from "../errors.js";
|
|
3
|
+
import { joinFact, optionalRunIdSchema, otherLiveSession, resolveRunId, } from "../active-run.js";
|
|
4
|
+
import { withCauseLead } from "../cause-lead.js";
|
|
5
|
+
import { legacyClientName, reportedClientName } from "../identity.js";
|
|
6
|
+
import { GUIDE_RESOURCES } from "../guide-resources.js";
|
|
7
|
+
import { protocolCapabilities, CAPABILITIES_HEADER, MCP_SERVER_VERSION, } from "../version.js";
|
|
8
|
+
import { DIAGNOSIS_CHANGES_CAPABILITY, DIFF_LINES_CAPABILITY, evidenceRefStructureShape, rememberServerCapabilities, resultChangeShape, resultStructureShape, stepStructureShape, stripResultChanges, stripResultDiffLines, stripResultFigureExtras, stripResultStructure, stripTraceStructure, summarizeWarnings, supportsDiagnosisChanges, supportsDiagnosisStructure, RECORDED_STEPS_CAPABILITY, knownCapability, supportsCompletionRepairs, COMPLETION_REPAIRS_CAPABILITY, supportsDiffLines, supportsFigureExtras, FIGURE_EXTRAS_CAPABILITY, traceStructureShape, unsupportedNotice, headlineNotice, } from "../diagnosis-structure.js";
|
|
5
9
|
const resultEvidenceRefSchema = z.object({
|
|
6
10
|
source: z.string().min(1),
|
|
7
11
|
query: z.string().optional(),
|
|
@@ -98,7 +102,9 @@ const resultSummarySchema = z
|
|
|
98
102
|
.object({
|
|
99
103
|
tone: z.enum(["success", "warning", "danger", "neutral"]),
|
|
100
104
|
eyebrow: z.string(),
|
|
101
|
-
sentence: z
|
|
105
|
+
sentence: z
|
|
106
|
+
.string()
|
|
107
|
+
.describe("The headline claim: 15 words or fewer, one cause. Put numbers and other causes in findings, causal_paths and ruled_out."),
|
|
102
108
|
show_new_investigation_cta: z.boolean(),
|
|
103
109
|
})
|
|
104
110
|
.describe("Short human-readable conclusion for the RCA record"),
|
|
@@ -245,20 +251,14 @@ function withCompletionChecklist(data) {
|
|
|
245
251
|
const capabilities = data.server_capabilities;
|
|
246
252
|
if (!Array.isArray(capabilities) || !capabilities.includes("diagnosis_structure_v1"))
|
|
247
253
|
return data;
|
|
254
|
+
// A Tellagen that answers a dry run lists the faults itself, when the model completes.
|
|
255
|
+
if (capabilities.includes(COMPLETION_REPAIRS_CAPABILITY))
|
|
256
|
+
return data;
|
|
248
257
|
return {
|
|
249
258
|
...data,
|
|
250
259
|
mcp_before_complete: BEFORE_COMPLETE_CHECKLIST,
|
|
251
260
|
};
|
|
252
261
|
}
|
|
253
|
-
function pickupClientName() {
|
|
254
|
-
const value = (process.env.TELLAGEN_MCP_CLIENT || "codex")
|
|
255
|
-
.trim()
|
|
256
|
-
.toLowerCase();
|
|
257
|
-
if (value !== "codex" && value !== "claude") {
|
|
258
|
-
throw new Error("TELLAGEN_MCP_CLIENT must be either codex or claude");
|
|
259
|
-
}
|
|
260
|
-
return value;
|
|
261
|
-
}
|
|
262
262
|
function pickupProfileID() {
|
|
263
263
|
const value = (process.env.TELLAGEN_MCP_PROFILE_ID || "").trim();
|
|
264
264
|
if (!value)
|
|
@@ -268,6 +268,221 @@ function pickupProfileID() {
|
|
|
268
268
|
}
|
|
269
269
|
return value;
|
|
270
270
|
}
|
|
271
|
+
/** The data source kinds a client can say it has, by Tellagen catalog key. */
|
|
272
|
+
export const AVAILABLE_SOURCE_KEYS = ["grafana", "kubernetes", "github", "docs", "local_host"];
|
|
273
|
+
const availableSourceSchema = z
|
|
274
|
+
.object({
|
|
275
|
+
key: z.enum(AVAILABLE_SOURCE_KEYS).describe("Tellagen catalog key of the source"),
|
|
276
|
+
state: z.enum(["found", "not_found"]).describe("Whether this client can reach the source"),
|
|
277
|
+
detail: z
|
|
278
|
+
.string()
|
|
279
|
+
.trim()
|
|
280
|
+
.max(200)
|
|
281
|
+
.optional()
|
|
282
|
+
.describe("A short fact such as the Grafana host. Never a token, a password or a path with a user name."),
|
|
283
|
+
})
|
|
284
|
+
.strict();
|
|
285
|
+
function incidentIdOf(data) {
|
|
286
|
+
if (typeof data !== "object" || data === null)
|
|
287
|
+
return undefined;
|
|
288
|
+
const record = data;
|
|
289
|
+
const id = record.incident?.id ?? record.run?.incident_id;
|
|
290
|
+
return typeof id === "number" && Number.isInteger(id) && id > 0 ? id : undefined;
|
|
291
|
+
}
|
|
292
|
+
function capabilitiesOf(data) {
|
|
293
|
+
const list = data?.server_capabilities;
|
|
294
|
+
return Array.isArray(list) ? list.filter((item) => typeof item === "string") : [];
|
|
295
|
+
}
|
|
296
|
+
/**
|
|
297
|
+
* Attaches this process to a run and remembers it as the active run.
|
|
298
|
+
*
|
|
299
|
+
* The client name and version come from the MCP handshake. A Tellagen that
|
|
300
|
+
* does not know the newer pickup fields answers 400; the pickup is then sent
|
|
301
|
+
* once more in the old shape, with the name mapped to codex or claude.
|
|
302
|
+
* Pickup is safe to repeat, so both forms may be retried.
|
|
303
|
+
*/
|
|
304
|
+
export async function pickUpRun(client, runId, options = {}) {
|
|
305
|
+
const session = client.session;
|
|
306
|
+
const profileID = pickupProfileID();
|
|
307
|
+
const identity = session.identity;
|
|
308
|
+
const path = `/api/v1/investigations/${encodeURIComponent(runId)}/pickup`;
|
|
309
|
+
const capabilities = protocolCapabilities();
|
|
310
|
+
const body = {
|
|
311
|
+
client: {
|
|
312
|
+
name: reportedClientName(identity),
|
|
313
|
+
...(identity?.version ? { version: identity.version } : {}),
|
|
314
|
+
mcp_server_version: MCP_SERVER_VERSION,
|
|
315
|
+
...(session.computer ? { computer: session.computer } : {}),
|
|
316
|
+
...(profileID ? { profile_id: profileID } : {}),
|
|
317
|
+
session_id: session.sessionId,
|
|
318
|
+
},
|
|
319
|
+
protocol_capabilities: capabilities,
|
|
320
|
+
};
|
|
321
|
+
if (options.model)
|
|
322
|
+
body.model = options.model;
|
|
323
|
+
if (options.availableSources && options.availableSources.length > 0) {
|
|
324
|
+
body.available_sources = options.availableSources;
|
|
325
|
+
}
|
|
326
|
+
if (options.takeover)
|
|
327
|
+
body.takeover = true;
|
|
328
|
+
let data;
|
|
329
|
+
let notice;
|
|
330
|
+
try {
|
|
331
|
+
data = await client.post(path, body, { safeToRepeat: true });
|
|
332
|
+
}
|
|
333
|
+
catch (err) {
|
|
334
|
+
if (!(err instanceof TellagenAPIError))
|
|
335
|
+
throw err;
|
|
336
|
+
const sentName = reportedClientName(identity);
|
|
337
|
+
const legacyName = legacyClientName(identity);
|
|
338
|
+
const withLegacyName = { ...body, client: { ...body.client, name: legacyName } };
|
|
339
|
+
// Each fallback is sent one time. If it fails too, the first error is
|
|
340
|
+
// the one the model sees, so a real error is never hidden.
|
|
341
|
+
const fallback = async (send, text) => {
|
|
342
|
+
try {
|
|
343
|
+
data = await send();
|
|
344
|
+
notice = text;
|
|
345
|
+
}
|
|
346
|
+
catch {
|
|
347
|
+
throw err;
|
|
348
|
+
}
|
|
349
|
+
};
|
|
350
|
+
if (err.code === "pickup_client_context_mismatch" && legacyName !== sentName) {
|
|
351
|
+
// An earlier pickup froze the run for the old short name. Keep that
|
|
352
|
+
// name so the run can go on.
|
|
353
|
+
await fallback(() => client.post(path, withLegacyName, { safeToRepeat: true }), `An earlier pickup stored this run for the client name ${legacyName}, so that name was sent instead of ${sentName}.`);
|
|
354
|
+
}
|
|
355
|
+
else if (err.status >= 500 && ![502, 503, 504].includes(err.status) && legacyName !== sentName) {
|
|
356
|
+
// A Tellagen that knows only codex and claude fails on another client
|
|
357
|
+
// name with a server error. Send the same pickup with the old name.
|
|
358
|
+
await fallback(() => client.post(path, withLegacyName, { safeToRepeat: true }), `The first pickup, with the client name ${sentName}, failed with a server error. It was sent again with the name ${legacyName}, which an older Tellagen accepts, so the run may show ${legacyName} as its client. Update Tellagen to record the real client.`);
|
|
359
|
+
}
|
|
360
|
+
else if (err.status === 400 && err.code === "unknown_field") {
|
|
361
|
+
// A Tellagen that refuses the newer pickup fields: send the old shape.
|
|
362
|
+
const dropped = [
|
|
363
|
+
"client.version",
|
|
364
|
+
"client.computer",
|
|
365
|
+
"client.session_id",
|
|
366
|
+
...(options.model ? ["model"] : []),
|
|
367
|
+
...(body.available_sources ? ["available_sources"] : []),
|
|
368
|
+
...(options.takeover ? ["takeover"] : []),
|
|
369
|
+
];
|
|
370
|
+
await fallback(() => client.post(path, {
|
|
371
|
+
client: {
|
|
372
|
+
name: legacyName,
|
|
373
|
+
mcp_server_version: MCP_SERVER_VERSION,
|
|
374
|
+
...(profileID ? { profile_id: profileID } : {}),
|
|
375
|
+
},
|
|
376
|
+
protocol_capabilities: capabilities,
|
|
377
|
+
}, { safeToRepeat: true }), `This Tellagen does not accept the newer pickup fields, so these were not sent: ${dropped.join(", ")}. The client name was sent as ${legacyName}. Update Tellagen to record them.`);
|
|
378
|
+
}
|
|
379
|
+
else {
|
|
380
|
+
throw err;
|
|
381
|
+
}
|
|
382
|
+
}
|
|
383
|
+
rememberServerCapabilities(client, runId, data);
|
|
384
|
+
noteUpdateAvailable(client, data);
|
|
385
|
+
session.setActiveRun({
|
|
386
|
+
runId,
|
|
387
|
+
incidentId: incidentIdOf(data),
|
|
388
|
+
pickedUpAt: new Date().toISOString(),
|
|
389
|
+
serverCapabilities: capabilitiesOf(data),
|
|
390
|
+
});
|
|
391
|
+
return withNotice(data, notice);
|
|
392
|
+
}
|
|
393
|
+
/** Remembers that Tellagen wants a newer server, so `status` and the session start can say so. */
|
|
394
|
+
function noteUpdateAvailable(client, data) {
|
|
395
|
+
if (typeof data !== "object" || data === null)
|
|
396
|
+
return;
|
|
397
|
+
const update = data.client_update_available;
|
|
398
|
+
if (typeof update !== "object" || update === null)
|
|
399
|
+
return;
|
|
400
|
+
const { your_version, current_version } = update;
|
|
401
|
+
if (typeof your_version === "string" && typeof current_version === "string") {
|
|
402
|
+
client.session.updateSeen?.({ your_version: your_version.slice(0, 40), current_version: current_version.slice(0, 40) });
|
|
403
|
+
}
|
|
404
|
+
}
|
|
405
|
+
/** Names the guide resources that apply to the run in a pickup answer. */
|
|
406
|
+
export function withRunGuides(input) {
|
|
407
|
+
// A lead from a past incident is cleaned and marked as untrusted data first.
|
|
408
|
+
const data = withCauseLead(input);
|
|
409
|
+
if (typeof data !== "object" || data === null || Array.isArray(data))
|
|
410
|
+
return data;
|
|
411
|
+
const skills = data.request?.skills;
|
|
412
|
+
const hasRunbooks = Array.isArray(skills) && skills.length > 0;
|
|
413
|
+
const resources = GUIDE_RESOURCES.filter((guide) => guide.when !== "runbooks" || hasRunbooks).map((guide) => ({ uri: guide.uri, read_when: guide.readWhen }));
|
|
414
|
+
return {
|
|
415
|
+
...data,
|
|
416
|
+
mcp_active_run: "This run is now the active run of this session. Later calls may leave investigation_run_id out.",
|
|
417
|
+
mcp_resources: resources,
|
|
418
|
+
};
|
|
419
|
+
}
|
|
420
|
+
/** Who holds the run, from the details of a run_has_active_client answer. */
|
|
421
|
+
function holderLine(payload) {
|
|
422
|
+
const details = payload && typeof payload.details === "object" && payload.details !== null
|
|
423
|
+
? payload.details
|
|
424
|
+
: {};
|
|
425
|
+
const part = (value, max) => typeof value === "string" ? value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, max) : "";
|
|
426
|
+
const holder = part(details.holder_name, 120) || "Another person";
|
|
427
|
+
const client = part(details.client_name, 80);
|
|
428
|
+
const computer = part(details.computer_name, 120);
|
|
429
|
+
const last = part(details.last_contact_at, 40);
|
|
430
|
+
return `${holder} runs this diagnosis${client ? ` in ${client}` : " in another client"}${computer ? ` on ${computer}` : ""}${last ? `, last contact at ${last}` : ""}.`;
|
|
431
|
+
}
|
|
432
|
+
const takeoverSchema = z
|
|
433
|
+
.boolean()
|
|
434
|
+
.optional()
|
|
435
|
+
.describe("Set true only after the person agreed that this session takes the run over from another client. Never set it on your own.");
|
|
436
|
+
function questionResult(code, message, extra = {}) {
|
|
437
|
+
return {
|
|
438
|
+
content: [
|
|
439
|
+
{
|
|
440
|
+
type: "text",
|
|
441
|
+
text: JSON.stringify({ ...extra, error: true, code, message, next_input: { takeover: true } }),
|
|
442
|
+
},
|
|
443
|
+
],
|
|
444
|
+
isError: true,
|
|
445
|
+
};
|
|
446
|
+
}
|
|
447
|
+
/**
|
|
448
|
+
* Pickup with the two questions a person must answer: a second session on
|
|
449
|
+
* this computer, and a run another client holds in Tellagen. The person is
|
|
450
|
+
* asked through the client when it can show a question; otherwise the model
|
|
451
|
+
* gets the question as the tool answer.
|
|
452
|
+
*/
|
|
453
|
+
export async function pickUpWithConsent(client, runId, options) {
|
|
454
|
+
const session = client.session;
|
|
455
|
+
let takeover = options.takeover === true;
|
|
456
|
+
const other = otherLiveSession(client, session.state.read());
|
|
457
|
+
if (other && other.run_id === runId && !takeover) {
|
|
458
|
+
const fact = joinFact(other);
|
|
459
|
+
const answer = await session.ask?.(`${fact} Should this session join the run?`);
|
|
460
|
+
if (answer !== true) {
|
|
461
|
+
return {
|
|
462
|
+
question: questionResult("run_open_in_other_session", answer === false
|
|
463
|
+
? "The person said no. Do not pick this run up in this session."
|
|
464
|
+
: `${fact} Ask the person whether this session should join the run. If they say yes, call the tool again with takeover set to true.`),
|
|
465
|
+
};
|
|
466
|
+
}
|
|
467
|
+
takeover = true;
|
|
468
|
+
}
|
|
469
|
+
try {
|
|
470
|
+
return { data: await pickUpRun(client, runId, { ...options, takeover }) };
|
|
471
|
+
}
|
|
472
|
+
catch (err) {
|
|
473
|
+
if (!(err instanceof TellagenAPIError) || err.code !== "run_has_active_client" || takeover)
|
|
474
|
+
throw err;
|
|
475
|
+
const fact = `${holderLine(err.payload)} Two clients on one run write over each other.`;
|
|
476
|
+
const question = `${fact} Ask the person whether this session should take the run over. If they say yes, call the tool again with takeover set to true.`;
|
|
477
|
+
const answer = await session.ask?.(`${fact} Should this session take the run over?`);
|
|
478
|
+
if (answer === true) {
|
|
479
|
+
return { data: await pickUpRun(client, runId, { ...options, takeover: true }) };
|
|
480
|
+
}
|
|
481
|
+
return {
|
|
482
|
+
question: questionResult("run_has_active_client", answer === false ? "The person said no. Do not pick this run up in this session." : question, err.payload ?? {}),
|
|
483
|
+
};
|
|
484
|
+
}
|
|
485
|
+
}
|
|
271
486
|
const investigationScopeSchema = z
|
|
272
487
|
.object({
|
|
273
488
|
services: z
|
|
@@ -364,7 +579,7 @@ const investigationGuidanceSchema = z
|
|
|
364
579
|
})
|
|
365
580
|
.strict(),
|
|
366
581
|
])
|
|
367
|
-
.describe("
|
|
582
|
+
.describe("Optional, immutable basis for this trace step. Leave it out for an ordinary check: Tellagen records your own judgment, with the step title as the reason. Give it when a frozen runbook or a responder guided the check: cite only frozen request.skills references or declare responder_request. Never submit legacy_unattributed.");
|
|
368
583
|
function isDiagnosticSessionID(id) {
|
|
369
584
|
return id.trim().startsWith("diag_");
|
|
370
585
|
}
|
|
@@ -386,7 +601,7 @@ function diagnosticSessionIDError(id) {
|
|
|
386
601
|
}
|
|
387
602
|
export function registerInvestigationTools(server, client) {
|
|
388
603
|
server.registerTool("tellagen_start_investigation", {
|
|
389
|
-
description: "Start a new local AI investigation run on a Tellagen incident when you were not given an investigation_run_id. If Tellagen UI already provided a run ID, use tellagen_pick_up_investigation instead. To follow up an earlier run of the same incident (it was wrong, or the fix needs a re-check), pass corrects_run_id; to answer an open diagnosis question (a gap finding), pass question_finding_id. The pickup bundle of a follow-up carries the earlier run as parent.",
|
|
604
|
+
description: "Start a new local AI investigation run on a Tellagen incident when you were not given an investigation_run_id. If Tellagen UI already provided a run ID, use tellagen_pick_up_investigation instead. To follow up an earlier run of the same incident (it was wrong, or the fix needs a re-check), pass corrects_run_id; to answer an open diagnosis question (a gap finding), pass question_finding_id. The pickup bundle of a follow-up carries the earlier run as parent. Returns the new run, which you then pick up with tellagen_pick_up_investigation.",
|
|
390
605
|
inputSchema: {
|
|
391
606
|
incident_id: z.number().int().positive().describe("Incident ID"),
|
|
392
607
|
agent_name: z
|
|
@@ -443,7 +658,9 @@ export function registerInvestigationTools(server, client) {
|
|
|
443
658
|
if (question_finding_id !== undefined) {
|
|
444
659
|
body.question_finding_id = question_finding_id;
|
|
445
660
|
}
|
|
446
|
-
|
|
661
|
+
// This request has no picked-up run, so the capabilities go in a header.
|
|
662
|
+
const caps = protocolCapabilities().filter((name) => name === "strict_fields_v1");
|
|
663
|
+
const data = await client.post(`/api/v1/incidents/${incident_id}/investigations`, body, caps.length > 0 ? { headers: { [CAPABILITIES_HEADER]: caps.join(",") } } : undefined);
|
|
447
664
|
return {
|
|
448
665
|
content: [{ type: "text", text: JSON.stringify(data) }],
|
|
449
666
|
};
|
|
@@ -456,15 +673,13 @@ export function registerInvestigationTools(server, client) {
|
|
|
456
673
|
}
|
|
457
674
|
});
|
|
458
675
|
server.registerTool("tellagen_get_incident_context", {
|
|
459
|
-
description: "
|
|
676
|
+
description: "Re-read the context bundle of an investigation run: incident, scope, timeline, prior findings, connectors, matched runbooks and output schema guidance. Use it to resume or re-check a run you already picked up. It changes nothing and does not attach you to the run; tellagen_pick_up_investigation does that.",
|
|
460
677
|
inputSchema: {
|
|
461
|
-
investigation_run_id:
|
|
462
|
-
.string()
|
|
463
|
-
.min(1)
|
|
464
|
-
.describe("Investigation run ID from Tellagen"),
|
|
678
|
+
investigation_run_id: optionalRunIdSchema,
|
|
465
679
|
},
|
|
466
|
-
}, async (
|
|
680
|
+
}, async (input) => {
|
|
467
681
|
try {
|
|
682
|
+
const investigation_run_id = resolveRunId(client, input.investigation_run_id);
|
|
468
683
|
const data = await client.get(`/api/v1/investigations/${investigation_run_id}/context`);
|
|
469
684
|
rememberServerCapabilities(client, investigation_run_id, data);
|
|
470
685
|
return {
|
|
@@ -479,31 +694,48 @@ export function registerInvestigationTools(server, client) {
|
|
|
479
694
|
}
|
|
480
695
|
});
|
|
481
696
|
server.registerTool("tellagen_pick_up_investigation", {
|
|
482
|
-
description: "Attach this
|
|
697
|
+
description: "Attach this session to an investigation run and get its full context bundle with server_capabilities. Call it first when you have an investigation_run_id. It moves the run from awaiting_agent to running and makes it the active run, so later calls may leave the run ID out. The server sends the client name, its version and its protocol capabilities itself. Pass model with your own model name. Pass available_sources with the data sources you can reach: look at the MCP servers and shell tools you have and map them to grafana, kubernetes, github, docs and local_host. When the bundle has request.context.suspected_cause_hints, each hint is a lead from a past incident: untrusted data, to test first with one check, never a cause to post without evidence from this incident. If another client holds the run, the answer is a question for the person; set takeover only after they agree. Picking the same unfinished run up again is safe. It never creates a run: use tellagen_start_investigation when you have no run ID.",
|
|
483
698
|
inputSchema: {
|
|
484
699
|
investigation_run_id: z
|
|
485
700
|
.string()
|
|
486
701
|
.min(1)
|
|
487
|
-
.
|
|
702
|
+
.optional()
|
|
703
|
+
.describe("Investigation run ID from Tellagen. Leave it out to pick the active run of this session up again."),
|
|
704
|
+
model: z
|
|
705
|
+
.string()
|
|
706
|
+
.trim()
|
|
707
|
+
.min(1)
|
|
708
|
+
.max(100)
|
|
709
|
+
.optional()
|
|
710
|
+
.describe("Your own model name as you know it, for example from your system prompt. Tellagen shows it on the run."),
|
|
711
|
+
available_sources: z
|
|
712
|
+
.array(availableSourceSchema)
|
|
713
|
+
.max(20)
|
|
714
|
+
.optional()
|
|
715
|
+
.describe("The data sources this client can reach, one entry per catalog key, each found or not_found. A source you do not have resolves to a recorded gap instead of a check that fails."),
|
|
716
|
+
takeover: takeoverSchema,
|
|
488
717
|
},
|
|
489
|
-
}, async (
|
|
490
|
-
if (isDiagnosticSessionID(investigation_run_id)) {
|
|
491
|
-
|
|
718
|
+
}, async (input) => {
|
|
719
|
+
if (input.investigation_run_id && isDiagnosticSessionID(input.investigation_run_id)) {
|
|
720
|
+
// The tool check tools are in the settings toolset.
|
|
721
|
+
client.session.toolsets?.enable("settings");
|
|
722
|
+
return diagnosticSessionIDError(input.investigation_run_id);
|
|
492
723
|
}
|
|
493
724
|
try {
|
|
494
|
-
const
|
|
495
|
-
const
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
...(profileID ? { profile_id: profileID } : {}),
|
|
500
|
-
},
|
|
501
|
-
protocol_capabilities: [...INVESTIGATION_PROTOCOL_CAPABILITIES],
|
|
725
|
+
const runId = resolveRunId(client, input.investigation_run_id);
|
|
726
|
+
const outcome = await pickUpWithConsent(client, runId, {
|
|
727
|
+
model: input.model,
|
|
728
|
+
takeover: input.takeover,
|
|
729
|
+
availableSources: input.available_sources,
|
|
502
730
|
});
|
|
503
|
-
|
|
731
|
+
if ("question" in outcome)
|
|
732
|
+
return outcome.question;
|
|
504
733
|
return {
|
|
505
734
|
content: [
|
|
506
|
-
{
|
|
735
|
+
{
|
|
736
|
+
type: "text",
|
|
737
|
+
text: JSON.stringify(withRunGuides(withCompletionChecklist(withAttachmentHint(outcome.data)))),
|
|
738
|
+
},
|
|
507
739
|
],
|
|
508
740
|
};
|
|
509
741
|
}
|
|
@@ -517,7 +749,7 @@ export function registerInvestigationTools(server, client) {
|
|
|
517
749
|
server.registerTool("tellagen_post_runbook_check_attempt", {
|
|
518
750
|
description: "Post or update one execution attempt for a frozen structured v2 runbook check. Copy runbook_id, runbook_version, check_id, and the source resolution selected by the frozen fallback policy. Reuse step_id and attempt_number while moving a usable source from running to done/error. For a frozen blocked record_gap source, post one direct terminal skipped attempt with a linked gap finding instead. Tellagen owns the final logical outcome.",
|
|
519
751
|
inputSchema: {
|
|
520
|
-
investigation_run_id:
|
|
752
|
+
investigation_run_id: optionalRunIdSchema,
|
|
521
753
|
runbook_id: z.number().int().positive(),
|
|
522
754
|
runbook_version: z.number().int().positive(),
|
|
523
755
|
check_id: z.string().min(1),
|
|
@@ -559,8 +791,9 @@ export function registerInvestigationTools(server, client) {
|
|
|
559
791
|
duration_ms: z.number().int().min(0).optional(),
|
|
560
792
|
},
|
|
561
793
|
}, async (input) => {
|
|
562
|
-
const { investigation_run_id, ...fields } = input;
|
|
794
|
+
const { investigation_run_id: givenRunId, ...fields } = input;
|
|
563
795
|
try {
|
|
796
|
+
const investigation_run_id = resolveRunId(client, givenRunId);
|
|
564
797
|
validateTraceReuseHintInput(input);
|
|
565
798
|
const data = await client.post(`/api/v1/investigation-runs/${investigation_run_id}/check-attempts`, {
|
|
566
799
|
...fields,
|
|
@@ -582,16 +815,13 @@ export function registerInvestigationTools(server, client) {
|
|
|
582
815
|
server.registerTool("tellagen_post_trace_step", {
|
|
583
816
|
description: "Post or update a readable investigation trace step for the active run. Every step requires an immutable guidance basis: exact frozen runbook ID/version/section references, or an honest non-runbook origin. Reuse the same guidance when updating a step from running to done/error.",
|
|
584
817
|
inputSchema: {
|
|
585
|
-
investigation_run_id:
|
|
586
|
-
.string()
|
|
587
|
-
.min(1)
|
|
588
|
-
.describe("Active investigation run ID"),
|
|
818
|
+
investigation_run_id: optionalRunIdSchema,
|
|
589
819
|
step_id: z
|
|
590
820
|
.string()
|
|
591
821
|
.refine((value) => value.trim().length > 0, {
|
|
592
822
|
message: "step_id must not be blank",
|
|
593
823
|
})
|
|
594
|
-
.describe(
|
|
824
|
+
.describe('Stable ID chosen before the check and reused for running → done/error updates. To add your outcome to a step that a hook of the client recorded, use the step ID the server names in a tool answer, or "recorded:latest" for the newest recorded step'),
|
|
595
825
|
step_index: z
|
|
596
826
|
.number()
|
|
597
827
|
.int()
|
|
@@ -608,7 +838,7 @@ export function registerInvestigationTools(server, client) {
|
|
|
608
838
|
tool_use_id: z
|
|
609
839
|
.string()
|
|
610
840
|
.optional()
|
|
611
|
-
.describe("
|
|
841
|
+
.describe("Send an identifier of your own for this check, any stable string that is unique per check (for example check-2-loki-errors). Send the same value as tool_use_id on the evidence refs of the findings this check produced: it is how Tellagen joins them. You may add it to a step that is already done by posting the step again with the same status, guidance and reuse_hint; a later post that leaves it out clears it"),
|
|
612
842
|
title: z.string().min(1).describe("Short human-readable step title"),
|
|
613
843
|
result_summary: z
|
|
614
844
|
.string()
|
|
@@ -621,7 +851,7 @@ export function registerInvestigationTools(server, client) {
|
|
|
621
851
|
reuse_hint: traceReuseHintSchema.optional(),
|
|
622
852
|
result_bytes: z.number().int().min(0).optional(),
|
|
623
853
|
truncated: z.boolean().optional(),
|
|
624
|
-
guidance: investigationGuidanceSchema,
|
|
854
|
+
guidance: investigationGuidanceSchema.optional(),
|
|
625
855
|
...traceStructureShape,
|
|
626
856
|
error: z.string().optional(),
|
|
627
857
|
started_at: z
|
|
@@ -636,8 +866,17 @@ export function registerInvestigationTools(server, client) {
|
|
|
636
866
|
.describe("ISO timestamp when the step completed"),
|
|
637
867
|
duration_ms: z.number().int().min(0).optional(),
|
|
638
868
|
},
|
|
639
|
-
}, async ({ investigation_run_id, step_id, step_index, status, tool_name, tool_use_id, title, result_summary, input_json, result_json, artifact_id, artifact_digest, reuse_hint, result_bytes, truncated, guidance, outcome, cause_key, error, started_at, completed_at, duration_ms, }) => {
|
|
869
|
+
}, async ({ investigation_run_id: givenRunId, step_id: givenStepId, step_index, status, tool_name, tool_use_id, title, result_summary, input_json, result_json, artifact_id, artifact_digest, reuse_hint, result_bytes, truncated, guidance, outcome, cause_key, error, started_at, completed_at, duration_ms, }) => {
|
|
640
870
|
try {
|
|
871
|
+
const investigation_run_id = resolveRunId(client, givenRunId);
|
|
872
|
+
let step_id = givenStepId;
|
|
873
|
+
if (step_id.trim() === "recorded:latest") {
|
|
874
|
+
const recorded = client.session.state.recordedSteps(investigation_run_id).at(-1);
|
|
875
|
+
if (!recorded) {
|
|
876
|
+
throw new Error("No step was recorded by a hook for this run. Post the step yourself with a step_id of your own.");
|
|
877
|
+
}
|
|
878
|
+
step_id = recorded.step_id;
|
|
879
|
+
}
|
|
641
880
|
validateTraceReuseHintInput({
|
|
642
881
|
status,
|
|
643
882
|
result_summary,
|
|
@@ -651,8 +890,14 @@ export function registerInvestigationTools(server, client) {
|
|
|
651
890
|
step_index: step_index ?? 0,
|
|
652
891
|
status,
|
|
653
892
|
title,
|
|
654
|
-
guidance,
|
|
655
893
|
};
|
|
894
|
+
if (guidance !== undefined) {
|
|
895
|
+
body.guidance = guidance;
|
|
896
|
+
}
|
|
897
|
+
else if (!knownCapability(client, investigation_run_id, RECORDED_STEPS_CAPABILITY)) {
|
|
898
|
+
// An older Tellagen has no default basis: send the one it would store.
|
|
899
|
+
body.guidance = { origin: "agent_judgment", refs: [], reason: title.trim().slice(0, 500) };
|
|
900
|
+
}
|
|
656
901
|
if (tool_name !== undefined)
|
|
657
902
|
body.tool_name = tool_name;
|
|
658
903
|
if (tool_use_id !== undefined)
|
|
@@ -696,8 +941,11 @@ export function registerInvestigationTools(server, client) {
|
|
|
696
941
|
notice = unsupportedNotice(stripped.removed);
|
|
697
942
|
}
|
|
698
943
|
}
|
|
699
|
-
const data = await client.post(`/api/v1/investigation-runs/${investigation_run_id}/trace`, sendBody
|
|
944
|
+
const data = await client.post(`/api/v1/investigation-runs/${investigation_run_id}/trace`, sendBody,
|
|
945
|
+
// A trace step is stored by its step_id, so a repeat updates it.
|
|
946
|
+
{ safeToRepeat: true });
|
|
700
947
|
requireReuseHintEcho(reuse_hint, data.steps?.[0]?.reuse_hint);
|
|
948
|
+
client.session.state.removeRecordedStep(investigation_run_id, step_id);
|
|
701
949
|
return {
|
|
702
950
|
content: [
|
|
703
951
|
{ type: "text", text: JSON.stringify(withNotice(data, notice)) },
|
|
@@ -714,13 +962,11 @@ export function registerInvestigationTools(server, client) {
|
|
|
714
962
|
server.registerTool("tellagen_list_trace_steps", {
|
|
715
963
|
description: "List trace steps already posted for an investigation run. Use this when resuming a run to avoid duplicate work.",
|
|
716
964
|
inputSchema: {
|
|
717
|
-
investigation_run_id:
|
|
718
|
-
.string()
|
|
719
|
-
.min(1)
|
|
720
|
-
.describe("Investigation run ID whose trace should be listed"),
|
|
965
|
+
investigation_run_id: optionalRunIdSchema,
|
|
721
966
|
},
|
|
722
|
-
}, async (
|
|
967
|
+
}, async (input) => {
|
|
723
968
|
try {
|
|
969
|
+
const investigation_run_id = resolveRunId(client, input.investigation_run_id);
|
|
724
970
|
const data = await client.get(`/api/v1/investigation-runs/${investigation_run_id}/trace`);
|
|
725
971
|
return {
|
|
726
972
|
content: [{ type: "text", text: JSON.stringify(data) }],
|
|
@@ -734,7 +980,7 @@ export function registerInvestigationTools(server, client) {
|
|
|
734
980
|
}
|
|
735
981
|
});
|
|
736
982
|
server.registerTool("tellagen_get_investigation_workspace", {
|
|
737
|
-
description: "
|
|
983
|
+
description: "Read the incident-level investigation workspace: all runs, findings, trace and review state. Use it for the big picture of an incident; use tellagen_get_incident_context for the bundle of one run. It changes nothing.",
|
|
738
984
|
inputSchema: {
|
|
739
985
|
incident_id: z.number().int().positive().describe("Incident ID"),
|
|
740
986
|
},
|
|
@@ -775,13 +1021,11 @@ export function registerInvestigationTools(server, client) {
|
|
|
775
1021
|
server.registerTool("tellagen_list_runbooks", {
|
|
776
1022
|
description: "List the runbooks/skills matched for an investigation run. Runbooks are guidance for the local agent, not executable code.",
|
|
777
1023
|
inputSchema: {
|
|
778
|
-
investigation_run_id:
|
|
779
|
-
.string()
|
|
780
|
-
.min(1)
|
|
781
|
-
.describe("Investigation run ID whose matched runbooks should be listed"),
|
|
1024
|
+
investigation_run_id: optionalRunIdSchema,
|
|
782
1025
|
},
|
|
783
|
-
}, async (
|
|
1026
|
+
}, async (input) => {
|
|
784
1027
|
try {
|
|
1028
|
+
const investigation_run_id = resolveRunId(client, input.investigation_run_id);
|
|
785
1029
|
const data = await client.get(`/api/v1/investigations/${investigation_run_id}/context`);
|
|
786
1030
|
const context = data;
|
|
787
1031
|
return {
|
|
@@ -801,7 +1045,7 @@ export function registerInvestigationTools(server, client) {
|
|
|
801
1045
|
}
|
|
802
1046
|
});
|
|
803
1047
|
server.registerTool("tellagen_list_investigation_runs", {
|
|
804
|
-
description: "List
|
|
1048
|
+
description: "List the investigation runs of an incident with each run's status, agent and finding count. Use it to find a run ID. For the bundle of one run, call tellagen_get_incident_context. It changes nothing.",
|
|
805
1049
|
inputSchema: {
|
|
806
1050
|
incident_id: z.number().int().positive().describe("Incident ID"),
|
|
807
1051
|
},
|
|
@@ -822,14 +1066,15 @@ export function registerInvestigationTools(server, client) {
|
|
|
822
1066
|
server.registerTool("tellagen_get_investigation_coverage", {
|
|
823
1067
|
description: "Preflight frozen runbook completion coverage for an active investigation. Use this before completion and after repairing missing checks or evidence; the response identifies exact missing check/evidence IDs and blocked sources.",
|
|
824
1068
|
inputSchema: {
|
|
825
|
-
investigation_run_id:
|
|
1069
|
+
investigation_run_id: optionalRunIdSchema,
|
|
826
1070
|
mitigation_state: z
|
|
827
1071
|
.enum(["none", "proposed", "applied", "recovered"])
|
|
828
1072
|
.optional()
|
|
829
1073
|
.describe("Current mitigation state. Applied or recovered requires the frozen remediation verification check."),
|
|
830
1074
|
},
|
|
831
|
-
}, async ({ investigation_run_id, mitigation_state }) => {
|
|
1075
|
+
}, async ({ investigation_run_id: givenRunId, mitigation_state }) => {
|
|
832
1076
|
try {
|
|
1077
|
+
const investigation_run_id = resolveRunId(client, givenRunId);
|
|
833
1078
|
const query = mitigation_state
|
|
834
1079
|
? `?mitigation_state=${encodeURIComponent(mitigation_state)}`
|
|
835
1080
|
: "";
|
|
@@ -848,10 +1093,11 @@ export function registerInvestigationTools(server, client) {
|
|
|
848
1093
|
server.registerTool("tellagen_list_investigation_runbook_waivers", {
|
|
849
1094
|
description: "List responder-created waivers for frozen runbook checks on an investigation. Waivers are read-only here and make covered completion explicitly inconclusive.",
|
|
850
1095
|
inputSchema: {
|
|
851
|
-
investigation_run_id:
|
|
1096
|
+
investigation_run_id: optionalRunIdSchema,
|
|
852
1097
|
},
|
|
853
|
-
}, async (
|
|
1098
|
+
}, async (input) => {
|
|
854
1099
|
try {
|
|
1100
|
+
const investigation_run_id = resolveRunId(client, input.investigation_run_id);
|
|
855
1101
|
const data = await client.get(`/api/v1/investigations/${investigation_run_id}/runbook-waivers`);
|
|
856
1102
|
return {
|
|
857
1103
|
content: [{ type: "text", text: JSON.stringify(data) }],
|
|
@@ -865,9 +1111,9 @@ export function registerInvestigationTools(server, client) {
|
|
|
865
1111
|
}
|
|
866
1112
|
});
|
|
867
1113
|
server.registerTool("tellagen_complete_investigation", {
|
|
868
|
-
description: 'Complete or fail an investigation run. Before you complete a run, post each cause with tellagen_update_cause, build figures with tellagen_build_figure, and post the key moment with tellagen_post_timeline_event. Set status to "completed" when done, or "failed" with a failure_reason if the investigation could not finish. Include result_summary for the shared RCA record whenever possible: causal_paths (2 to 4 steps, each citing finding_ids and a figure), ruled_out, coverage and unknowns, and for a regression or CI failure change_refs (the regression_source, the fix and the verified_by runs after it). The response carries the backend warnings[] verbatim
|
|
1114
|
+
description: 'Complete or fail an investigation run. Tellagen checks the result first, when it can: if something is missing, the answer is completed false with every repair at once (the field, what is missing, one example of a valid value), and nothing is changed; fix them and call again. Before you complete a run, post each cause with tellagen_update_cause, build figures with tellagen_build_figure, and post the key moment with tellagen_post_timeline_event. Set status to "completed" when done, or "failed" with a failure_reason if the investigation could not finish. Write the headline claim (result_summary.conclusion.sentence) in 15 words or fewer, with one cause, for example "The checkout pool size of 5 ran out of database connections at 14:02." and not a long sentence that lists the checks you made; the detail goes in the findings. Include result_summary for the shared RCA record whenever possible: causal_paths (2 to 4 steps, each citing finding_ids and a figure), ruled_out, coverage and unknowns, and for a regression or CI failure change_refs (the regression_source, the fix and the verified_by runs after it). The response carries the backend warnings[] verbatim and, only when there are warnings, a one-line warnings_summary; read it and name anything you could not fix in your report. result_summary must have conclusion, likely_cause_label, customer_impact, confidence_percent, signals_checked and takeaways, and should have assessment.diagnosis_state. The result can only propose a cause. A person accepts or rejects the root cause in Tellagen, and an API key cannot do it.',
|
|
869
1115
|
inputSchema: {
|
|
870
|
-
run_id:
|
|
1116
|
+
run_id: optionalRunIdSchema,
|
|
871
1117
|
status: z
|
|
872
1118
|
.enum(["completed", "failed"])
|
|
873
1119
|
.describe("Final status for the run"),
|
|
@@ -881,8 +1127,9 @@ export function registerInvestigationTools(server, client) {
|
|
|
881
1127
|
.describe('Explicit mitigation state for completed runs. Use "applied" or "recovered" only after posting the frozen verification check.'),
|
|
882
1128
|
result_summary: resultSummarySchema.optional(),
|
|
883
1129
|
},
|
|
884
|
-
}, async ({ run_id, status, failure_reason, mitigation_state, result_summary, }) => {
|
|
1130
|
+
}, async ({ run_id: givenRunId, status, failure_reason, mitigation_state, result_summary, }) => {
|
|
885
1131
|
try {
|
|
1132
|
+
const run_id = resolveRunId(client, givenRunId);
|
|
886
1133
|
const body = { status };
|
|
887
1134
|
if (failure_reason) {
|
|
888
1135
|
body.failure_reason = failure_reason;
|
|
@@ -910,9 +1157,63 @@ export function registerInvestigationTools(server, client) {
|
|
|
910
1157
|
body.result_summary = changes.summary;
|
|
911
1158
|
notices.push(unsupportedNotice(changes.removed, DIAGNOSIS_CHANGES_CAPABILITY));
|
|
912
1159
|
}
|
|
1160
|
+
// Unchanged lines and line numbers of a diff figure go only to a
|
|
1161
|
+
// backend that advertises diff_lines_v1; an older one drops the
|
|
1162
|
+
// whole figure (figure_invalid).
|
|
1163
|
+
const diffs = stripResultDiffLines(body.result_summary);
|
|
1164
|
+
if (diffs.removed.length > 0 &&
|
|
1165
|
+
!(await supportsDiffLines(client, run_id))) {
|
|
1166
|
+
body.result_summary = diffs.summary;
|
|
1167
|
+
notices.push(unsupportedNotice(diffs.removed, DIFF_LINES_CAPABILITY));
|
|
1168
|
+
}
|
|
1169
|
+
// A stats title, stats after the fourth and runs_not_shown go only
|
|
1170
|
+
// to a backend that advertises figure_extras_v1; an older one
|
|
1171
|
+
// rejects them and drops the whole figure (figure_invalid).
|
|
1172
|
+
const extras = stripResultFigureExtras(body.result_summary);
|
|
1173
|
+
if (extras.removed.length > 0 &&
|
|
1174
|
+
!(await supportsFigureExtras(client, run_id))) {
|
|
1175
|
+
body.result_summary = extras.summary;
|
|
1176
|
+
notices.push(unsupportedNotice(extras.removed, FIGURE_EXTRAS_CAPABILITY));
|
|
1177
|
+
}
|
|
913
1178
|
}
|
|
1179
|
+
const headline = headlineNotice(result_summary);
|
|
1180
|
+
if (headline)
|
|
1181
|
+
notices.push(headline);
|
|
914
1182
|
const notice = notices.length > 0 ? notices.join(" ") : undefined;
|
|
915
|
-
|
|
1183
|
+
// Ask first, when Tellagen can answer a dry run: one answer then holds
|
|
1184
|
+
// every fault, and the model repairs them in one go.
|
|
1185
|
+
let data;
|
|
1186
|
+
if (supportsCompletionRepairs(client, run_id)) {
|
|
1187
|
+
const dry = await client.patch(`/api/v1/investigations/${run_id}`, { ...body, dry_run: true },
|
|
1188
|
+
// A dry run writes nothing, so it is safe to repeat.
|
|
1189
|
+
{ safeToRepeat: true });
|
|
1190
|
+
if (dry.dry_run === true) {
|
|
1191
|
+
if (dry.ready !== true) {
|
|
1192
|
+
return {
|
|
1193
|
+
content: [
|
|
1194
|
+
{
|
|
1195
|
+
type: "text",
|
|
1196
|
+
text: JSON.stringify(withNotice({
|
|
1197
|
+
completed: false,
|
|
1198
|
+
ready: false,
|
|
1199
|
+
repairs: Array.isArray(dry.repairs) ? dry.repairs : [],
|
|
1200
|
+
...(Array.isArray(dry.warnings) && dry.warnings.length > 0 ? { warnings: dry.warnings } : {}),
|
|
1201
|
+
...(dry.coverage !== undefined ? { coverage: dry.coverage } : {}),
|
|
1202
|
+
message: "The run was not completed. Fix every repair (each has the field, what is missing and one example of a valid value), then call this tool again.",
|
|
1203
|
+
}, notice)),
|
|
1204
|
+
},
|
|
1205
|
+
],
|
|
1206
|
+
};
|
|
1207
|
+
}
|
|
1208
|
+
}
|
|
1209
|
+
else {
|
|
1210
|
+
// This Tellagen did not know the dry run and completed the run.
|
|
1211
|
+
data = dry;
|
|
1212
|
+
}
|
|
1213
|
+
}
|
|
1214
|
+
data ??= await client.patch(`/api/v1/investigations/${run_id}`, body);
|
|
1215
|
+
// The run is over: forget it, so the next run starts clean.
|
|
1216
|
+
client.session.clearActiveRun(run_id);
|
|
916
1217
|
const out = { ...data };
|
|
917
1218
|
const summary = summarizeWarnings(data.warnings);
|
|
918
1219
|
if (summary)
|