@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.
Files changed (184) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +337 -104
  3. package/SKILL.md +83 -17
  4. package/contracts/mcp-protocol.json +155 -0
  5. package/contracts/runbooks/manifest.json +26 -6
  6. package/contracts/runbooks/v2/cause-lead.guidance.json +37 -0
  7. package/contracts/runbooks/v2/client-protocol.json +926 -0
  8. package/contracts/runbooks/v2/client-writes.guidance.json +42 -0
  9. package/contracts/runbooks/v2/fixtures/timeline-event-blocks-rejected.json +30 -5
  10. package/contracts/runbooks/v2/result-summary.guidance.json +21 -0
  11. package/contracts/runbooks/v2/timeline-event-blocks.schema.json +18 -11
  12. package/contracts/tellagen-runbook-contracts.json +4 -4
  13. package/dist/active-run.d.ts +29 -0
  14. package/dist/active-run.js +67 -0
  15. package/dist/active-run.js.map +1 -0
  16. package/dist/bootstrap.d.ts +20 -0
  17. package/dist/bootstrap.js +29 -0
  18. package/dist/bootstrap.js.map +1 -0
  19. package/dist/cause-lead.d.ts +25 -0
  20. package/dist/cause-lead.js +145 -0
  21. package/dist/cause-lead.js.map +1 -0
  22. package/dist/cli/auth.d.ts +22 -0
  23. package/dist/cli/auth.js +207 -0
  24. package/dist/cli/auth.js.map +1 -0
  25. package/dist/cli/io.d.ts +16 -0
  26. package/dist/cli/io.js +53 -0
  27. package/dist/cli/io.js.map +1 -0
  28. package/dist/cli/listen-guard.d.ts +12 -0
  29. package/dist/cli/listen-guard.js +50 -0
  30. package/dist/cli/listen-guard.js.map +1 -0
  31. package/dist/cli/listen.d.ts +28 -0
  32. package/dist/cli/listen.js +205 -0
  33. package/dist/cli/listen.js.map +1 -0
  34. package/dist/cli/main.d.ts +3 -0
  35. package/dist/cli/main.js +53 -0
  36. package/dist/cli/main.js.map +1 -0
  37. package/dist/cli/trace-hook.d.ts +23 -0
  38. package/dist/cli/trace-hook.js +99 -0
  39. package/dist/cli/trace-hook.js.map +1 -0
  40. package/dist/client.d.ts +92 -6
  41. package/dist/client.js +300 -23
  42. package/dist/client.js.map +1 -1
  43. package/dist/config.d.ts +17 -0
  44. package/dist/config.js +38 -0
  45. package/dist/config.js.map +1 -0
  46. package/dist/credentials.d.ts +120 -0
  47. package/dist/credentials.js +363 -0
  48. package/dist/credentials.js.map +1 -0
  49. package/dist/diagnosis-structure.d.ts +257 -197
  50. package/dist/diagnosis-structure.js +144 -1
  51. package/dist/diagnosis-structure.js.map +1 -1
  52. package/dist/diff-figure.d.ts +56 -0
  53. package/dist/diff-figure.js +276 -0
  54. package/dist/diff-figure.js.map +1 -0
  55. package/dist/errors.d.ts +21 -0
  56. package/dist/errors.js +60 -0
  57. package/dist/errors.js.map +1 -1
  58. package/dist/figures.d.ts +312 -232
  59. package/dist/figures.js +189 -47
  60. package/dist/figures.js.map +1 -1
  61. package/dist/guide-resources.d.ts +28 -0
  62. package/dist/guide-resources.js +81 -0
  63. package/dist/guide-resources.js.map +1 -0
  64. package/dist/heartbeat.d.ts +24 -0
  65. package/dist/heartbeat.js +94 -0
  66. package/dist/heartbeat.js.map +1 -0
  67. package/dist/home.d.ts +8 -0
  68. package/dist/home.js +14 -0
  69. package/dist/home.js.map +1 -0
  70. package/dist/identity.d.ts +32 -0
  71. package/dist/identity.js +83 -0
  72. package/dist/identity.js.map +1 -0
  73. package/dist/index.js +46 -14
  74. package/dist/index.js.map +1 -1
  75. package/dist/listen-config.d.ts +67 -0
  76. package/dist/listen-config.js +83 -0
  77. package/dist/listen-config.js.map +1 -0
  78. package/dist/listen-probe.d.ts +57 -0
  79. package/dist/listen-probe.js +158 -0
  80. package/dist/listen-probe.js.map +1 -0
  81. package/dist/listen-rules.d.ts +88 -0
  82. package/dist/listen-rules.js +252 -0
  83. package/dist/listen-rules.js.map +1 -0
  84. package/dist/listen-settings.d.ts +18 -0
  85. package/dist/listen-settings.js +50 -0
  86. package/dist/listen-settings.js.map +1 -0
  87. package/dist/listen-wrap.d.ts +21 -0
  88. package/dist/listen-wrap.js +52 -0
  89. package/dist/listen-wrap.js.map +1 -0
  90. package/dist/listener.d.ts +195 -0
  91. package/dist/listener.js +600 -0
  92. package/dist/listener.js.map +1 -0
  93. package/dist/open-run.d.ts +2 -0
  94. package/dist/open-run.js +5 -0
  95. package/dist/open-run.js.map +1 -0
  96. package/dist/prompts.d.ts +12 -0
  97. package/dist/prompts.js +37 -0
  98. package/dist/prompts.js.map +1 -0
  99. package/dist/redact.d.ts +13 -0
  100. package/dist/redact.js +76 -0
  101. package/dist/redact.js.map +1 -0
  102. package/dist/run-events.d.ts +54 -0
  103. package/dist/run-events.js +210 -0
  104. package/dist/run-events.js.map +1 -0
  105. package/dist/run-state.d.ts +221 -0
  106. package/dist/run-state.js +221 -0
  107. package/dist/run-state.js.map +1 -0
  108. package/dist/server.d.ts +22 -2
  109. package/dist/server.js +137 -29
  110. package/dist/server.js.map +1 -1
  111. package/dist/session.d.ts +99 -0
  112. package/dist/session.js +187 -0
  113. package/dist/session.js.map +1 -0
  114. package/dist/shell-rules.d.ts +49 -0
  115. package/dist/shell-rules.js +335 -0
  116. package/dist/shell-rules.js.map +1 -0
  117. package/dist/signin-index.d.ts +164 -0
  118. package/dist/signin-index.js +116 -0
  119. package/dist/signin-index.js.map +1 -0
  120. package/dist/signin.d.ts +169 -0
  121. package/dist/signin.js +541 -0
  122. package/dist/signin.js.map +1 -0
  123. package/dist/source-bases.d.ts +75 -0
  124. package/dist/source-bases.js +125 -0
  125. package/dist/source-bases.js.map +1 -0
  126. package/dist/start.d.ts +7 -6
  127. package/dist/start.js +14 -7
  128. package/dist/start.js.map +1 -1
  129. package/dist/tools/catalog.d.ts +44 -0
  130. package/dist/tools/catalog.js +105 -0
  131. package/dist/tools/catalog.js.map +1 -0
  132. package/dist/tools/causes.d.ts +6 -6
  133. package/dist/tools/causes.js +4 -5
  134. package/dist/tools/causes.js.map +1 -1
  135. package/dist/tools/context.js +5 -5
  136. package/dist/tools/context.js.map +1 -1
  137. package/dist/tools/datasources.js +71 -14
  138. package/dist/tools/datasources.js.map +1 -1
  139. package/dist/tools/diagnostics.js +2 -2
  140. package/dist/tools/diagnostics.js.map +1 -1
  141. package/dist/tools/figures.d.ts +3 -2
  142. package/dist/tools/figures.js +38 -13
  143. package/dist/tools/figures.js.map +1 -1
  144. package/dist/tools/findings.d.ts +28 -0
  145. package/dist/tools/findings.js +75 -12
  146. package/dist/tools/findings.js.map +1 -1
  147. package/dist/tools/incidents.js +5 -5
  148. package/dist/tools/incidents.js.map +1 -1
  149. package/dist/tools/index.d.ts +19 -2
  150. package/dist/tools/index.js +115 -14
  151. package/dist/tools/index.js.map +1 -1
  152. package/dist/tools/investigations.d.ts +54 -0
  153. package/dist/tools/investigations.js +372 -68
  154. package/dist/tools/investigations.js.map +1 -1
  155. package/dist/tools/next.d.ts +20 -0
  156. package/dist/tools/next.js +136 -0
  157. package/dist/tools/next.js.map +1 -0
  158. package/dist/tools/postmortem-runbooks.d.ts +52 -52
  159. package/dist/tools/postmortem-runbooks.js +3 -10
  160. package/dist/tools/postmortem-runbooks.js.map +1 -1
  161. package/dist/tools/resume.d.ts +5 -0
  162. package/dist/tools/resume.js +136 -0
  163. package/dist/tools/resume.js.map +1 -0
  164. package/dist/tools/signin.d.ts +12 -0
  165. package/dist/tools/signin.js +54 -0
  166. package/dist/tools/signin.js.map +1 -0
  167. package/dist/tools/source-links.d.ts +16 -0
  168. package/dist/tools/source-links.js +25 -13
  169. package/dist/tools/source-links.js.map +1 -1
  170. package/dist/tools/timeline.js +57 -11
  171. package/dist/tools/timeline.js.map +1 -1
  172. package/dist/trace-record.d.ts +36 -0
  173. package/dist/trace-record.js +283 -0
  174. package/dist/trace-record.js.map +1 -0
  175. package/dist/version.d.ts +10 -2
  176. package/dist/version.js +20 -1
  177. package/dist/version.js.map +1 -1
  178. package/package.json +23 -3
  179. package/server.json +9 -9
  180. package/contracts/runbooks/v1/fixtures/global-runbook.json +0 -7
  181. package/contracts/runbooks/v1/runbook-definition.schema.json +0 -25
  182. package/dist/auth.d.ts +0 -7
  183. package/dist/auth.js +0 -19
  184. package/dist/auth.js.map +0 -1
