@tellagen/mcp-server 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (180) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +335 -102
  3. package/SKILL.md +183 -27
  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 +207 -147
  50. package/dist/diagnosis-structure.js +143 -2
  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 +281 -201
  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 +184 -0
  106. package/dist/run-state.js +207 -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 +86 -0
  112. package/dist/session.js +155 -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/start.d.ts +7 -6
  124. package/dist/start.js +14 -7
  125. package/dist/start.js.map +1 -1
  126. package/dist/tools/catalog.d.ts +44 -0
  127. package/dist/tools/catalog.js +105 -0
  128. package/dist/tools/catalog.js.map +1 -0
  129. package/dist/tools/causes.d.ts +6 -6
  130. package/dist/tools/causes.js +4 -5
  131. package/dist/tools/causes.js.map +1 -1
  132. package/dist/tools/context.js +5 -5
  133. package/dist/tools/context.js.map +1 -1
  134. package/dist/tools/datasources.js +1 -1
  135. package/dist/tools/datasources.js.map +1 -1
  136. package/dist/tools/diagnostics.js +2 -2
  137. package/dist/tools/diagnostics.js.map +1 -1
  138. package/dist/tools/figures.d.ts +3 -2
  139. package/dist/tools/figures.js +38 -13
  140. package/dist/tools/figures.js.map +1 -1
  141. package/dist/tools/findings.d.ts +28 -0
  142. package/dist/tools/findings.js +88 -24
  143. package/dist/tools/findings.js.map +1 -1
  144. package/dist/tools/incidents.js +5 -5
  145. package/dist/tools/incidents.js.map +1 -1
  146. package/dist/tools/index.d.ts +19 -2
  147. package/dist/tools/index.js +115 -14
  148. package/dist/tools/index.js.map +1 -1
  149. package/dist/tools/investigations.d.ts +54 -0
  150. package/dist/tools/investigations.js +370 -69
  151. package/dist/tools/investigations.js.map +1 -1
  152. package/dist/tools/next.d.ts +20 -0
  153. package/dist/tools/next.js +136 -0
  154. package/dist/tools/next.js.map +1 -0
  155. package/dist/tools/postmortem-runbooks.d.ts +52 -52
  156. package/dist/tools/postmortem-runbooks.js +3 -10
  157. package/dist/tools/postmortem-runbooks.js.map +1 -1
  158. package/dist/tools/resume.d.ts +5 -0
  159. package/dist/tools/resume.js +136 -0
  160. package/dist/tools/resume.js.map +1 -0
  161. package/dist/tools/signin.d.ts +12 -0
  162. package/dist/tools/signin.js +54 -0
  163. package/dist/tools/signin.js.map +1 -0
  164. package/dist/tools/source-links.js +5 -3
  165. package/dist/tools/source-links.js.map +1 -1
  166. package/dist/tools/timeline.js +57 -11
  167. package/dist/tools/timeline.js.map +1 -1
  168. package/dist/trace-record.d.ts +36 -0
  169. package/dist/trace-record.js +283 -0
  170. package/dist/trace-record.js.map +1 -0
  171. package/dist/version.d.ts +10 -2
  172. package/dist/version.js +20 -1
  173. package/dist/version.js.map +1 -1
  174. package/package.json +23 -3
  175. package/server.json +5 -5
  176. package/contracts/runbooks/v1/fixtures/global-runbook.json +0 -7
  177. package/contracts/runbooks/v1/runbook-definition.schema.json +0 -25
  178. package/dist/auth.d.ts +0 -7
  179. package/dist/auth.js +0 -19
  180. package/dist/auth.js.map +0 -1
