@tellagen/mcp-server 0.4.2 → 0.5.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/LICENSE +21 -0
- package/README.md +337 -104
- package/SKILL.md +83 -17
- 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 +257 -197
- package/dist/diagnosis-structure.js +144 -1
- 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 +312 -232
- 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 +221 -0
- package/dist/run-state.js +221 -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 +99 -0
- package/dist/session.js +187 -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/source-bases.d.ts +75 -0
- package/dist/source-bases.js +125 -0
- package/dist/source-bases.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 +71 -14
- 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 +75 -12
- 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 +372 -68
- 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.d.ts +16 -0
- package/dist/tools/source-links.js +25 -13
- 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 +9 -9
- 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,12 @@
|
|
|
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 { rememberSourceBases, sourceBasesOf } from "../source-bases.js";
|
|
6
|
+
import { legacyClientName, reportedClientName } from "../identity.js";
|
|
7
|
+
import { GUIDE_RESOURCES } from "../guide-resources.js";
|
|
8
|
+
import { protocolCapabilities, CAPABILITIES_HEADER, MCP_SERVER_VERSION, } from "../version.js";
|
|
9
|
+
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
10
|
const resultEvidenceRefSchema = z.object({
|
|
6
11
|
source: z.string().min(1),
|
|
7
12
|
query: z.string().optional(),
|
|
@@ -98,7 +103,9 @@ const resultSummarySchema = z
|
|
|
98
103
|
.object({
|
|
99
104
|
tone: z.enum(["success", "warning", "danger", "neutral"]),
|
|
100
105
|
eyebrow: z.string(),
|
|
101
|
-
sentence: z
|
|
106
|
+
sentence: z
|
|
107
|
+
.string()
|
|
108
|
+
.describe("The headline claim: 15 words or fewer, one cause. Put numbers and other causes in findings, causal_paths and ruled_out."),
|
|
102
109
|
show_new_investigation_cta: z.boolean(),
|
|
103
110
|
})
|
|
104
111
|
.describe("Short human-readable conclusion for the RCA record"),
|
|
@@ -245,20 +252,14 @@ function withCompletionChecklist(data) {
|
|
|
245
252
|
const capabilities = data.server_capabilities;
|
|
246
253
|
if (!Array.isArray(capabilities) || !capabilities.includes("diagnosis_structure_v1"))
|
|
247
254
|
return data;
|
|
255
|
+
// A Tellagen that answers a dry run lists the faults itself, when the model completes.
|
|
256
|
+
if (capabilities.includes(COMPLETION_REPAIRS_CAPABILITY))
|
|
257
|
+
return data;
|
|
248
258
|
return {
|
|
249
259
|
...data,
|
|
250
260
|
mcp_before_complete: BEFORE_COMPLETE_CHECKLIST,
|
|
251
261
|
};
|
|
252
262
|
}
|
|
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
263
|
function pickupProfileID() {
|
|
263
264
|
const value = (process.env.TELLAGEN_MCP_PROFILE_ID || "").trim();
|
|
264
265
|
if (!value)
|
|
@@ -268,6 +269,222 @@ function pickupProfileID() {
|
|
|
268
269
|
}
|
|
269
270
|
return value;
|
|
270
271
|
}
|
|
272
|
+
/** The data source kinds a client can say it has, by Tellagen catalog key. */
|
|
273
|
+
export const AVAILABLE_SOURCE_KEYS = ["grafana", "kubernetes", "github", "docs", "local_host"];
|
|
274
|
+
const availableSourceSchema = z
|
|
275
|
+
.object({
|
|
276
|
+
key: z.enum(AVAILABLE_SOURCE_KEYS).describe("Tellagen catalog key of the source"),
|
|
277
|
+
state: z.enum(["found", "not_found"]).describe("Whether this client can reach the source"),
|
|
278
|
+
detail: z
|
|
279
|
+
.string()
|
|
280
|
+
.trim()
|
|
281
|
+
.max(200)
|
|
282
|
+
.optional()
|
|
283
|
+
.describe("A short fact such as the Grafana host. Never a token, a password or a path with a user name."),
|
|
284
|
+
})
|
|
285
|
+
.strict();
|
|
286
|
+
function incidentIdOf(data) {
|
|
287
|
+
if (typeof data !== "object" || data === null)
|
|
288
|
+
return undefined;
|
|
289
|
+
const record = data;
|
|
290
|
+
const id = record.incident?.id ?? record.run?.incident_id;
|
|
291
|
+
return typeof id === "number" && Number.isInteger(id) && id > 0 ? id : undefined;
|
|
292
|
+
}
|
|
293
|
+
function capabilitiesOf(data) {
|
|
294
|
+
const list = data?.server_capabilities;
|
|
295
|
+
return Array.isArray(list) ? list.filter((item) => typeof item === "string") : [];
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* Attaches this process to a run and remembers it as the active run.
|
|
299
|
+
*
|
|
300
|
+
* The client name and version come from the MCP handshake. A Tellagen that
|
|
301
|
+
* does not know the newer pickup fields answers 400; the pickup is then sent
|
|
302
|
+
* once more in the old shape, with the name mapped to codex or claude.
|
|
303
|
+
* Pickup is safe to repeat, so both forms may be retried.
|
|
304
|
+
*/
|
|
305
|
+
export async function pickUpRun(client, runId, options = {}) {
|
|
306
|
+
const session = client.session;
|
|
307
|
+
const profileID = pickupProfileID();
|
|
308
|
+
const identity = session.identity;
|
|
309
|
+
const path = `/api/v1/investigations/${encodeURIComponent(runId)}/pickup`;
|
|
310
|
+
const capabilities = protocolCapabilities();
|
|
311
|
+
const body = {
|
|
312
|
+
client: {
|
|
313
|
+
name: reportedClientName(identity),
|
|
314
|
+
...(identity?.version ? { version: identity.version } : {}),
|
|
315
|
+
mcp_server_version: MCP_SERVER_VERSION,
|
|
316
|
+
...(session.computer ? { computer: session.computer } : {}),
|
|
317
|
+
...(profileID ? { profile_id: profileID } : {}),
|
|
318
|
+
session_id: session.sessionId,
|
|
319
|
+
},
|
|
320
|
+
protocol_capabilities: capabilities,
|
|
321
|
+
};
|
|
322
|
+
if (options.model)
|
|
323
|
+
body.model = options.model;
|
|
324
|
+
if (options.availableSources && options.availableSources.length > 0) {
|
|
325
|
+
body.available_sources = options.availableSources;
|
|
326
|
+
}
|
|
327
|
+
if (options.takeover)
|
|
328
|
+
body.takeover = true;
|
|
329
|
+
let data;
|
|
330
|
+
let notice;
|
|
331
|
+
try {
|
|
332
|
+
data = await client.post(path, body, { safeToRepeat: true });
|
|
333
|
+
}
|
|
334
|
+
catch (err) {
|
|
335
|
+
if (!(err instanceof TellagenAPIError))
|
|
336
|
+
throw err;
|
|
337
|
+
const sentName = reportedClientName(identity);
|
|
338
|
+
const legacyName = legacyClientName(identity);
|
|
339
|
+
const withLegacyName = { ...body, client: { ...body.client, name: legacyName } };
|
|
340
|
+
// Each fallback is sent one time. If it fails too, the first error is
|
|
341
|
+
// the one the model sees, so a real error is never hidden.
|
|
342
|
+
const fallback = async (send, text) => {
|
|
343
|
+
try {
|
|
344
|
+
data = await send();
|
|
345
|
+
notice = text;
|
|
346
|
+
}
|
|
347
|
+
catch {
|
|
348
|
+
throw err;
|
|
349
|
+
}
|
|
350
|
+
};
|
|
351
|
+
if (err.code === "pickup_client_context_mismatch" && legacyName !== sentName) {
|
|
352
|
+
// An earlier pickup froze the run for the old short name. Keep that
|
|
353
|
+
// name so the run can go on.
|
|
354
|
+
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}.`);
|
|
355
|
+
}
|
|
356
|
+
else if (err.status >= 500 && ![502, 503, 504].includes(err.status) && legacyName !== sentName) {
|
|
357
|
+
// A Tellagen that knows only codex and claude fails on another client
|
|
358
|
+
// name with a server error. Send the same pickup with the old name.
|
|
359
|
+
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.`);
|
|
360
|
+
}
|
|
361
|
+
else if (err.status === 400 && err.code === "unknown_field") {
|
|
362
|
+
// A Tellagen that refuses the newer pickup fields: send the old shape.
|
|
363
|
+
const dropped = [
|
|
364
|
+
"client.version",
|
|
365
|
+
"client.computer",
|
|
366
|
+
"client.session_id",
|
|
367
|
+
...(options.model ? ["model"] : []),
|
|
368
|
+
...(body.available_sources ? ["available_sources"] : []),
|
|
369
|
+
...(options.takeover ? ["takeover"] : []),
|
|
370
|
+
];
|
|
371
|
+
await fallback(() => client.post(path, {
|
|
372
|
+
client: {
|
|
373
|
+
name: legacyName,
|
|
374
|
+
mcp_server_version: MCP_SERVER_VERSION,
|
|
375
|
+
...(profileID ? { profile_id: profileID } : {}),
|
|
376
|
+
},
|
|
377
|
+
protocol_capabilities: capabilities,
|
|
378
|
+
}, { 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.`);
|
|
379
|
+
}
|
|
380
|
+
else {
|
|
381
|
+
throw err;
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
rememberServerCapabilities(client, runId, data);
|
|
385
|
+
noteUpdateAvailable(client, data);
|
|
386
|
+
session.setActiveRun({
|
|
387
|
+
runId,
|
|
388
|
+
incidentId: incidentIdOf(data),
|
|
389
|
+
pickedUpAt: new Date().toISOString(),
|
|
390
|
+
serverCapabilities: capabilitiesOf(data),
|
|
391
|
+
sourceBases: sourceBasesOf(data),
|
|
392
|
+
});
|
|
393
|
+
return withNotice(data, notice);
|
|
394
|
+
}
|
|
395
|
+
/** Remembers that Tellagen wants a newer server, so `status` and the session start can say so. */
|
|
396
|
+
function noteUpdateAvailable(client, data) {
|
|
397
|
+
if (typeof data !== "object" || data === null)
|
|
398
|
+
return;
|
|
399
|
+
const update = data.client_update_available;
|
|
400
|
+
if (typeof update !== "object" || update === null)
|
|
401
|
+
return;
|
|
402
|
+
const { your_version, current_version } = update;
|
|
403
|
+
if (typeof your_version === "string" && typeof current_version === "string") {
|
|
404
|
+
client.session.updateSeen?.({ your_version: your_version.slice(0, 40), current_version: current_version.slice(0, 40) });
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
/** Names the guide resources that apply to the run in a pickup answer. */
|
|
408
|
+
export function withRunGuides(input) {
|
|
409
|
+
// A lead from a past incident is cleaned and marked as untrusted data first.
|
|
410
|
+
const data = withCauseLead(input);
|
|
411
|
+
if (typeof data !== "object" || data === null || Array.isArray(data))
|
|
412
|
+
return data;
|
|
413
|
+
const skills = data.request?.skills;
|
|
414
|
+
const hasRunbooks = Array.isArray(skills) && skills.length > 0;
|
|
415
|
+
const resources = GUIDE_RESOURCES.filter((guide) => guide.when !== "runbooks" || hasRunbooks).map((guide) => ({ uri: guide.uri, read_when: guide.readWhen }));
|
|
416
|
+
return {
|
|
417
|
+
...data,
|
|
418
|
+
mcp_active_run: "This run is now the active run of this session. Later calls may leave investigation_run_id out.",
|
|
419
|
+
mcp_resources: resources,
|
|
420
|
+
};
|
|
421
|
+
}
|
|
422
|
+
/** Who holds the run, from the details of a run_has_active_client answer. */
|
|
423
|
+
function holderLine(payload) {
|
|
424
|
+
const details = payload && typeof payload.details === "object" && payload.details !== null
|
|
425
|
+
? payload.details
|
|
426
|
+
: {};
|
|
427
|
+
const part = (value, max) => typeof value === "string" ? value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, max) : "";
|
|
428
|
+
const holder = part(details.holder_name, 120) || "Another person";
|
|
429
|
+
const client = part(details.client_name, 80);
|
|
430
|
+
const computer = part(details.computer_name, 120);
|
|
431
|
+
const last = part(details.last_contact_at, 40);
|
|
432
|
+
return `${holder} runs this diagnosis${client ? ` in ${client}` : " in another client"}${computer ? ` on ${computer}` : ""}${last ? `, last contact at ${last}` : ""}.`;
|
|
433
|
+
}
|
|
434
|
+
const takeoverSchema = z
|
|
435
|
+
.boolean()
|
|
436
|
+
.optional()
|
|
437
|
+
.describe("Set true only after the person agreed that this session takes the run over from another client. Never set it on your own.");
|
|
438
|
+
function questionResult(code, message, extra = {}) {
|
|
439
|
+
return {
|
|
440
|
+
content: [
|
|
441
|
+
{
|
|
442
|
+
type: "text",
|
|
443
|
+
text: JSON.stringify({ ...extra, error: true, code, message, next_input: { takeover: true } }),
|
|
444
|
+
},
|
|
445
|
+
],
|
|
446
|
+
isError: true,
|
|
447
|
+
};
|
|
448
|
+
}
|
|
449
|
+
/**
|
|
450
|
+
* Pickup with the two questions a person must answer: a second session on
|
|
451
|
+
* this computer, and a run another client holds in Tellagen. The person is
|
|
452
|
+
* asked through the client when it can show a question; otherwise the model
|
|
453
|
+
* gets the question as the tool answer.
|
|
454
|
+
*/
|
|
455
|
+
export async function pickUpWithConsent(client, runId, options) {
|
|
456
|
+
const session = client.session;
|
|
457
|
+
let takeover = options.takeover === true;
|
|
458
|
+
const other = otherLiveSession(client, session.state.read());
|
|
459
|
+
if (other && other.run_id === runId && !takeover) {
|
|
460
|
+
const fact = joinFact(other);
|
|
461
|
+
const answer = await session.ask?.(`${fact} Should this session join the run?`);
|
|
462
|
+
if (answer !== true) {
|
|
463
|
+
return {
|
|
464
|
+
question: questionResult("run_open_in_other_session", answer === false
|
|
465
|
+
? "The person said no. Do not pick this run up in this session."
|
|
466
|
+
: `${fact} Ask the person whether this session should join the run. If they say yes, call the tool again with takeover set to true.`),
|
|
467
|
+
};
|
|
468
|
+
}
|
|
469
|
+
takeover = true;
|
|
470
|
+
}
|
|
471
|
+
try {
|
|
472
|
+
return { data: await pickUpRun(client, runId, { ...options, takeover }) };
|
|
473
|
+
}
|
|
474
|
+
catch (err) {
|
|
475
|
+
if (!(err instanceof TellagenAPIError) || err.code !== "run_has_active_client" || takeover)
|
|
476
|
+
throw err;
|
|
477
|
+
const fact = `${holderLine(err.payload)} Two clients on one run write over each other.`;
|
|
478
|
+
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.`;
|
|
479
|
+
const answer = await session.ask?.(`${fact} Should this session take the run over?`);
|
|
480
|
+
if (answer === true) {
|
|
481
|
+
return { data: await pickUpRun(client, runId, { ...options, takeover: true }) };
|
|
482
|
+
}
|
|
483
|
+
return {
|
|
484
|
+
question: questionResult("run_has_active_client", answer === false ? "The person said no. Do not pick this run up in this session." : question, err.payload ?? {}),
|
|
485
|
+
};
|
|
486
|
+
}
|
|
487
|
+
}
|
|
271
488
|
const investigationScopeSchema = z
|
|
272
489
|
.object({
|
|
273
490
|
services: z
|
|
@@ -364,7 +581,7 @@ const investigationGuidanceSchema = z
|
|
|
364
581
|
})
|
|
365
582
|
.strict(),
|
|
366
583
|
])
|
|
367
|
-
.describe("
|
|
584
|
+
.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
585
|
function isDiagnosticSessionID(id) {
|
|
369
586
|
return id.trim().startsWith("diag_");
|
|
370
587
|
}
|
|
@@ -386,7 +603,7 @@ function diagnosticSessionIDError(id) {
|
|
|
386
603
|
}
|
|
387
604
|
export function registerInvestigationTools(server, client) {
|
|
388
605
|
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.",
|
|
606
|
+
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
607
|
inputSchema: {
|
|
391
608
|
incident_id: z.number().int().positive().describe("Incident ID"),
|
|
392
609
|
agent_name: z
|
|
@@ -443,7 +660,9 @@ export function registerInvestigationTools(server, client) {
|
|
|
443
660
|
if (question_finding_id !== undefined) {
|
|
444
661
|
body.question_finding_id = question_finding_id;
|
|
445
662
|
}
|
|
446
|
-
|
|
663
|
+
// This request has no picked-up run, so the capabilities go in a header.
|
|
664
|
+
const caps = protocolCapabilities().filter((name) => name === "strict_fields_v1");
|
|
665
|
+
const data = await client.post(`/api/v1/incidents/${incident_id}/investigations`, body, caps.length > 0 ? { headers: { [CAPABILITIES_HEADER]: caps.join(",") } } : undefined);
|
|
447
666
|
return {
|
|
448
667
|
content: [{ type: "text", text: JSON.stringify(data) }],
|
|
449
668
|
};
|
|
@@ -456,17 +675,16 @@ export function registerInvestigationTools(server, client) {
|
|
|
456
675
|
}
|
|
457
676
|
});
|
|
458
677
|
server.registerTool("tellagen_get_incident_context", {
|
|
459
|
-
description: "
|
|
678
|
+
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
679
|
inputSchema: {
|
|
461
|
-
investigation_run_id:
|
|
462
|
-
.string()
|
|
463
|
-
.min(1)
|
|
464
|
-
.describe("Investigation run ID from Tellagen"),
|
|
680
|
+
investigation_run_id: optionalRunIdSchema,
|
|
465
681
|
},
|
|
466
|
-
}, async (
|
|
682
|
+
}, async (input) => {
|
|
467
683
|
try {
|
|
684
|
+
const investigation_run_id = resolveRunId(client, input.investigation_run_id);
|
|
468
685
|
const data = await client.get(`/api/v1/investigations/${investigation_run_id}/context`);
|
|
469
686
|
rememberServerCapabilities(client, investigation_run_id, data);
|
|
687
|
+
rememberSourceBases(client, investigation_run_id, data);
|
|
470
688
|
return {
|
|
471
689
|
content: [{ type: "text", text: JSON.stringify(data) }],
|
|
472
690
|
};
|
|
@@ -479,31 +697,48 @@ export function registerInvestigationTools(server, client) {
|
|
|
479
697
|
}
|
|
480
698
|
});
|
|
481
699
|
server.registerTool("tellagen_pick_up_investigation", {
|
|
482
|
-
description: "Attach this
|
|
700
|
+
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
701
|
inputSchema: {
|
|
484
702
|
investigation_run_id: z
|
|
485
703
|
.string()
|
|
486
704
|
.min(1)
|
|
487
|
-
.
|
|
705
|
+
.optional()
|
|
706
|
+
.describe("Investigation run ID from Tellagen. Leave it out to pick the active run of this session up again."),
|
|
707
|
+
model: z
|
|
708
|
+
.string()
|
|
709
|
+
.trim()
|
|
710
|
+
.min(1)
|
|
711
|
+
.max(100)
|
|
712
|
+
.optional()
|
|
713
|
+
.describe("Your own model name as you know it, for example from your system prompt. Tellagen shows it on the run."),
|
|
714
|
+
available_sources: z
|
|
715
|
+
.array(availableSourceSchema)
|
|
716
|
+
.max(20)
|
|
717
|
+
.optional()
|
|
718
|
+
.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."),
|
|
719
|
+
takeover: takeoverSchema,
|
|
488
720
|
},
|
|
489
|
-
}, async (
|
|
490
|
-
if (isDiagnosticSessionID(investigation_run_id)) {
|
|
491
|
-
|
|
721
|
+
}, async (input) => {
|
|
722
|
+
if (input.investigation_run_id && isDiagnosticSessionID(input.investigation_run_id)) {
|
|
723
|
+
// The tool check tools are in the settings toolset.
|
|
724
|
+
client.session.toolsets?.enable("settings");
|
|
725
|
+
return diagnosticSessionIDError(input.investigation_run_id);
|
|
492
726
|
}
|
|
493
727
|
try {
|
|
494
|
-
const
|
|
495
|
-
const
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
...(profileID ? { profile_id: profileID } : {}),
|
|
500
|
-
},
|
|
501
|
-
protocol_capabilities: [...INVESTIGATION_PROTOCOL_CAPABILITIES],
|
|
728
|
+
const runId = resolveRunId(client, input.investigation_run_id);
|
|
729
|
+
const outcome = await pickUpWithConsent(client, runId, {
|
|
730
|
+
model: input.model,
|
|
731
|
+
takeover: input.takeover,
|
|
732
|
+
availableSources: input.available_sources,
|
|
502
733
|
});
|
|
503
|
-
|
|
734
|
+
if ("question" in outcome)
|
|
735
|
+
return outcome.question;
|
|
504
736
|
return {
|
|
505
737
|
content: [
|
|
506
|
-
{
|
|
738
|
+
{
|
|
739
|
+
type: "text",
|
|
740
|
+
text: JSON.stringify(withRunGuides(withCompletionChecklist(withAttachmentHint(outcome.data)))),
|
|
741
|
+
},
|
|
507
742
|
],
|
|
508
743
|
};
|
|
509
744
|
}
|
|
@@ -517,7 +752,7 @@ export function registerInvestigationTools(server, client) {
|
|
|
517
752
|
server.registerTool("tellagen_post_runbook_check_attempt", {
|
|
518
753
|
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
754
|
inputSchema: {
|
|
520
|
-
investigation_run_id:
|
|
755
|
+
investigation_run_id: optionalRunIdSchema,
|
|
521
756
|
runbook_id: z.number().int().positive(),
|
|
522
757
|
runbook_version: z.number().int().positive(),
|
|
523
758
|
check_id: z.string().min(1),
|
|
@@ -559,8 +794,9 @@ export function registerInvestigationTools(server, client) {
|
|
|
559
794
|
duration_ms: z.number().int().min(0).optional(),
|
|
560
795
|
},
|
|
561
796
|
}, async (input) => {
|
|
562
|
-
const { investigation_run_id, ...fields } = input;
|
|
797
|
+
const { investigation_run_id: givenRunId, ...fields } = input;
|
|
563
798
|
try {
|
|
799
|
+
const investigation_run_id = resolveRunId(client, givenRunId);
|
|
564
800
|
validateTraceReuseHintInput(input);
|
|
565
801
|
const data = await client.post(`/api/v1/investigation-runs/${investigation_run_id}/check-attempts`, {
|
|
566
802
|
...fields,
|
|
@@ -582,16 +818,13 @@ export function registerInvestigationTools(server, client) {
|
|
|
582
818
|
server.registerTool("tellagen_post_trace_step", {
|
|
583
819
|
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
820
|
inputSchema: {
|
|
585
|
-
investigation_run_id:
|
|
586
|
-
.string()
|
|
587
|
-
.min(1)
|
|
588
|
-
.describe("Active investigation run ID"),
|
|
821
|
+
investigation_run_id: optionalRunIdSchema,
|
|
589
822
|
step_id: z
|
|
590
823
|
.string()
|
|
591
824
|
.refine((value) => value.trim().length > 0, {
|
|
592
825
|
message: "step_id must not be blank",
|
|
593
826
|
})
|
|
594
|
-
.describe(
|
|
827
|
+
.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
828
|
step_index: z
|
|
596
829
|
.number()
|
|
597
830
|
.int()
|
|
@@ -621,7 +854,7 @@ export function registerInvestigationTools(server, client) {
|
|
|
621
854
|
reuse_hint: traceReuseHintSchema.optional(),
|
|
622
855
|
result_bytes: z.number().int().min(0).optional(),
|
|
623
856
|
truncated: z.boolean().optional(),
|
|
624
|
-
guidance: investigationGuidanceSchema,
|
|
857
|
+
guidance: investigationGuidanceSchema.optional(),
|
|
625
858
|
...traceStructureShape,
|
|
626
859
|
error: z.string().optional(),
|
|
627
860
|
started_at: z
|
|
@@ -636,8 +869,17 @@ export function registerInvestigationTools(server, client) {
|
|
|
636
869
|
.describe("ISO timestamp when the step completed"),
|
|
637
870
|
duration_ms: z.number().int().min(0).optional(),
|
|
638
871
|
},
|
|
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, }) => {
|
|
872
|
+
}, 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
873
|
try {
|
|
874
|
+
const investigation_run_id = resolveRunId(client, givenRunId);
|
|
875
|
+
let step_id = givenStepId;
|
|
876
|
+
if (step_id.trim() === "recorded:latest") {
|
|
877
|
+
const recorded = client.session.state.recordedSteps(investigation_run_id).at(-1);
|
|
878
|
+
if (!recorded) {
|
|
879
|
+
throw new Error("No step was recorded by a hook for this run. Post the step yourself with a step_id of your own.");
|
|
880
|
+
}
|
|
881
|
+
step_id = recorded.step_id;
|
|
882
|
+
}
|
|
641
883
|
validateTraceReuseHintInput({
|
|
642
884
|
status,
|
|
643
885
|
result_summary,
|
|
@@ -651,8 +893,14 @@ export function registerInvestigationTools(server, client) {
|
|
|
651
893
|
step_index: step_index ?? 0,
|
|
652
894
|
status,
|
|
653
895
|
title,
|
|
654
|
-
guidance,
|
|
655
896
|
};
|
|
897
|
+
if (guidance !== undefined) {
|
|
898
|
+
body.guidance = guidance;
|
|
899
|
+
}
|
|
900
|
+
else if (!knownCapability(client, investigation_run_id, RECORDED_STEPS_CAPABILITY)) {
|
|
901
|
+
// An older Tellagen has no default basis: send the one it would store.
|
|
902
|
+
body.guidance = { origin: "agent_judgment", refs: [], reason: title.trim().slice(0, 500) };
|
|
903
|
+
}
|
|
656
904
|
if (tool_name !== undefined)
|
|
657
905
|
body.tool_name = tool_name;
|
|
658
906
|
if (tool_use_id !== undefined)
|
|
@@ -696,8 +944,11 @@ export function registerInvestigationTools(server, client) {
|
|
|
696
944
|
notice = unsupportedNotice(stripped.removed);
|
|
697
945
|
}
|
|
698
946
|
}
|
|
699
|
-
const data = await client.post(`/api/v1/investigation-runs/${investigation_run_id}/trace`, sendBody
|
|
947
|
+
const data = await client.post(`/api/v1/investigation-runs/${investigation_run_id}/trace`, sendBody,
|
|
948
|
+
// A trace step is stored by its step_id, so a repeat updates it.
|
|
949
|
+
{ safeToRepeat: true });
|
|
700
950
|
requireReuseHintEcho(reuse_hint, data.steps?.[0]?.reuse_hint);
|
|
951
|
+
client.session.state.removeRecordedStep(investigation_run_id, step_id);
|
|
701
952
|
return {
|
|
702
953
|
content: [
|
|
703
954
|
{ type: "text", text: JSON.stringify(withNotice(data, notice)) },
|
|
@@ -714,13 +965,11 @@ export function registerInvestigationTools(server, client) {
|
|
|
714
965
|
server.registerTool("tellagen_list_trace_steps", {
|
|
715
966
|
description: "List trace steps already posted for an investigation run. Use this when resuming a run to avoid duplicate work.",
|
|
716
967
|
inputSchema: {
|
|
717
|
-
investigation_run_id:
|
|
718
|
-
.string()
|
|
719
|
-
.min(1)
|
|
720
|
-
.describe("Investigation run ID whose trace should be listed"),
|
|
968
|
+
investigation_run_id: optionalRunIdSchema,
|
|
721
969
|
},
|
|
722
|
-
}, async (
|
|
970
|
+
}, async (input) => {
|
|
723
971
|
try {
|
|
972
|
+
const investigation_run_id = resolveRunId(client, input.investigation_run_id);
|
|
724
973
|
const data = await client.get(`/api/v1/investigation-runs/${investigation_run_id}/trace`);
|
|
725
974
|
return {
|
|
726
975
|
content: [{ type: "text", text: JSON.stringify(data) }],
|
|
@@ -734,7 +983,7 @@ export function registerInvestigationTools(server, client) {
|
|
|
734
983
|
}
|
|
735
984
|
});
|
|
736
985
|
server.registerTool("tellagen_get_investigation_workspace", {
|
|
737
|
-
description: "
|
|
986
|
+
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
987
|
inputSchema: {
|
|
739
988
|
incident_id: z.number().int().positive().describe("Incident ID"),
|
|
740
989
|
},
|
|
@@ -775,13 +1024,11 @@ export function registerInvestigationTools(server, client) {
|
|
|
775
1024
|
server.registerTool("tellagen_list_runbooks", {
|
|
776
1025
|
description: "List the runbooks/skills matched for an investigation run. Runbooks are guidance for the local agent, not executable code.",
|
|
777
1026
|
inputSchema: {
|
|
778
|
-
investigation_run_id:
|
|
779
|
-
.string()
|
|
780
|
-
.min(1)
|
|
781
|
-
.describe("Investigation run ID whose matched runbooks should be listed"),
|
|
1027
|
+
investigation_run_id: optionalRunIdSchema,
|
|
782
1028
|
},
|
|
783
|
-
}, async (
|
|
1029
|
+
}, async (input) => {
|
|
784
1030
|
try {
|
|
1031
|
+
const investigation_run_id = resolveRunId(client, input.investigation_run_id);
|
|
785
1032
|
const data = await client.get(`/api/v1/investigations/${investigation_run_id}/context`);
|
|
786
1033
|
const context = data;
|
|
787
1034
|
return {
|
|
@@ -801,7 +1048,7 @@ export function registerInvestigationTools(server, client) {
|
|
|
801
1048
|
}
|
|
802
1049
|
});
|
|
803
1050
|
server.registerTool("tellagen_list_investigation_runs", {
|
|
804
|
-
description: "List
|
|
1051
|
+
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
1052
|
inputSchema: {
|
|
806
1053
|
incident_id: z.number().int().positive().describe("Incident ID"),
|
|
807
1054
|
},
|
|
@@ -822,14 +1069,15 @@ export function registerInvestigationTools(server, client) {
|
|
|
822
1069
|
server.registerTool("tellagen_get_investigation_coverage", {
|
|
823
1070
|
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
1071
|
inputSchema: {
|
|
825
|
-
investigation_run_id:
|
|
1072
|
+
investigation_run_id: optionalRunIdSchema,
|
|
826
1073
|
mitigation_state: z
|
|
827
1074
|
.enum(["none", "proposed", "applied", "recovered"])
|
|
828
1075
|
.optional()
|
|
829
1076
|
.describe("Current mitigation state. Applied or recovered requires the frozen remediation verification check."),
|
|
830
1077
|
},
|
|
831
|
-
}, async ({ investigation_run_id, mitigation_state }) => {
|
|
1078
|
+
}, async ({ investigation_run_id: givenRunId, mitigation_state }) => {
|
|
832
1079
|
try {
|
|
1080
|
+
const investigation_run_id = resolveRunId(client, givenRunId);
|
|
833
1081
|
const query = mitigation_state
|
|
834
1082
|
? `?mitigation_state=${encodeURIComponent(mitigation_state)}`
|
|
835
1083
|
: "";
|
|
@@ -848,10 +1096,11 @@ export function registerInvestigationTools(server, client) {
|
|
|
848
1096
|
server.registerTool("tellagen_list_investigation_runbook_waivers", {
|
|
849
1097
|
description: "List responder-created waivers for frozen runbook checks on an investigation. Waivers are read-only here and make covered completion explicitly inconclusive.",
|
|
850
1098
|
inputSchema: {
|
|
851
|
-
investigation_run_id:
|
|
1099
|
+
investigation_run_id: optionalRunIdSchema,
|
|
852
1100
|
},
|
|
853
|
-
}, async (
|
|
1101
|
+
}, async (input) => {
|
|
854
1102
|
try {
|
|
1103
|
+
const investigation_run_id = resolveRunId(client, input.investigation_run_id);
|
|
855
1104
|
const data = await client.get(`/api/v1/investigations/${investigation_run_id}/runbook-waivers`);
|
|
856
1105
|
return {
|
|
857
1106
|
content: [{ type: "text", text: JSON.stringify(data) }],
|
|
@@ -865,9 +1114,9 @@ export function registerInvestigationTools(server, client) {
|
|
|
865
1114
|
}
|
|
866
1115
|
});
|
|
867
1116
|
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 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.',
|
|
1117
|
+
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
1118
|
inputSchema: {
|
|
870
|
-
run_id:
|
|
1119
|
+
run_id: optionalRunIdSchema,
|
|
871
1120
|
status: z
|
|
872
1121
|
.enum(["completed", "failed"])
|
|
873
1122
|
.describe("Final status for the run"),
|
|
@@ -881,8 +1130,9 @@ export function registerInvestigationTools(server, client) {
|
|
|
881
1130
|
.describe('Explicit mitigation state for completed runs. Use "applied" or "recovered" only after posting the frozen verification check.'),
|
|
882
1131
|
result_summary: resultSummarySchema.optional(),
|
|
883
1132
|
},
|
|
884
|
-
}, async ({ run_id, status, failure_reason, mitigation_state, result_summary, }) => {
|
|
1133
|
+
}, async ({ run_id: givenRunId, status, failure_reason, mitigation_state, result_summary, }) => {
|
|
885
1134
|
try {
|
|
1135
|
+
const run_id = resolveRunId(client, givenRunId);
|
|
886
1136
|
const body = { status };
|
|
887
1137
|
if (failure_reason) {
|
|
888
1138
|
body.failure_reason = failure_reason;
|
|
@@ -910,9 +1160,63 @@ export function registerInvestigationTools(server, client) {
|
|
|
910
1160
|
body.result_summary = changes.summary;
|
|
911
1161
|
notices.push(unsupportedNotice(changes.removed, DIAGNOSIS_CHANGES_CAPABILITY));
|
|
912
1162
|
}
|
|
1163
|
+
// Unchanged lines and line numbers of a diff figure go only to a
|
|
1164
|
+
// backend that advertises diff_lines_v1; an older one drops the
|
|
1165
|
+
// whole figure (figure_invalid).
|
|
1166
|
+
const diffs = stripResultDiffLines(body.result_summary);
|
|
1167
|
+
if (diffs.removed.length > 0 &&
|
|
1168
|
+
!(await supportsDiffLines(client, run_id))) {
|
|
1169
|
+
body.result_summary = diffs.summary;
|
|
1170
|
+
notices.push(unsupportedNotice(diffs.removed, DIFF_LINES_CAPABILITY));
|
|
1171
|
+
}
|
|
1172
|
+
// A stats title, stats after the fourth and runs_not_shown go only
|
|
1173
|
+
// to a backend that advertises figure_extras_v1; an older one
|
|
1174
|
+
// rejects them and drops the whole figure (figure_invalid).
|
|
1175
|
+
const extras = stripResultFigureExtras(body.result_summary);
|
|
1176
|
+
if (extras.removed.length > 0 &&
|
|
1177
|
+
!(await supportsFigureExtras(client, run_id))) {
|
|
1178
|
+
body.result_summary = extras.summary;
|
|
1179
|
+
notices.push(unsupportedNotice(extras.removed, FIGURE_EXTRAS_CAPABILITY));
|
|
1180
|
+
}
|
|
913
1181
|
}
|
|
1182
|
+
const headline = headlineNotice(result_summary);
|
|
1183
|
+
if (headline)
|
|
1184
|
+
notices.push(headline);
|
|
914
1185
|
const notice = notices.length > 0 ? notices.join(" ") : undefined;
|
|
915
|
-
|
|
1186
|
+
// Ask first, when Tellagen can answer a dry run: one answer then holds
|
|
1187
|
+
// every fault, and the model repairs them in one go.
|
|
1188
|
+
let data;
|
|
1189
|
+
if (supportsCompletionRepairs(client, run_id)) {
|
|
1190
|
+
const dry = await client.patch(`/api/v1/investigations/${run_id}`, { ...body, dry_run: true },
|
|
1191
|
+
// A dry run writes nothing, so it is safe to repeat.
|
|
1192
|
+
{ safeToRepeat: true });
|
|
1193
|
+
if (dry.dry_run === true) {
|
|
1194
|
+
if (dry.ready !== true) {
|
|
1195
|
+
return {
|
|
1196
|
+
content: [
|
|
1197
|
+
{
|
|
1198
|
+
type: "text",
|
|
1199
|
+
text: JSON.stringify(withNotice({
|
|
1200
|
+
completed: false,
|
|
1201
|
+
ready: false,
|
|
1202
|
+
repairs: Array.isArray(dry.repairs) ? dry.repairs : [],
|
|
1203
|
+
...(Array.isArray(dry.warnings) && dry.warnings.length > 0 ? { warnings: dry.warnings } : {}),
|
|
1204
|
+
...(dry.coverage !== undefined ? { coverage: dry.coverage } : {}),
|
|
1205
|
+
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.",
|
|
1206
|
+
}, notice)),
|
|
1207
|
+
},
|
|
1208
|
+
],
|
|
1209
|
+
};
|
|
1210
|
+
}
|
|
1211
|
+
}
|
|
1212
|
+
else {
|
|
1213
|
+
// This Tellagen did not know the dry run and completed the run.
|
|
1214
|
+
data = dry;
|
|
1215
|
+
}
|
|
1216
|
+
}
|
|
1217
|
+
data ??= await client.patch(`/api/v1/investigations/${run_id}`, body);
|
|
1218
|
+
// The run is over: forget it, so the next run starts clean.
|
|
1219
|
+
client.session.clearActiveRun(run_id);
|
|
916
1220
|
const out = { ...data };
|
|
917
1221
|
const summary = summarizeWarnings(data.warnings);
|
|
918
1222
|
if (summary)
|