@minionry/minion 0.7.36

package/dist/server/utils/port.js

@@ -0,0 +1,204 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { createSocket } from 'node:dgram';
+import { createServer } from 'node:net';
+export function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => {
+            server.close();
+            resolve(false);
+        });
+        server.once('listening', () => {
+            server.close();
+            resolve(true);
+        });
+        server.listen(port, '::');
+    });
+}
+export async function findFirstAvailablePort(ports) {
+    const results = await Promise.all(ports.map(async (port) => ({ port, available: await isPortAvailable(port) })));
+    const available = results.find(r => r.available);
+    return available ? available.port : null;
+}
+export function allocateEphemeralTcpPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        const onError = (err) => {
+            try {
+                server.close();
+            }
+            catch {   }
+            reject(err);
+        };
+        server.once('error', onError);
+        server.listen(0, '::', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : null;
+            server.removeListener('error', onError);
+            server.close(() => {
+                if (typeof port === 'number' && port > 0) {
+                    resolve(port);
+                }
+                else {
+                    reject(new Error('allocateEphemeralTcpPort: kernel did not assign a port'));
+                }
+            });
+        });
+    });
+}
+class PortReservations {
+    ttlMs;
+    held = new Map();
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+    }
+    isReserved(port) {
+        return this.held.has(port);
+    }
+    reserve(port) {
+        const existing = this.held.get(port);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => this.held.delete(port), this.ttlMs);
+        timer.unref?.();
+        this.held.set(port, timer);
+    }
+}
+const reservations = new PortReservations(30_000);
+export class SequentialScanStrategy {
+    startPort;
+    maxTries;
+    name = 'sequential-scan';
+    constructor(startPort, maxTries) {
+        this.startPort = startPort;
+        this.maxTries = maxTries;
+    }
+    async acquire() {
+        const ports = Array.from({ length: this.maxTries }, (_, i) => this.startPort + i)
+            .filter((p) => !reservations.isReserved(p));
+        if (ports.length === 0)
+            return null;
+        return findFirstAvailablePort(ports);
+    }
+}
+export class EphemeralPortStrategy {
+    name = 'ephemeral';
+    async acquire() {
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                const port = await allocateEphemeralTcpPort();
+                if (!reservations.isReserved(port))
+                    return port;
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+}
+export class PortAllocator {
+    strategies;
+    constructor(strategies) {
+        if (strategies.length === 0) {
+            throw new Error('PortAllocator requires at least one strategy');
+        }
+        this.strategies = strategies;
+    }
+    async acquire() {
+        return withAllocationLock(async () => {
+            for (const strategy of this.strategies) {
+                const port = await strategy.acquire();
+                if (port !== null) {
+                    reservations.reserve(port);
+                    return port;
+                }
+            }
+            throw new Error(`PortAllocator exhausted all strategies (${this.strategies.map((s) => s.name).join(', ')})`);
+        });
+    }
+}
+let allocationLock = Promise.resolve();
+function withAllocationLock(task) {
+    const run = allocationLock.then(task, task);
+    allocationLock = run.catch(() => { });
+    return run;
+}
+export function findAvailablePort(startPort, maxTries = 20) {
+    return new PortAllocator([
+        new SequentialScanStrategy(startPort, maxTries),
+        new EphemeralPortStrategy()
+    ]).acquire();
+}
+export function allocateEphemeralUdpPort() {
+    return new Promise((resolve, reject) => {
+        const socket = createSocket('udp4');
+        const onError = (err) => {
+            try {
+                socket.close();
+            }
+            catch {   }
+            reject(err);
+        };
+        socket.once('error', onError);
+        socket.bind(0, '127.0.0.1', () => {
+            const address = socket.address();
+            const port = typeof address === 'object' && address ? address.port : null;
+            socket.removeListener('error', onError);
+            socket.close(() => {
+                if (typeof port === 'number' && port > 0) {
+                    resolve(port);
+                }
+                else {
+                    reject(new Error('allocateEphemeralUdpPort: kernel did not assign a port'));
+                }
+            });
+        });
+    });
+}
+export async function allocateUdpPortPair() {
+    const tryEphemeral = async () => {
+        try {
+            const videoPort = await allocateEphemeralUdpPort();
+            let audioPort = await allocateEphemeralUdpPort();
+            if (audioPort === videoPort) {
+                audioPort = await allocateEphemeralUdpPort();
+            }
+            if (audioPort === videoPort)
+                return null;
+            return { videoPort, audioPort };
+        }
+        catch {
+            return null;
+        }
+    };
+    const pair = await tryEphemeral();
+    if (pair)
+        return pair;
+    const start = 49152 + Math.floor(Math.random() * 1000) * 2;
+    for (let offset = 0; offset < 4000; offset += 2) {
+        const v = start + offset;
+        const a = v + 1;
+        const vFree = await isUdpPortFree(v);
+        const aFree = await isUdpPortFree(a);
+        if (vFree && aFree)
+            return { videoPort: v, audioPort: a };
+    }
+    throw new Error('allocateUdpPortPair: no free port pair found in dynamic range');
+}
+function isUdpPortFree(port) {
+    return new Promise((resolve) => {
+        const socket = createSocket('udp4');
+        socket.once('error', () => {
+            try {
+                socket.close();
+            }
+            catch {   }
+            resolve(false);
+        });
+        socket.bind(port, '127.0.0.1', () => {
+            socket.close(() => resolve(true));
+        });
+    });
+}

package/electron-host/dist/agent-lease.js

@@ -0,0 +1,141 @@
+import { EventEmitter } from "node:events";
+export const DEFAULT_LEASE_TTL_MS = 30_000;
+export const GC_INTERVAL_MS = 5_000;
+export const GRACE_PERIOD_MS = 15_000;
+export class TabAlreadyLeasedError extends Error {
+    code = "tab_already_leased";
+    currentOwner;
+    constructor(currentOwner) {
+        super(`Tab ${currentOwner.tabId} is already leased by agent ${currentOwner.agentId}`);
+        this.name = "TabAlreadyLeasedError";
+        this.currentOwner = { ...currentOwner };
+    }
+}
+export class AgentLeaseRegistry extends EventEmitter {
+    entries = new Map();
+    nowMs;
+    defaultTtlMs;
+    gcIntervalMs;
+    gracePeriodMs;
+    setIntervalFn;
+    clearIntervalFn;
+    gcHandle;
+    constructor(options = {}) {
+        super();
+        this.nowMs = options.nowMs ?? (() => Date.now());
+        this.defaultTtlMs = options.defaultTtlMs ?? DEFAULT_LEASE_TTL_MS;
+        this.gcIntervalMs = options.gcIntervalMs ?? GC_INTERVAL_MS;
+        this.gracePeriodMs = options.gracePeriodMs ?? GRACE_PERIOD_MS;
+        this.setIntervalFn =
+            options.setIntervalFn ??
+                ((handler, ms) => setInterval(handler, ms));
+        this.clearIntervalFn =
+            options.clearIntervalFn ?? ((handle) => clearInterval(handle));
+    }
+    lease(req) {
+        const existing = this.entries.get(req.tabId);
+        if (existing !== undefined) {
+            throw new TabAlreadyLeasedError(existing);
+        }
+        const now = this.nowMs();
+        const ttl = req.ttlMs ?? this.defaultTtlMs;
+        const entry = {
+            tabId: req.tabId,
+            agentId: req.agentId,
+            ...(req.planId !== undefined ? { planId: req.planId } : {}),
+            leasedAt: now,
+            leasedUntil: now + ttl,
+        };
+        this.entries.set(req.tabId, entry);
+        return { ...entry };
+    }
+    release(tabId, agentId) {
+        const existing = this.entries.get(tabId);
+        if (existing === undefined)
+            return false;
+        if (existing.agentId !== agentId)
+            return false;
+        this.entries.delete(tabId);
+        return true;
+    }
+    heartbeat(req) {
+        const now = this.nowMs();
+        const ttl = req.ttlMs ?? this.defaultTtlMs;
+        const stillLeased = [];
+        for (const tabId of req.tabIds) {
+            const entry = this.entries.get(tabId);
+            if (entry === undefined)
+                continue;
+            if (entry.agentId !== req.agentId)
+                continue;
+            entry.leasedUntil = now + ttl;
+            stillLeased.push(tabId);
+        }
+        return { stillLeased };
+    }
+    releasePlan(planId) {
+        const released = [];
+        for (const [tabId, entry] of this.entries) {
+            if (entry.planId !== planId)
+                continue;
+            released.push(tabId);
+            this.entries.delete(tabId);
+            this.emit("lease-expired", {
+                tabId: entry.tabId,
+                agentId: entry.agentId,
+                ...(entry.planId !== undefined ? { planId: entry.planId } : {}),
+            });
+        }
+        return released;
+    }
+    list(filter = {}) {
+        const out = [];
+        for (const entry of this.entries.values()) {
+            if (filter.agentId !== undefined && entry.agentId !== filter.agentId)
+                continue;
+            if (filter.planId !== undefined && entry.planId !== filter.planId)
+                continue;
+            out.push({ ...entry });
+        }
+        return out;
+    }
+    gcLoop() {
+        if (this.gcHandle !== undefined)
+            return;
+        this.gcHandle = this.setIntervalFn(() => this.sweepExpired(), this.gcIntervalMs);
+        const handle = this.gcHandle;
+        if (handle && typeof handle.unref === "function") {
+            handle.unref();
+        }
+    }
+    stopGc() {
+        if (this.gcHandle === undefined)
+            return;
+        this.clearIntervalFn(this.gcHandle);
+        this.gcHandle = undefined;
+    }
+    sweepExpired() {
+        const now = this.nowMs();
+        const expired = [];
+        for (const [tabId, entry] of this.entries) {
+            if (now >= entry.leasedUntil + this.gracePeriodMs) {
+                expired.push(tabId);
+            }
+        }
+        for (const tabId of expired) {
+            const entry = this.entries.get(tabId);
+            if (entry === undefined)
+                continue;
+            this.entries.delete(tabId);
+            this.emit("lease-expired", {
+                tabId: entry.tabId,
+                agentId: entry.agentId,
+                ...(entry.planId !== undefined ? { planId: entry.planId } : {}),
+            });
+        }
+        return expired;
+    }
+    size() {
+        return this.entries.size;
+    }
+}

package/electron-host/dist/capture-recovery.js

@@ -0,0 +1,77 @@
+import { hostLog, shortId } from './host-log.js';
+const log = hostLog('ctrl');
+export const RECOVERY_BASE_DELAY_MS = 100;
+export const RECOVERY_MAX_ATTEMPTS = 7;
+export function recoveryDelayMs(attempt) {
+    return RECOVERY_BASE_DELAY_MS * 2 ** (attempt - 1);
+}
+export class CaptureRecovery {
+    pending = new Map();
+    deps;
+    timers;
+    constructor(deps) {
+        this.deps = deps;
+        this.timers = deps.timers ?? { setTimeout, clearTimeout };
+    }
+    onTrackEnded(sessionId, tabId) {
+        const session = this.deps.sessions.get(sessionId);
+        if (!session || session.activeTabId !== tabId)
+            return;
+        session.detachTracks();
+        this.arm(sessionId, tabId);
+    }
+    arm(sessionId, tabId, attempt = 1) {
+        const session = this.deps.sessions.get(sessionId);
+        if (!session)
+            return;
+        this.cancel(sessionId);
+        const timer = this.timers.setTimeout(() => {
+            this.pending.delete(sessionId);
+            void this.recover(session, tabId, attempt);
+        }, recoveryDelayMs(attempt));
+        this.pending.set(sessionId, timer);
+    }
+    cancel(sessionId) {
+        const timer = this.pending.get(sessionId);
+        if (timer === undefined)
+            return;
+        this.timers.clearTimeout(timer);
+        this.pending.delete(sessionId);
+    }
+    stillWatching(session, tabId) {
+        return this.deps.sessions.get(session.sessionId) === session && session.activeTabId === tabId;
+    }
+    async recover(session, tabId, attempt) {
+        if (!this.stillWatching(session, tabId) || session.hasLiveVideo())
+            return;
+        await this.reattach(session, tabId, attempt);
+        if (!this.stillWatching(session, tabId))
+            return;
+        if (session.hasLiveVideo()) {
+            log('endedRecovery.reattached', `session=${shortId(session.sessionId)} tab=${shortId(tabId)} attempt=${attempt}`);
+            return;
+        }
+        if (attempt < RECOVERY_MAX_ATTEMPTS) {
+            this.arm(session.sessionId, tabId, attempt + 1);
+            return;
+        }
+        session.reportError('ended_recovery_failed', `ended-recovery exhausted after ${RECOVERY_MAX_ATTEMPTS} attempts`);
+        session.reportState('failed', { reason: 'capture_failed' });
+    }
+    async reattach(session, tabId, attempt) {
+        const attach = async () => {
+            await session.attachStream(await this.deps.refresh(session.sessionId, tabId));
+        };
+        try {
+            if (session.hasOffered()) {
+                await attach();
+                return;
+            }
+            log.info('endedRecovery.initialNegotiate', `session=${shortId(session.sessionId)} attempt=${attempt}`);
+            await session.offerAfter(attach);
+        }
+        catch (err) {
+            log.info('endedRecovery.attemptFailed', `session=${shortId(session.sessionId)} attempt=${attempt}/${RECOVERY_MAX_ATTEMPTS} ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/electron-host/dist/codec-policy.js

@@ -0,0 +1,37 @@
+const VIDEO_CODEC_RANK = [/^video\/H264$/i, /^video\/VP9$/i, /^video\/VP8$/i];
+const DROPPED_CODECS = /^video\/(red|ulpfec)$/i;
+function rankOf(mimeType) {
+    const rank = VIDEO_CODEC_RANK.findIndex((pattern) => pattern.test(mimeType));
+    return rank === -1 ? VIDEO_CODEC_RANK.length : rank;
+}
+export function orderVideoCodecs(codecs) {
+    return codecs
+        .filter((codec) => !DROPPED_CODECS.test(codec.mimeType))
+        .map((codec, index) => ({ codec, index, rank: rankOf(codec.mimeType) }))
+        .sort((a, b) => a.rank - b.rank || a.index - b.index)
+        .map((entry) => entry.codec);
+}
+export function applyVideoCodecPolicy(transceiver, capabilities) {
+    if (!capabilities || typeof transceiver.setCodecPreferences !== 'function')
+        return false;
+    try {
+        transceiver.setCodecPreferences(orderVideoCodecs(capabilities.codecs));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function applyScreenEncodingPolicy(sender) {
+    try {
+        const params = sender.getParameters();
+        params.degradationPreference = 'maintain-resolution';
+        const encodings = params.encodings;
+        if (encodings.length === 0)
+            encodings.push({ active: true });
+        encodings[0].scalabilityMode = 'L1T1';
+        sender.setParameters(params).catch(() => undefined);
+    }
+    catch {
+    }
+}

package/electron-host/dist/controller-channel.js

@@ -0,0 +1,60 @@
+export const DEFAULT_MAX_QUEUED = 256;
+export class ControllerChannel {
+    transport;
+    log;
+    maxQueued;
+    queue = [];
+    ready = false;
+    constructor(options) {
+        this.transport = options.transport;
+        this.log = options.log ?? (() => { });
+        this.maxQueued = options.maxQueued ?? DEFAULT_MAX_QUEUED;
+    }
+    get isReady() {
+        return this.ready;
+    }
+    get pendingCount() {
+        return this.queue.length;
+    }
+    send(channel, payload) {
+        if (this.transport.isDestroyed()) {
+            this.log("controller.send.dropped", `channel=${channel} reason=destroyed`);
+            return false;
+        }
+        if (!this.ready) {
+            if (this.queue.length >= this.maxQueued) {
+                const dropped = this.queue.shift();
+                this.log("controller.send.queueOverflow", `dropped=${dropped?.channel ?? "?"}`);
+            }
+            this.queue.push({ channel, payload });
+            this.log("controller.send.queued", `channel=${channel} pending=${this.queue.length}`);
+            return false;
+        }
+        return this.deliver(channel, payload);
+    }
+    markReady() {
+        this.ready = true;
+        if (this.queue.length === 0)
+            return;
+        const pending = this.queue.splice(0);
+        this.log("controller.flush", `count=${pending.length}`);
+        for (const message of pending)
+            this.deliver(message.channel, message.payload);
+    }
+    markNotReady() {
+        this.ready = false;
+    }
+    clear() {
+        this.queue.length = 0;
+    }
+    deliver(channel, payload) {
+        try {
+            this.transport.send(channel, payload);
+            return true;
+        }
+        catch (err) {
+            this.log("controller.send.failed", `channel=${channel} ${String(err)}`);
+            return false;
+        }
+    }
+}

package/electron-host/dist/controller-handlers.js

@@ -0,0 +1,153 @@
+import { hostLog, shortId } from './host-log.js';
+import { CH_CLOSE_SESSION, CH_CLOSE_VIEWER, CH_EVICT_SESSION_CAPTURE, CH_REFRESH_CAPTURE, CH_REMOTE_ANSWER, CH_REMOTE_ICE, CH_SET_ICE_CONFIG, CH_START_SESSION, CH_SWITCH_VIEWER_TAB, } from './webrtc-channels.js';
+import { BASE_RTC_CONFIG, normalizeTabId } from './webrtc-peer.js';
+const log = hostLog('ctrl');
+function asRecord(payload) {
+    return payload !== null && typeof payload === 'object' ? payload : null;
+}
+function readSessionId(payload) {
+    const sessionId = asRecord(payload)?.sessionId;
+    return typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+}
+function readSessionTab(payload) {
+    const sessionId = readSessionId(payload);
+    const tabId = asRecord(payload)?.tabId;
+    if (sessionId === null)
+        return null;
+    if (typeof tabId === 'number')
+        return { sessionId, tabId: normalizeTabId(tabId) };
+    return typeof tabId === 'string' && tabId.length > 0 ? { sessionId, tabId } : null;
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+const setIceConfig = (ctx, payload) => {
+    const iceServers = asRecord(payload)?.iceServers;
+    if (!Array.isArray(iceServers))
+        return;
+    ctx.registry.setRtcConfig({ ...BASE_RTC_CONFIG, iceServers: iceServers });
+};
+const startSession = async (ctx, payload) => {
+    const target = readSessionTab(payload);
+    if (!target)
+        return;
+    const { sessionId, tabId } = target;
+    log.info('startSession', `session=${shortId(sessionId)} tab=${shortId(tabId)} iceServers=${ctx.registry.iceServerCount} audio=${ctx.captureCache.audioEnabled}`);
+    const session = ctx.registry.ensure(sessionId);
+    session.arm(tabId);
+    try {
+        await session.offerAfter(async () => session.attachStream(await ctx.captureCache.acquire(sessionId, tabId)));
+    }
+    catch (err) {
+        log.info('startSession.error', `session=${shortId(sessionId)} ${messageOf(err)} — handing to the bounded re-acquire net`);
+        session.reportError('start_session_failed', `start-session failed: ${messageOf(err)}`);
+        session.reportState('negotiating', { reason: 'capture_retrying' });
+        ctx.recovery.arm(sessionId, tabId);
+    }
+};
+const switchViewerTab = async (ctx, payload) => {
+    const target = readSessionTab(payload);
+    if (!target)
+        return;
+    const session = ctx.registry.get(target.sessionId);
+    if (!session || session.activeTabId === target.tabId) {
+        log('switchViewerTab.skip', `session=${shortId(target.sessionId)} tab=${shortId(target.tabId)} known=${session !== undefined}`);
+        return;
+    }
+    log('switchViewerTab', `session=${shortId(target.sessionId)} from=${shortId(session.activeTabId)} to=${shortId(target.tabId)}`);
+    try {
+        await session.attachStream(await ctx.captureCache.acquire(target.sessionId, target.tabId));
+        session.activeTabId = target.tabId;
+    }
+    catch (err) {
+        session.reportError('switch_viewer_tab_failed', `switch-viewer-tab failed: ${messageOf(err)}`);
+    }
+};
+const refreshCapture = async (ctx, payload) => {
+    const target = readSessionTab(payload);
+    if (!target)
+        return;
+    const { sessionId, tabId } = target;
+    const session = ctx.registry.get(sessionId);
+    if (!session || session.activeTabId !== tabId) {
+        ctx.captureCache.evict(sessionId, tabId);
+        return;
+    }
+    const startedAt = Date.now();
+    try {
+        const stream = await ctx.captureCache.refresh(sessionId, tabId);
+        const acquiredAt = Date.now();
+        await session.attachStream(stream);
+        log('refreshCapture.done', `session=${shortId(sessionId)} tab=${shortId(tabId)} acquireMs=${acquiredAt - startedAt} attachMs=${Date.now() - acquiredAt} t=${Date.now()}`);
+    }
+    catch (err) {
+        session.reportError('refresh_capture_failed', `refresh-capture failed: ${messageOf(err)}`);
+        ctx.recovery.arm(sessionId, tabId);
+    }
+};
+const remoteAnswer = async (ctx, payload) => {
+    const sessionId = readSessionId(payload);
+    const sdp = asRecord(payload)?.sdp;
+    if (sessionId === null || typeof sdp !== 'string' || sdp.length === 0)
+        return;
+    await ctx.registry.get(sessionId)?.applyAnswer(sdp);
+};
+const remoteIce = async (ctx, payload) => {
+    const sessionId = readSessionId(payload);
+    if (sessionId === null)
+        return;
+    const candidate = (asRecord(payload)?.candidate ?? null);
+    log('remoteIce', `session=${shortId(sessionId)} eoc=${candidate === null}`);
+    await ctx.registry.get(sessionId)?.addRemoteIce(candidate);
+};
+const evictSessionCapture = (ctx, payload) => {
+    const sessionId = readSessionId(payload);
+    if (sessionId === null)
+        return;
+    log('evictSessionCapture', `session=${shortId(sessionId)}`);
+    ctx.captureCache.evictSession(sessionId);
+};
+const closeViewer = (ctx, payload) => {
+    const sessionId = readSessionId(payload);
+    if (sessionId === null)
+        return;
+    log.info('closeViewer', `session=${shortId(sessionId)} known=${ctx.registry.get(sessionId) !== undefined}`);
+    ctx.registry.destroy(sessionId, 'remote_closed');
+    releaseCaptureIfIdle(ctx);
+};
+const closeAllViewers = (ctx) => {
+    log('closeSession.all');
+    ctx.registry.destroyAll('remote_closed');
+    releaseCaptureIfIdle(ctx);
+};
+function releaseCaptureIfIdle(ctx) {
+    if (ctx.registry.size === 0)
+        ctx.captureCache.clear();
+}
+export const CONTROLLER_HANDLERS = {
+    [CH_SET_ICE_CONFIG]: setIceConfig,
+    [CH_START_SESSION]: startSession,
+    [CH_SWITCH_VIEWER_TAB]: switchViewerTab,
+    [CH_REFRESH_CAPTURE]: refreshCapture,
+    [CH_REMOTE_ANSWER]: remoteAnswer,
+    [CH_REMOTE_ICE]: remoteIce,
+    [CH_EVICT_SESSION_CAPTURE]: evictSessionCapture,
+    [CH_CLOSE_VIEWER]: closeViewer,
+    [CH_CLOSE_SESSION]: closeAllViewers,
+};
+export async function dispatchControllerMessage(ctx, channel, payload) {
+    const handler = CONTROLLER_HANDLERS[channel];
+    if (!handler)
+        return;
+    try {
+        await handler(ctx, payload);
+    }
+    catch (err) {
+        const sessionId = readSessionId(payload);
+        ctx.sink.error({
+            ...(sessionId !== null ? { sessionId } : {}),
+            message: `${channel} handler failed: ${messageOf(err)}`,
+            code: 'controller_handler_failed',
+        });
+    }
+}