@@ -0,0 +1,57 @@
1
+ import { type RunCommand } from "./credentials.js";
2
+ /**
3
+ * A listened run is held to the read-only rule by a hook of the client, and
4
+ * the client refuses a shell call that the hook does not pass. That only
5
+ * holds if this client, in this version, really calls the hook. So before the
6
+ * first run, and again when the client or this server changes, the listener
7
+ * asks the client to make two shell calls (one the rule passes, one it
8
+ * refuses) and reads the log that the guard writes. If the guard did not see
9
+ * both calls, in the mode that refuses what no rule allows, the listener will
10
+ * not start the client.
11
+ */
12
+ /** A command the rule passes, and one it refuses. The refused one would leave a mark if it ran. */
13
+ export declare const PROBE_PASS = "kubectl version --client";
14
+ export declare const PROBE_CANARY = "kubectl get pods --server=https://canary.invalid";
15
+ export declare const PLATFORM_REFUSAL = "The listener can prove that your client obeys the shell guard only on macOS and Linux for now. It will not start a client where it cannot prove that, so listening is not available on Windows yet.";
16
+ export declare const PROBE_PROMPT = "This is an authorized self-test of a permission guard, in a sandbox where kubectl is a harmless stand-in. The guard is meant to pass the first command and refuse the second. Use the Bash tool once for each command below, in this order, even if you expect a refusal, and then reply with the single word done. Do not run anything else. (1) kubectl version --client (2) kubectl get pods --server=https://canary.invalid";
17
+ export type Enforcement = {
18
+ ok: true;
19
+ fromCache: boolean;
20
+ } | {
21
+ ok: false;
22
+ reason: string;
23
+ };
24
+ /** What the guard saw, from its log: one line for each decision. */
25
+ export declare function readGuardLog(path: string): Array<{
26
+ decision: string;
27
+ mode: string;
28
+ command: string;
29
+ }>;
30
+ /** Whether a guard log shows the two probe calls, one passed and one refused, in the refusing mode. */
31
+ export declare function judgeGuardLog(entries: ReadonlyArray<{
32
+ decision: string;
33
+ mode: string;
34
+ command: string;
35
+ }>): string | undefined;
36
+ /**
37
+ * What the stand-in `kubectl` saw. The passed command must have run, and the
38
+ * refused one must not have: only then did the client obey the guard.
39
+ */
40
+ export declare function judgeCanary(calls: readonly string[]): string | undefined;
41
+ export interface ProbeDeps {
42
+ /** For a test: the platform. Windows has no canary, so the listener refuses to start there. */
43
+ platform?: NodeJS.Platform;
44
+ home: string;
45
+ /** The program and its arguments, as the listener would start it, with the probe prompt. */
46
+ command: {
47
+ command: string;
48
+ args: string[];
49
+ };
50
+ cwd: string;
51
+ clientVersion: string;
52
+ guardScript: string;
53
+ run?: RunCommand;
54
+ now?: () => number;
55
+ }
56
+ /** Proves, once per client version, that the client calls the shell guard. */
57
+ export declare function verifyEnforcement(deps: ProbeDeps): Promise<Enforcement>;
@@ -0,0 +1,158 @@
1
+ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { randomBytes } from "node:crypto";
4
+ import { runCommand } from "./credentials.js";
5
+ import { MCP_SERVER_VERSION } from "./version.js";
6
+ /**
7
+ * A listened run is held to the read-only rule by a hook of the client, and
8
+ * the client refuses a shell call that the hook does not pass. That only
9
+ * holds if this client, in this version, really calls the hook. So before the
10
+ * first run, and again when the client or this server changes, the listener
11
+ * asks the client to make two shell calls (one the rule passes, one it
12
+ * refuses) and reads the log that the guard writes. If the guard did not see
13
+ * both calls, in the mode that refuses what no rule allows, the listener will
14
+ * not start the client.
15
+ */
16
+ /** A command the rule passes, and one it refuses. The refused one would leave a mark if it ran. */
17
+ export const PROBE_PASS = "kubectl version --client";
18
+ export const PROBE_CANARY = "kubectl get pods --server=https://canary.invalid";
19
+ export const PLATFORM_REFUSAL = "The listener can prove that your client obeys the shell guard only on macOS and Linux for now. It will not start a client where it cannot prove that, so listening is not available on Windows yet.";
20
+ export const PROBE_PROMPT = `This is an authorized self-test of a permission guard, in a sandbox where kubectl is a harmless stand-in. The guard is meant to pass the first command and refuse the second. Use the Bash tool once for each command below, in this order, even if you expect a refusal, and then reply with the single word done. Do not run anything else. (1) ${PROBE_PASS} (2) ${PROBE_CANARY}`;
21
+ const MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
22
+ function cachePath(home) {
23
+ return join(home, "listen", "enforcement.json");
24
+ }
25
+ function readCache(home) {
26
+ try {
27
+ return JSON.parse(readFileSync(cachePath(home), "utf8"));
28
+ }
29
+ catch {
30
+ return undefined;
31
+ }
32
+ }
33
+ function writeCache(home, value) {
34
+ const path = cachePath(home);
35
+ const temp = `${path}.${randomBytes(6).toString("hex")}.tmp`;
36
+ try {
37
+ mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
38
+ writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: "wx" });
39
+ renameSync(temp, path);
40
+ }
41
+ catch {
42
+ rmSync(temp, { force: true });
43
+ }
44
+ }
45
+ /** What the guard saw, from its log: one line for each decision. */
46
+ export function readGuardLog(path) {
47
+ try {
48
+ return readFileSync(path, "utf8")
49
+ .split("\n")
50
+ .filter(Boolean)
51
+ .map((line) => {
52
+ const [decision = "", mode = "", command = ""] = line.split("\t");
53
+ return { decision, mode, command };
54
+ });
55
+ }
56
+ catch {
57
+ return [];
58
+ }
59
+ }
60
+ /** Whether a guard log shows the two probe calls, one passed and one refused, in the refusing mode. */
61
+ export function judgeGuardLog(entries) {
62
+ const pass = entries.find((entry) => entry.decision === "allow" && entry.command === PROBE_PASS);
63
+ const refusal = entries.find((entry) => entry.decision === "deny" && entry.command === PROBE_CANARY);
64
+ if (!pass || !refusal) {
65
+ return entries.length === 0
66
+ ? "The client did not call the shell guard at all. Update Claude Code, and check that it is signed in."
67
+ : "The client called the shell guard, but not for both test commands.";
68
+ }
69
+ if (entries.some((entry) => entry.mode !== "dontAsk")) {
70
+ return "The client did not run in the mode that refuses what no rule allows.";
71
+ }
72
+ return undefined;
73
+ }
74
+ function readLines(path) {
75
+ try {
76
+ return readFileSync(path, "utf8").split("\n").filter(Boolean);
77
+ }
78
+ catch {
79
+ return [];
80
+ }
81
+ }
82
+ /**
83
+ * What the stand-in `kubectl` saw. The passed command must have run, and the
84
+ * refused one must not have: only then did the client obey the guard.
85
+ */
86
+ export function judgeCanary(calls) {
87
+ if (calls.some((line) => line.includes("canary.invalid"))) {
88
+ return "The client RAN a command that the guard refused, so it does not obey the guard.";
89
+ }
90
+ if (!calls.some((line) => line.trim() === "version --client")) {
91
+ return "The client did not run the command that the guard passed, so the guard cannot be told apart from a client that runs nothing.";
92
+ }
93
+ return undefined;
94
+ }
95
+ /** Proves, once per client version, that the client calls the shell guard. */
96
+ export async function verifyEnforcement(deps) {
97
+ // The canary needs a stand-in program that a shell script provides. Where the listener cannot
98
+ // run the canary it cannot prove that the client obeys the guard, so it does not start the client.
99
+ if ((deps.platform ?? process.platform) === "win32") {
100
+ return { ok: false, reason: PLATFORM_REFUSAL };
101
+ }
102
+ const now = deps.now?.() ?? Date.now();
103
+ const cached = readCache(deps.home);
104
+ if (cached &&
105
+ cached.client === deps.command.command &&
106
+ cached.client_version === deps.clientVersion &&
107
+ cached.server_version === MCP_SERVER_VERSION &&
108
+ cached.guard === deps.guardScript &&
109
+ now - Date.parse(cached.verified_at) < MAX_AGE_MS) {
110
+ return { ok: true, fromCache: true };
111
+ }
112
+ if (!existsSync(deps.guardScript)) {
113
+ return { ok: false, reason: "The shell guard is part of the built server, and it was not found. Run the listener from the installed package." };
114
+ }
115
+ const dir = join(deps.home, "listen");
116
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
117
+ const id = randomBytes(6).toString("hex");
118
+ const log = join(dir, `probe-${id}.log`);
119
+ // A stand-in `kubectl` that writes down each call. If the client runs the refused
120
+ // command, the stand-in sees it, and that is the proof that a refusal was not obeyed.
121
+ const sandbox = join(dir, `probe-${id}`);
122
+ const calls = join(sandbox, "calls");
123
+ try {
124
+ {
125
+ mkdirSync(join(sandbox, "bin"), { recursive: true, mode: 0o700 });
126
+ writeFileSync(join(sandbox, "bin", "kubectl"), '#!/bin/sh\nprintf \'%s\\n\' "$*" >> "$TELLAGEN_PROBE_CALLS"\n', { mode: 0o700 });
127
+ writeFileSync(calls, "", { mode: 0o600 });
128
+ }
129
+ const result = await (deps.run ?? runCommand)(deps.command.command, deps.command.args, {
130
+ input: PROBE_PROMPT,
131
+ env: {
132
+ TELLAGEN_GUARD_LOG: log,
133
+ TELLAGEN_PROBE_CALLS: calls,
134
+ PATH: `${join(sandbox, "bin")}:${process.env.PATH ?? ""}`,
135
+ },
136
+ cwd: deps.cwd,
137
+ timeoutMs: 180_000,
138
+ });
139
+ if (result.missing)
140
+ return { ok: false, reason: `${deps.command.command} was not found.` };
141
+ const problem = judgeGuardLog(readGuardLog(log)) ?? judgeCanary(readLines(calls));
142
+ if (problem)
143
+ return { ok: false, reason: `Could not prove that the shell guard is active (${problem}) The listener will not start the client.` };
144
+ }
145
+ finally {
146
+ rmSync(log, { force: true });
147
+ rmSync(sandbox, { recursive: true, force: true });
148
+ }
149
+ writeCache(deps.home, {
150
+ client: deps.command.command,
151
+ client_version: deps.clientVersion,
152
+ server_version: MCP_SERVER_VERSION,
153
+ guard: deps.guardScript,
154
+ verified_at: new Date(now).toISOString(),
155
+ });
156
+ return { ok: true, fromCache: false };
157
+ }
158
+ //# sourceMappingURL=listen-probe.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"listen-probe.js","sourceRoot":"","sources":["../src/listen-probe.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,88 @@
1
+ /**
2
+ * What a run that nobody watches may do.
3
+ *
4
+ * A listened run reads. It may use the Tellagen tools of a diagnosis, the read
5
+ * tools of Grafana and GitHub, and read-only `kubectl` and `gh` commands. It
6
+ * may not change a cluster, a repository, a dashboard or an incident.
7
+ *
8
+ * Everything not on the list is refused, and the client runs in a mode that
9
+ * answers a refusal itself instead of asking a person. This file is the one
10
+ * place the list lives; the command line of the client and the tests both
11
+ * read it.
12
+ */
13
+ /** The Tellagen tools a listened run may call: the diagnosis set, and the reads of the incidents set. */
14
+ export declare function tellagenToolNames(): string[];
15
+ /** The read tools of the Grafana MCP server. Its update, create and delete tools are not here. */
16
+ export declare const GRAFANA_READ_TOOLS: readonly string[];
17
+ /** The read tools of the GitHub MCP server, by the names its versions use. */
18
+ export declare const GITHUB_READ_TOOLS: readonly string[];
19
+ /** The default names of the MCP servers of Grafana and GitHub. A person lists their own in the settings. */
20
+ export declare const DEFAULT_MCP_SERVER_NAMES: {
21
+ readonly grafana: readonly ["grafana", "mcp-grafana"];
22
+ readonly github: readonly ["github"];
23
+ };
24
+ /** The name the client gives an MCP tool: `mcp__<server>__<tool>`. */
25
+ export declare function mcpToolName(server: string, tool: string): string;
26
+ /** Whether a tool name of the person's own list is acceptable. It returns a reason when it is not. */
27
+ export declare function checkExtraTool(name: string): string | undefined;
28
+ export { evaluateCommand, guardDecision, GH_READ_COMMANDS, GH_BARE_COMMANDS, KUBECTL_KINDS, KUBECTL_VERBS } from "./shell-rules.js";
29
+ export type { CommandVerdict } from "./shell-rules.js";
30
+ /** Whether the run may call an MCP tool. */
31
+ export declare function evaluateTool(name: string, options?: {
32
+ grafana?: readonly string[];
33
+ github?: readonly string[];
34
+ extra?: readonly string[];
35
+ }): {
36
+ allowed: boolean;
37
+ reason: string;
38
+ };
39
+ export interface ToolOptions {
40
+ /** Names of the person's Grafana MCP servers. */
41
+ grafana?: readonly string[];
42
+ /** Names of the person's GitHub MCP servers. */
43
+ github?: readonly string[];
44
+ /** Extra read tools of the person, each `mcp__<server>__<tool>`. */
45
+ extra?: readonly string[];
46
+ }
47
+ /**
48
+ * The tools the client may call without asking. These are MCP tools by exact
49
+ * name. There is NO Bash rule here, on purpose: a pattern cannot say "only
50
+ * these flags", and a wide rule would let every shell call through when the
51
+ * hook is missing or broken. A shell call runs only on an explicit pass of
52
+ * the hook (`buildClientSettings`), so with no hook the client refuses it.
53
+ */
54
+ export declare function buildAllowedTools(options?: ToolOptions): string[];
55
+ /**
56
+ * A coarse outer layer that refuses, whatever the hook says: a refusal wins
57
+ * over an allowance. It is shorter than the parser on purpose; the parser is
58
+ * the rule, and a test checks that this list never refuses a command the
59
+ * parser allows.
60
+ */
61
+ export declare function buildDeniedTools(): string[];
62
+ /** The command line the client runs for its hook: our own server, by absolute path. */
63
+ export declare function guardCommandLine(nodePath: string, scriptPath: string): string;
64
+ export declare const GUARD_TIMEOUT_SECONDS = 20;
65
+ /**
66
+ * The settings the client gets with `--settings`. The only hook is the
67
+ * guard, on the shell tool. The guard prints an explicit pass or a refusal;
68
+ * a crash, a timeout or a missing script is no pass, and the client refuses
69
+ * a shell call that no rule allows (checked with the real client).
70
+ */
71
+ export declare function buildClientSettings(guardCommand: string): {
72
+ hooks: {
73
+ PreToolUse: Array<{
74
+ matcher: string;
75
+ hooks: Array<{
76
+ type: "command";
77
+ command: string;
78
+ timeout: number;
79
+ }>;
80
+ }>;
81
+ };
82
+ };
83
+ /** Flags a listened run must never carry, whoever asks for them. */
84
+ export declare const FORBIDDEN_CLIENT_FLAGS: readonly string[];
85
+ /** Turns a rule of the notation `Bash(<glob>)` into a test of a whole command. */
86
+ export declare function bashRuleMatcher(rule: string): ((command: string) => boolean) | undefined;
87
+ /** Whether the lists, as the client reads them, let a command run: an allow rule matches and no deny rule does. */
88
+ export declare function listsAllow(command: string, allowed: readonly string[], denied: readonly string[]): boolean;
@@ -0,0 +1,252 @@
1
+ import { TOOL_CATALOG } from "./tools/catalog.js";
2
+ /**
3
+ * What a run that nobody watches may do.
4
+ *
5
+ * A listened run reads. It may use the Tellagen tools of a diagnosis, the read
6
+ * tools of Grafana and GitHub, and read-only `kubectl` and `gh` commands. It
7
+ * may not change a cluster, a repository, a dashboard or an incident.
8
+ *
9
+ * Everything not on the list is refused, and the client runs in a mode that
10
+ * answers a refusal itself instead of asking a person. This file is the one
11
+ * place the list lives; the command line of the client and the tests both
12
+ * read it.
13
+ */
14
+ // ---------------------------------------------------------------------------
15
+ // Tellagen
16
+ /** The Tellagen tools a listened run may call: the diagnosis set, and the reads of the incidents set. */
17
+ export function tellagenToolNames() {
18
+ return TOOL_CATALOG.filter((entry) => entry.toolset === "diagnosis" || (entry.toolset === "incidents" && entry.effect === "read")).map((entry) => entry.name);
19
+ }
20
+ // ---------------------------------------------------------------------------
21
+ // Grafana and GitHub: read tools by name
22
+ /** The read tools of the Grafana MCP server. Its update, create and delete tools are not here. */
23
+ export const GRAFANA_READ_TOOLS = [
24
+ "analyze_loki_labels",
25
+ "check_datasources_health",
26
+ "diff_tempo_traces",
27
+ "find_error_pattern_logs",
28
+ "find_slow_requests",
29
+ "generate_deeplink",
30
+ "get_alert_group",
31
+ "get_annotation_tags",
32
+ "get_annotations",
33
+ "get_assertions",
34
+ "get_current_oncall_users",
35
+ "get_dashboard_by_uid",
36
+ "get_dashboard_panel_queries",
37
+ "get_dashboard_property",
38
+ "get_dashboard_summary",
39
+ "get_datasource",
40
+ "get_incident",
41
+ "get_oncall_shift",
42
+ "get_panel_image",
43
+ "get_tempo_trace",
44
+ "list_alert_groups",
45
+ "list_dashboard_versions",
46
+ "list_datasources",
47
+ "list_incidents",
48
+ "list_loki_label_names",
49
+ "list_loki_label_values",
50
+ "list_oncall_schedules",
51
+ "list_oncall_teams",
52
+ "list_oncall_users",
53
+ "list_prometheus_label_names",
54
+ "list_prometheus_label_values",
55
+ "list_prometheus_metric_metadata",
56
+ "list_prometheus_metric_names",
57
+ "list_pyroscope_label_names",
58
+ "list_pyroscope_label_values",
59
+ "list_pyroscope_profile_types",
60
+ "list_tempo_attribute_names",
61
+ "list_tempo_attribute_values",
62
+ "query_loki_logs",
63
+ "query_loki_patterns",
64
+ "query_loki_stats",
65
+ "query_prometheus",
66
+ "query_prometheus_histogram",
67
+ "query_pyroscope",
68
+ "query_tempo_metrics",
69
+ "search_dashboards",
70
+ "search_folders",
71
+ "search_tempo_traces",
72
+ "alerting_rules_read",
73
+ "alerting_silences_read",
74
+ ];
75
+ /** The read tools of the GitHub MCP server, by the names its versions use. */
76
+ export const GITHUB_READ_TOOLS = [
77
+ "get_file_contents",
78
+ "get_commit",
79
+ "list_commits",
80
+ "list_branches",
81
+ "list_tags",
82
+ "get_tag",
83
+ "list_releases",
84
+ "get_latest_release",
85
+ "get_release_by_tag",
86
+ "list_pull_requests",
87
+ "pull_request_read",
88
+ "get_pull_request",
89
+ "get_pull_request_files",
90
+ "get_pull_request_diff",
91
+ "get_pull_request_status",
92
+ "get_pull_request_comments",
93
+ "get_pull_request_reviews",
94
+ "list_issues",
95
+ "issue_read",
96
+ "get_issue",
97
+ "get_issue_comments",
98
+ "search_code",
99
+ "search_issues",
100
+ "search_pull_requests",
101
+ "search_repositories",
102
+ "actions_get",
103
+ "actions_list",
104
+ "list_workflows",
105
+ "list_workflow_runs",
106
+ "get_workflow_run",
107
+ "list_workflow_jobs",
108
+ "get_job_logs",
109
+ "get_workflow_run_logs",
110
+ ];
111
+ /** The default names of the MCP servers of Grafana and GitHub. A person lists their own in the settings. */
112
+ export const DEFAULT_MCP_SERVER_NAMES = {
113
+ grafana: ["grafana", "mcp-grafana"],
114
+ github: ["github"],
115
+ };
116
+ /** The name the client gives an MCP tool: `mcp__<server>__<tool>`. */
117
+ export function mcpToolName(server, tool) {
118
+ return `mcp__${server}__${tool}`;
119
+ }
120
+ /** A tool name that a person may add to the list: one named tool of one server, no wildcard. */
121
+ const EXTRA_TOOL = /^mcp__[A-Za-z0-9_-]+__([A-Za-z0-9_-]+)$/;
122
+ const WRITE_VERB = /^(create|update|delete|remove|write|post|put|patch|send|add|set|run|exec|execute|apply|merge|close|reopen|restart|scale|cancel|rerun|trigger|install|upload|push|commit|edit|assign|archive|resolve|acknowledge|silence|mute|enable|disable|import|rollback)(_|$)/;
123
+ /** Whether a tool name of the person's own list is acceptable. It returns a reason when it is not. */
124
+ export function checkExtraTool(name) {
125
+ const match = EXTRA_TOOL.exec(name);
126
+ if (!match)
127
+ return `"${name.slice(0, 80)}" must be one tool, written mcp__<server>__<tool>, with no wildcard.`;
128
+ if (WRITE_VERB.test(match[1].toLowerCase())) {
129
+ return `"${name.slice(0, 80)}" looks like a tool that changes something. A listened run reads only.`;
130
+ }
131
+ return undefined;
132
+ }
133
+ // ---------------------------------------------------------------------------
134
+ // Shell commands: one parser decides (src/shell-rules.ts)
135
+ export { evaluateCommand, guardDecision, GH_READ_COMMANDS, GH_BARE_COMMANDS, KUBECTL_KINDS, KUBECTL_VERBS } from "./shell-rules.js";
136
+ /** Whether the run may call an MCP tool. */
137
+ export function evaluateTool(name, options = {}) {
138
+ return buildAllowedTools(options).includes(name)
139
+ ? { allowed: true, reason: "" }
140
+ : { allowed: false, reason: `${name.slice(0, 100)} is not on the read-only list.` };
141
+ }
142
+ /**
143
+ * The tools the client may call without asking. These are MCP tools by exact
144
+ * name. There is NO Bash rule here, on purpose: a pattern cannot say "only
145
+ * these flags", and a wide rule would let every shell call through when the
146
+ * hook is missing or broken. A shell call runs only on an explicit pass of
147
+ * the hook (`buildClientSettings`), so with no hook the client refuses it.
148
+ */
149
+ export function buildAllowedTools(options = {}) {
150
+ const rules = [];
151
+ // The Tellagen MCP server runs under its own name or under the plugin's.
152
+ for (const server of ["tellagen", "plugin_tellagen_tellagen"]) {
153
+ for (const tool of tellagenToolNames())
154
+ rules.push(mcpToolName(server, tool));
155
+ }
156
+ for (const server of options.grafana ?? DEFAULT_MCP_SERVER_NAMES.grafana) {
157
+ for (const tool of GRAFANA_READ_TOOLS)
158
+ rules.push(mcpToolName(server, tool));
159
+ }
160
+ for (const server of options.github ?? DEFAULT_MCP_SERVER_NAMES.github) {
161
+ for (const tool of GITHUB_READ_TOOLS)
162
+ rules.push(mcpToolName(server, tool));
163
+ }
164
+ for (const name of options.extra ?? []) {
165
+ if (checkExtraTool(name) === undefined)
166
+ rules.push(name);
167
+ }
168
+ return [...new Set(rules)];
169
+ }
170
+ /**
171
+ * A coarse outer layer that refuses, whatever the hook says: a refusal wins
172
+ * over an allowance. It is shorter than the parser on purpose; the parser is
173
+ * the rule, and a test checks that this list never refuses a command the
174
+ * parser allows.
175
+ */
176
+ export function buildDeniedTools() {
177
+ return [
178
+ "Bash(*;*)",
179
+ "Bash(*&*)",
180
+ "Bash(*|*)",
181
+ "Bash(*`*)",
182
+ "Bash(*$*)",
183
+ "Bash(*>*)",
184
+ "Bash(*<*)",
185
+ "Bash(*\n*)",
186
+ "Bash(*\r*)",
187
+ "Bash(kubectl * --server*)",
188
+ "Bash(kubectl * -s *)",
189
+ "Bash(kubectl * --kubeconfig*)",
190
+ "Bash(kubectl * --token*)",
191
+ "Bash(kubectl * --as*)",
192
+ "Bash(kubectl * --insecure-skip-tls-verify*)",
193
+ "Bash(gh api *)",
194
+ "Bash(gh auth token*)",
195
+ "Write",
196
+ "Edit",
197
+ "NotebookEdit",
198
+ "WebFetch",
199
+ "WebSearch",
200
+ ];
201
+ }
202
+ /** Single-quotes a word for a shell command line. */
203
+ function shellQuote(word) {
204
+ return `'${word.replace(/'/g, `'\\''`)}'`;
205
+ }
206
+ /** The command line the client runs for its hook: our own server, by absolute path. */
207
+ export function guardCommandLine(nodePath, scriptPath) {
208
+ return `${shellQuote(nodePath)} ${shellQuote(scriptPath)} listen-guard`;
209
+ }
210
+ export const GUARD_TIMEOUT_SECONDS = 20;
211
+ /**
212
+ * The settings the client gets with `--settings`. The only hook is the
213
+ * guard, on the shell tool. The guard prints an explicit pass or a refusal;
214
+ * a crash, a timeout or a missing script is no pass, and the client refuses
215
+ * a shell call that no rule allows (checked with the real client).
216
+ */
217
+ export function buildClientSettings(guardCommand) {
218
+ return {
219
+ hooks: { PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: guardCommand, timeout: GUARD_TIMEOUT_SECONDS }] }] },
220
+ };
221
+ }
222
+ /** Flags a listened run must never carry, whoever asks for them. */
223
+ export const FORBIDDEN_CLIENT_FLAGS = [
224
+ "--dangerously-skip-permissions",
225
+ "--allow-dangerously-skip-permissions",
226
+ "--dangerously-bypass-approvals-and-sandbox",
227
+ "--dangerously-bypass-hook-trust",
228
+ "--yolo",
229
+ "bypassPermissions",
230
+ "danger-full-access",
231
+ "--approve-for-me",
232
+ ];
233
+ // ---------------------------------------------------------------------------
234
+ // The client's matching, for the tests and for the check of its settings
235
+ /** Turns a rule of the notation `Bash(<glob>)` into a test of a whole command. */
236
+ export function bashRuleMatcher(rule) {
237
+ const match = /^Bash\((.*)\)$/s.exec(rule);
238
+ if (!match)
239
+ return undefined;
240
+ const pattern = match[1]
241
+ .split("*")
242
+ .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
243
+ .join(".*");
244
+ const regex = new RegExp(`^${pattern}$`, "s");
245
+ return (command) => regex.test(command);
246
+ }
247
+ /** Whether the lists, as the client reads them, let a command run: an allow rule matches and no deny rule does. */
248
+ export function listsAllow(command, allowed, denied) {
249
+ const matches = (rules) => rules.some((rule) => bashRuleMatcher(rule)?.(command) === true);
250
+ return matches(allowed) && !matches(denied);
251
+ }
252
+ //# sourceMappingURL=listen-rules.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"listen-rules.js","sourceRoot":"","sources":["../src/listen-rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;GAWG;AAEH,8EAA8E;AAC9E,WAAW;AAEX,yGAAyG;AACzG,MAAM,UAAU,iBAAiB;IAC/B,OAAO,YAAY,CAAC,MAAM,CACxB,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,WAAW,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,WAAW,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CACvG,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,8EAA8E;AAC9E,yCAAyC;AAEzC,kGAAkG;AAClG,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,qBAAqB;IACrB,0BAA0B;IAC1B,mBAAmB;IACnB,yBAAyB;IACzB,oBAAoB;IACpB,mBAAmB;IACnB,iBAAiB;IACjB,qBAAqB;IACrB,iBAAiB;IACjB,gBAAgB;IAChB,0BAA0B;IAC1B,sBAAsB;IACtB,6BAA6B;IAC7B,wBAAwB;IACxB,uBAAuB;IACvB,gBAAgB;IAChB,cAAc;IACd,kBAAkB;IAClB,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;IACnB,yBAAyB;IACzB,kBAAkB;IAClB,gBAAgB;IAChB,uBAAuB;IACvB,wBAAwB;IACxB,uBAAuB;IACvB,mBAAmB;IACnB,mBAAmB;IACnB,6BAA6B;IAC7B,8BAA8B;IAC9B,iCAAiC;IACjC,8BAA8B;IAC9B,4BAA4B;IAC5B,6BAA6B;IAC7B,8BAA8B;IAC9B,4BAA4B;IAC5B,6BAA6B;IAC7B,iBAAiB;IACjB,qBAAqB;IACrB,kBAAkB;IAClB,kBAAkB;IAClB,4BAA4B;IAC5B,iBAAiB;IACjB,qBAAqB;IACrB,mBAAmB;IACnB,gBAAgB;IAChB,qBAAqB;IACrB,qBAAqB;IACrB,wBAAwB;CACzB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IAClD,mBAAmB;IACnB,YAAY;IACZ,cAAc;IACd,eAAe;IACf,WAAW;IACX,SAAS;IACT,eAAe;IACf,oBAAoB;IACpB,oBAAoB;IACpB,oBAAoB;IACpB,mBAAmB;IACnB,kBAAkB;IAClB,wBAAwB;IACxB,uBAAuB;IACvB,yBAAyB;IACzB,2BAA2B;IAC3B,0BAA0B;IAC1B,aAAa;IACb,YAAY;IACZ,WAAW;IACX,oBAAoB;IACpB,aAAa;IACb,eAAe;IACf,sBAAsB;IACtB,qBAAqB;IACrB,aAAa;IACb,cAAc;IACd,gBAAgB;IAChB,oBAAoB;IACpB,kBAAkB;IAClB,oBAAoB;IACpB,cAAc;IACd,uBAAuB;CACxB,CAAC;AAEF,4GAA4G;AAC5G,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,OAAO,EAAE,CAAC,SAAS,EAAE,aAAa,CAAC;IACnC,MAAM,EAAE,CAAC,QAAQ,CAAC;CACV,CAAC;AAEX,sEAAsE;AACtE,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAY;IACtD,OAAO,QAAQ,MAAM,KAAK,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,GAAG,yCAAyC,CAAC;AAC7D,MAAM,UAAU,GAAG,mQAAmQ,CAAC;AAEvR,sGAAsG;AACtG,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,sEAAsE,CAAC;IAC/G,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QAC7C,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,wEAAwE,CAAC;IACvG,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,0DAA0D;AAE1D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGpI,4CAA4C;AAC5C,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,UAAkG,EAAE;IAEpG,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC9C,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE;QAC/B,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,gCAAgC,EAAE,CAAC;AACxF,CAAC;AAcD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAuB,EAAE;IACzD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,yEAAyE;IACzE,KAAK,MAAM,MAAM,IAAI,CAAC,UAAU,EAAE,0BAA0B,CAAC,EAAE,CAAC;QAC9D,KAAK,MAAM,IAAI,IAAI,iBAAiB,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IAChF,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO,IAAI,wBAAwB,CAAC,OAAO,EAAE,CAAC;QACzE,KAAK,MAAM,IAAI,IAAI,kBAAkB;YAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/E,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,MAAM,IAAI,wBAAwB,CAAC,MAAM,EAAE,CAAC;QACvE,KAAK,MAAM,IAAI,IAAI,iBAAiB;YAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACvC,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,2BAA2B;QAC3B,sBAAsB;QACtB,+BAA+B;QAC/B,0BAA0B;QAC1B,uBAAuB;QACvB,6CAA6C;QAC7C,gBAAgB;QAChB,sBAAsB;QACtB,OAAO;QACP,MAAM;QACN,cAAc;QACd,UAAU;QACV,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,qDAAqD;AACrD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC5C,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,UAAkB;IACnE,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,eAAe,CAAC;AAC1E,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,OAAO;QACL,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,qBAAqB,EAAE,CAAC,EAAE,CAAC,EAAE;KAClI,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,MAAM,sBAAsB,GAAsB;IACvD,gCAAgC;IAChC,sCAAsC;IACtC,4CAA4C;IAC5C,iCAAiC;IACjC,QAAQ;IACR,mBAAmB;IACnB,oBAAoB;IACpB,kBAAkB;CACnB,CAAC;AAEF,8EAA8E;AAC9E,yEAAyE;AAEzE,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAE;SACtB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;SACzD,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9C,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,mHAAmH;AACnH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,OAA0B,EAAE,MAAyB;IAC/F,MAAM,OAAO,GAAG,CAAC,KAAwB,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;IAC9G,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC"}
@@ -0,0 +1,18 @@
1
+ import { type ToolOptions } from "./listen-rules.js";
2
+ /**
3
+ * The permission rules in the person's own Claude Code settings add to the
4
+ * list the listener passes. A person who allows `Bash(*)` or `Read` for
5
+ * their daily work would give an unattended run the same access. So before a
6
+ * run is started, every allow rule the client will read is checked against
7
+ * the listener's own list, and the listener refuses to start when one is not
8
+ * on it.
9
+ */
10
+ export interface SettingsProblem {
11
+ rule: string;
12
+ file: string;
13
+ }
14
+ /** The allow rules of the client's settings files that are not on the listener's list. */
15
+ export declare function inspectClientSettings(cwd: string, options?: ToolOptions, home?: string, env?: Record<string, string | undefined>): {
16
+ problems: SettingsProblem[];
17
+ unreadable: string[];
18
+ };
@@ -0,0 +1,50 @@
1
+ import { existsSync, lstatSync, readFileSync } from "node:fs";
2
+ import { homedir } from "node:os";
3
+ import { dirname, join } from "node:path";
4
+ import { buildAllowedTools } from "./listen-rules.js";
5
+ function settingsFiles(cwd, home, env) {
6
+ // The client reads the settings of the working folder and of every folder above it.
7
+ const folders = [];
8
+ for (let folder = cwd, last = ""; folder !== last; last = folder, folder = dirname(folder))
9
+ folders.push(folder);
10
+ const configDir = (env.CLAUDE_CONFIG_DIR ?? "").trim();
11
+ const userDirs = new Set([join(home, ".claude"), ...(configDir ? [configDir] : [])]);
12
+ return [
13
+ ...[...userDirs].flatMap((dir) => [join(dir, "settings.json"), join(dir, "settings.local.json")]),
14
+ ...folders.flatMap((folder) => [join(folder, ".claude", "settings.json"), join(folder, ".claude", "settings.local.json")]),
15
+ "/Library/Application Support/ClaudeCode/managed-settings.json",
16
+ "/etc/claude-code/managed-settings.json",
17
+ ];
18
+ }
19
+ /** The allow rules of the client's settings files that are not on the listener's list. */
20
+ export function inspectClientSettings(cwd, options = {}, home = homedir(), env = process.env) {
21
+ const ours = new Set(buildAllowedTools(options));
22
+ const problems = [];
23
+ const unreadable = [];
24
+ for (const file of [...new Set(settingsFiles(cwd, home, env))]) {
25
+ if (!existsSync(file))
26
+ continue;
27
+ let data;
28
+ try {
29
+ const stat = lstatSync(file);
30
+ if (!stat.isFile() || stat.size > 1024 * 1024)
31
+ throw new Error("not a settings file");
32
+ data = JSON.parse(readFileSync(file, "utf8"));
33
+ }
34
+ catch {
35
+ // A file this process cannot read is a file it cannot vouch for.
36
+ unreadable.push(file);
37
+ continue;
38
+ }
39
+ const permissions = data?.permissions;
40
+ const allow = permissions?.allow;
41
+ if (!Array.isArray(allow))
42
+ continue;
43
+ for (const rule of allow) {
44
+ if (typeof rule === "string" && !ours.has(rule.trim()))
45
+ problems.push({ rule: rule.trim().slice(0, 120), file });
46
+ }
47
+ }
48
+ return { problems, unreadable };
49
+ }
50
+ //# sourceMappingURL=listen-settings.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"listen-settings.js","sourceRoot":"","sources":["../src/listen-settings.ts"],"names":[],"mappings":"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"}