@geohar/pi-mcp-combiner 0.24.4 → 0.24.5

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 (39) hide show
  1. package/CHANGELOG.md +76 -0
  2. package/dist/client/footer.d.ts +10 -2
  3. package/dist/client/footer.d.ts.map +1 -1
  4. package/dist/client/footer.js +15 -6
  5. package/dist/client/footer.js.map +1 -1
  6. package/dist/combiner-process.d.ts +160 -0
  7. package/dist/combiner-process.d.ts.map +1 -0
  8. package/dist/combiner-process.js +721 -0
  9. package/dist/combiner-process.js.map +1 -0
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js +140 -306
  12. package/dist/index.js.map +1 -1
  13. package/dist/native/combiner-connection.d.ts +84 -0
  14. package/dist/native/combiner-connection.d.ts.map +1 -1
  15. package/dist/native/combiner-connection.js +187 -4
  16. package/dist/native/combiner-connection.js.map +1 -1
  17. package/dist/native/index.d.ts +32 -4
  18. package/dist/native/index.d.ts.map +1 -1
  19. package/dist/native/index.js +94 -6
  20. package/dist/native/index.js.map +1 -1
  21. package/dist/native/resources.d.ts +3 -0
  22. package/dist/native/resources.d.ts.map +1 -1
  23. package/dist/native/resources.js +6 -1
  24. package/dist/native/resources.js.map +1 -1
  25. package/dist/native/tool-surface.d.ts +31 -2
  26. package/dist/native/tool-surface.d.ts.map +1 -1
  27. package/dist/native/tool-surface.js +62 -18
  28. package/dist/native/tool-surface.js.map +1 -1
  29. package/dist/pi.d.ts +8 -0
  30. package/dist/pi.d.ts.map +1 -1
  31. package/package.json +2 -2
  32. package/src/client/footer.ts +16 -4
  33. package/src/combiner-process.ts +813 -0
  34. package/src/index.ts +142 -355
  35. package/src/native/combiner-connection.ts +212 -6
  36. package/src/native/index.ts +119 -18
  37. package/src/native/resources.ts +8 -1
  38. package/src/native/tool-surface.ts +80 -18
  39. package/src/pi.ts +5 -0
