@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,21 @@
1
+ /**
2
+ * `listen-wrap`: runs one client command under a timer of its own. The
3
+ * listener starts every client through it, so the time limit of a run holds
4
+ * even when the listener is killed or its terminal closes: the wrapper is a
5
+ * separate process. It passes standard input, output and the exit code
6
+ * through. At the limit it sends SIGTERM, then SIGKILL after the grace time,
7
+ * and exits with 124.
8
+ */
9
+ export declare function runWrapped(options: {
10
+ limitSeconds: number;
11
+ graceSeconds?: number;
12
+ command: string;
13
+ args: readonly string[];
14
+ }): Promise<number>;
15
+ /** Parses `--limit-seconds N [--grace-seconds N] -- command args...`. */
16
+ export declare function parseWrapArgs(args: readonly string[]): {
17
+ limitSeconds: number;
18
+ graceSeconds?: number;
19
+ command: string;
20
+ args: string[];
21
+ } | undefined;
@@ -0,0 +1,52 @@
1
+ import { spawn } from "node:child_process";
2
+ /**
3
+ * `listen-wrap`: runs one client command under a timer of its own. The
4
+ * listener starts every client through it, so the time limit of a run holds
5
+ * even when the listener is killed or its terminal closes: the wrapper is a
6
+ * separate process. It passes standard input, output and the exit code
7
+ * through. At the limit it sends SIGTERM, then SIGKILL after the grace time,
8
+ * and exits with 124.
9
+ */
10
+ export async function runWrapped(options) {
11
+ return new Promise((resolve) => {
12
+ const child = spawn(options.command, [...options.args], { stdio: ["inherit", "inherit", "inherit"], windowsHide: true });
13
+ let timedOut = false;
14
+ let killer;
15
+ const limit = setTimeout(() => {
16
+ timedOut = true;
17
+ child.kill("SIGTERM");
18
+ killer = setTimeout(() => child.kill("SIGKILL"), (options.graceSeconds ?? 15) * 1000);
19
+ }, options.limitSeconds * 1000);
20
+ const forward = (signal) => () => void child.kill(signal);
21
+ const handlers = ["SIGTERM", "SIGINT", "SIGHUP"].map((s) => [s, forward(s)]);
22
+ for (const [signal, handler] of handlers)
23
+ process.on(signal, handler);
24
+ const done = (code) => {
25
+ clearTimeout(limit);
26
+ if (killer)
27
+ clearTimeout(killer);
28
+ for (const [signal, handler] of handlers)
29
+ process.off(signal, handler);
30
+ resolve(code);
31
+ };
32
+ child.on("error", () => done(127));
33
+ child.on("close", (code, signal) => done(timedOut ? 124 : code ?? (signal ? 128 : 1)));
34
+ });
35
+ }
36
+ /** Parses `--limit-seconds N [--grace-seconds N] -- command args...`. */
37
+ export function parseWrapArgs(args) {
38
+ const dash = args.indexOf("--");
39
+ if (dash < 0 || dash === args.length - 1)
40
+ return undefined;
41
+ const flags = args.slice(0, dash);
42
+ const value = (name) => {
43
+ const index = flags.indexOf(name);
44
+ const number = index >= 0 ? Number(flags[index + 1]) : NaN;
45
+ return Number.isFinite(number) && number > 0 ? number : undefined;
46
+ };
47
+ const limitSeconds = value("--limit-seconds");
48
+ if (!limitSeconds)
49
+ return undefined;
50
+ return { limitSeconds, graceSeconds: value("--grace-seconds"), command: args[dash + 1], args: args.slice(dash + 2) };
51
+ }
52
+ //# sourceMappingURL=listen-wrap.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"listen-wrap.js","sourceRoot":"","sources":["../src/listen-wrap.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,195 @@
1
+ import type { TellagenClient } from "./client.js";
2
+ import type { ListenConfig } from "./listen-config.js";
3
+ /**
4
+ * The listener: asks Tellagen which diagnosis runs wait for this person's
5
+ * computer, and for each one starts the person's own AI client with no
6
+ * window. The client then follows the same path as `/tellagen:diagnose`: it
7
+ * picks the run up through the Tellagen MCP server and writes the result
8
+ * back. The listener itself never reads or writes a run.
9
+ *
10
+ * Bounds: at most `max_runs` runs at a time (default 1), a time limit for
11
+ * each run, a back-off for a run the client could not start, and a stop that
12
+ * waits for the runs that are going on.
13
+ */
14
+ export declare const WAIT_SECONDS = 25;
15
+ /** The codes Tellagen accepts for why the listener could not start a run. */
16
+ export type ListenerReason = "client_not_installed" | "client_not_signed_in" | "client_start_failed" | "limit_reached" | "gave_up";
17
+ /** The coded reason for a client that ended without the run being picked up. Exported for tests. */
18
+ export declare function reasonForEnd(end: {
19
+ code: number | null;
20
+ failedToStart?: string;
21
+ timedOut?: boolean;
22
+ }, logTail: string): ListenerReason | undefined;
23
+ /** A run that is still waiting after this many starts is left alone. */
24
+ export declare const MAX_STARTS_PER_RUN = 5;
25
+ export interface WaitingRun {
26
+ run_id: string;
27
+ /** True for a run that this person asked for. The listener starts no other. */
28
+ requested_by_me?: boolean;
29
+ incident_human_id?: string;
30
+ incident_title?: string;
31
+ }
32
+ export interface ClientCommand {
33
+ command: string;
34
+ args: string[];
35
+ /** Written to the client's standard input. */
36
+ stdin: string;
37
+ cwd: string;
38
+ }
39
+ /** The text a listened run starts from: the diagnose prompt, and the rules of an unattended run. */
40
+ export declare function listenPrompt(runId: string, limitMinutes: number): string;
41
+ /** A client that cannot be started because it cannot be held to the read-only rules. */
42
+ export declare class ListenerRefusal extends Error {
43
+ }
44
+ /**
45
+ * Which clients can enforce the read-only tool list with their own settings.
46
+ * Claude Code can: an allow list, a deny list and a mode that refuses the rest.
47
+ * Codex limits shell commands and file writes with its sandbox, but it has no
48
+ * way to limit the tools of the person's MCP servers (a merge on GitHub, an
49
+ * update in Grafana) from the command line. A prompt is not enforcement, so
50
+ * the listener will not start it.
51
+ */
52
+ export declare const CLIENT_ENFORCES_TOOL_LIST: Record<string, boolean>;
53
+ export declare function clientRefusal(client: string): string;
54
+ /** The command that starts the client for one run. It never carries a flag that skips permission prompts. */
55
+ export interface GuardPaths {
56
+ /** The program that runs the guard, normally `process.execPath`. */
57
+ nodePath: string;
58
+ /** The built `index.js` of this server: it holds the `listen-guard` command. */
59
+ scriptPath: string;
60
+ }
61
+ export declare function buildClientCommand(config: ListenConfig, runId: string, cwd: string, guard?: GuardPaths, options?: {
62
+ prompt?: string;
63
+ }): ClientCommand;
64
+ export interface ProcessEnd {
65
+ code: number | null;
66
+ signal: string | null;
67
+ /** Set when the client could not be started at all. */
68
+ failedToStart?: string;
69
+ }
70
+ export interface RunningProcess {
71
+ pid?: number;
72
+ exited: Promise<ProcessEnd>;
73
+ kill(signal: NodeJS.Signals): void;
74
+ }
75
+ export interface StartOptions {
76
+ /**
77
+ * The built `index.js` of this server. When it is given, the client runs
78
+ * under `listen-wrap`, a small process with its own timer, so the time
79
+ * limit holds even if the listener is killed.
80
+ */
81
+ wrapperScript?: string;
82
+ /** The limit the wrapper enforces, in milliseconds. */
83
+ limitMs?: number;
84
+ }
85
+ export type StartProcess = (command: ClientCommand, logPath: string, options?: StartOptions) => RunningProcess;
86
+ /** Starts the client with its output in a log file that only this user can read. */
87
+ export declare const startClientProcess: StartProcess;
88
+ interface RunRecord {
89
+ run_id: string;
90
+ title?: string;
91
+ started_at: string;
92
+ ended_at?: string;
93
+ result?: string;
94
+ log: string;
95
+ pid?: number;
96
+ }
97
+ export interface ListenStatus {
98
+ listener: {
99
+ pid: number;
100
+ started_at: string;
101
+ client: string;
102
+ working_folder: string;
103
+ max_runs: number;
104
+ computer: string;
105
+ };
106
+ current: RunRecord[];
107
+ recent: RunRecord[];
108
+ problem?: string;
109
+ }
110
+ export interface ListenerDeps {
111
+ client: TellagenClient;
112
+ config: ListenConfig;
113
+ /** The folder the client starts in. */
114
+ cwd: string;
115
+ /** The folder `listen/` is under. */
116
+ home: string;
117
+ out: (line: string) => void;
118
+ startProcess?: StartProcess;
119
+ sleep?: (ms: number) => Promise<void>;
120
+ now?: () => number;
121
+ /** The built `index.js`, to run the client under its own timer. */
122
+ wrapperScript?: string;
123
+ /** The built `index.js` that holds the shell guard. A listened run cannot start without it. */
124
+ guardScript?: string;
125
+ /**
126
+ * Checked before each run starts. A sentence means "do not start this run",
127
+ * for example when the person's own client settings now allow too much.
128
+ */
129
+ preflight?: () => string | undefined;
130
+ /** For a test: the time limit of a run in milliseconds, instead of minutes. */
131
+ runLimitMs?: number;
132
+ /** For a test: the grace between the stop signal and the kill. */
133
+ killGraceMs?: number;
134
+ /** For a test: how long to rest after a list that held runs. */
135
+ restMs?: number;
136
+ }
137
+ export declare class Listener {
138
+ private readonly deps;
139
+ private readonly active;
140
+ private readonly cooldown;
141
+ /** How many times each run was started. A run that comes back after a start was not picked up. */
142
+ private readonly starts;
143
+ private readonly gaveUp;
144
+ private warnedList;
145
+ /** The reason a run could not be started, sent once on the next wait request. */
146
+ private pendingReason;
147
+ private readonly limitReported;
148
+ private recent;
149
+ private stopping;
150
+ private forced;
151
+ private readonly stopped;
152
+ private resolveStopped;
153
+ private takingRuns;
154
+ private lastError;
155
+ private problem;
156
+ private startedAt;
157
+ /** Why the loop ended: nothing for a stop, a sentence for a fault. */
158
+ fatal: string | undefined;
159
+ constructor(deps: ListenerDeps);
160
+ private now;
161
+ private logDir;
162
+ statusPath(): string;
163
+ /** Stops asking for runs. A run in progress finishes. */
164
+ stop(): void;
165
+ /** Ends the runs in progress too: first a termination signal, then a kill. */
166
+ forceStop(): void;
167
+ activeCount(): number;
168
+ private idle;
169
+ private poll;
170
+ /** Runs until `stop()` or a fault, then waits for the runs in progress. */
171
+ run(): Promise<void>;
172
+ private noteSwitch;
173
+ private onError;
174
+ private start;
175
+ private terminate;
176
+ private onExit;
177
+ private fail;
178
+ private pushRecent;
179
+ /** The end of a log, to tell why a client stopped. */
180
+ private logTail;
181
+ private lastLogLine;
182
+ private pruneLogs;
183
+ private writeStatus;
184
+ }
185
+ /** Reads the status file the listener writes. */
186
+ export declare function readListenStatus(home: string): ListenStatus | undefined;
187
+ /** One listener runs on a computer. Takes the lock, or says who holds it. */
188
+ export declare function acquireLock(home: string, ownPid?: number): {
189
+ ok: true;
190
+ release: () => void;
191
+ } | {
192
+ ok: false;
193
+ pid: number;
194
+ };
195
+ export {};