@@ -0,0 +1,12 @@
1
+ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ /**
3
+ * The text of the diagnose prompt. A run or an incident the person typed is
4
+ * put in only when it looks like an id; anything else is left out, so the
5
+ * prompt never carries free text as if it were an instruction.
6
+ */
7
+ export declare function diagnosePromptText(args: {
8
+ run?: string;
9
+ incident?: string;
10
+ }): string;
11
+ /** The `diagnose` prompt: a client shows it as a command the person can run. */
12
+ export declare function registerDiagnosePrompt(server: McpServer): void;
@@ -0,0 +1,37 @@
1
+ import { z } from "zod";
2
+ const RUN_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
3
+ /**
4
+ * The text of the diagnose prompt. A run or an incident the person typed is
5
+ * put in only when it looks like an id; anything else is left out, so the
6
+ * prompt never carries free text as if it were an instruction.
7
+ */
8
+ export function diagnosePromptText(args) {
9
+ const run = args.run?.trim();
10
+ const incident = args.incident?.trim().replace(/^#/, "");
11
+ const lines = [];
12
+ if (run && RUN_ID_PATTERN.test(run)) {
13
+ lines.push(`Diagnose with Tellagen. Call tellagen_pick_up_investigation with investigation_run_id "${run}", your model name and the data sources you can reach.`);
14
+ }
15
+ else if (incident && /^\d{1,12}$/.test(incident)) {
16
+ lines.push(`Diagnose incident ${incident} with Tellagen. Call tellagen_next_investigation with incident_id ${incident}. If a run waits, pick it up with tellagen_pick_up_investigation. If none waits, start one with tellagen_start_investigation and pick it up.`);
17
+ }
18
+ else {
19
+ lines.push("Diagnose with Tellagen. Call tellagen_next_investigation to find the run that waits for you, then call tellagen_pick_up_investigation with its ID, your model name and the data sources you can reach. If several runs wait and you are asked which one, ask the person.");
20
+ }
21
+ lines.push("Then follow the run guide: read the context and the resources the pickup answer names in mcp_resources, post each check as a trace step, post each cause you test and each finding when you find it, build figures with tellagen_build_figure, and complete the run with a result_summary whose headline has 15 words or fewer.", "If Tellagen answers that it is not set up, tell the person the setup steps and stop.");
22
+ return lines.join("\n\n");
23
+ }
24
+ /** The `diagnose` prompt: a client shows it as a command the person can run. */
25
+ export function registerDiagnosePrompt(server) {
26
+ server.registerPrompt("diagnose", {
27
+ title: "Diagnose with Tellagen",
28
+ description: "Find the diagnosis run that waits in Tellagen, pick it up and run it. Give a run ID or an incident number to choose one.",
29
+ argsSchema: {
30
+ run: z.string().max(128).optional().describe("A run ID from Tellagen. Optional."),
31
+ incident: z.string().max(16).optional().describe("An incident number. Optional."),
32
+ },
33
+ }, (args) => ({
34
+ messages: [{ role: "user", content: { type: "text", text: diagnosePromptText(args) } }],
35
+ }));
36
+ }
37
+ //# sourceMappingURL=prompts.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,cAAc,GAAG,qCAAqC,CAAC;AAE7D;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAyC;IAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACzD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,KAAK,CAAC,IAAI,CACR,0FAA0F,GAAG,wDAAwD,CACtJ,CAAC;IACJ,CAAC;SAAM,IAAI,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnD,KAAK,CAAC,IAAI,CACR,qBAAqB,QAAQ,qEAAqE,QAAQ,8IAA8I,CACzP,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CACR,0QAA0Q,CAC3Q,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,IAAI,CACR,iUAAiU,EACjU,sFAAsF,CACvF,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,sBAAsB,CAAC,MAAiB;IACtD,MAAM,CAAC,cAAc,CACnB,UAAU,EACV;QACE,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EACT,0HAA0H;QAC5H,UAAU,EAAE;YACV,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;YACjF,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;SAClF;KACF,EACD,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACT,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;KAC1G,CAAC,CACH,CAAC;AACJ,CAAC"}
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Masks tokens and passwords in a text before it leaves this computer. The
3
+ * rules follow the ones Tellagen applies again when it receives a step, so a
4
+ * secret that this list misses is still removed there; this list exists so
5
+ * that a secret is never sent at all.
6
+ *
7
+ * It masks secrets only. Hosts, namespaces and queries stay, because they are
8
+ * what a recorded step is for.
9
+ */
10
+ /** A text with the tokens and passwords in it masked. */
11
+ export declare function redactSecrets(text: string): string;
12
+ /** A JSON value with secrets masked: a secret key loses its value, every string is cleaned. */
13
+ export declare function redactValue(value: unknown, depth?: number): unknown;
package/dist/redact.js ADDED
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Masks tokens and passwords in a text before it leaves this computer. The
3
+ * rules follow the ones Tellagen applies again when it receives a step, so a
4
+ * secret that this list misses is still removed there; this list exists so
5
+ * that a secret is never sent at all.
6
+ *
7
+ * It masks secrets only. Hosts, namespaces and queries stay, because they are
8
+ * what a recorded step is for.
9
+ */
10
+ const MASK = "[redacted]";
11
+ const PATTERNS = [
12
+ /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g,
13
+ /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}(?:\.[A-Za-z0-9_-]*)?/g,
14
+ // user:password@ in a URL
15
+ /\b[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s/:@"']+:[^\s/@"']+@/g,
16
+ /\bbearer\s+[A-Za-z0-9._~+/=-]{8,}/gi,
17
+ /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|glsa_[A-Za-z0-9_]{20,}|glc_[A-Za-z0-9+/=_-]{20,}|npm_[A-Za-z0-9]{20,}|xox[abeprs]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9_-]{20,}|[sr]k_live_[A-Za-z0-9]{10,}|tlg_[a-z]+_[A-Za-z0-9._-]{8,}|tgn_[A-Za-z0-9._-]{8,}|tllg_[A-Za-z0-9._-]{8,})/g,
18
+ /\b(?:AKIA|ASIA|ABIA|ACCA)[0-9A-Z]{16}\b/g,
19
+ /\bAIza[0-9A-Za-z_-]{35}/g,
20
+ /\b(?:AccountKey|SharedAccessKey|SharedAccessSignature)=[^;\s"']+/gi,
21
+ // An old Grafana API key (base64 of {"k":...}) in any header or value.
22
+ /\beyJr[A-Za-z0-9+/=_-]{16,}/g,
23
+ // A DSN or address with one secret part: https://<key>@host
24
+ /\b[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s/@"':]{8,}@/g,
25
+ ];
26
+ // authorization: <rest of the line>, cookie: ...
27
+ const HEADER = /\b(authorization|proxy[-_]?authorization|cookie|set-cookie)(\\?["']?\s*[:=]\s*)([^\r\n]*)/gi;
28
+ // password: the rest of the line (a password can hold spaces)
29
+ const SECRET_PHRASE = /\b([A-Za-z0-9_.-]*(?:password|passwd|passphrase|pwd|secret))([ \t]*:[ \t]*)((?:[^\s"':\\]|\\[^"\r\n])(?:[^\r\n"\\]|\\[^"\r\n])*)/gi;
30
+ // key=value, key: value, "key": "value" for a key that names a secret
31
+ const SECRET_KEY = "[A-Za-z0-9_.-]*(?:password|passwd|passphrase|pwd|secret|token|api[-_]?key|apikey|access[-_]?key|private[-_]?key|credential|auth)[A-Za-z0-9_.-]*";
32
+ const FIELD = new RegExp(`(${SECRET_KEY})(\\\\?["']?\\s*[:=]\\s*)(\\\\"(?:[^"\\\\]|\\\\[^"])*\\\\"|"(?:[^"\\\\]|\\\\.)*"|'[^']*'|[^\\s,;&}\\])"']+)`, "gi");
33
+ // curl -u user:password, --user user:password
34
+ const USER_FLAG = /(\s(?:-u|--user)(?:\s+|=))(\S+)/g;
35
+ // --from-literal=name=value (kubectl create secret)
36
+ const LITERAL_FLAG = /(--from-literal(?:\s+|=))(\S+)/g;
37
+ // A command-line flag that names a secret: --token abc, --password=abc, -p abc is left alone.
38
+ const FLAG = /(--(?:[a-z0-9-]*(?:token|password|passwd|secret|api-key|apikey|auth-key|credential)[a-z0-9-]*))(\s+|=)(\S+)/gi;
39
+ /** A text with the tokens and passwords in it masked. */
40
+ export function redactSecrets(text) {
41
+ let out = text;
42
+ for (const pattern of PATTERNS)
43
+ out = out.replace(pattern, MASK);
44
+ out = out.replace(HEADER, (_m, name, sep) => `${name}${sep}${MASK}`);
45
+ out = out.replace(SECRET_PHRASE, (_m, name, sep) => `${name}${sep}${MASK}`);
46
+ out = out.replace(FLAG, (_m, flag, sep) => `${flag}${sep}${MASK}`);
47
+ out = out.replace(USER_FLAG, (_m, flag) => `${flag}${MASK}`);
48
+ out = out.replace(LITERAL_FLAG, (_m, flag) => `${flag}${MASK}`);
49
+ out = out.replace(FIELD, (_m, key, sep, value) => {
50
+ // A value that an earlier rule already masked stays as it is: the pattern for a value stops at "]".
51
+ if (value === MASK || value.startsWith("[redacted"))
52
+ return `${key}${sep}${value}`;
53
+ const quote = value.startsWith('"') ? '"' : value.startsWith("'") ? "'" : value.startsWith('\\"') ? '\\"' : "";
54
+ return `${key}${sep}${quote}${MASK}${quote}`;
55
+ });
56
+ return out;
57
+ }
58
+ const SECRET_KEY_EXACT = /^(token|access_token|api_key|apikey|password|passwd|cookie|authorization|client_secret|refresh_token|private_key|webhook_secret|basic_auth|bearer_token|secret)$/i;
59
+ /** A JSON value with secrets masked: a secret key loses its value, every string is cleaned. */
60
+ export function redactValue(value, depth = 0) {
61
+ if (depth > 8)
62
+ return "[too deep]";
63
+ if (typeof value === "string")
64
+ return redactSecrets(value);
65
+ if (Array.isArray(value))
66
+ return value.slice(0, 50).map((item) => redactValue(item, depth + 1));
67
+ if (typeof value === "object" && value !== null) {
68
+ const out = {};
69
+ for (const [key, item] of Object.entries(value).slice(0, 50)) {
70
+ out[key] = SECRET_KEY_EXACT.test(key.replace(/-/g, "_")) ? MASK : redactValue(item, depth + 1);
71
+ }
72
+ return out;
73
+ }
74
+ return value;
75
+ }
76
+ //# sourceMappingURL=redact.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,54 @@
1
+ import type { TellagenClient } from "./client.js";
2
+ import type { PendingNote } from "./run-state.js";
3
+ /**
4
+ * What Tellagen says next to an answer of a run call: a note from a
5
+ * responder, a cancel request, an ended run, a run another client took over.
6
+ * This module turns those into plain lines that go first in the tool result,
7
+ * and clears the remembered run when the run is over.
8
+ *
9
+ * Everything read here is data from the server or from a person in the
10
+ * workspace. It is shown to the model as a quoted note and is never run,
11
+ * parsed for commands or used to choose what this server does next.
12
+ */
13
+ type ToolContent = {
14
+ type: string;
15
+ text?: string;
16
+ [key: string]: unknown;
17
+ };
18
+ export interface ToolResultLike {
19
+ content: ToolContent[];
20
+ isError?: boolean;
21
+ [key: string]: unknown;
22
+ }
23
+ /**
24
+ * One note as a line: who wrote it, when, and the words in quotes. The words
25
+ * are JSON-quoted, so a line break inside a note cannot start a new line
26
+ * that looks like another note or like a line of this server.
27
+ */
28
+ export declare function noteLine(note: {
29
+ author?: unknown;
30
+ at?: unknown;
31
+ text?: unknown;
32
+ }): string | undefined;
33
+ /** The lines for the `responder_notes` of an answer. */
34
+ export declare function responderNoteLines(notes: unknown): string[];
35
+ /**
36
+ * The notes of an answer in the shape of the state file. A note that is only
37
+ * in memory is lost when the client restarts, so a note that arrives where no
38
+ * tool answer can carry it (a heartbeat, a step hook) is kept in the state
39
+ * file until the next tool answer shows it. The text is the note and nothing
40
+ * else: no key, no token.
41
+ */
42
+ export declare function pendingNotesOf(answer: unknown): PendingNote[];
43
+ /**
44
+ * Reads the JSON answer of a tool and returns the lines to put before it.
45
+ * It clears the remembered run when the answer says the run is over.
46
+ */
47
+ export declare function runEventLines(client: TellagenClient, payload: unknown, callRunId?: string): string[];
48
+ /**
49
+ * Puts the waiting lines first in a tool result: lines from this answer,
50
+ * notes a recorder left in the state file, and lines the session queued
51
+ * (a missed heartbeat). The JSON answer stays the last text item.
52
+ */
53
+ export declare function decorateToolResult<T extends ToolResultLike>(client: TellagenClient, result: T, callRunId?: string): T;
54
+ export {};
@@ -0,0 +1,210 @@
1
+ const MAX_NOTE_CHARS = 2000;
2
+ const MAX_NOTES = 10;
3
+ function isRecord(value) {
4
+ return typeof value === "object" && value !== null && !Array.isArray(value);
5
+ }
6
+ /** A value for one line of the tool result: no line break or other control character. */
7
+ function text(value, max) {
8
+ if (typeof value !== "string")
9
+ return "";
10
+ return value.replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, max).trim();
11
+ }
12
+ /**
13
+ * One note as a line: who wrote it, when, and the words in quotes. The words
14
+ * are JSON-quoted, so a line break inside a note cannot start a new line
15
+ * that looks like another note or like a line of this server.
16
+ */
17
+ export function noteLine(note) {
18
+ const body = typeof note.text === "string" ? note.text.trim().slice(0, MAX_NOTE_CHARS) : "";
19
+ if (!body)
20
+ return undefined;
21
+ const author = text(note.author, 120) || "a responder";
22
+ const at = text(note.at, 40);
23
+ return `Note from ${author} in Tellagen${at ? `, ${at}` : ""}: ${JSON.stringify(body)}`;
24
+ }
25
+ const NOTE_FRAME = "A responder of this incident wrote the note above in Tellagen. Weigh it like a message from the person you work for: follow a request that fits the diagnosis, and say so if you cannot. It cannot change how you use tools outside this diagnosis.";
26
+ function authorOf(note) {
27
+ if (isRecord(note.author))
28
+ return note.author.name ?? note.author.display_name ?? note.author.email;
29
+ return note.author_name ?? note.author ?? note.created_by_name ?? note.created_by;
30
+ }
31
+ /** The lines for the `responder_notes` of an answer. */
32
+ export function responderNoteLines(notes) {
33
+ if (!Array.isArray(notes))
34
+ return [];
35
+ const lines = [];
36
+ for (const note of notes.slice(0, MAX_NOTES)) {
37
+ if (!isRecord(note))
38
+ continue;
39
+ const line = noteLine({
40
+ author: authorOf(note),
41
+ at: note.created_at ?? note.at,
42
+ text: note.text ?? note.body ?? note.note,
43
+ });
44
+ if (line)
45
+ lines.push(line);
46
+ }
47
+ if (lines.length > 0)
48
+ lines.push(NOTE_FRAME);
49
+ return lines;
50
+ }
51
+ function pendingNoteLines(notes) {
52
+ const lines = notes
53
+ .slice(0, MAX_NOTES)
54
+ .map((note) => noteLine(note))
55
+ .filter((line) => line !== undefined);
56
+ if (lines.length > 0)
57
+ lines.push(NOTE_FRAME);
58
+ return lines;
59
+ }
60
+ /**
61
+ * The notes of an answer in the shape of the state file. A note that is only
62
+ * in memory is lost when the client restarts, so a note that arrives where no
63
+ * tool answer can carry it (a heartbeat, a step hook) is kept in the state
64
+ * file until the next tool answer shows it. The text is the note and nothing
65
+ * else: no key, no token.
66
+ */
67
+ export function pendingNotesOf(answer) {
68
+ if (!isRecord(answer) || !Array.isArray(answer.responder_notes))
69
+ return [];
70
+ const notes = [];
71
+ for (const raw of answer.responder_notes.slice(0, MAX_NOTES)) {
72
+ if (!isRecord(raw))
73
+ continue;
74
+ const body = typeof (raw.text ?? raw.body) === "string" ? String(raw.text ?? raw.body).trim().slice(0, MAX_NOTE_CHARS) : "";
75
+ if (!body)
76
+ continue;
77
+ notes.push({
78
+ id: typeof raw.id === "string" || typeof raw.id === "number" ? raw.id : undefined,
79
+ author: text(authorOf(raw), 120) || undefined,
80
+ at: text(raw.created_at ?? raw.at, 40) || undefined,
81
+ text: body,
82
+ });
83
+ }
84
+ return notes;
85
+ }
86
+ function runStateValue(value) {
87
+ if (typeof value === "string")
88
+ return { state: value, reason: "" };
89
+ if (!isRecord(value))
90
+ return { state: "", reason: "" };
91
+ const state = typeof value.state === "string" ? value.state : typeof value.status === "string" ? value.status : "";
92
+ const cancel = value.cancel_requested === true ? "cancel_requested" : "";
93
+ return {
94
+ state: cancel || state,
95
+ reason: text(value.reason ?? value.cancel_reason ?? value.message, 300),
96
+ };
97
+ }
98
+ const ENDED_STATES = new Set(["cancel_requested", "cancelled", "completed", "failed"]);
99
+ /** The run id an answer or an error is about, when it names one. */
100
+ function runIdOf(payload, fallback) {
101
+ for (const key of ["investigation_run_id", "run_id"]) {
102
+ const value = payload[key];
103
+ if (typeof value === "string" && value)
104
+ return value;
105
+ }
106
+ if (isRecord(payload.run) && typeof payload.run.id === "string")
107
+ return payload.run.id;
108
+ return fallback;
109
+ }
110
+ /**
111
+ * Reads the JSON answer of a tool and returns the lines to put before it.
112
+ * It clears the remembered run when the answer says the run is over.
113
+ */
114
+ export function runEventLines(client, payload, callRunId) {
115
+ if (!isRecord(payload))
116
+ return [];
117
+ const session = client.session;
118
+ // The run the call named, else the active run. An answer about another run
119
+ // must not make this session forget its own.
120
+ const active = callRunId ?? session.activeRun()?.runId;
121
+ const lines = [];
122
+ lines.push(...responderNoteLines(payload.responder_notes));
123
+ if (payload.error === true) {
124
+ const code = typeof payload.code === "string" ? payload.code : "";
125
+ if (code === "run_taken_over") {
126
+ const at = text(payload.taken_over_at ?? (isRecord(payload.details) ? payload.details.taken_over_at : undefined), 40);
127
+ const runId = runIdOf(payload, active);
128
+ if (runId)
129
+ session.clearActiveRun(runId);
130
+ lines.push(`Another client took this run over${at ? ` at ${at}` : ""}. Stop: do not write to this run again, and tell the person.`);
131
+ }
132
+ else if (code === "investigation_run_ended") {
133
+ const runId = runIdOf(payload, active);
134
+ if (runId)
135
+ session.clearActiveRun(runId);
136
+ const reason = isRecord(payload.details) ? text(payload.details.reason, 100) : "";
137
+ const why = [text(payload.message, 300), reason && `reason: ${reason}`].filter(Boolean).join("; ");
138
+ lines.push(`This run has ended${why ? ` (${why})` : ""}. Stop: do not write to this run again. Tell the person what you found so far.`);
139
+ }
140
+ return lines;
141
+ }
142
+ if (payload.run_state !== undefined) {
143
+ const { state, reason } = runStateValue(payload.run_state);
144
+ if (ENDED_STATES.has(state)) {
145
+ const runId = runIdOf(payload, active);
146
+ if (runId)
147
+ session.clearActiveRun(runId);
148
+ const what = state === "cancel_requested" || state === "cancelled"
149
+ ? "A responder cancelled this run in Tellagen"
150
+ : `This run is ${state}`;
151
+ lines.push(`${what}${reason ? ` (${reason})` : ""}. Stop: do not write to this run again. Tell the person what you found so far.`);
152
+ }
153
+ }
154
+ return lines;
155
+ }
156
+ /**
157
+ * One line for the steps a hook recorded that the model has not updated: it
158
+ * names their ids, because the model cannot see the id of a tool call. Each
159
+ * step is named once; the model can also use the step id "recorded:latest".
160
+ */
161
+ function recordedStepLines(client, runId) {
162
+ const fresh = client.session.state
163
+ .recordedSteps(runId)
164
+ .filter((step) => client.session.announceRecordedStep(step.step_id))
165
+ .slice(-5);
166
+ if (fresh.length === 0)
167
+ return [];
168
+ const list = fresh.map((step) => `${step.step_id} (${JSON.stringify(step.title.replace(/[\u0000-\u001f\u007f]+/g, " ").slice(0, 100))})`).join("; ");
169
+ return [
170
+ `Tellagen recorded these tool calls as steps for you: ${list}. After you read a result, add what you concluded with tellagen_post_trace_step and that step_id (or "recorded:latest" for the newest): outcome, cause_key and a short result_summary. Do not post a new step for the same call.`,
171
+ ];
172
+ }
173
+ /**
174
+ * Puts the waiting lines first in a tool result: lines from this answer,
175
+ * notes a recorder left in the state file, and lines the session queued
176
+ * (a missed heartbeat). The JSON answer stays the last text item.
177
+ */
178
+ export function decorateToolResult(client, result, callRunId) {
179
+ if (!result || !Array.isArray(result.content))
180
+ return result;
181
+ const lines = [];
182
+ const last = [...result.content].reverse().find((item) => item.type === "text" && typeof item.text === "string");
183
+ if (last?.text) {
184
+ try {
185
+ lines.push(...runEventLines(client, JSON.parse(last.text), callRunId));
186
+ }
187
+ catch {
188
+ // Not JSON: nothing to read.
189
+ }
190
+ }
191
+ const active = client.session.activeRun();
192
+ if (active) {
193
+ lines.push(...pendingNoteLines(client.session.state.takePendingNotes(active.runId)));
194
+ lines.push(...recordedStepLines(client, active.runId));
195
+ // A step hook saw Tellagen end the run, and this process did not.
196
+ const stop = client.session.state.takeStop(active.runId);
197
+ if (stop) {
198
+ client.session.clearActiveRun(active.runId);
199
+ lines.push(`This run has ended (${stop.reason}). Stop: do not write to this run again. Tell the person what you found so far.`);
200
+ }
201
+ }
202
+ lines.push(...client.session.takePendingLines());
203
+ if (lines.length === 0)
204
+ return result;
205
+ return {
206
+ ...result,
207
+ content: [{ type: "text", text: lines.join("\n") }, ...result.content],
208
+ };
209
+ }
210
+ //# sourceMappingURL=run-events.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run-events.js","sourceRoot":"","sources":["../src/run-events.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,221 @@
1
+ import { z } from "zod";
2
+ import { type SourceBase } from "./source-bases.js";
3
+ /**
4
+ * The run this computer is working on, remembered across a client restart.
5
+ *
6
+ * The file holds no secret: no key, no token, no evidence. It is written with
7
+ * owner-only permissions because a run id and a note are still private.
8
+ */
9
+ declare const pendingNoteSchema: z.ZodObject<{
10
+ id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
11
+ author: z.ZodOptional<z.ZodString>;
12
+ at: z.ZodOptional<z.ZodString>;
13
+ text: z.ZodString;
14
+ }, "strip", z.ZodTypeAny, {
15
+ text: string;
16
+ at?: string | undefined;
17
+ id?: string | number | undefined;
18
+ author?: string | undefined;
19
+ }, {
20
+ text: string;
21
+ at?: string | undefined;
22
+ id?: string | number | undefined;
23
+ author?: string | undefined;
24
+ }>;
25
+ declare const runStateSchema: z.ZodObject<{
26
+ version: z.ZodLiteral<1>;
27
+ run_id: z.ZodString;
28
+ incident_id: z.ZodOptional<z.ZodNumber>;
29
+ picked_up_at: z.ZodString;
30
+ server_capabilities: z.ZodArray<z.ZodString, "many">;
31
+ /** The MCP server process that last picked the run up. */
32
+ session_id: z.ZodString;
33
+ pid: z.ZodNumber;
34
+ client_name: z.ZodOptional<z.ZodString>;
35
+ client_version: z.ZodOptional<z.ZodString>;
36
+ /** The short client name Tellagen knows, such as "claude-code"; a hook sends it as its client. */
37
+ client_id: z.ZodOptional<z.ZodString>;
38
+ /** The Grafana and GitHub addresses Tellagen sent for this run, so a source link needs no address of its own. */
39
+ source_bases: z.ZodOptional<z.ZodArray<z.ZodObject<{
40
+ kind: z.ZodEnum<["grafana", "github"]>;
41
+ name: z.ZodString;
42
+ base_url: z.ZodString;
43
+ network: z.ZodOptional<z.ZodString>;
44
+ repositories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
45
+ }, "strip", z.ZodTypeAny, {
46
+ name: string;
47
+ kind: "grafana" | "github";
48
+ base_url: string;
49
+ network?: string | undefined;
50
+ repositories?: string[] | undefined;
51
+ }, {
52
+ name: string;
53
+ kind: "grafana" | "github";
54
+ base_url: string;
55
+ network?: string | undefined;
56
+ repositories?: string[] | undefined;
57
+ }>, "many">>;
58
+ /** Notes a recorder outside this process left for the model. */
59
+ pending_notes: z.ZodOptional<z.ZodArray<z.ZodObject<{
60
+ id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
61
+ author: z.ZodOptional<z.ZodString>;
62
+ at: z.ZodOptional<z.ZodString>;
63
+ text: z.ZodString;
64
+ }, "strip", z.ZodTypeAny, {
65
+ text: string;
66
+ at?: string | undefined;
67
+ id?: string | number | undefined;
68
+ author?: string | undefined;
69
+ }, {
70
+ text: string;
71
+ at?: string | undefined;
72
+ id?: string | number | undefined;
73
+ author?: string | undefined;
74
+ }>, "many">>;
75
+ /** Steps a hook recorded that the model has not updated yet, oldest first. */
76
+ recorded_steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
77
+ step_id: z.ZodString;
78
+ title: z.ZodString;
79
+ at: z.ZodString;
80
+ }, "strip", z.ZodTypeAny, {
81
+ at: string;
82
+ title: string;
83
+ step_id: string;
84
+ }, {
85
+ at: string;
86
+ title: string;
87
+ step_id: string;
88
+ }>, "many">>;
89
+ /** Set by a recorder outside this process when Tellagen said the run is over. */
90
+ stop: z.ZodOptional<z.ZodObject<{
91
+ reason: z.ZodString;
92
+ at: z.ZodString;
93
+ }, "strip", z.ZodTypeAny, {
94
+ at: string;
95
+ reason: string;
96
+ }, {
97
+ at: string;
98
+ reason: string;
99
+ }>>;
100
+ }, "strip", z.ZodTypeAny, {
101
+ version: 1;
102
+ run_id: string;
103
+ picked_up_at: string;
104
+ server_capabilities: string[];
105
+ session_id: string;
106
+ pid: number;
107
+ source_bases?: {
108
+ name: string;
109
+ kind: "grafana" | "github";
110
+ base_url: string;
111
+ network?: string | undefined;
112
+ repositories?: string[] | undefined;
113
+ }[] | undefined;
114
+ incident_id?: number | undefined;
115
+ client_name?: string | undefined;
116
+ client_version?: string | undefined;
117
+ client_id?: string | undefined;
118
+ pending_notes?: {
119
+ text: string;
120
+ at?: string | undefined;
121
+ id?: string | number | undefined;
122
+ author?: string | undefined;
123
+ }[] | undefined;
124
+ recorded_steps?: {
125
+ at: string;
126
+ title: string;
127
+ step_id: string;
128
+ }[] | undefined;
129
+ stop?: {
130
+ at: string;
131
+ reason: string;
132
+ } | undefined;
133
+ }, {
134
+ version: 1;
135
+ run_id: string;
136
+ picked_up_at: string;
137
+ server_capabilities: string[];
138
+ session_id: string;
139
+ pid: number;
140
+ source_bases?: {
141
+ name: string;
142
+ kind: "grafana" | "github";
143
+ base_url: string;
144
+ network?: string | undefined;
145
+ repositories?: string[] | undefined;
146
+ }[] | undefined;
147
+ incident_id?: number | undefined;
148
+ client_name?: string | undefined;
149
+ client_version?: string | undefined;
150
+ client_id?: string | undefined;
151
+ pending_notes?: {
152
+ text: string;
153
+ at?: string | undefined;
154
+ id?: string | number | undefined;
155
+ author?: string | undefined;
156
+ }[] | undefined;
157
+ recorded_steps?: {
158
+ at: string;
159
+ title: string;
160
+ step_id: string;
161
+ }[] | undefined;
162
+ stop?: {
163
+ at: string;
164
+ reason: string;
165
+ } | undefined;
166
+ }>;
167
+ export type RunState = z.infer<typeof runStateSchema>;
168
+ export type PendingNote = z.infer<typeof pendingNoteSchema>;
169
+ /** The default folder of the state files: `~/.tellagen/state`. */
170
+ export declare function defaultStateDir(): string;
171
+ /** A file name for the workspace of an API address, with no path characters. */
172
+ export declare function workspaceKey(apiUrl: string): string;
173
+ /** Whether a process with this id is alive on this computer. */
174
+ export declare function processAlive(pid: number): boolean;
175
+ /**
176
+ * Reads and writes one workspace's state file. With no folder it does
177
+ * nothing, so a client built without one (a test, an embedder) never touches
178
+ * the home folder. No method throws: a state file is a convenience, and a
179
+ * disk error must not fail a tool call.
180
+ */
181
+ export declare class RunStateStore {
182
+ private readonly dir;
183
+ private readonly path;
184
+ constructor(dir: string | undefined, workspace: string);
185
+ /** The file, for a message to a person. Undefined when nothing is stored. */
186
+ filePath(): string | undefined;
187
+ read(): RunState | undefined;
188
+ write(state: RunState): boolean;
189
+ /** Removes the file. With a run id, only when the file names that run. */
190
+ clear(runId?: string): void;
191
+ /**
192
+ * Adds notes that a recorder (a step hook) got from Tellagen, so the model
193
+ * sees them in the next answer of the server. A note is kept once by its id.
194
+ */
195
+ addPendingNotes(runId: string, notes: PendingNote[]): void;
196
+ /** Remembers a step that a hook recorded, so the model can add its outcome to it. */
197
+ addRecordedStep(runId: string, step: {
198
+ step_id: string;
199
+ title: string;
200
+ at?: string;
201
+ }): void;
202
+ /** The steps a hook recorded for this run that have no update from the model yet. */
203
+ recordedSteps(runId: string): Array<{
204
+ step_id: string;
205
+ title: string;
206
+ at: string;
207
+ }>;
208
+ removeRecordedStep(runId: string, stepId: string): void;
209
+ /** Keeps the source addresses of a run. An empty list removes them. */
210
+ setSourceBases(runId: string, bases: SourceBase[]): void;
211
+ /** Records that Tellagen ended the run or gave it to another client. */
212
+ setStop(runId: string, reason: string, at?: string): void;
213
+ /** Takes the stop a recorder left for this run. The file stays until the server clears the run. */
214
+ takeStop(runId: string): {
215
+ reason: string;
216
+ at: string;
217
+ } | undefined;
218
+ /** Takes the notes a recorder left for this run and removes them from the file. */
219
+ takePendingNotes(runId: string): PendingNote[];
220
+ }
221
+ export {};