@@ -0,0 +1,813 @@
1
+ // The combiner PROCESS, as this pi process sees it: launching it or attaching to it
2
+ // through sharedserver, holding this pi process's reference on it, checking it's
3
+ // alive, respawning it (rate-capped), and releasing the reference at quit. One place
4
+ // for all of it, so there is one launch procedure.
5
+ //
6
+ // Rules (design: pi-one-combiner-process-module-one-attach-function-for-launch-ref-and-respawn-respawn-capped-at-2-per-minute.md):
7
+ // - attach() is the ONLY way pi launches the combiner or takes a ref
8
+ // (`sharedserver use`). Every pi process holds its own ref: sharedserver keys
9
+ // refs by pid, and several pi processes are normally attached at once.
10
+ // - After a reconnect, if the combiner is a DIFFERENT process from the one this pi
11
+ // attached to (someone else started or restarted it, which drops every client's
12
+ // ref), call attach() again: same function, same ref.
13
+ // - When connects are refused, the connection asks onRefused(): our process still
14
+ // alive -> keep retrying; a different process -> attach() and keep retrying;
15
+ // dead -> respawn with attach(), at most RESPAWN_LIMIT times per
16
+ // RESPAWN_WINDOW_MS. One more inside the window stops respawning and reports it.
17
+ // - Host-owned / unmanaged combiners never get a CombinerProcess (index.ts).
18
+ //
19
+ // State is per pi PROCESS (globalThis, Symbol.for): pi re-instantiates the extension
20
+ // for every session (jiti moduleCache:false), but there is one ref per pid.
21
+
22
+ import { spawn, spawnSync } from "node:child_process"
23
+ import { existsSync, mkdirSync, readFileSync } from "node:fs"
24
+ import { homedir } from "node:os"
25
+ import { dirname, join } from "node:path"
26
+ import { fileURLToPath } from "node:url"
27
+ import { resolveSharedserver } from "./sharedserver-resolve.js"
28
+ import type { Liveness } from "./native/combiner-connection.js"
29
+
30
+ export type LogFn = (level: "info" | "warn" | "error", message: string) => void
31
+
32
+ export const DEFAULT_PORT = 9741
33
+ const DEFAULT_NAME = "mcp-combiner"
34
+ const DEFAULT_GRACE = "30m"
35
+ // The `--mcp` serve flag arrived in combiner 0.8.0; older versions serve with a bare
36
+ // `--config`. That boundary is also the floor for trusting a PATH install — below it we
37
+ // fetch a known-good release via uvx rather than limp along. NOT the lockstep release
38
+ // version; it moves only when this extension depends on newer combiner behaviour.
39
+ const MIN_COMBINER_VERSION: [number, number, number] = [0, 8, 0]
40
+ // Floor-only against sharedserver's latest release: this repo consumes sharedserver
41
+ // rather than shipping it. Kept equal to the OpenCode plugin's and the Claude plugin's
42
+ // (bin/sharedserver.conf) values: they resolve the same binary the same way.
43
+ // 0.9.6 adds the launch lock: concurrent `use` calls on a stopped server start exactly
44
+ // one and keep every ref (0.9.5 could start two and lose refs). The automatic respawn
45
+ // in this module relies on it: several pi processes respawn a dead combiner at once.
46
+ const SHAREDSERVER_MIN_VERSION = "0.9.6"
47
+
48
+
49
+ /** Respawn cap: at most RESPAWN_LIMIT respawns in any RESPAWN_WINDOW_MS; one more
50
+ * inside the window means the combiner keeps dying, so stop and report. */
51
+ export const RESPAWN_LIMIT = 2
52
+ export const RESPAWN_WINDOW_MS = 60_000
53
+ /** How often watch() checks that the combiner process still exists. */
54
+ export const WATCH_INTERVAL_MS = 2_000
55
+ /** Every this many watch ticks (~30 s), also re-read sharedserver's view: catches a
56
+ * reused pid and a different combiner process replacing ours. */
57
+ export const WATCH_STATUS_EVERY = 15
58
+ /** How long after this pi launched the combiner it counts as still booting (the
59
+ * connection's first-connect budget). */
60
+ export const COLD_START_MS = 15_000
61
+
62
+ /** `sharedserver use` attempts while the server reads "defunct" (being reaped). */
63
+ const ATTACH_DEFUNCT_RETRIES = 4
64
+ const ATTACH_DEFUNCT_DELAY_MS = 300
65
+
66
+ // ── env configuration ──────────────────────────────────────────────
67
+
68
+ export function env(name: string): string | undefined {
69
+ const v = process.env[name]
70
+ return v !== undefined && v !== "" ? v : undefined
71
+ }
72
+
73
+ function splitArgs(value: string | undefined): string[] {
74
+ if (!value) return []
75
+ return value.split(/\s+/).filter((s) => s.length > 0)
76
+ }
77
+
78
+ // ── combiner command resolution (ported from the OpenCode plugin) ──
79
+
80
+ type Command = {
81
+ cmd: string
82
+ /** Structural args identifying WHAT to run. Probed with; never omitted. */
83
+ args: string[]
84
+ /** The user's own extra args. Appended at spawn time only — never probed with. */
85
+ extra?: string[]
86
+ version?: [number, number, number]
87
+ }
88
+
89
+ function parseVersion(text: string): [number, number, number] | undefined {
90
+ const m = text.match(/(\d+)\.(\d+)\.(\d+)/)
91
+ if (!m) return undefined
92
+ return [Number(m[1]), Number(m[2]), Number(m[3])]
93
+ }
94
+
95
+ function gte(a: [number, number, number], b: [number, number, number]): boolean {
96
+ for (let i = 0; i < 3; i++) {
97
+ if (a[i] !== b[i]) return a[i] > b[i]
98
+ }
99
+ return true
100
+ }
101
+
102
+ /** Probe a command once for BOTH facts: is it runnable, and which version. Presence is
103
+ * "spawn did not fail", NOT "exited 0" — a pre-0.8.0 combiner exits non-zero on
104
+ * `--version` (the flag did not exist), which is exactly the stale install the floor
105
+ * exists to catch. Probes with ONLY the structural args; the user's extras are never
106
+ * folded in, so one arg the CLI rejects cannot make a healthy install look absent. */
107
+ function probe(cmd: Command): { present: boolean; version?: [number, number, number] } {
108
+ const r = spawnSync(cmd.cmd, [...cmd.args, "--version"], { env: process.env })
109
+ if (r.error) return { present: false }
110
+ if (r.status !== 0) return { present: true }
111
+ return { present: true, version: parseVersion(`${r.stdout?.toString() ?? ""}${r.stderr?.toString() ?? ""}`) }
112
+ }
113
+
114
+ function probeUsable(cmd: Command): Command | undefined {
115
+ const { version } = probe(cmd)
116
+ if (!version || !gte(version, MIN_COMBINER_VERSION)) return undefined
117
+ return { ...cmd, version }
118
+ }
119
+
120
+ /** This extension's own version, kept equal to the published PyPI mcp-combiner by
121
+ * lockstep releases (scripts/bump-version.sh). Used as the uvx pin — read from the
122
+ * manifest, never duplicated as a constant. */
123
+ const PLUGIN_VERSION: string | undefined = (() => {
124
+ try {
125
+ const here = dirname(fileURLToPath(import.meta.url))
126
+ const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")) as { version?: string }
127
+ return pkg.version
128
+ } catch {
129
+ return undefined
130
+ }
131
+ })()
132
+
133
+ /** Resolve how to invoke the combiner, mirroring the sibling plugins' priority:
134
+ * explicit env command → `mcp-combiner` on PATH (only when new enough) →
135
+ * `uv run --project <checkout> python -m mcp_combiner` → a pinned release via uvx. The
136
+ * uvx tail is what makes a bare install work with nothing installed by hand. */
137
+ function resolveCombiner(log: LogFn): Command | undefined {
138
+ const extra = splitArgs(env("PI_MCP_COMBINER_ARGS"))
139
+
140
+ const command = env("PI_MCP_COMBINER_COMMAND")
141
+ if (command) {
142
+ return { cmd: command, args: [], extra }
143
+ }
144
+
145
+ const onPath: Command = { cmd: "mcp-combiner", args: [] }
146
+ const pathProbe = probe(onPath)
147
+ if (pathProbe.present) {
148
+ if (pathProbe.version && gte(pathProbe.version, MIN_COMBINER_VERSION)) {
149
+ return { ...onPath, extra, version: pathProbe.version }
150
+ }
151
+ log(
152
+ "warn",
153
+ `mcp-combiner on PATH reports ${pathProbe.version?.join(".") ?? "a pre-0.8.0 version"}, older than ` +
154
+ `${MIN_COMBINER_VERSION.join(".")} — ignoring it and fetching a pinned release instead. ` +
155
+ "Upgrade with: uv tool install --upgrade mcp-combiner",
156
+ )
157
+ }
158
+
159
+ const checkout = env("PI_MCP_COMBINER_CHECKOUT")
160
+ if (checkout && existsSync(checkout) && probe({ cmd: "uv", args: [] }).present) {
161
+ return { cmd: "uv", args: ["run", "--project", checkout, "python", "-m", "mcp_combiner"], extra }
162
+ }
163
+
164
+ // Out-of-the-box path: no install required, fetch from PyPI. Pinned to this
165
+ // extension's version so the pair moves in lockstep; if that exact release is
166
+ // missing, fall back to latest rather than failing. The probe both validates the pin
167
+ // and warms uv's cache, so the real spawn is a cache hit.
168
+ if (probe({ cmd: "uvx", args: [] }).present) {
169
+ if (PLUGIN_VERSION) {
170
+ const pinned = probeUsable({ cmd: "uvx", args: [`mcp-combiner@${PLUGIN_VERSION}`] })
171
+ if (pinned) return { ...pinned, extra }
172
+ log("warn", `pinned mcp-combiner@${PLUGIN_VERSION} unavailable or too old; trying latest from PyPI`)
173
+ }
174
+ const latest = probeUsable({ cmd: "uvx", args: ["mcp-combiner"] })
175
+ if (latest) return { ...latest, extra }
176
+ }
177
+
178
+ return undefined
179
+ }
180
+
181
+ /** True if the resolved combiner supports (needs) the `--mcp` serve flag. Unknown
182
+ * version → assume NO: a version we cannot read is a pre-0.8.0 build serving on a bare
183
+ * `--config`, and a bare `--config` still serves on newer releases (with a deprecation
184
+ * warning), so guessing low degrades gracefully whereas guessing high does not. */
185
+ function combinerNeedsMcpFlag(cmd: Command): boolean {
186
+ const ver = cmd.version ?? probe({ cmd: cmd.cmd, args: cmd.args }).version
187
+ return ver ? gte(ver, MIN_COMBINER_VERSION) : false
188
+ }
189
+
190
+ // ── servers.json resolution (mirrors the sibling plugins) ──
191
+
192
+ function resolveConfig(log: LogFn): string | undefined {
193
+ const explicit = env("PI_MCP_COMBINER_CONFIG")
194
+ if (explicit) return explicit
195
+ const user = process.env.USER ?? process.env.LOGNAME ?? ""
196
+ const candidates = [
197
+ join(homedir(), ".cache", "secrets", `${user}.mcpservers.json`),
198
+ join(homedir(), ".config", "mcp-combiner", "servers.json"),
199
+ join(homedir(), ".config", "mcp", "servers.json"),
200
+ ]
201
+ const found = candidates.find(existsSync)
202
+ if (!found) {
203
+ log(
204
+ "error",
205
+ "no combiner servers.json found; set $PI_MCP_COMBINER_CONFIG (probed " +
206
+ "~/.cache/secrets/<user>.mcpservers.json, ~/.config/mcp-combiner/servers.json, " +
207
+ "~/.config/mcp/servers.json)",
208
+ )
209
+ }
210
+ return found
211
+ }
212
+
213
+ // ── which combiner process ─────────────────────────────────────────
214
+
215
+ /** A combiner process: its pid and start time, so a reused pid isn't mistaken for
216
+ * the same process. */
217
+ export type CombinerIdentity = { pid: number; startTime: number | undefined }
218
+
219
+ /** What sharedserver says about `name` (`sharedserver info <name> --json`):
220
+ * - running: active or in its grace period, with the real server process;
221
+ * - stopped: not running, or defunct (it died; sharedserver is cleaning up);
222
+ * - unknown: a start is still publishing its process (`watcher_pid` null), or the
223
+ * lookup got no answer (`noAnswer`: timed out, errored, or unparseable output).
224
+ * sharedserver answers in a few ms with a definite state, so no answer is a
225
+ * sharedserver bug: callers report it and fall back to checking the pid. */
226
+ export type CombinerStatus =
227
+ | { kind: "running"; identity: CombinerIdentity }
228
+ | { kind: "stopped" }
229
+ | { kind: "unknown"; noAnswer?: string }
230
+
231
+ /** Cap on the synchronous `sharedserver use` / `unuse` (they normally take a few
232
+ * ms; a hung sharedserver must not freeze pi's main thread indefinitely). */
233
+ const SHAREDSERVER_TIMEOUT_MS = 10_000
234
+
235
+ /** How long to wait for `sharedserver info` (it normally answers in ~4 ms). */
236
+ export const STATUS_TIMEOUT_MS = 500
237
+
238
+ /** Parse `sharedserver info --json` output (exported for tests). */
239
+ export function parseCombinerStatus(out: string): CombinerStatus {
240
+ let info: { state?: unknown; pid?: unknown; start_time?: unknown; watcher_pid?: unknown }
241
+ try {
242
+ info = JSON.parse(out) as typeof info
243
+ } catch {
244
+ return { kind: "unknown", noAnswer: "unparseable output" }
245
+ }
246
+ if (info.state === "stopped" || info.state === "defunct") return { kind: "stopped" }
247
+ if (info.state !== "active" && info.state !== "grace") return { kind: "unknown" }
248
+ if (typeof info.pid !== "number" || typeof info.watcher_pid !== "number") return { kind: "unknown" }
249
+ return {
250
+ kind: "running",
251
+ identity: { pid: info.pid, startTime: typeof info.start_time === "number" ? info.start_time : undefined },
252
+ }
253
+ }
254
+
255
+ /** Ask sharedserver about `name`. Async (never blocks pi's main thread). */
256
+ function combinerStatus(binary: string, name: string): Promise<CombinerStatus> {
257
+ return new Promise((resolve) => {
258
+ const child = spawn(binary, ["info", name, "--json"], { stdio: ["ignore", "pipe", "ignore"], env: process.env })
259
+ child.unref()
260
+ let out = ""
261
+ child.stdout?.on("data", (chunk: Buffer) => {
262
+ out += chunk.toString()
263
+ })
264
+ const timer = setTimeout(() => {
265
+ child.kill()
266
+ resolve({ kind: "unknown", noAnswer: `no answer within ${STATUS_TIMEOUT_MS} ms` })
267
+ }, STATUS_TIMEOUT_MS)
268
+ timer.unref()
269
+ child.on("error", (e) => {
270
+ clearTimeout(timer)
271
+ resolve({ kind: "unknown", noAnswer: `couldn't run it (${e.message})` })
272
+ })
273
+ // "close", not "exit": stdout is only fully read by then.
274
+ child.on("close", (code) => {
275
+ clearTimeout(timer)
276
+ resolve(code === 0 ? parseCombinerStatus(out) : { kind: "unknown", noAnswer: `it exited ${code}` })
277
+ })
278
+ })
279
+ }
280
+
281
+ function sameCombiner(a: CombinerIdentity | undefined, b: CombinerIdentity): boolean {
282
+ return a !== undefined && a.pid === b.pid && a.startTime === b.startTime
283
+ }
284
+
285
+ function identityKey(id: CombinerIdentity | undefined): string {
286
+ return id ? `${id.pid}:${id.startTime ?? "?"}` : "unknown"
287
+ }
288
+
289
+ // ── port ───────────────────────────────────────────────────────────
290
+
291
+ /** The port to serve on, reconciling PI_MCP_COMBINER_PORT with any explicit
292
+ * MCP_COMPANION_COMBINER_URL. */
293
+ export function resolvePort(log: LogFn): number {
294
+ const raw = env("PI_MCP_COMBINER_PORT")
295
+ let port = DEFAULT_PORT
296
+ if (raw !== undefined) {
297
+ const n = Number(raw)
298
+ if (Number.isInteger(n) && n > 0) port = n
299
+ else log("warn", `PI_MCP_COMBINER_PORT=${raw} is not a positive integer; using ${DEFAULT_PORT}`)
300
+ }
301
+ const url = env("MCP_COMPANION_COMBINER_URL")
302
+ if (url && raw !== undefined) {
303
+ let urlPort = Number.NaN
304
+ try {
305
+ urlPort = Number(new URL(url).port)
306
+ } catch {
307
+ // malformed URL — fall through to the no-usable-port warning below
308
+ }
309
+ if (!Number.isInteger(urlPort) || urlPort <= 0) {
310
+ log(
311
+ "warn",
312
+ `MCP_COMPANION_COMBINER_URL=${url} has no explicit port; serving on ${port}. ` +
313
+ `Use an explicit port in the URL (e.g. http://127.0.0.1:${port}/mcp).`,
314
+ )
315
+ } else if (urlPort !== port) {
316
+ log(
317
+ "warn",
318
+ `PI_MCP_COMBINER_PORT=${port} disagrees with MCP_COMPANION_COMBINER_URL=${url}; the URL is what ` +
319
+ `pi-mcp-adapter registers, so serving on ${port} would be unreachable — using ${urlPort}. ` +
320
+ "Set them to the same port.",
321
+ )
322
+ port = urlPort
323
+ }
324
+ }
325
+ return port
326
+ }
327
+
328
+ // ── per-process state ──────────────────────────────────────────────
329
+
330
+ /** The combiner process this pi holds its ref on. `identity` is undefined until
331
+ * known (filled in lazily when the attach-time lookup came back unknown). */
332
+ export type Attachment = { binary: string; name: string; identity: CombinerIdentity | undefined }
333
+
334
+ export type ProcessState = {
335
+ attachment: Attachment | null
336
+ /** Set at quit: an attach in flight must not re-take the combiner afterwards. */
337
+ quitting: boolean
338
+ /** attach()'s single flight, so concurrent callers share one `use`; and whether
339
+ * that flight may launch (a launching caller never settles for an attach-only
340
+ * flight that failed). */
341
+ attaching?: Promise<boolean>
342
+ attachingLaunches?: boolean
343
+ /** The respawn in flight, keyed by the dead process: concurrent callers for the
344
+ * same death share it, so one death counts once. */
345
+ respawning?: { key: string; promise: Promise<Liveness> }
346
+ /** When this pi respawned a dead combiner (ms timestamps, newest last). */
347
+ respawns: number[]
348
+ /** Set once the respawn cap was hit (or restarts kept failing); cleared by start(). */
349
+ respawnStopped: boolean
350
+ /** Consecutive restarts whose attach failed (no combiner launched). */
351
+ respawnFailures: number
352
+ /** When this pi's own `use` launched the combiner (it said "Started server"):
353
+ * a combiner that young is still booting, so connects get the cold-start budget. */
354
+ launchedAt?: number
355
+ /** How many times this pi's `use` launched the combiner (vs only attached). */
356
+ launches: number
357
+ /** The combiner's log files, for the report when respawning stops. */
358
+ logs: string[]
359
+ }
360
+
361
+ /** The globalThis key of the per-process state (tests reset it). */
362
+ export const COMBINER_PROCESS_STATE = Symbol.for("mcp-companion:combiner-process")
363
+ const STATE = COMBINER_PROCESS_STATE
364
+ function processState(): ProcessState {
365
+ const g = globalThis as Record<symbol, ProcessState | undefined>
366
+ return (g[STATE] ??= { attachment: null, quitting: false, respawns: [], respawnStopped: false, respawnFailures: 0, launches: 0, logs: [] })
367
+ }
368
+
369
+ /** Process-global guard: the exit and signal handlers are installed once per
370
+ * process no matter how many sessions bind (same trick pi-permission-system's
371
+ * service.ts uses). */
372
+ const CLEANUP_GUARD = Symbol.for("mcp-companion:cleanup-installed")
373
+
374
+ function installProcessCleanup(): void {
375
+ const g = globalThis as Record<symbol, boolean | undefined>
376
+ if (g[CLEANUP_GUARD]) return
377
+ g[CLEANUP_GUARD] = true
378
+ // Belt to the session_shutdown("quit") braces: if Pi is killed hard enough that
379
+ // session_shutdown never fires, still release the refcount. Idempotent via `detach`.
380
+ process.on("exit", () => detach())
381
+ for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as NodeJS.Signals[]) {
382
+ const handler = () => {
383
+ detach()
384
+ // Remove our listener before re-raising: re-killing with the handler
385
+ // still installed re-delivers the signal to it forever (loop verified —
386
+ // ctrl+c wedged pi instead of exiting). Gone, the re-raise falls through
387
+ // to the default disposition and terminates; the idempotent "exit"
388
+ // belt stays for any path that gets there.
389
+ process.removeListener(sig, handler)
390
+ process.kill(process.pid, sig)
391
+ }
392
+ process.on(sig, handler)
393
+ }
394
+ }
395
+
396
+ /** Release this pi process's ref (sharedserver `unuse`). Idempotent. */
397
+ function detach(): void {
398
+ const st = processState()
399
+ if (!st.attachment) return
400
+ const { binary, name } = st.attachment
401
+ st.attachment = null
402
+ spawnSync(binary, ["unuse", name, "--pid", String(process.pid)], {
403
+ stdio: "ignore",
404
+ env: process.env,
405
+ timeout: SHAREDSERVER_TIMEOUT_MS,
406
+ })
407
+ }
408
+
409
+ // ── the class ──────────────────────────────────────────────────────
410
+
411
+ export class CombinerProcess {
412
+ protected readonly state = processState()
413
+ private log: LogFn
414
+ private releaseReady: () => void = () => undefined
415
+ /** Resolves once this instance's start() has run, whatever its outcome. Connects
416
+ * wait on it, so the first connect never races the launch. */
417
+ readonly ready: Promise<void>
418
+ /** Set when a connect succeeded with no attachment (start()'s attach failed):
419
+ * attach once then, not on every reconnect (the attach runs synchronous probes). */
420
+ private reconnectAttachTried = false
421
+
422
+ constructor(log: LogFn) {
423
+ this.log = log
424
+ this.ready = new Promise<void>((resolve) => {
425
+ this.releaseReady = resolve
426
+ })
427
+ }
428
+
429
+ /** True while this pi process holds a ref on a combiner process. */
430
+ get attached(): boolean {
431
+ return this.state.attachment !== null
432
+ }
433
+
434
+ /** session_start: attach (launching if needed) unless this pi process already
435
+ * holds a ref; always releases `ready`. An explicit start also lifts a respawn
436
+ * stop and clears the respawn history. */
437
+ async start(log: LogFn): Promise<void> {
438
+ this.log = log
439
+ try {
440
+ // An explicit start (a new session) is the user's say-so: lift a respawn
441
+ // stop and forget earlier respawns.
442
+ this.state.respawnStopped = false
443
+ this.state.respawns = []
444
+ this.state.respawnFailures = 0
445
+ if (!this.state.attachment) await this.attach()
446
+ } finally {
447
+ this.releaseReady()
448
+ }
449
+ }
450
+
451
+ /** session_shutdown("quit"): release the ref; no attach after this. */
452
+ quit(): void {
453
+ this.state.quitting = true
454
+ detach()
455
+ }
456
+
457
+ /** After a successful (re)connect. Attached: if the combiner is now a different
458
+ * process, attach() again (same function, same ref). Not attached (start()'s
459
+ * attach failed, or respawning stopped): attach once, to a running combiner. */
460
+ async onReconnected(): Promise<void> {
461
+ const att = this.state.attachment
462
+ if (!att) {
463
+ if (this.reconnectAttachTried) return
464
+ this.reconnectAttachTried = true
465
+ await this.attach({ onlyIfRunning: true })
466
+ return
467
+ }
468
+ const status = await this.statusOf(att.binary, att.name)
469
+ if (status.kind !== "running" || this.state.attachment !== att) return
470
+ const ours = await this.attachedIdentity(att)
471
+ if (!ours || sameCombiner(ours, status.identity)) return
472
+ this.log("info", `combiner "${att.name}" is a new process (pid ${status.identity.pid}); attaching to it`)
473
+ await this.attach({ onlyIfRunning: true })
474
+ }
475
+
476
+ /** Between refused-connect retries (the connection's liveness check):
477
+ * - ours, alive: "alive" (a blip), or "relaunched" while our own fresh launch
478
+ * is still booting, so the connect gets the cold-start budget;
479
+ * - a different process: attach to it (same function, same ref), "alive";
480
+ * - ours, stopped: respawn within the cap ("relaunched" / "gone");
481
+ * - unknown, or never attached: "alive". An unknown lookup is never dead, and
482
+ * with nothing of ours to judge there is nothing to respawn. */
483
+ async onRefused(): Promise<Liveness> {
484
+ if (this.state.quitting) return "gone"
485
+ const att = this.state.attachment
486
+ // No attachment: respawning stopped (fail fast; a combiner someone else starts
487
+ // is picked up by onReconnected), or never attached (let the budget run).
488
+ if (!att) return this.state.respawnStopped ? "gone" : "alive"
489
+ const status = await this.statusOf(att.binary, att.name)
490
+ if (this.state.quitting) return "gone"
491
+ // Someone re-attached while we looked (another caller's respawn or attach).
492
+ if (this.state.attachment !== att) return this.booting() ? "relaunched" : "alive"
493
+ if (status.kind === "unknown") {
494
+ // No answer from sharedserver is its bug: report it (once per streak) and
495
+ // decide by our own pid check: gone means dead.
496
+ if (status.noAnswer) this.reportNoAnswer(status.noAnswer)
497
+ const known = att.identity
498
+ if (!known || this.isAlive(known.pid)) return this.booting() ? "relaunched" : "alive"
499
+ return this.respawn(att, known)
500
+ }
501
+ this.noAnswerReported = false
502
+ const ours = await this.attachedIdentity(att)
503
+ if (status.kind === "running") {
504
+ if (!ours) return this.booting() ? "relaunched" : "alive"
505
+ if (sameCombiner(ours, status.identity)) {
506
+ // sharedserver can still read "active" just after a death: trust the pid.
507
+ if (!this.isAlive(ours.pid)) return this.respawn(att, ours)
508
+ return this.booting() ? "relaunched" : "alive"
509
+ }
510
+ // Someone else started a new combiner: same function, same ref.
511
+ await this.attach({ onlyIfRunning: true })
512
+ return "alive"
513
+ }
514
+ return this.respawn(att, ours)
515
+ }
516
+
517
+ /** Respawn our dead combiner with the one attach function, within the cap.
518
+ * Concurrent callers for the same death share one respawn. */
519
+ private respawn(att: Attachment, dead: CombinerIdentity | undefined): Promise<Liveness> {
520
+ const key = identityKey(dead)
521
+ const inflight = this.state.respawning
522
+ if (inflight && inflight.key === key) return inflight.promise
523
+ const promise = (async (): Promise<Liveness> => {
524
+ if (this.state.respawnStopped) return "gone"
525
+ if (this.state.attachment !== att) return "alive" // someone already re-attached
526
+ const t = Date.now()
527
+ this.state.respawns = this.state.respawns.filter((at) => t - at < RESPAWN_WINDOW_MS)
528
+ if (this.state.respawns.length >= RESPAWN_LIMIT) {
529
+ return this.stopRespawning(
530
+ att,
531
+ `the combiner died ${RESPAWN_LIMIT + 1} times within ${RESPAWN_WINDOW_MS / 1000} s; not ` +
532
+ "restarting it again.",
533
+ )
534
+ }
535
+ this.log("warn", "the combiner is not running; restarting it")
536
+ const launchesBefore = this.state.launches
537
+ const ok = await this.attach()
538
+ // Only a restart that actually ran the combiner counts against the cap; a
539
+ // restart that couldn't (sharedserver or the combiner can't be started)
540
+ // counts separately, so it isn't reported as deaths.
541
+ if (ok && this.state.launches !== launchesBefore) this.state.respawns.push(t)
542
+ if (ok) {
543
+ this.state.respawnFailures = 0
544
+ return "relaunched"
545
+ }
546
+ this.state.respawnFailures++
547
+ if (this.state.respawnFailures >= RESPAWN_LIMIT + 1) {
548
+ return this.stopRespawning(
549
+ att,
550
+ `couldn't restart the combiner (${this.state.respawnFailures} attempts in a row); not trying again.`,
551
+ )
552
+ }
553
+ return "gone"
554
+ })().finally(() => {
555
+ if (this.state.respawning?.promise === promise) this.state.respawning = undefined
556
+ })
557
+ this.state.respawning = { key, promise }
558
+ return promise
559
+ }
560
+
561
+ /** Set after reporting that sharedserver gave no answer; cleared by an answer. */
562
+ private noAnswerReported = false
563
+
564
+ private reportNoAnswer(why: string): void {
565
+ if (this.noAnswerReported) return
566
+ this.noAnswerReported = true
567
+ this.log(
568
+ "warn",
569
+ `sharedserver info gave no answer (${why}); judging the combiner by its process instead. ` +
570
+ "sharedserver normally answers in a few ms, so this is worth reporting.",
571
+ )
572
+ }
573
+
574
+ /** Stop respawning and report why, once. The dead process's ref died with it;
575
+ * dropping the attachment lets a combiner someone else starts later be picked up
576
+ * (onReconnected attaches to it). */
577
+ private stopRespawning(att: Attachment, why: string): Liveness {
578
+ this.state.respawnStopped = true
579
+ if (this.state.attachment === att) this.state.attachment = null
580
+ const logs = this.state.logs.length ? ` Its logs: ${this.state.logs.join(", ")}.` : ""
581
+ this.log("error", `${why}${logs} Start a new pi session to try again.`)
582
+ return "gone"
583
+ }
584
+
585
+ /** Record that this pi's attach launched the combiner (rather than attaching to
586
+ * a running one). Protected so a test subclass's scripted launch can call it. */
587
+ protected noteLaunched(): void {
588
+ this.state.launches++
589
+ this.state.launchedAt = Date.now()
590
+ }
591
+
592
+ /** True while a combiner this pi launched is younger than COLD_START_MS. */
593
+ private booting(): boolean {
594
+ const at = this.state.launchedAt
595
+ return at !== undefined && Date.now() - at < COLD_START_MS
596
+ }
597
+
598
+ /** The process our ref is on; fills it in if the attach-time lookup was unknown. */
599
+ private async attachedIdentity(att: Attachment): Promise<CombinerIdentity | undefined> {
600
+ if (att.identity) return att.identity
601
+ const status = await this.statusOf(att.binary, att.name)
602
+ if (status.kind === "running" && this.state.attachment === att && !att.identity) att.identity = status.identity
603
+ return att.identity
604
+ }
605
+
606
+ /** Watch the combiner process this pi holds its ref on. Every WATCH_INTERVAL_MS,
607
+ * check its pid still exists (a syscall, no child process); every
608
+ * WATCH_STATUS_EVERY ticks also ask sharedserver, which catches a reused pid and
609
+ * a different process replacing ours. When ours is gone, call `onGone` once for
610
+ * that process: the caller reconnects, and the reconnect asks onRefused /
611
+ * onReconnected. A dropped connection isn't reliably reported when the combiner
612
+ * dies, so this is what makes recovery prompt. Returns a stop function; nothing
613
+ * is reported after it's called. */
614
+ watch(onGone: () => void): () => void {
615
+ let reportedFor: string | undefined
616
+ let ticks = 0
617
+ let stopped = false
618
+ const report = (key: string) => {
619
+ if (stopped || key === reportedFor) return
620
+ reportedFor = key
621
+ onGone()
622
+ }
623
+ const timer = setInterval(() => {
624
+ ticks++
625
+ void (async () => {
626
+ const att = this.state.attachment
627
+ if (!att || this.state.quitting) return
628
+ const ours = att.identity
629
+ if (!ours) {
630
+ // Identity not known yet: no pid to check. Ask sharedserver only on
631
+ // the periodic ticks, and report a stopped combiner even so.
632
+ if (ticks % WATCH_STATUS_EVERY !== 0) return
633
+ const status = await this.statusOf(att.binary, att.name)
634
+ if (this.state.attachment !== att) return
635
+ if (status.kind === "running" && !att.identity) att.identity = status.identity
636
+ else if (status.kind === "stopped") report("unknown")
637
+ return
638
+ }
639
+ const key = identityKey(ours)
640
+ if (key === reportedFor) return
641
+ if (!this.isAlive(ours.pid)) return report(key)
642
+ if (ticks % WATCH_STATUS_EVERY !== 0) return
643
+ const status = await this.statusOf(att.binary, att.name)
644
+ if (this.state.attachment !== att) return
645
+ if (status.kind === "stopped" || (status.kind === "running" && !sameCombiner(ours, status.identity)))
646
+ report(key)
647
+ })()
648
+ }, WATCH_INTERVAL_MS)
649
+ timer.unref()
650
+ return () => {
651
+ stopped = true
652
+ clearInterval(timer)
653
+ }
654
+ }
655
+
656
+ /** Whether process `pid` exists (a seam for tests). EPERM means it exists but
657
+ * isn't ours to signal. */
658
+ protected isAlive(pid: number): boolean {
659
+ try {
660
+ process.kill(pid, 0)
661
+ return true
662
+ } catch (e) {
663
+ return (e as NodeJS.ErrnoException).code === "EPERM"
664
+ }
665
+ }
666
+
667
+ /** What sharedserver says about the combiner now (a seam for tests). */
668
+ protected statusOf(binary: string, name: string): Promise<CombinerStatus> {
669
+ return combinerStatus(binary, name)
670
+ }
671
+
672
+ /** The ONE attach procedure: `sharedserver use` (launches the combiner when it
673
+ * isn't running, else just takes this pi process's ref), then records which
674
+ * process the ref is on. `onlyIfRunning`: attach to a running combiner, never
675
+ * launch one. Single-flight; resolves true when attached. */
676
+ attach(opts: { onlyIfRunning?: boolean } = {}): Promise<boolean> {
677
+ const launches = !opts.onlyIfRunning
678
+ const inflight = this.state.attaching
679
+ if (inflight) {
680
+ // A launching caller never settles for an attach-only flight that failed.
681
+ if (!launches || this.state.attachingLaunches) return inflight
682
+ return inflight.then((ok) => (ok ? true : this.attach(opts)))
683
+ }
684
+ const flight = this.attachOnce(opts).finally(() => {
685
+ if (this.state.attaching === flight) {
686
+ this.state.attaching = undefined
687
+ this.state.attachingLaunches = undefined
688
+ }
689
+ })
690
+ this.state.attaching = flight
691
+ this.state.attachingLaunches = launches
692
+ return flight
693
+ }
694
+
695
+ /** The attach itself (resolve sharedserver + the combiner, `sharedserver use`,
696
+ * record the identity). Protected so tests can subclass it; nothing else
697
+ * overrides it. */
698
+ protected async attachOnce(opts: { onlyIfRunning?: boolean }): Promise<boolean> {
699
+ if (this.state.quitting) return false
700
+ const log = this.log
701
+ const binary = resolveSharedserver(
702
+ {
703
+ label: "mcp-combiner",
704
+ minVersion: SHAREDSERVER_MIN_VERSION,
705
+ installerUrl:
706
+ "https://github.com/georgeharker/sharedserver/releases/latest/download/sharedserver-installer.sh",
707
+ },
708
+ env("SHAREDSERVER_BIN"),
709
+ process.env,
710
+ log,
711
+ )
712
+ if (!binary) {
713
+ log("error", "sharedserver binary not found; set $SHAREDSERVER_BIN, or PI_MCP_COMBINER_MANAGE=false")
714
+ return false
715
+ }
716
+
717
+ const combiner = resolveCombiner(log)
718
+ if (!combiner) {
719
+ log(
720
+ "error",
721
+ "mcp-combiner could not be found or fetched; install uv and it is fetched from PyPI on demand, " +
722
+ "or install mcp-combiner, or set $PI_MCP_COMBINER_COMMAND / $PI_MCP_COMBINER_CHECKOUT",
723
+ )
724
+ return false
725
+ }
726
+
727
+ const cfgPath = resolveConfig(log)
728
+ if (!cfgPath) return false // resolveConfig already logged the specifics
729
+
730
+ const name = env("PI_MCP_COMBINER_NAME") ?? DEFAULT_NAME
731
+ // `use` launches a stopped server; the reconnect paths must only attach.
732
+ if (opts.onlyIfRunning && (await this.statusOf(binary, name)).kind !== "running") return false
733
+ if (this.state.quitting) return false
734
+ const port = resolvePort(log)
735
+ const grace = env("PI_MCP_COMBINER_GRACE") ?? DEFAULT_GRACE
736
+
737
+ // Assemble: <combiner> [--mcp] --config <cfg> --port <port> [--host <host>]
738
+ const serve: string[] = []
739
+ const modern = combinerNeedsMcpFlag(combiner)
740
+ if (modern) serve.push("--mcp")
741
+ serve.push("--config", cfgPath, "--port", String(port))
742
+ const host = env("PI_MCP_COMBINER_HOST")
743
+ if (host) serve.push("--host", host)
744
+
745
+ // Logging parity with the sibling plugins' two-file scheme: sharedserver captures
746
+ // raw stdout/stderr (--log-file on `use`), and the combiner writes its own
747
+ // --log-file. Both default under $XDG_STATE_HOME/mcp-combiner; "none" disables.
748
+ // Combiner-side flags ride the same version gate as --mcp.
749
+ const logDir = join(process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "mcp-combiner")
750
+ const pyLogFile = env("PI_MCP_COMBINER_PYLOG") ?? join(logDir, "mcp-combiner-py.log")
751
+ if (modern) {
752
+ if (pyLogFile !== "none") serve.push("--log-file", pyLogFile)
753
+ serve.push("--log-level", env("PI_MCP_COMBINER_LOG_LEVEL") ?? "info")
754
+ }
755
+
756
+ const wrappedArgs = [...combiner.args, ...(combiner.extra ?? []), ...serve]
757
+ const useArgs = [
758
+ "use",
759
+ name,
760
+ "--pid",
761
+ String(process.pid),
762
+ "--grace-period",
763
+ grace,
764
+ "--metadata",
765
+ `pi-${process.pid}`,
766
+ ]
767
+ const logFile = env("PI_MCP_COMBINER_LOG") ?? join(logDir, "mcp-combiner.log")
768
+ if (logFile !== "none") {
769
+ try {
770
+ mkdirSync(dirname(logFile), { recursive: true })
771
+ } catch {
772
+ // best-effort — a failed mkdir just means sharedserver may drop the capture
773
+ }
774
+ useArgs.push("--log-file", logFile)
775
+ }
776
+ useArgs.push("--", combiner.cmd, ...wrappedArgs)
777
+
778
+ installProcessCleanup()
779
+ // A combiner that just died reads "defunct" until sharedserver's watcher has
780
+ // reaped it, and `use` refuses with "Retry shortly": retry a few times.
781
+ for (let attempt = 1; ; attempt++) {
782
+ const result = spawnSync(binary, useArgs, { stdio: "pipe", env: process.env, timeout: SHAREDSERVER_TIMEOUT_MS })
783
+ if (result.error) {
784
+ log("error", `${name}: failed to spawn sharedserver (${result.error.message})`)
785
+ return false
786
+ }
787
+ if (result.status === 0) {
788
+ // `use` says "Started server" when it launched the combiner itself.
789
+ if (/Started server/.test(result.stdout?.toString() ?? "")) this.noteLaunched()
790
+ break
791
+ }
792
+ const stderr = result.stderr?.toString().trim() ?? ""
793
+ if (attempt < ATTACH_DEFUNCT_RETRIES && /defunct|retry shortly/i.test(stderr)) {
794
+ await new Promise((resolve) => setTimeout(resolve, ATTACH_DEFUNCT_DELAY_MS).unref())
795
+ // Quit may have released the combiner while we slept: don't re-take it.
796
+ if (this.state.quitting) return false
797
+ continue
798
+ }
799
+ log("error", `${name}: sharedserver use exited ${result.status}${stderr ? ` (${stderr})` : ""}`)
800
+ return false
801
+ }
802
+
803
+ const attachment: Attachment = { binary, name, identity: undefined }
804
+ this.state.attachment = attachment
805
+ this.state.logs = [logFile, pyLogFile].filter((f) => f !== "none")
806
+ void this.statusOf(binary, name).then((status) => {
807
+ if (status.kind === "running" && this.state.attachment === attachment && !attachment.identity)
808
+ attachment.identity = status.identity
809
+ })
810
+ log("info", `combiner "${name}" attached on port ${port} (${combiner.cmd} ${wrappedArgs.join(" ")})`)
811
+ return true
812
+ }
813
+ }