@almyty/mcp-mux 1.2.0

package/README.md

@@ -0,0 +1,99 @@
+# @almyty/mcp-mux
+
+Southbound stdio-MCP **id-rewrite multiplexer**: fan N client sessions into one
+downstream stdio MCP child over a Unix socket, with safe id remapping, framing
+serialization, response routing, and crash-respawn.
+
+> Scope: **southbound MCP only** (almyty as the client/proxy to a downstream MCP
+> server). This package does not touch northbound ACP/A2A serving.
+
+## Why
+
+A stdio MCP server is a single process with one stdin/stdout pair. If several
+sessions write to it concurrently you get interleaved framing and JSON-RPC `id`
+collisions (two clients both pick `id: 1`; responses can't be told apart). This
+package puts the child behind a proxy that:
+
+- **rewrites** every client request `id` to a global monotonic proxy id and
+  reverse-maps `{proxyId -> (sessionId, originalId)}`, so colliding client ids
+  never alias and each response routes home with its original id restored;
+- **serializes** stdin writes through a single async queue, so concurrent
+  sessions can never interleave a frame;
+- **routes** each response to its issuing session; load-and-delete on the id-map
+  means a duplicate/late response is dropped, never double-routed;
+- **isolates teardown**: closing one session drops only that session's mappings,
+  leaving every other session's in-flight requests intact;
+- **survives downstream death**: on child exit, all in-flight requests are
+  errored (`-32011`), the id-map is cleared, and the child is respawned with
+  exponential backoff (3s → 30s).
+
+## Architecture
+
+```
+ clients ──unix socket──► SocketListener ──Session──┐
+                                                    ├──► McpStdioMux ──Downstream──► child stdio MCP
+ Supervisor ──spawn/respawn/reap──► NodeDownstream ─┘     (id remap, write queue,
+   (FSM + error-path resource ledger)                      response routing, TTL sweep)
+```
+
+- `McpStdioMux` — pure logic, owns NO process or socket. Fully unit-testable
+  with in-process fakes (`Downstream` / `Session` are the test seams).
+- `Supervisor` — owns the child lifecycle + respawn/teardown FSM, and enforces
+  the **error-path resource-ownership invariant** (see below).
+- `NodeDownstream` / `SocketListener` — the only files that touch
+  `child_process` / `net`.
+
+### The FD-leak invariant
+
+The reference implementation this was specced against leaked a log fd: `Start()`
+opened it, then errored *before* registering for `Stop()`, so the fd was never
+closed — repeated failing attaches drained the fd budget over hours.
+
+`Supervisor.start()` pre-empts that bug class with an **acquire ledger**: every
+resource acquired is pushed onto a release list *before* the next acquisition.
+If anything throws before the ownership-transfer point, the ledger is unwound in
+reverse. The `FD-LEAK HAMMER` test runs 500 failing starts and asserts the net
+open-handle count returns to zero.
+
+## Usage
+
+```ts
+import { createStdioMux } from '@almyty/mcp-mux';
+
+const handle = await createStdioMux({
+  socketPath: '/tmp/my-mcp.sock',
+  downstream: { command: 'npx', args: ['-y', 'some-mcp-server'] },
+  supervisor: { backoffBaseMs: 3000, backoffCapMs: 30000 },
+});
+
+// ... clients connect to the socket and speak newline-delimited JSON-RPC ...
+
+await handle.close(); // stop accepting, reap child, release resources
+```
+
+## Design note
+
+Full design — id-map lifecycle, framing serialization, response routing, the
+respawn/teardown state machine, and error-path resource ownership — lives in
+[`DESIGN.md`](./DESIGN.md).
+
+## Develop
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit (includes tests)
+npm test            # vitest run
+npm run build       # emits dist/ (tests excluded)
+```
+
+## About almyty
+
+almyty is the full-stack platform for AI agents, agnostic by design: any LLM, any
+API turned into tools, served over MCP, A2A, UTCP, and Agent Skills. Open source,
+no lock-in.
+
+- Website — https://almyty.com
+- Docs — https://docs.almyty.com
+- Source — https://github.com/almyty-inc/almyty
+
+Apache-2.0 © Almyty Inc.

package/dist/create-stdio-mux.d.ts

@@ -0,0 +1,24 @@
+/**
+ * createStdioMux — convenience wiring for the common case: serve one stdio MCP
+ * child to many clients over a Unix socket. Builds the McpStdioMux, a
+ * NodeDownstreamFactory + Supervisor (which owns spawn/respawn), and a
+ * SocketListener, then starts both.
+ *
+ * Returns a handle whose `close()` tears everything down in dependency order:
+ * stop accepting connections, stop the supervisor (reap child + release log),
+ * then close the mux. Southbound only — this never touches northbound serving.
+ */
+import { McpStdioMux } from './mux.js';
+import { Supervisor, type SupervisorOptions } from './supervisor.js';
+import { type NodeDownstreamSpec } from './node-downstream.js';
+export interface StdioMuxConfig {
+    socketPath: string;
+    downstream: NodeDownstreamSpec;
+    supervisor?: SupervisorOptions;
+}
+export interface StdioMuxHandle {
+    readonly mux: McpStdioMux;
+    readonly supervisor: Supervisor;
+    close(): Promise<void>;
+}
+export declare function createStdioMux(config: StdioMuxConfig): Promise<StdioMuxHandle>;

package/dist/create-stdio-mux.js

@@ -0,0 +1,40 @@
+/**
+ * createStdioMux — convenience wiring for the common case: serve one stdio MCP
+ * child to many clients over a Unix socket. Builds the McpStdioMux, a
+ * NodeDownstreamFactory + Supervisor (which owns spawn/respawn), and a
+ * SocketListener, then starts both.
+ *
+ * Returns a handle whose `close()` tears everything down in dependency order:
+ * stop accepting connections, stop the supervisor (reap child + release log),
+ * then close the mux. Southbound only — this never touches northbound serving.
+ */
+import { McpStdioMux } from './mux.js';
+import { Supervisor } from './supervisor.js';
+import { NodeDownstreamFactory } from './node-downstream.js';
+import { SocketListener } from './socket-listener.js';
+export async function createStdioMux(config) {
+    const mux = new McpStdioMux(config.supervisor);
+    const factory = new NodeDownstreamFactory(config.downstream);
+    const supervisor = new Supervisor(factory, mux, config.supervisor);
+    const listener = new SocketListener(mux, { socketPath: config.socketPath });
+    await supervisor.start(); // spawn the child first so early clients have a target
+    try {
+        await listener.listen();
+    }
+    catch (e) {
+        // Listener failed to bind — don't leak the running child.
+        await supervisor.stop();
+        mux.close();
+        throw e;
+    }
+    return {
+        mux,
+        supervisor,
+        async close() {
+            await listener.close();
+            await supervisor.stop();
+            mux.close();
+        },
+    };
+}
+//# sourceMappingURL=create-stdio-mux.js.map

package/dist/create-stdio-mux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-stdio-mux.js","sourceRoot":"","sources":["../src/create-stdio-mux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,UAAU,EAA0B,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAA2B,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AActD,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAsB;IACzD,MAAM,GAAG,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,qBAAqB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAE5E,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,uDAAuD;IACjF,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,0DAA0D;QAC1D,MAAM,UAAU,CAAC,IAAI,EAAE,CAAC;QACxB,GAAG,CAAC,KAAK,EAAE,CAAC;QACZ,MAAM,CAAC,CAAC;IACV,CAAC;IAED,OAAO;QACL,GAAG;QACH,UAAU;QACV,KAAK,CAAC,KAAK;YACT,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC;YACvB,MAAM,UAAU,CAAC,IAAI,EAAE,CAAC;YACxB,GAAG,CAAC,KAAK,EAAE,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { McpStdioMux } from './mux.js';
+export { Supervisor } from './supervisor.js';
+export type { SupervisorOptions, SupervisorState, Closable } from './supervisor.js';
+export { LineReader } from './line-reader.js';
+export { NodeDownstream, NodeDownstreamFactory } from './node-downstream.js';
+export type { NodeDownstreamSpec } from './node-downstream.js';
+export { SocketListener } from './socket-listener.js';
+export type { SocketListenerOptions } from './socket-listener.js';
+export { createStdioMux } from './create-stdio-mux.js';
+export type { StdioMuxConfig, StdioMuxHandle } from './create-stdio-mux.js';
+export { RPC } from './types.js';
+export type { Downstream, DownstreamFactory, DownstreamExit, Session, JsonRpcFrame, JsonRpcId, IdMapping, MuxOptions, } from './types.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { McpStdioMux } from './mux.js';
+export { Supervisor } from './supervisor.js';
+export { LineReader } from './line-reader.js';
+export { NodeDownstream, NodeDownstreamFactory } from './node-downstream.js';
+export { SocketListener } from './socket-listener.js';
+export { createStdioMux } from './create-stdio-mux.js';
+export { RPC } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC"}

package/dist/line-reader.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Newline-delimited frame reader. Downstream stdout arrives in arbitrary
+ * chunks; a frame may span chunks or several frames may share one chunk.
+ * NEVER JSON.parse a raw chunk — buffer until '\n'.
+ */
+export declare class LineReader {
+    private readonly onLine;
+    private buf;
+    constructor(onLine: (line: string) => void);
+    push(chunk: string | Buffer): void;
+    /** Any trailing bytes with no terminating newline (e.g. at EOF). */
+    flushRemainder(): string;
+}

package/dist/line-reader.js

@@ -0,0 +1,31 @@
+/**
+ * Newline-delimited frame reader. Downstream stdout arrives in arbitrary
+ * chunks; a frame may span chunks or several frames may share one chunk.
+ * NEVER JSON.parse a raw chunk — buffer until '\n'.
+ */
+export class LineReader {
+    onLine;
+    buf = '';
+    constructor(onLine) {
+        this.onLine = onLine;
+    }
+    push(chunk) {
+        this.buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        let nl;
+        while ((nl = this.buf.indexOf('\n')) !== -1) {
+            const line = this.buf.slice(0, nl);
+            this.buf = this.buf.slice(nl + 1);
+            // Tolerate \r\n and skip blank keep-alive lines.
+            const trimmed = line.endsWith('\r') ? line.slice(0, -1) : line;
+            if (trimmed.length > 0)
+                this.onLine(trimmed);
+        }
+    }
+    /** Any trailing bytes with no terminating newline (e.g. at EOF). */
+    flushRemainder() {
+        const rem = this.buf;
+        this.buf = '';
+        return rem;
+    }
+}
+//# sourceMappingURL=line-reader.js.map

package/dist/line-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-reader.js","sourceRoot":"","sources":["../src/line-reader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,UAAU;IAGQ;IAFrB,GAAG,GAAG,EAAE,CAAC;IAEjB,YAA6B,MAA8B;QAA9B,WAAM,GAAN,MAAM,CAAwB;IAAG,CAAC;IAE/D,IAAI,CAAC,KAAsB;QACzB,IAAI,CAAC,GAAG,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACvE,IAAI,EAAU,CAAC;QACf,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACnC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YAClC,iDAAiD;YACjD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC/D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,cAAc;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}

package/dist/mux.d.ts

@@ -0,0 +1,52 @@
+/**
+ * McpStdioMux — the multiplexer proper. Fans N sessions into ONE downstream
+ * stdio MCP child:
+ *   - rewrites each client request `id` to a global monotonic proxy id and
+ *     reverse-maps {proxyId -> (sessionId, originalId)} so responses route back;
+ *   - serializes stdin frames (write queue) so concurrent sessions can't
+ *     interleave framing;
+ *   - restores the original id on the way back and routes to the issuing session;
+ *   - on downstream loss, errors every in-flight request and clears the map;
+ *   - per-session teardown removes only that session's mappings.
+ *
+ * It owns NO process and NO socket — the supervisor hands it a Downstream and
+ * the listener hands it Sessions. That keeps it fully unit-testable with fakes.
+ *
+ * Direction scope (v1): client->downstream requests/notifications and
+ * downstream->client responses are fully multiplexed. downstream->client
+ * messages that carry a `method` (server-initiated notifications/requests, e.g.
+ * progress, sampling) are BROADCAST to all sessions — server-initiated requests
+ * cannot be cleanly fanned to one client, so they are surfaced, not routed.
+ */
+import type { Downstream, Session, MuxOptions } from './types.js';
+export declare class McpStdioMux {
+    private readonly idMap;
+    private proxyIdSeq;
+    private readonly sessions;
+    private downstream;
+    private writeChain;
+    private sweepTimer;
+    private closed;
+    private readonly ttlMs;
+    private readonly warn;
+    constructor(opts?: MuxOptions);
+    /** In-flight request count (test/observability). */
+    get inFlight(): number;
+    get sessionCount(): number;
+    setDownstream(downstream: Downstream): void;
+    /** Called by the supervisor when the child is lost; errors all in-flight. */
+    onDownstreamGone(reason: string): void;
+    addSession(session: Session): void;
+    /** Per-session teardown: drop ONLY this session's mappings; never the child. */
+    teardownSession(sessionId: string): void;
+    private onClientFrame;
+    private nextProxyId;
+    /** Serialize frames to the downstream; resolves after the frame is flushed. */
+    private enqueueFrame;
+    private onDownstreamLine;
+    private normalizeId;
+    private sweep;
+    private errorSession;
+    /** Stop sweeping + forget everything. Does not touch the downstream/sessions' sockets. */
+    close(): void;
+}

package/dist/mux.js

@@ -0,0 +1,180 @@
+import { RPC } from './types.js';
+const DEFAULT_TTL_MS = 300_000;
+const DEFAULT_SWEEP_MS = 30_000;
+export class McpStdioMux {
+    idMap = new Map();
+    proxyIdSeq = 0; // monotonic across the mux's life (incl. respawns)
+    sessions = new Map();
+    downstream = null;
+    writeChain = Promise.resolve();
+    sweepTimer = null;
+    closed = false;
+    ttlMs;
+    warn;
+    constructor(opts = {}) {
+        this.ttlMs = opts.requestTtlMs ?? DEFAULT_TTL_MS;
+        this.warn = opts.warn ?? ((m) => process.stderr.write(`[mcp-mux] ${m}\n`));
+        const sweepMs = opts.sweepIntervalMs ?? DEFAULT_SWEEP_MS;
+        this.sweepTimer = setInterval(() => this.sweep(), sweepMs);
+        this.sweepTimer.unref?.();
+    }
+    /** In-flight request count (test/observability). */
+    get inFlight() {
+        return this.idMap.size;
+    }
+    get sessionCount() {
+        return this.sessions.size;
+    }
+    // ── downstream wiring (called by the supervisor on spawn/respawn) ──
+    setDownstream(downstream) {
+        this.downstream = downstream;
+        downstream.on('line', (line) => this.onDownstreamLine(line));
+        downstream.once('exit', () => this.onDownstreamGone('downstream exited'));
+        downstream.on('error', (e) => this.warn(`downstream error: ${e?.message ?? e}`));
+    }
+    /** Called by the supervisor when the child is lost; errors all in-flight. */
+    onDownstreamGone(reason) {
+        this.downstream = null;
+        const affected = new Set();
+        for (const m of this.idMap.values())
+            affected.add(m.sessionId);
+        this.idMap.clear();
+        for (const sid of affected) {
+            this.errorSession(sid, null, RPC.DOWNSTREAM_GONE, `downstream unavailable: ${reason}`);
+        }
+    }
+    // ── session wiring (called by the listener) ──
+    addSession(session) {
+        this.sessions.set(session.id, session);
+        session.on('frame', (frame) => this.onClientFrame(session.id, frame));
+        session.once('close', () => this.teardownSession(session.id));
+    }
+    /** Per-session teardown: drop ONLY this session's mappings; never the child. */
+    teardownSession(sessionId) {
+        for (const [proxyId, m] of this.idMap) {
+            if (m.sessionId === sessionId)
+                this.idMap.delete(proxyId);
+        }
+        this.sessions.delete(sessionId);
+    }
+    // ── client -> downstream ──
+    onClientFrame(sessionId, raw) {
+        if (this.closed)
+            return;
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            this.errorSession(sessionId, null, RPC.PARSE_ERROR, 'invalid JSON frame');
+            return;
+        }
+        // Notification (request without an id): forward verbatim, allocate nothing —
+        // a mapping for something that never gets a response would leak forever.
+        if (frame.id === undefined || frame.id === null) {
+            void this.enqueueFrame(raw);
+            return;
+        }
+        const proxyId = this.nextProxyId();
+        this.idMap.set(proxyId, { sessionId, originalId: frame.id, sentAt: Date.now() });
+        frame.id = proxyId;
+        void this.enqueueFrame(JSON.stringify(frame)).catch(() => {
+            // Write failed (downstream gone / EPIPE): free the mapping and tell the
+            // client now rather than leaving it hung until the TTL sweep.
+            if (this.idMap.delete(proxyId)) {
+                this.errorSession(sessionId, frame.id, RPC.DOWNSTREAM_GONE, 'downstream write failed');
+            }
+        });
+    }
+    nextProxyId() {
+        if (this.proxyIdSeq >= Number.MAX_SAFE_INTEGER) {
+            // ~9e15 ids into a single process life — practically unreachable, but a
+            // wrap would alias live mappings, so refuse loudly instead.
+            throw new Error('mcp-mux: proxy id space exhausted');
+        }
+        return ++this.proxyIdSeq;
+    }
+    /** Serialize frames to the downstream; resolves after the frame is flushed. */
+    enqueueFrame(frame) {
+        const run = async () => {
+            const ds = this.downstream;
+            if (!ds)
+                throw new Error('no downstream');
+            await ds.write(frame);
+        };
+        // Chain so frames never interleave; isolate failures so the chain survives.
+        this.writeChain = this.writeChain.then(run, run);
+        return this.writeChain;
+    }
+    // ── downstream -> client ──
+    onDownstreamLine(line) {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            this.warn(`unparseable downstream line dropped: ${line.slice(0, 120)}`);
+            return;
+        }
+        // Server-initiated (has a method): notification or request. Can't be routed
+        // to one session — broadcast and move on.
+        if (typeof frame.method === 'string') {
+            for (const s of this.sessions.values())
+                s.send(line);
+            return;
+        }
+        // Otherwise it's a response: route by the proxy id.
+        const proxyId = this.normalizeId(frame.id);
+        if (proxyId === null) {
+            this.warn('downstream response with non-numeric id dropped');
+            return;
+        }
+        const mapping = this.idMap.get(proxyId);
+        if (!mapping) {
+            // Unknown or already-freed (duplicate/late) — drop, never double-route.
+            this.warn(`downstream response for unknown id ${proxyId} dropped`);
+            return;
+        }
+        this.idMap.delete(proxyId); // load-and-delete: a second response can't re-route
+        frame.id = mapping.originalId; // restore the client's original id
+        const session = this.sessions.get(mapping.sessionId);
+        if (session)
+            session.send(JSON.stringify(frame));
+        // If the session is already gone, silently drop — its mappings were cleared
+        // at teardown; this guards the late-arrival race.
+    }
+    normalizeId(id) {
+        if (typeof id === 'number' && Number.isSafeInteger(id))
+            return id;
+        if (typeof id === 'string' && /^\d+$/.test(id))
+            return Number(id); // tolerant of stringified ids
+        return null;
+    }
+    // ── TTL sweep ──
+    sweep() {
+        const cutoff = Date.now() - this.ttlMs;
+        for (const [proxyId, m] of this.idMap) {
+            if (m.sentAt <= cutoff) {
+                this.idMap.delete(proxyId);
+                this.errorSession(m.sessionId, m.originalId, RPC.DOWNSTREAM_TIMEOUT, 'downstream did not respond in time');
+            }
+        }
+    }
+    errorSession(sessionId, id, code, message) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        session.send(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }));
+    }
+    /** Stop sweeping + forget everything. Does not touch the downstream/sessions' sockets. */
+    close() {
+        this.closed = true;
+        if (this.sweepTimer)
+            clearInterval(this.sweepTimer);
+        this.sweepTimer = null;
+        this.idMap.clear();
+        this.sessions.clear();
+        this.downstream = null;
+    }
+}
+//# sourceMappingURL=mux.js.map

package/dist/mux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mux.js","sourceRoot":"","sources":["../src/mux.ts"],"names":[],"mappings":"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"}

package/dist/node-downstream.d.ts

@@ -0,0 +1,30 @@
+import { EventEmitter } from 'node:events';
+import type { Downstream, DownstreamFactory } from './types.js';
+export interface NodeDownstreamSpec {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Where to forward the child's stderr. Default: inherit to this process' stderr. */
+    stderr?: 'inherit' | 'ignore' | ((chunk: Buffer) => void);
+}
+export declare class NodeDownstream extends EventEmitter implements Downstream {
+    private readonly child;
+    private readonly reader;
+    private exited;
+    constructor(spec: NodeDownstreamSpec);
+    get pid(): number | undefined;
+    /**
+     * Write one frame + newline. Resolves once the data is accepted (or flushed
+     * past a full buffer). The mux awaits this to serialize framing, so a write
+     * that can't complete must reject rather than silently drop.
+     */
+    write(frame: string): Promise<void>;
+    kill(signal?: NodeJS.Signals): void;
+}
+/** Factory the Supervisor uses to (re)spawn the child on demand. */
+export declare class NodeDownstreamFactory implements DownstreamFactory {
+    private readonly spec;
+    constructor(spec: NodeDownstreamSpec);
+    spawn(): Promise<Downstream>;
+}

package/dist/node-downstream.js

@@ -0,0 +1,76 @@
+/**
+ * NodeDownstream — the real child_process implementation of the `Downstream`
+ * seam. Spawns one stdio MCP server, parses its stdout into newline-delimited
+ * JSON frames (via LineReader, so partial lines never reach the mux), and
+ * serializes writes to stdin with back-pressure-aware flushing.
+ *
+ * This is the ONLY file in the package that touches child_process; everything
+ * else is driven through the `Downstream` interface so it stays unit-testable.
+ */
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { LineReader } from './line-reader.js';
+export class NodeDownstream extends EventEmitter {
+    child;
+    reader = new LineReader((line) => this.emit('line', line));
+    exited = false;
+    constructor(spec) {
+        super();
+        const stderrMode = spec.stderr === undefined ? 'inherit' : spec.stderr;
+        this.child = spawn(spec.command, spec.args ?? [], {
+            cwd: spec.cwd,
+            env: spec.env,
+            stdio: ['pipe', 'pipe', typeof stderrMode === 'function' ? 'pipe' : stderrMode],
+        });
+        this.child.stdout.on('data', (chunk) => this.reader.push(chunk));
+        if (typeof stderrMode === 'function' && this.child.stderr) {
+            this.child.stderr.on('data', stderrMode);
+        }
+        this.child.on('error', (err) => this.emit('error', err));
+        this.child.once('exit', (code, signal) => {
+            this.exited = true;
+            const tail = this.reader.flushRemainder();
+            if (tail)
+                this.emit('line', tail);
+            this.emit('exit', { code, signal });
+        });
+    }
+    get pid() {
+        return this.child.pid;
+    }
+    /**
+     * Write one frame + newline. Resolves once the data is accepted (or flushed
+     * past a full buffer). The mux awaits this to serialize framing, so a write
+     * that can't complete must reject rather than silently drop.
+     */
+    write(frame) {
+        return new Promise((resolve, reject) => {
+            if (this.exited || !this.child.stdin.writable) {
+                reject(new Error('downstream stdin not writable'));
+                return;
+            }
+            this.child.stdin.write(frame + '\n', (err) => (err ? reject(err) : resolve()));
+        });
+    }
+    kill(signal = 'SIGTERM') {
+        if (this.exited)
+            return;
+        try {
+            this.child.kill(signal);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** Factory the Supervisor uses to (re)spawn the child on demand. */
+export class NodeDownstreamFactory {
+    spec;
+    constructor(spec) {
+        this.spec = spec;
+    }
+    async spawn() {
+        return new NodeDownstream(this.spec);
+    }
+}
+//# sourceMappingURL=node-downstream.js.map

package/dist/node-downstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-downstream.js","sourceRoot":"","sources":["../src/node-downstream.ts"],"names":[],"mappings":"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"}

package/dist/socket-listener.d.ts

@@ -0,0 +1,16 @@
+import type { McpStdioMux } from './mux.js';
+export interface SocketListenerOptions {
+    /** Filesystem path for the Unix domain socket. */
+    socketPath: string;
+}
+export declare class SocketListener {
+    private readonly mux;
+    private readonly opts;
+    private readonly server;
+    private seq;
+    constructor(mux: McpStdioMux, opts: SocketListenerOptions);
+    /** Register the connection with the mux SYNCHRONOUSLY — no await before this. */
+    private onConnection;
+    listen(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/socket-listener.js

@@ -0,0 +1,77 @@
+/**
+ * SocketListener — the real Unix-socket implementation of the inbound side.
+ * Each accepted connection becomes one `Session`: its stream is framed by a
+ * LineReader (partial lines never reach the mux), `send` writes frame+newline,
+ * and `close` destroys the socket. The listener registers each session with the
+ * mux; the mux tears the session down on the socket's 'close' event.
+ *
+ * One process leak class to avoid here too: a socket accepted but never handed
+ * to the mux would leak. We register synchronously on 'connection', before any
+ * await, so every accepted fd has an owner.
+ */
+import { createServer } from 'node:net';
+import { EventEmitter } from 'node:events';
+import { LineReader } from './line-reader.js';
+class SocketSession extends EventEmitter {
+    id;
+    socket;
+    reader;
+    closed = false;
+    constructor(id, socket) {
+        super();
+        this.id = id;
+        this.socket = socket;
+        this.reader = new LineReader((line) => this.emit('frame', line));
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => this.reader.push(chunk));
+        socket.once('close', () => this.markClosed());
+        socket.on('error', () => this.markClosed());
+    }
+    send(frame) {
+        if (this.closed || !this.socket.writable)
+            return;
+        this.socket.write(frame + '\n');
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.socket.destroy();
+        // 'close' will fire markClosed(); guard in case destroy is synchronous.
+        this.markClosed();
+    }
+    markClosed() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.emit('close');
+    }
+}
+export class SocketListener {
+    mux;
+    opts;
+    server;
+    seq = 0;
+    constructor(mux, opts) {
+        this.mux = mux;
+        this.opts = opts;
+        this.server = createServer((socket) => this.onConnection(socket));
+    }
+    /** Register the connection with the mux SYNCHRONOUSLY — no await before this. */
+    onConnection(socket) {
+        const session = new SocketSession(`s${++this.seq}`, socket);
+        this.mux.addSession(session); // mux wires 'frame'/'close' and owns teardown
+    }
+    listen() {
+        return new Promise((resolve, reject) => {
+            this.server.once('error', reject);
+            this.server.listen(this.opts.socketPath, () => {
+                this.server.removeListener('error', reject);
+                resolve();
+            });
+        });
+    }
+    close() {
+        return new Promise((resolve) => this.server.close(() => resolve()));
+    }
+}
+//# sourceMappingURL=socket-listener.js.map

package/dist/socket-listener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-listener.js","sourceRoot":"","sources":["../src/socket-listener.ts"],"names":[],"mappings":"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"}

package/dist/supervisor.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Supervisor — owns the downstream child's lifecycle and the respawn/teardown
+ * state machine, and enforces the error-path resource-ownership invariant that
+ * pre-empts the reference's FD leak.
+ *
+ *   idle ──start()ok──► running ──exit/error──► failed ──reap+sweep──► respawning ──backoff──► (start again)
+ *     ▲                    │
+ *     └──── stop() ────────┴──────────────────────────────────────────► stopped (terminal)
+ *
+ * THE INVARIANT (their bug class): every resource acquired in start() is pushed
+ * onto an `acquired` ledger BEFORE the next acquisition. If anything throws
+ * before ownership is transferred (registerForStop), the ledger is unwound in
+ * reverse — so a half-built start can never leak a log fd / socket / child.
+ * Their leak: Start() opened a log fd, then errored before registering for
+ * Stop(); the fd was never closed; repeated failing attaches drained the budget.
+ */
+import type { DownstreamFactory, MuxOptions } from './types.js';
+import type { McpStdioMux } from './mux.js';
+export interface Closable {
+    close(): void;
+}
+export type SupervisorState = 'idle' | 'running' | 'failed' | 'respawning' | 'stopped';
+export interface SupervisorOptions extends MuxOptions {
+    /** Acquire the leak-prone pre-spawn resource (e.g. a log fd). Optional. */
+    openLog?: () => Closable;
+    backoffBaseMs?: number;
+    backoffCapMs?: number;
+    /** A run lasting at least this long resets the backoff. */
+    backoffResetAfterMs?: number;
+}
+export declare class Supervisor {
+    private readonly factory;
+    private readonly mux;
+    private readonly opts;
+    private state;
+    private downstream;
+    private log;
+    private childExited;
+    private reaped;
+    private respawnTimer;
+    private backoffMs;
+    private runStartedAt;
+    private readonly warn;
+    private readonly backoffBaseMs;
+    private readonly backoffCapMs;
+    private readonly backoffResetAfterMs;
+    constructor(factory: DownstreamFactory, mux: McpStdioMux, opts?: SupervisorOptions);
+    get current(): SupervisorState;
+    /**
+     * Acquire resources + spawn the downstream. The ledger guarantees that any
+     * failure before ownership transfer releases everything acquired so far.
+     */
+    start(): Promise<void>;
+    /** Child exited unexpectedly (or via our kill during reap). */
+    private onChildExit;
+    /** Kill (if alive) + mark reaped EXACTLY once — pre-empts double-kill/zombie. */
+    private reap;
+    private releaseLog;
+    private scheduleRespawn;
+    /** Terminal shutdown. Idempotent. Cancels respawn, reaps, releases resources. */
+    stop(): Promise<void>;
+}

package/dist/supervisor.js

@@ -0,0 +1,160 @@
+export class Supervisor {
+    factory;
+    mux;
+    opts;
+    state = 'idle';
+    downstream = null;
+    log = null;
+    childExited = false;
+    reaped = false;
+    respawnTimer = null;
+    backoffMs;
+    runStartedAt = 0;
+    warn;
+    backoffBaseMs;
+    backoffCapMs;
+    backoffResetAfterMs;
+    constructor(factory, mux, opts = {}) {
+        this.factory = factory;
+        this.mux = mux;
+        this.opts = opts;
+        this.warn = opts.warn ?? ((m) => process.stderr.write(`[mcp-mux:sup] ${m}\n`));
+        this.backoffBaseMs = opts.backoffBaseMs ?? 3_000;
+        this.backoffCapMs = opts.backoffCapMs ?? 30_000;
+        this.backoffResetAfterMs = opts.backoffResetAfterMs ?? 30_000;
+        this.backoffMs = this.backoffBaseMs;
+    }
+    get current() {
+        return this.state;
+    }
+    /**
+     * Acquire resources + spawn the downstream. The ledger guarantees that any
+     * failure before ownership transfer releases everything acquired so far.
+     */
+    async start() {
+        if (this.state === 'stopped')
+            throw new Error('supervisor stopped');
+        const acquired = [];
+        const unwind = () => {
+            while (acquired.length) {
+                try {
+                    acquired.pop()();
+                }
+                catch (e) {
+                    this.warn(`cleanup error: ${e?.message ?? e}`);
+                }
+            }
+        };
+        try {
+            // (1) leak-prone pre-spawn resource
+            if (this.opts.openLog) {
+                const log = this.opts.openLog();
+                acquired.push(() => log.close());
+                this.log = log;
+            }
+            // (2) the child + its pipes
+            const ds = await this.factory.spawn();
+            acquired.push(() => {
+                try {
+                    ds.kill('SIGKILL');
+                }
+                catch {
+                    /* */
+                }
+            });
+            // (3) wire it up — still inside the guarded region
+            this.childExited = false;
+            this.reaped = false;
+            ds.once('exit', () => this.onChildExit());
+            this.mux.setDownstream(ds);
+            // ── ownership transfer point ──
+            // Past here the Supervisor (via stop()) owns these; do NOT unwind them.
+            this.downstream = ds;
+            acquired.length = 0;
+            this.state = 'running';
+            this.runStartedAt = Date.now();
+        }
+        catch (e) {
+            unwind(); // releases log + child if acquired
+            this.log = null;
+            this.downstream = null;
+            this.state = 'failed';
+            throw e;
+        }
+    }
+    /** Child exited unexpectedly (or via our kill during reap). */
+    onChildExit() {
+        this.childExited = true;
+        if (this.state === 'stopped')
+            return; // intentional shutdown; nothing to do
+        // Reset backoff if the run was healthy for long enough.
+        if (Date.now() - this.runStartedAt >= this.backoffResetAfterMs) {
+            this.backoffMs = this.backoffBaseMs;
+        }
+        this.state = 'failed';
+        this.reap();
+        // NOTE: we do NOT call mux.onDownstreamGone() here. The mux self-subscribes
+        // to its downstream's 'exit' in setDownstream() and clears its own in-flight
+        // state. Single ownership: the mux owns its id-map; the supervisor owns the
+        // process (reap) and the respawn FSM. Calling it here would double-fire.
+        this.releaseLog();
+        this.scheduleRespawn();
+    }
+    /** Kill (if alive) + mark reaped EXACTLY once — pre-empts double-kill/zombie. */
+    reap() {
+        if (this.reaped)
+            return;
+        this.reaped = true;
+        const ds = this.downstream;
+        this.downstream = null;
+        if (ds && !this.childExited) {
+            try {
+                ds.kill('SIGKILL');
+            }
+            catch {
+                /* */
+            }
+        }
+    }
+    releaseLog() {
+        if (this.log) {
+            try {
+                this.log.close();
+            }
+            catch {
+                /* */
+            }
+            this.log = null;
+        }
+    }
+    scheduleRespawn() {
+        if (this.respawnTimer || this.state === 'stopped')
+            return; // never two in flight
+        this.state = 'respawning';
+        const delay = this.backoffMs;
+        this.backoffMs = Math.min(this.backoffCapMs, this.backoffMs * 2);
+        this.respawnTimer = setTimeout(() => {
+            this.respawnTimer = null;
+            if (this.state === 'stopped')
+                return;
+            this.start().catch((e) => {
+                this.warn(`respawn failed: ${e?.message ?? e}`);
+                this.scheduleRespawn(); // start() already set state=failed; back off again
+            });
+        }, delay);
+        this.respawnTimer.unref?.();
+    }
+    /** Terminal shutdown. Idempotent. Cancels respawn, reaps, releases resources. */
+    async stop() {
+        if (this.state === 'stopped')
+            return;
+        this.state = 'stopped';
+        if (this.respawnTimer) {
+            clearTimeout(this.respawnTimer);
+            this.respawnTimer = null;
+        }
+        this.reap();
+        this.releaseLog();
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Wire + seam types for the southbound stdio-MCP multiplexer.
+ *
+ * The `Downstream` and `Session` interfaces are the test seams (mirroring the
+ * runner's AdapterFactory idiom): the multiplexer never spawns a process or
+ * opens a socket itself — it's handed these, so tests inject in-process fakes.
+ */
+import type { EventEmitter } from 'node:events';
+/** A JSON-RPC id per the spec: string | number | null (null only on errors). */
+export type JsonRpcId = string | number | null;
+/** Minimal JSON-RPC frame. We only care about `id`; everything else is opaque. */
+export interface JsonRpcFrame {
+    jsonrpc?: string;
+    id?: JsonRpcId;
+    method?: string;
+    [k: string]: unknown;
+}
+/** One proxy-id -> origin reverse-map entry. */
+export interface IdMapping {
+    sessionId: string;
+    originalId: JsonRpcId;
+    /** Epoch ms the request was forwarded — drives TTL eviction. */
+    sentAt: number;
+}
+/**
+ * One downstream MCP child as seen by the multiplexer. Emits exactly one
+ * `'line'` per complete newline-delimited JSON frame from the child's stdout
+ * (partial-line buffering is the implementation's job, never the consumer's),
+ * and `'exit'` once when the child is gone.
+ *
+ * `write` resolves only after the frame (including its trailing newline) is
+ * flushed past back-pressure, so the caller can serialize frames by awaiting.
+ */
+export interface Downstream extends EventEmitter {
+    readonly pid: number | undefined;
+    /** Write one already-serialized JSON frame (no trailing newline; we add it). */
+    write(frame: string): Promise<void>;
+    /** Best-effort terminate. */
+    kill(signal?: NodeJS.Signals): void;
+}
+export interface DownstreamExit {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
+/** Factory the supervisor uses to (re)spawn the downstream. */
+export interface DownstreamFactory {
+    spawn(): Promise<Downstream>;
+}
+/**
+ * One client connection == one session. The multiplexer reads `'frame'`
+ * events (incoming client frames) and calls `send` to push responses back.
+ */
+export interface Session extends EventEmitter {
+    readonly id: string;
+    /** Push one serialized JSON frame to the client (newline added by impl). */
+    send(frame: string): void;
+    close(): void;
+}
+export interface MuxOptions {
+    /** Evict id-map entries older than this (ms) and error their sessions. Default 300_000. */
+    requestTtlMs?: number;
+    /** Sweep cadence (ms). Default 30_000. */
+    sweepIntervalMs?: number;
+    /** Non-fatal logger. Defaults to stderr. */
+    warn?: (msg: string) => void;
+}
+/** JSON-RPC error codes we synthesize. */
+export declare const RPC: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly INTERNAL: -32603;
+    readonly DOWNSTREAM_TIMEOUT: -32010;
+    readonly DOWNSTREAM_GONE: -32011;
+};

package/dist/types.js

@@ -0,0 +1,9 @@
+/** JSON-RPC error codes we synthesize. */
+export const RPC = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    INTERNAL: -32603,
+    DOWNSTREAM_TIMEOUT: -32010,
+    DOWNSTREAM_GONE: -32011,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA6EA,0CAA0C;AAC1C,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,WAAW,EAAE,CAAC,KAAK;IACnB,eAAe,EAAE,CAAC,KAAK;IACvB,QAAQ,EAAE,CAAC,KAAK;IAChB,kBAAkB,EAAE,CAAC,KAAK;IAC1B,eAAe,EAAE,CAAC,KAAK;CACf,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@almyty/mcp-mux",
+  "version": "1.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "stdio-MCP multiplexer \u2014 fans many client sessions into one downstream MCP child over a Unix socket, rewriting ids. Internal almyty plumbing.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.0"
+  },
+  "keywords": [
+    "almyty",
+    "mcp",
+    "multiplexer",
+    "stdio",
+    "proxy"
+  ],
+  "author": "almyty",
+  "license": "Apache-2.0",
+  "homepage": "https://almyty.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almyty-inc/almyty.git",
+    "directory": "packages/mcp-mux"
+  },
+  "bugs": {
+    "url": "https://github.com/almyty-inc/almyty/issues"
+  }
+}