@minionry/minion 0.7.36

package/dist/server/services/browser/index.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+export { BrowserHostService, ElectronBrowserHost, MockBrowserHost } from './host.js';
+export { BrowserPreflightError, chromiumInstallCommands, detectPackageManager, pipewireInstallCommands, preflight, xvfbInstallCommands, } from './preflight.js';

package/dist/server/services/browser/ipc-client.js

@@ -0,0 +1,354 @@
+import { encodeFrame, FrameParser, isPlainObject, JsonRpcError, JsonRpcErrorCode, } from "../../../electron-host/ipc-protocol.js";
+import { browserLog } from "./debug-log.js";
+const log = browserLog('ipc');
+const NOISY_NOTIFY = new Set(['input.forward']);
+function isNoisy(method) {
+    return NOISY_NOTIFY.has(method);
+}
+export { JsonRpcError, JsonRpcErrorCode, };
+export class IpcClient {
+    defaultTimeoutMs;
+    onError;
+    onDisconnect;
+    onFatal;
+    listeners = new Map();
+    transport = null;
+    parser = null;
+    writeChain = Promise.resolve();
+    pending = new Map();
+    nextId = 1;
+    unheardEvents = new Set();
+    boundOnData = null;
+    boundOnEnd = null;
+    boundOnError = null;
+    constructor(opts = {}) {
+        this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 30_000;
+        this.onError =
+            opts.onError ??
+                ((err) => {
+                    console.error("[ipc-client]", err);
+                });
+        this.onDisconnect = opts.onDisconnect;
+        this.onFatal = opts.onFatal;
+    }
+    connect(transport) {
+        if (this.transport) {
+            throw new Error("IpcClient: already connected — call disconnect() first");
+        }
+        this.transport = transport;
+        this.parser = new FrameParser();
+        this.boundOnData = (chunk) => this.handleChunk(chunk);
+        this.boundOnEnd = () => this.handleEnd();
+        this.boundOnError = (err) => this.onError(err);
+        transport.readable.on("data", this.boundOnData);
+        transport.readable.on("end", this.boundOnEnd);
+        transport.readable.on("error", this.boundOnError);
+        transport.writable.on("error", this.boundOnError);
+    }
+    async disconnect() {
+        const transport = this.transport;
+        if (!transport)
+            return;
+        this.transport = null;
+        if (this.boundOnData)
+            transport.readable.off("data", this.boundOnData);
+        if (this.boundOnEnd)
+            transport.readable.off("end", this.boundOnEnd);
+        if (this.boundOnError) {
+            transport.readable.off("error", this.boundOnError);
+            transport.writable.off("error", this.boundOnError);
+        }
+        this.boundOnData = null;
+        this.boundOnEnd = null;
+        this.boundOnError = null;
+        this.parser = null;
+        this.rejectInflight("disconnect", new Error("IpcClient: disconnected before response"));
+        try {
+            await this.writeChain;
+        }
+        catch {
+        }
+        this.writeChain = Promise.resolve();
+    }
+    call(method, params, opts = {}) {
+        if (!this.transport) {
+            return Promise.reject(new Error("IpcClient: not connected"));
+        }
+        if (opts.signal?.aborted) {
+            return Promise.reject(this.abortError(opts.signal));
+        }
+        const id = this.nextId++;
+        const request = {
+            jsonrpc: "2.0",
+            id,
+            method,
+            ...(params === undefined ? {} : { params }),
+        };
+        const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
+        if (!isNoisy(method))
+            log('call', `id=${id} method=${method}`);
+        return new Promise((resolve, reject) => {
+            const pending = {
+                method,
+                startedAt: Date.now(),
+                resolve: resolve,
+                reject,
+                timer: null,
+            };
+            if (timeoutMs > 0) {
+                pending.timer = setTimeout(() => {
+                    if (!this.pending.has(id))
+                        return;
+                    this.pending.delete(id);
+                    this.detachAbort(pending);
+                    log.error('call.timeout', `id=${id} method=${method} after=${timeoutMs}ms inflight=${this.pending.size}`);
+                    reject(new JsonRpcError(JsonRpcErrorCode.InternalError, `IpcClient: request "${method}" timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }
+            if (opts.signal) {
+                const signal = opts.signal;
+                pending.signal = signal;
+                pending.onAbort = () => {
+                    if (!this.pending.has(id))
+                        return;
+                    this.pending.delete(id);
+                    this.clearTimer(pending);
+                    reject(this.abortError(signal));
+                };
+                signal.addEventListener("abort", pending.onAbort, { once: true });
+            }
+            this.pending.set(id, pending);
+            this.send(request).catch((err) => {
+                if (!this.pending.has(id))
+                    return;
+                this.pending.delete(id);
+                this.clearTimer(pending);
+                this.detachAbort(pending);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
+        });
+    }
+    notify(event, payload) {
+        if (!isNoisy(event))
+            log('notify', `method=${event}`);
+        const message = {
+            jsonrpc: "2.0",
+            method: event,
+            ...(payload === undefined ? {} : { params: payload }),
+        };
+        return this.send(message);
+    }
+    on(event, handler) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(handler);
+        return () => {
+            this.off(event, handler);
+        };
+    }
+    off(event, handler) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        set.delete(handler);
+        if (set.size === 0)
+            this.listeners.delete(event);
+    }
+    get pendingCount() {
+        return this.pending.size;
+    }
+    get connected() {
+        return this.transport !== null;
+    }
+    clearTimer(p) {
+        if (p.timer) {
+            clearTimeout(p.timer);
+            p.timer = null;
+        }
+    }
+    detachAbort(p) {
+        if (p.signal && p.onAbort) {
+            p.signal.removeEventListener("abort", p.onAbort);
+            p.onAbort = undefined;
+        }
+    }
+    abortError(signal) {
+        if (signal.reason instanceof Error)
+            return signal.reason;
+        const message = typeof signal.reason === "string" && signal.reason.length > 0
+            ? signal.reason
+            : "IpcClient: request aborted";
+        const err = new Error(message);
+        err.name = "AbortError";
+        return err;
+    }
+    handleChunk(chunk) {
+        if (!this.parser)
+            return;
+        try {
+            this.parser.push(chunk, (json) => this.handleMessage(json));
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.parser = null;
+            this.onError(error);
+            this.rejectInflight("stream.unreadable", error);
+            this.onFatal?.(error);
+        }
+    }
+    handleEnd() {
+        this.rejectInflight("peer.closed", new Error("IpcClient: the peer closed the channel before responding"));
+        this.onDisconnect?.();
+    }
+    rejectInflight(why, err) {
+        const inflight = Array.from(this.pending.values());
+        this.pending.clear();
+        if (inflight.length === 0)
+            return;
+        log.info(why, `rejecting ${inflight.length} in-flight call(s): ${inflight.map((p) => p.method).join(',')}`);
+        for (const p of inflight) {
+            this.clearTimer(p);
+            this.detachAbort(p);
+            p.reject(err);
+        }
+    }
+    handleMessage(json) {
+        let parsed;
+        try {
+            parsed = JSON.parse(json);
+        }
+        catch (err) {
+            this.onError(new JsonRpcError(JsonRpcErrorCode.ParseError, "IpcClient: failed to parse incoming JSON", { cause: err instanceof Error ? err.message : String(err) }));
+            return;
+        }
+        if (!isPlainObject(parsed) || parsed.jsonrpc !== "2.0") {
+            this.onError(new JsonRpcError(JsonRpcErrorCode.InvalidRequest, "IpcClient: received non-JSON-RPC 2.0 message"));
+            return;
+        }
+        const hasResult = "result" in parsed;
+        const hasError = "error" in parsed;
+        if (hasResult || hasError) {
+            this.handleResponse(parsed);
+            return;
+        }
+        const method = parsed.method;
+        if (typeof method !== "string" || method.length === 0) {
+            this.onError(new JsonRpcError(JsonRpcErrorCode.InvalidRequest, "IpcClient: incoming notification missing method"));
+            return;
+        }
+        const params = parsed.params;
+        this.dispatchEvent(method, params);
+    }
+    handleResponse(response) {
+        const id = response.id;
+        if (id === null || id === undefined) {
+            if ("error" in response) {
+                this.onError(new JsonRpcError(response.error.code, response.error.message, response.error.data));
+            }
+            return;
+        }
+        const pending = this.pending.get(id);
+        if (!pending) {
+            log.warn('response.orphan', `id=${id}`);
+            return;
+        }
+        this.pending.delete(id);
+        this.clearTimer(pending);
+        this.detachAbort(pending);
+        const ms = Date.now() - pending.startedAt;
+        if ("error" in response) {
+            const body = response.error;
+            log.warn('response.error', `id=${id} method=${pending.method} ms=${ms} code=${body.code} msg=${body.message}`);
+            pending.reject(new JsonRpcError(body.code, body.message, body.data));
+        }
+        else {
+            if (!isNoisy(pending.method))
+                log('response.ok', `id=${id} method=${pending.method} ms=${ms}`);
+            pending.resolve(response.result);
+        }
+    }
+    dispatchEvent(event, params) {
+        const set = this.listeners.get(event);
+        if (!set || set.size === 0) {
+            if (isNoisy(event))
+                return;
+            if (!this.unheardEvents.has(event)) {
+                this.unheardEvents.add(event);
+                log.info('event.noListener', `method=${event} — the Electron host emits it but nothing subscribed; dropped (reported once)`);
+            }
+            else {
+                log('event.noListener', `method=${event}`);
+            }
+            return;
+        }
+        if (!isNoisy(event))
+            log('event', `method=${event} listeners=${set.size}`);
+        for (const handler of Array.from(set)) {
+            try {
+                handler(params);
+            }
+            catch (err) {
+                this.onError(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+    }
+    send(message) {
+        const transport = this.transport;
+        if (!transport)
+            return Promise.reject(new Error("IpcClient: not connected"));
+        const frame = encodeFrame(message);
+        const next = this.writeChain.then(() => this.writeOne(transport, frame), () => this.writeOne(transport, frame));
+        this.writeChain = next.catch(() => undefined);
+        return next;
+    }
+    writeOne(transport, frame) {
+        return new Promise((resolve, reject) => {
+            const writable = transport.writable;
+            if (writable.writableEnded || writable.destroyed) {
+                reject(new Error("IpcClient: transport writable is closed"));
+                return;
+            }
+            let settled = false;
+            const ok = writable.write(frame, (err) => {
+                if (err && !settled) {
+                    settled = true;
+                    reject(err);
+                }
+            });
+            if (ok) {
+                if (!settled) {
+                    settled = true;
+                    resolve();
+                }
+                return;
+            }
+            writable.once("drain", () => {
+                if (!settled) {
+                    settled = true;
+                    resolve();
+                }
+            });
+        });
+    }
+}
+export function defaultBrowserHostIpcClientFactory(deps) {
+    const client = new IpcClient({ onFatal: deps.onFatal });
+    client.connect({ readable: deps.readFromChild, writable: deps.writeToChild });
+    return {
+        call: (method, payload, opts) => 
+        client.call(method, payload, opts),
+        notify: (method, payload) => {
+            void client.notify(method, payload).catch((err) => {
+                if (!isNoisy(method))
+                    log.warn('notify.failed', `method=${method} ${err instanceof Error ? err.message : String(err)}`);
+            });
+        },
+        on: (event, handler) => {
+            client.on(event, handler);
+        },
+        close: () => client.disconnect(),
+    };
+}

package/dist/server/services/browser/pipewire-sink.js

@@ -0,0 +1,199 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { execFile as defaultExecFile, execFileSync as defaultExecFileSync, } from 'node:child_process';
+export const PACTL_BIN = 'pactl';
+export const PACTL_TIMEOUT_MS = 5_000;
+export function shouldRunPipeWireSink(platform = process.platform, env = process.env) {
+    if (platform !== 'linux')
+        return false;
+    if (env.MINIONRY_NO_PIPEWIRE_SINK === '1')
+        return false;
+    return true;
+}
+export function sanitizeOrchestraId(orchestraId) {
+    return orchestraId.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+export function buildSinkName(orchestraId) {
+    return `minionry_${sanitizeOrchestraId(orchestraId)}`;
+}
+export function buildLoadModuleArgs(sinkName) {
+    return [
+        'load-module',
+        'module-null-sink',
+        `sink_name=${sinkName}`,
+        `sink_properties=device.description='Minionry ${sinkName}'`,
+        'channel_map=stereo',
+    ];
+}
+export function buildUnloadModuleArgs(moduleId) {
+    return ['unload-module', String(moduleId)];
+}
+export function parseModuleId(stdout) {
+    const lines = stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    const first = lines[0];
+    if (!first || !/^\d+$/.test(first)) {
+        throw new Error(`pactl load-module: unexpected stdout (${JSON.stringify(stdout)})`);
+    }
+    const id = Number.parseInt(first, 10);
+    if (!Number.isFinite(id) || id < 0) {
+        throw new Error(`pactl load-module: invalid module id ${first}`);
+    }
+    return id;
+}
+export class PipeWireSinkSupervisor {
+    platform;
+    env;
+    execFileSyncFn;
+    execFileFn;
+    pactlBin;
+    timeoutMs;
+    logger;
+    current = null;
+    currentOrchestraId = null;
+    exitHook = null;
+    constructor(options = {}) {
+        this.platform = options.platform ?? process.platform;
+        this.env = options.env ?? process.env;
+        this.execFileSyncFn =
+            options.execFileSync ?? defaultExecFileSync;
+        this.execFileFn = options.execFile ?? defaultExecFile;
+        this.pactlBin = options.pactlBin ?? PACTL_BIN;
+        this.timeoutMs = options.timeoutMs ?? PACTL_TIMEOUT_MS;
+        this.logger = options.logger;
+    }
+    start(orchestraId, onError) {
+        if (this.current && this.currentOrchestraId === orchestraId) {
+            return this.current;
+        }
+        if (this.current) {
+            this.unloadSync();
+        }
+        if (!shouldRunPipeWireSink(this.platform, this.env)) {
+            this.current = { sinkName: null, moduleId: null, monitorSource: null };
+            this.currentOrchestraId = orchestraId;
+            return this.current;
+        }
+        const sinkName = buildSinkName(orchestraId);
+        const args = buildLoadModuleArgs(sinkName);
+        try {
+            const stdout = this.execFileSyncFn(this.pactlBin, args, {
+                encoding: 'utf8',
+                timeout: this.timeoutMs,
+            });
+            const moduleId = parseModuleId(stdout);
+            this.current = {
+                sinkName,
+                moduleId,
+                monitorSource: `${sinkName}.monitor`,
+            };
+            this.currentOrchestraId = orchestraId;
+            this.installExitHook();
+            return this.current;
+        }
+        catch (err) {
+            const error = this.normaliseError(err, args);
+            this.logger?.error?.('pipewire-sink: load-module failed', {
+                sinkName,
+                message: error.message,
+            });
+            if (onError)
+                onError(error);
+            this.current = { sinkName: null, moduleId: null, monitorSource: null };
+            this.currentOrchestraId = orchestraId;
+            return this.current;
+        }
+    }
+    getHandle() {
+        return this.current;
+    }
+    async stop() {
+        const handle = this.current;
+        const orchestraId = this.currentOrchestraId;
+        this.current = null;
+        this.currentOrchestraId = null;
+        this.uninstallExitHook();
+        if (!handle || handle.moduleId === null)
+            return;
+        await new Promise((resolve) => {
+            this.execFileFn(this.pactlBin, buildUnloadModuleArgs(handle.moduleId), { encoding: 'utf8', timeout: this.timeoutMs }, (err, _stdout, stderr) => {
+                if (err) {
+                    const trimmed = (stderr ?? '').trim();
+                    this.logger?.error?.('pipewire-sink: unload-module failed', {
+                        moduleId: handle.moduleId,
+                        sinkName: handle.sinkName,
+                        orchestraId,
+                        message: `${err.message}${trimmed ? ` — ${trimmed}` : ''}`,
+                    });
+                }
+                resolve();
+            });
+        });
+    }
+    envOverrides() {
+        if (!this.current || this.current.sinkName === null)
+            return {};
+        return { PULSE_SINK: this.current.sinkName };
+    }
+    unloadSync() {
+        const handle = this.current;
+        if (!handle || handle.moduleId === null) {
+            this.current = null;
+            return;
+        }
+        try {
+            this.execFileSyncFn(this.pactlBin, buildUnloadModuleArgs(handle.moduleId), { encoding: 'utf8', timeout: this.timeoutMs });
+        }
+        catch (err) {
+            this.logger?.error?.('pipewire-sink: re-key unload-module failed', {
+                moduleId: handle.moduleId,
+                sinkName: handle.sinkName,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+        this.current = null;
+        this.uninstallExitHook();
+    }
+    normaliseError(raw, args) {
+        if (raw instanceof Error) {
+            const code = raw.code;
+            if (code === 'ENOENT') {
+                return new Error('pactl not found on PATH — install PipeWire (pipewire-pulse) or PulseAudio (pulseaudio-utils) to enable browser audio capture');
+            }
+            const stderr = raw.stderr;
+            const stderrText = typeof stderr === 'string'
+                ? stderr.trim()
+                : stderr instanceof Buffer
+                    ? stderr.toString('utf8').trim()
+                    : '';
+            return new Error(`pactl ${args.join(' ')} failed: ${raw.message}${stderrText ? ` — ${stderrText}` : ''}`);
+        }
+        return new Error(`pactl ${args.join(' ')} failed: ${String(raw)}`);
+    }
+    installExitHook() {
+        if (this.exitHook)
+            return;
+        const handle = this.current;
+        if (!handle || handle.moduleId === null)
+            return;
+        const moduleId = handle.moduleId;
+        const hook = () => {
+            try {
+                this.execFileSyncFn(this.pactlBin, buildUnloadModuleArgs(moduleId), { encoding: 'utf8', timeout: this.timeoutMs });
+            }
+            catch {
+            }
+        };
+        this.exitHook = hook;
+        process.once('exit', hook);
+    }
+    uninstallExitHook() {
+        if (!this.exitHook)
+            return;
+        try {
+            process.off('exit', this.exitHook);
+        }
+        catch {
+        }
+        this.exitHook = null;
+    }
+}