llmspy 0.0.0-stage → 0.3.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.
@@ -0,0 +1,337 @@
1
+ import * as http from 'node:http';
2
+ import { forwardAndCapture } from './capture.js';
3
+ import { toMarkdown } from './conversation.js';
4
+ import { isAllowedUiRequest } from './guard.js';
5
+ import { exchangeParser } from './parsers/index.js';
6
+ import { parseListRequest, parseStatsRequest, parseWait } from './query.js';
7
+ import { serveStatic } from './static.js';
8
+ import { toStats } from './stats.js';
9
+ import { toSummary } from './summary.js';
10
+ import { isProjectName, listUpstreams, resolveRoute } from './upstreams.js';
11
+ /**
12
+ * The routes that serve captured traffic or act on it. Upstream forwarding is
13
+ * not guarded: apps in other containers reach it by other host names.
14
+ */
15
+ function isUiRoute(path) {
16
+ return path === '/ping' || path === '/events' || path.startsWith('/api/');
17
+ }
18
+ /** `/api/requests/<id>`: ids are UUIDs, so no decoding is needed. */
19
+ const RECORD_PATH = /^\/api\/requests\/([\w-]+)$/;
20
+ /** `/api/requests/<id>/conversation`: the call as Markdown. */
21
+ const CONVERSATION_PATH = /^\/api\/requests\/([\w-]+)\/conversation$/;
22
+ /**
23
+ * One HTTP server for both jobs: `/<upstream>/...` is forwarded and captured,
24
+ * and `/ping`, `/events` and `/api/*` serve the UI.
25
+ */
26
+ export class ProxyServer {
27
+ server;
28
+ config;
29
+ store;
30
+ sseClients = new Set();
31
+ /** Reads held by `?wait=` until their call ends, by call id: each answers once. */
32
+ waiting = new Map();
33
+ constructor(config, store) {
34
+ this.config = config;
35
+ this.store = store;
36
+ this.server = http.createServer((req, res) => this.handleRequest(req, res));
37
+ }
38
+ handleRequest(req, res) {
39
+ const url = req.url ?? '/';
40
+ // The UI routes match on the path alone; the few that take parameters
41
+ // read the query themselves. The full URL still goes to `resolveRoute`,
42
+ // so upstreams get their query.
43
+ const path = url.split('?')[0];
44
+ if (isUiRoute(path) &&
45
+ !isAllowedUiRequest(req.headers, this.config.host)) {
46
+ res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
47
+ res.end('LLMSpy: the UI API only answers the UI on this machine.');
48
+ return;
49
+ }
50
+ if (path === '/ping') {
51
+ this.handlePing(res);
52
+ return;
53
+ }
54
+ if (path === '/events') {
55
+ this.handleSSE(req, res);
56
+ return;
57
+ }
58
+ if (path === '/api/requests') {
59
+ this.handleGetRequests(res, url);
60
+ return;
61
+ }
62
+ if (path === '/api/stats') {
63
+ this.handleGetStats(res, url);
64
+ return;
65
+ }
66
+ if (path === '/api/upstreams') {
67
+ res.writeHead(200, { 'Content-Type': 'application/json' });
68
+ res.end(JSON.stringify(listUpstreams(this.config.upstreams)));
69
+ return;
70
+ }
71
+ if (path === '/api/clear' && req.method === 'POST') {
72
+ this.handleClearRequests(res, url);
73
+ return;
74
+ }
75
+ if (this.handleRecordRoute(req, res, url, path))
76
+ return;
77
+ const route = resolveRoute(url, this.config.upstreams);
78
+ if (!route) {
79
+ this.handleStaticOrNotFound(req, res);
80
+ return;
81
+ }
82
+ const parse = exchangeParser();
83
+ const parseAndPublish = (captured) => {
84
+ const llm = parse(captured);
85
+ if (llm)
86
+ captured.llm = llm;
87
+ this.publish(captured);
88
+ };
89
+ forwardAndCapture(req, res, route, {
90
+ onUpdate: (captured) => {
91
+ // When the response headers arrive the reply body is still
92
+ // empty, and parsing it would report an error.
93
+ if (captured.response?.body === '')
94
+ this.publish(captured);
95
+ else
96
+ parseAndPublish(captured);
97
+ },
98
+ onDone: parseAndPublish,
99
+ });
100
+ }
101
+ /** The routes on one call, `/api/requests/<id>...`; false when `path` is none of them. */
102
+ handleRecordRoute(req, res, url, path) {
103
+ const record = RECORD_PATH.exec(path);
104
+ if (record && req.method === 'DELETE') {
105
+ this.handleDeleteRequest(res, record[1]);
106
+ return true;
107
+ }
108
+ if (req.method !== 'GET')
109
+ return false;
110
+ if (record) {
111
+ const id = record[1];
112
+ this.handleRead(res, url, id, () => this.handleGetRequest(res, id));
113
+ return true;
114
+ }
115
+ const conversation = CONVERSATION_PATH.exec(path);
116
+ if (conversation) {
117
+ const id = conversation[1];
118
+ this.handleRead(res, url, id, () => this.handleGetConversation(res, id));
119
+ return true;
120
+ }
121
+ return false;
122
+ }
123
+ /**
124
+ * Answers a read of one call with `answer`: at once, or with `?wait=` once
125
+ * a running call ends. A call that ended, or is unknown, is answered at once.
126
+ */
127
+ handleRead(res, url, id, answer) {
128
+ const asked = parseWait(new URLSearchParams(url.split('?')[1]));
129
+ if ('error' in asked) {
130
+ this.badRequest(res, asked.error);
131
+ return;
132
+ }
133
+ const captured = this.store.get(id);
134
+ if (asked.seconds === undefined ||
135
+ captured === undefined ||
136
+ captured.timings.end !== undefined) {
137
+ answer();
138
+ return;
139
+ }
140
+ this.holdUntilEnded(res, id, asked.seconds, answer);
141
+ }
142
+ /**
143
+ * Holds `answer` until `wake(id)` or `seconds` run out, when it answers
144
+ * with the call as it is then. A client that hangs up is forgotten.
145
+ */
146
+ holdUntilEnded(res, id, seconds, answer) {
147
+ const waiters = this.waiting.get(id) ?? new Set();
148
+ this.waiting.set(id, waiters);
149
+ const forget = () => {
150
+ clearTimeout(timer);
151
+ res.off('close', forget);
152
+ waiters.delete(release);
153
+ if (waiters.size === 0)
154
+ this.waiting.delete(id);
155
+ };
156
+ const release = () => {
157
+ forget();
158
+ answer();
159
+ };
160
+ const timer = setTimeout(release, seconds * 1000);
161
+ res.on('close', forget);
162
+ waiters.add(release);
163
+ }
164
+ /** Answers every read waiting on call `id`, with the call as it is now. */
165
+ wake(id) {
166
+ for (const release of [...(this.waiting.get(id) ?? [])])
167
+ release();
168
+ }
169
+ publish(captured) {
170
+ this.store.addRequest(captured);
171
+ this.broadcast(captured);
172
+ if (captured.timings.end !== undefined)
173
+ this.wake(captured.id);
174
+ }
175
+ async handleStaticOrNotFound(req, res) {
176
+ const { uiDir } = this.config;
177
+ if (uiDir && (await serveStatic(req, res, uiDir)))
178
+ return;
179
+ const prefixes = [...this.config.upstreams.keys()]
180
+ .map((name) => `/${name}`)
181
+ .join(', ');
182
+ res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
183
+ res.end(`LLMSpy: no upstream for ${req.url}. Known prefixes: ${prefixes} (put /@<project> in front to tag a project).`);
184
+ }
185
+ /** Clients are sent the summary; they fetch the full record when they need it. */
186
+ broadcast(captured) {
187
+ this.sendToClients(`data: ${JSON.stringify(toSummary(captured))}\n\n`);
188
+ }
189
+ sendToClients(event) {
190
+ for (const client of this.sseClients) {
191
+ client.write(event);
192
+ }
193
+ }
194
+ handleSSE(req, res) {
195
+ res.writeHead(200, {
196
+ 'Content-Type': 'text/event-stream',
197
+ 'Cache-Control': 'no-cache',
198
+ Connection: 'keep-alive',
199
+ });
200
+ // Node holds the headers back until the first write, and with an empty
201
+ // store there is nothing to replay, so the browser would never see the
202
+ // stream open.
203
+ res.flushHeaders();
204
+ this.sseClients.add(res);
205
+ req.on('close', () => {
206
+ this.sseClients.delete(res);
207
+ });
208
+ for (const summary of this.store.summaries()) {
209
+ res.write(`data: ${JSON.stringify(summary)}\n\n`);
210
+ }
211
+ }
212
+ /**
213
+ * `GET /api/requests`: summaries, newest first, or full records with
214
+ * `full=1`; `parseListRequest` reads the filters.
215
+ */
216
+ handleGetRequests(res, url) {
217
+ const asked = parseListRequest(new URLSearchParams(url.split('?')[1]));
218
+ if ('error' in asked) {
219
+ this.badRequest(res, asked.error);
220
+ return;
221
+ }
222
+ const calls = asked.full
223
+ ? this.store.getRequests(asked.query)
224
+ : this.store.summaries(asked.query);
225
+ res.writeHead(200, { 'Content-Type': 'application/json' });
226
+ res.end(JSON.stringify(calls));
227
+ }
228
+ /** `GET /api/stats`: counts over the calls the filters of `GET /api/requests` match. */
229
+ handleGetStats(res, url) {
230
+ const asked = parseStatsRequest(new URLSearchParams(url.split('?')[1]));
231
+ if ('error' in asked) {
232
+ this.badRequest(res, asked.error);
233
+ return;
234
+ }
235
+ res.writeHead(200, { 'Content-Type': 'application/json' });
236
+ res.end(JSON.stringify(toStats(this.store.summaries(asked.query))));
237
+ }
238
+ /** `GET /api/requests/<id>`: the full record. */
239
+ handleGetRequest(res, id) {
240
+ const captured = this.store.get(id);
241
+ if (!captured) {
242
+ this.noSuchCall(res, id);
243
+ return;
244
+ }
245
+ res.writeHead(200, { 'Content-Type': 'application/json' });
246
+ res.end(JSON.stringify(captured));
247
+ }
248
+ /** `GET /api/requests/<id>/conversation`: the call as Markdown. */
249
+ handleGetConversation(res, id) {
250
+ const captured = this.store.get(id);
251
+ if (!captured) {
252
+ this.noSuchCall(res, id);
253
+ return;
254
+ }
255
+ const markdown = toMarkdown(captured);
256
+ if (markdown === undefined) {
257
+ res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
258
+ res.end(`LLMSpy: call ${id} was not read as an LLM API call; the full record is /api/requests/${id}.`);
259
+ return;
260
+ }
261
+ res.writeHead(200, { 'content-type': 'text/markdown; charset=utf-8' });
262
+ res.end(markdown);
263
+ }
264
+ noSuchCall(res, id) {
265
+ res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
266
+ res.end(`LLMSpy: no captured call ${id}.`);
267
+ }
268
+ badRequest(res, message) {
269
+ res.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
270
+ res.end(`LLMSpy: ${message}`);
271
+ }
272
+ handlePing(res) {
273
+ res.writeHead(200, { 'Content-Type': 'application/json' });
274
+ res.end(JSON.stringify({
275
+ status: 'running',
276
+ message: 'LLMSpy proxy server is running',
277
+ version: this.config.version,
278
+ // The port really bound, so the UI can show it even when it is
279
+ // served from elsewhere (Vite in dev).
280
+ port: this.server.address().port,
281
+ // So `npm run stop` can check the pid file names this process.
282
+ pid: process.pid,
283
+ timestamp: new Date().toISOString(),
284
+ }));
285
+ }
286
+ /** `POST /api/clear?project=<name>` clears one project; without it, all. */
287
+ handleClearRequests(res, url) {
288
+ const project = new URLSearchParams(url.split('?')[1]).get('project') ?? undefined;
289
+ if (project !== undefined && !isProjectName(project)) {
290
+ this.badRequest(res, `"${project}" is not a project name.`);
291
+ return;
292
+ }
293
+ this.store.clear(project);
294
+ // Reads waiting on a cleared call now find nothing, and say so.
295
+ for (const id of [...this.waiting.keys()]) {
296
+ if (this.store.get(id) === undefined)
297
+ this.wake(id);
298
+ }
299
+ // Named, so a client that only reads records (`onmessage`) ignores it.
300
+ // No `project` means every project was cleared.
301
+ this.sendToClients(`event: clear\ndata: ${JSON.stringify({ project })}\n\n`);
302
+ res.writeHead(200, { 'Content-Type': 'application/json' });
303
+ res.end(JSON.stringify({ success: true }));
304
+ }
305
+ handleDeleteRequest(res, id) {
306
+ if (!this.store.remove(id)) {
307
+ this.noSuchCall(res, id);
308
+ return;
309
+ }
310
+ this.wake(id);
311
+ // Named like `clear`, so every tab drops the row.
312
+ this.sendToClients(`event: delete\ndata: ${JSON.stringify({ id })}\n\n`);
313
+ res.writeHead(204);
314
+ res.end();
315
+ }
316
+ /** Starts listening and resolves with the port (useful when `port` is 0). */
317
+ start() {
318
+ return new Promise((resolve, reject) => {
319
+ this.server.once('error', reject);
320
+ this.server.listen(this.config.port, this.config.host, () => {
321
+ this.server.off('error', reject);
322
+ resolve(this.server.address().port);
323
+ });
324
+ });
325
+ }
326
+ stop() {
327
+ for (const id of [...this.waiting.keys()])
328
+ this.wake(id);
329
+ for (const client of this.sseClients)
330
+ client.end();
331
+ this.sseClients.clear();
332
+ return new Promise((resolve) => {
333
+ this.server.close(() => resolve());
334
+ this.server.closeAllConnections();
335
+ });
336
+ }
337
+ }
@@ -0,0 +1,111 @@
1
+ import { isProjectName } from './upstreams.js';
2
+ /**
3
+ * Reads the parameters of `GET /api/requests`: `project`, `q`, `since` (an
4
+ * ISO time or epoch milliseconds), `limit` (a positive whole number),
5
+ * `full=1`, and the filters `model`, `status` and `failed=1`. Anything it
6
+ * can not read is an error, so a typo never quietly lists every call.
7
+ */
8
+ export function parseListRequest(params) {
9
+ const project = params.get('project') ?? undefined;
10
+ if (project !== undefined && !isProjectName(project)) {
11
+ return { error: `"${project}" is not a project name.` };
12
+ }
13
+ const sinceParam = params.get('since');
14
+ const since = sinceParam === null ? undefined : parseTime(sinceParam);
15
+ if (Number.isNaN(since)) {
16
+ return {
17
+ error: `since must be an ISO time (2026-11-15T10:00:00Z) or epoch milliseconds, not "${sinceParam}".`,
18
+ };
19
+ }
20
+ const limitParam = params.get('limit');
21
+ if (limitParam !== null && !/^[1-9]\d*$/.test(limitParam)) {
22
+ return {
23
+ error: `limit must be a whole number above 0, not "${limitParam}".`,
24
+ };
25
+ }
26
+ const fullParam = params.get('full');
27
+ if (fullParam !== null && fullParam !== '1') {
28
+ return { error: `full must be 1, not "${fullParam}".` };
29
+ }
30
+ const filters = parseFilters(params);
31
+ if ('error' in filters)
32
+ return filters;
33
+ return {
34
+ query: {
35
+ project,
36
+ search: params.get('q') ?? '',
37
+ since,
38
+ limit: limitParam === null ? undefined : Number(limitParam),
39
+ ...filters,
40
+ },
41
+ full: fullParam === '1',
42
+ };
43
+ }
44
+ /**
45
+ * Reads the parameters of `GET /api/stats`: the filters of `GET /api/requests`.
46
+ * `limit` and `full` are errors, since the counts are over every match.
47
+ */
48
+ export function parseStatsRequest(params) {
49
+ for (const name of ['limit', 'full']) {
50
+ if (params.has(name)) {
51
+ return { error: `${name} does not apply to /api/stats.` };
52
+ }
53
+ }
54
+ const asked = parseListRequest(params);
55
+ return 'error' in asked ? asked : { query: asked.query };
56
+ }
57
+ /**
58
+ * Reads `model` (any text), `status` (`429`, or a class such as `5xx`) and
59
+ * `failed=1`. Only the filters given are set.
60
+ */
61
+ function parseFilters(params) {
62
+ const filters = {};
63
+ const model = params.get('model');
64
+ if (model !== null) {
65
+ if (!model)
66
+ return { error: 'model must not be empty.' };
67
+ filters.model = model;
68
+ }
69
+ const status = params.get('status');
70
+ if (status !== null) {
71
+ if (!/^[1-5](\d\d|xx)$/.test(status)) {
72
+ return {
73
+ error: `status must be a status code (429) or a class (5xx), not "${status}".`,
74
+ };
75
+ }
76
+ filters.status = status;
77
+ }
78
+ const failed = params.get('failed');
79
+ if (failed !== null) {
80
+ if (failed !== '1') {
81
+ return { error: `failed must be 1, not "${failed}".` };
82
+ }
83
+ filters.failed = true;
84
+ }
85
+ return filters;
86
+ }
87
+ /** The longest `?wait=` takes, in seconds. */
88
+ const MAX_WAIT_SECONDS = 300;
89
+ /**
90
+ * Reads `wait` on the routes of one call: a whole number of seconds from 1 to
91
+ * 300. Without it the call is answered as it is now.
92
+ */
93
+ export function parseWait(params) {
94
+ const wait = params.get('wait');
95
+ if (wait === null)
96
+ return {};
97
+ if (!/^[1-9]\d*$/.test(wait) || Number(wait) > MAX_WAIT_SECONDS) {
98
+ return {
99
+ error: `wait must be a whole number of seconds from 1 to ${MAX_WAIT_SECONDS}, not "${wait}".`,
100
+ };
101
+ }
102
+ return { seconds: Number(wait) };
103
+ }
104
+ /** Epoch ms from digits or an ISO time; NaN for anything else. */
105
+ function parseTime(value) {
106
+ if (/^\d+$/.test(value))
107
+ return Number(value);
108
+ if (!/^\d{4}-\d{2}-\d{2}/.test(value))
109
+ return Number.NaN;
110
+ return Date.parse(value);
111
+ }
@@ -0,0 +1,61 @@
1
+ import { createReadStream } from 'node:fs';
2
+ import { stat } from 'node:fs/promises';
3
+ import * as path from 'node:path';
4
+ const CONTENT_TYPES = {
5
+ '.html': 'text/html; charset=utf-8',
6
+ '.js': 'text/javascript; charset=utf-8',
7
+ '.css': 'text/css; charset=utf-8',
8
+ '.json': 'application/json; charset=utf-8',
9
+ '.map': 'application/json; charset=utf-8',
10
+ '.svg': 'image/svg+xml',
11
+ '.png': 'image/png',
12
+ '.ico': 'image/x-icon',
13
+ '.woff2': 'font/woff2',
14
+ };
15
+ /**
16
+ * Serves a file from `root` (the built UI) for a GET or HEAD request.
17
+ * `/` serves `index.html`. Paths that would leave `root` are refused.
18
+ * Resolves false when there is no such file, so the caller can answer 404.
19
+ */
20
+ export async function serveStatic(req, res, root) {
21
+ if (req.method !== 'GET' && req.method !== 'HEAD')
22
+ return false;
23
+ let pathname;
24
+ try {
25
+ pathname = decodeURIComponent(new URL(req.url ?? '/', 'http://localhost').pathname);
26
+ }
27
+ catch {
28
+ return false;
29
+ }
30
+ if (pathname.includes('\0'))
31
+ return false;
32
+ if (pathname.endsWith('/'))
33
+ pathname += 'index.html';
34
+ const base = path.resolve(root);
35
+ const file = path.resolve(base, `.${pathname}`);
36
+ if (!file.startsWith(base + path.sep))
37
+ return false;
38
+ try {
39
+ const info = await stat(file);
40
+ if (!info.isFile())
41
+ return false;
42
+ res.writeHead(200, {
43
+ 'content-type': CONTENT_TYPES[path.extname(file)] ?? 'application/octet-stream',
44
+ 'content-length': info.size,
45
+ 'cache-control': 'no-cache',
46
+ 'x-content-type-options': 'nosniff',
47
+ });
48
+ if (req.method === 'HEAD') {
49
+ res.end();
50
+ }
51
+ else {
52
+ createReadStream(file)
53
+ .on('error', () => res.destroy())
54
+ .pipe(res);
55
+ }
56
+ return true;
57
+ }
58
+ catch {
59
+ return false;
60
+ }
61
+ }
@@ -0,0 +1,71 @@
1
+ import { isFailed } from './failed.js';
2
+ /** The key in `byModel` for calls with no model (not LLM calls, or failed before one was read). */
3
+ export const NO_MODEL = 'none';
4
+ /** Counts over `summaries`, in all and per model and project. */
5
+ export function toStats(summaries) {
6
+ return {
7
+ ...toCounts(summaries),
8
+ byModel: countBy(summaries, (s) => s.llm?.model ?? NO_MODEL),
9
+ byProject: countBy(summaries, (s) => s.project),
10
+ };
11
+ }
12
+ function countBy(summaries, key) {
13
+ const groups = new Map();
14
+ for (const summary of summaries) {
15
+ const name = key(summary);
16
+ const group = groups.get(name);
17
+ if (group)
18
+ group.push(summary);
19
+ else
20
+ groups.set(name, [summary]);
21
+ }
22
+ // fromEntries defines each key as its own property, so a model named
23
+ // `__proto__` is a key like any other rather than setting the prototype.
24
+ return Object.fromEntries([...groups].map(([name, group]) => [name, toCounts(group)]));
25
+ }
26
+ /** The counts over `summaries`, without the per-model and per-project ones. */
27
+ export function toCounts(summaries) {
28
+ const tokens = {
29
+ input: 0,
30
+ output: 0,
31
+ cacheRead: 0,
32
+ cacheWrite: 0,
33
+ };
34
+ const latencies = [];
35
+ let running = 0;
36
+ let failed = 0;
37
+ for (const summary of summaries) {
38
+ const usage = summary.llm?.usage;
39
+ tokens.input += usage?.input ?? 0;
40
+ tokens.output += usage?.output ?? 0;
41
+ tokens.cacheRead += usage?.cacheRead ?? 0;
42
+ tokens.cacheWrite += usage?.cacheWrite ?? 0;
43
+ if (summary.timings.end === undefined)
44
+ running++;
45
+ else if (summary.latency !== undefined)
46
+ latencies.push(summary.latency);
47
+ if (isFailed(summary))
48
+ failed++;
49
+ }
50
+ return {
51
+ calls: summaries.length,
52
+ running,
53
+ failed,
54
+ tokens,
55
+ latencyMs: toLatency(latencies),
56
+ };
57
+ }
58
+ function toLatency(latencies) {
59
+ if (latencies.length === 0)
60
+ return null;
61
+ const sorted = [...latencies].sort((a, b) => a - b);
62
+ return {
63
+ p50: nearestRank(sorted, 50),
64
+ p95: nearestRank(sorted, 95),
65
+ max: sorted[sorted.length - 1],
66
+ };
67
+ }
68
+ /** The value at rank ceil(p% of n) in `sorted` (ascending, not empty). */
69
+ function nearestRank(sorted, percent) {
70
+ return sorted[Math.ceil((percent / 100) * sorted.length) - 1];
71
+ }
@@ -0,0 +1,68 @@
1
+ // `llmspy stop` (and `npm run stop`): stops the LLMSpy started with `llmspy`,
2
+ // `npm start` or `npm run dev` on this machine, found from the pid file it
3
+ // writes on startup. Not for Docker (use `npm run stop:docker`).
4
+ import { rmSync } from 'node:fs';
5
+ import { PID_FILE, readPidFile } from './pidfile.js';
6
+ const POLL_MS = 100;
7
+ const POLLS = 50;
8
+ /** The pid that answers at `url`, or undefined if nothing does. */
9
+ async function pingPid(url) {
10
+ try {
11
+ const res = await fetch(`${url}/ping`, {
12
+ signal: AbortSignal.timeout(2000),
13
+ });
14
+ return (await res.json()).pid;
15
+ }
16
+ catch {
17
+ return undefined;
18
+ }
19
+ }
20
+ /** Stops the LLMSpy recorded in `file`, and resolves with the exit code. */
21
+ export async function stop(file = PID_FILE) {
22
+ let record;
23
+ try {
24
+ record = readPidFile(file);
25
+ }
26
+ catch (error) {
27
+ console.error(`Could not read ${file}: ${error.message}`);
28
+ return 1;
29
+ }
30
+ if (record === 'none') {
31
+ console.log('LLMSpy is not running (no pid file).');
32
+ return 0;
33
+ }
34
+ if (record === 'invalid') {
35
+ rmSync(file, { force: true });
36
+ console.log('LLMSpy is not running (removed an unreadable pid file).');
37
+ return 0;
38
+ }
39
+ const { pid, url } = record;
40
+ // A pid file left by a process that died without cleaning up may name a
41
+ // pid the system has since given to something else: only stop it if
42
+ // LLMSpy at the recorded URL says it is that process.
43
+ if ((await pingPid(url)) !== pid) {
44
+ rmSync(file, { force: true });
45
+ console.log('LLMSpy is not running (removed a stale pid file).');
46
+ return 0;
47
+ }
48
+ try {
49
+ process.kill(pid, 'SIGTERM');
50
+ }
51
+ catch (error) {
52
+ // It ended between the ping and the kill, which is what we wanted.
53
+ if (error.code !== 'ESRCH')
54
+ throw error;
55
+ }
56
+ // SIGTERM lets the proxy close and remove its pid file; on Windows it ends
57
+ // the process at once, so the file is removed here as well.
58
+ for (let polls = 0; (await pingPid(url)) === pid; polls++) {
59
+ if (polls === POLLS) {
60
+ console.error(`LLMSpy (pid ${pid}) did not stop.`);
61
+ return 1;
62
+ }
63
+ await new Promise((resolve) => setTimeout(resolve, POLL_MS));
64
+ }
65
+ rmSync(file, { force: true });
66
+ console.log(`LLMSpy stopped (pid ${pid}).`);
67
+ return 0;
68
+ }