@sstar/embedlink_agent 0.1.0

package/dist/board_uart/resource.js

@@ -0,0 +1,578 @@
+import { getSharedBoardUartManager } from './manager.js';
+import { DefaultTimeouts, error, ErrorCodes } from '../core/errors.js';
+import { addSessionConsumer, closeAllSessionHardwarePreserveState, forceCloseAllSessions, listBoardUartSessions, listExistingBoardUartSessions, readFromSession, reopenSessionHardwareByIds, removeSessionConsumer, setBoardUartHardwareSuspended, writeToSession, } from './sessions.js';
+const HOST_LEASE_IDLE_MS = 30000;
+const HOST_LEASE_HEARTBEAT_TIMEOUT_MS = 15000;
+const HOST_LEASE_SWEEP_INTERVAL_MS = 1000;
+const MAX_HOST_LEASE_BUFFER_BYTES = 1024 * 1024;
+export class BoardUartResourceManager {
+    static getInstance() {
+        if (!BoardUartResourceManager.instance) {
+            BoardUartResourceManager.instance = new BoardUartResourceManager();
+        }
+        return BoardUartResourceManager.instance;
+    }
+    constructor() {
+        this.firmwareClosedSessionIds = null;
+        this.attached = new Map();
+        this.seq = 0;
+        this.hostLeases = new Map();
+        this.hostHeartbeats = new Map();
+        this.hostLeaseSeq = 0;
+        this.hostLeaseSweepTimer = null;
+        this.suspended = false;
+        this.suspendOwner = null;
+        this.suspendedSinceMs = null;
+        this.maxSuspendMs = null;
+        this.autoResumed = false;
+        this.suspendTimer = null;
+        this.hostLeaseSweepTimer = setInterval(() => {
+            try {
+                this.sweepHostLeases();
+            }
+            catch {
+                // ignore sweep errors
+            }
+        }, HOST_LEASE_SWEEP_INTERVAL_MS);
+        // Do not keep the process alive only for this timer.
+        this.hostLeaseSweepTimer.unref?.();
+    }
+    updateHostHeartbeat(hostInstanceId) {
+        const id = (hostInstanceId || '').trim();
+        if (!id)
+            return;
+        const now = Date.now();
+        this.hostHeartbeats.set(id, now);
+        const lease = this.hostLeases.get(id);
+        if (lease) {
+            lease.lastHeartbeatAtMs = now;
+        }
+    }
+    normalizeHostInstanceId(hostInstanceId) {
+        const id = (hostInstanceId || '').trim();
+        if (!id) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, 'missing hostInstanceId (metadata: x-embedlink-host-instance-id)');
+        }
+        return id;
+    }
+    enqueueHostLeaseData(lease, chunk) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        lease.buffer.push(buf);
+        lease.bufferBytes += buf.length;
+        while (lease.bufferBytes > MAX_HOST_LEASE_BUFFER_BYTES && lease.buffer.length > 0) {
+            const old = lease.buffer.shift();
+            lease.bufferBytes -= old.length;
+        }
+        const waiters = Array.from(lease.waiters);
+        for (const fn of waiters) {
+            try {
+                fn();
+            }
+            catch {
+                // ignore waiter errors
+            }
+        }
+    }
+    detachHostLease(hostInstanceId) {
+        const rec = this.hostLeases.get(hostInstanceId);
+        if (!rec)
+            return;
+        this.hostLeases.delete(hostInstanceId);
+        try {
+            removeSessionConsumer(rec.sessionId, rec.consumerId);
+        }
+        catch {
+            // ignore detach errors
+        }
+    }
+    sweepHostLeases() {
+        const now = Date.now();
+        for (const [hostInstanceId, lease] of this.hostLeases.entries()) {
+            if (lease.inFlight > 0)
+                continue;
+            const idleMs = now - lease.lastIoAtMs;
+            const heartbeatMs = now - lease.lastHeartbeatAtMs;
+            const hasHeartbeat = this.hostHeartbeats.has(hostInstanceId);
+            const heartbeatExpired = hasHeartbeat && heartbeatMs > HOST_LEASE_HEARTBEAT_TIMEOUT_MS;
+            if (idleMs > HOST_LEASE_IDLE_MS || heartbeatExpired) {
+                this.detachHostLease(hostInstanceId);
+            }
+        }
+    }
+    async touchHostIo(params) {
+        const id = this.normalizeHostInstanceId(params.hostInstanceId);
+        const existing = this.hostLeases.get(id);
+        if (existing) {
+            existing.lastIoAtMs = Date.now();
+            const hb = this.hostHeartbeats.get(id);
+            if (hb)
+                existing.lastHeartbeatAtMs = hb;
+            return existing;
+        }
+        const consumerId = `mcp-${Date.now()}-${++this.hostLeaseSeq}`;
+        const now = Date.now();
+        const lease = {
+            hostInstanceId: id,
+            id: `mcp-host:${id}`,
+            source: `mcp-host ${id}`,
+            consumerId,
+            sessionId: params.sessionId || '',
+            port: params.port || '',
+            baud: params.baud || 0,
+            attachedAt: now,
+            lastIoAtMs: now,
+            lastHeartbeatAtMs: this.hostHeartbeats.get(id) || now,
+            reading: false,
+            inFlight: 0,
+            buffer: [],
+            bufferBytes: 0,
+            waiters: new Set(),
+        };
+        const session = await addSessionConsumer({
+            consumerId,
+            sessionId: params.sessionId,
+            port: params.port,
+            baud: params.baud,
+            onData: (chunk) => this.enqueueHostLeaseData(lease, chunk),
+        });
+        lease.sessionId = session.id;
+        lease.port = session.port;
+        lease.baud = session.baud;
+        this.hostLeases.set(id, lease);
+        return lease;
+    }
+    async readForHost(params) {
+        if (this.suspended) {
+            const owner = this.suspendOwner || 'unknown';
+            throw error(ErrorCodes.EL_BOARD_UART_SUSPENDED, `board uart resource is suspended by ${owner}`);
+        }
+        const lease = await this.touchHostIo({
+            hostInstanceId: params.hostInstanceId,
+            sessionId: params.sessionId,
+        });
+        if (lease.reading) {
+            throw error(ErrorCodes.EL_BOARD_UART_READ_IN_PROGRESS, `board-uart lease is already reading: ${lease.hostInstanceId}`);
+        }
+        const maxBytes = params.maxBytes && params.maxBytes > 0 ? params.maxBytes : 8192;
+        const quietMs = params.quietMs && params.quietMs > 0 ? params.quietMs : 200;
+        const timeoutMs = params.timeoutMs && params.timeoutMs > 0 ? params.timeoutMs : DefaultTimeouts.boardUart.read;
+        lease.reading = true;
+        lease.inFlight += 1;
+        try {
+            const chunks = [];
+            let bytes = 0;
+            let lastActivity = Date.now();
+            const drainFromBuffer = () => {
+                while (lease.buffer.length && bytes < maxBytes) {
+                    const chunk = lease.buffer.shift();
+                    lease.bufferBytes -= chunk.length;
+                    const remaining = maxBytes - bytes;
+                    if (chunk.length <= remaining) {
+                        chunks.push(chunk);
+                        bytes += chunk.length;
+                    }
+                    else {
+                        const part = chunk.subarray(0, remaining);
+                        const rest = chunk.subarray(remaining);
+                        chunks.push(part);
+                        bytes += part.length;
+                        lease.buffer.unshift(rest);
+                        lease.bufferBytes += rest.length;
+                        break;
+                    }
+                }
+            };
+            drainFromBuffer();
+            return await new Promise((resolve) => {
+                let finished = false;
+                const finish = (timedOut) => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    clearTimeout(timeoutTimer);
+                    clearInterval(quietTimer);
+                    lease.waiters.delete(onNewData);
+                    drainFromBuffer();
+                    const remains = lease.bufferBytes;
+                    resolve({ data: Buffer.concat(chunks, bytes), bytes, timedOut, remains });
+                };
+                const onNewData = () => {
+                    lastActivity = Date.now();
+                    drainFromBuffer();
+                    if (bytes >= maxBytes) {
+                        finish(false);
+                    }
+                };
+                lease.waiters.add(onNewData);
+                const quietTimer = setInterval(() => {
+                    const now = Date.now();
+                    if (now - lastActivity >= quietMs) {
+                        finish(false);
+                    }
+                }, quietMs);
+                const timeoutTimer = setTimeout(() => {
+                    finish(true);
+                }, timeoutMs);
+                if (bytes >= maxBytes) {
+                    finish(false);
+                }
+            });
+        }
+        finally {
+            lease.inFlight -= 1;
+            lease.reading = false;
+        }
+    }
+    /**
+     * 通过 session/port/baud 将监听器附加到现有会话模型上。
+     * 当前实现基于 board_uart/sessions.ts，作为轻量封装，后续可演进为独立资源管理器。
+     */
+    async attachResource(params) {
+        if (this.suspended) {
+            const owner = this.suspendOwner || 'unknown';
+            throw error(ErrorCodes.EL_BOARD_UART_SUSPENDED, `board uart resource is suspended by ${owner}`);
+        }
+        const consumerId = `att-${Date.now()}-${++this.seq}`;
+        const { listener, source } = params;
+        const session = await addSessionConsumer({
+            consumerId,
+            sessionId: params.sessionId,
+            port: params.port,
+            baud: params.baud,
+            onData: listener.onData,
+            onError: listener.onError,
+        });
+        const id = `att-${session.id}-${consumerId}`;
+        const rec = {
+            id,
+            source,
+            sessionId: session.id,
+            port: session.port,
+            baud: session.baud,
+            attachedAt: Date.now(),
+            consumerId,
+        };
+        this.attached.set(id, rec);
+        return {
+            id: rec.id,
+            source: rec.source,
+            sessionId: rec.sessionId,
+            port: rec.port,
+            baud: rec.baud,
+            attachedAt: rec.attachedAt,
+        };
+    }
+    detachResource(attachId) {
+        const rec = this.attached.get(attachId);
+        if (!rec)
+            return;
+        this.attached.delete(attachId);
+        removeSessionConsumer(rec.sessionId, rec.consumerId);
+    }
+    async writeCommand(params) {
+        if (this.suspended) {
+            const owner = this.suspendOwner || 'unknown';
+            throw error(ErrorCodes.EL_BOARD_UART_SUSPENDED, `board uart resource is suspended by ${owner}`);
+        }
+        const startTime = Date.now();
+        const cmdStr = params.command.endsWith('\n') ? params.command : params.command + '\n';
+        const cmdBuffer = Buffer.from(cmdStr);
+        const timeoutMs = params.timeoutMs && params.timeoutMs > 0 ? params.timeoutMs : 5000;
+        const activeGap = Math.min(Math.max(Math.floor(timeoutMs * 0.1), 100), 1000);
+        const maxOutputBytes = 16384;
+        // 无 waitFor 时直接写入并返回 done
+        if (!params.waitFor) {
+            await this.write({ data: cmdBuffer, sessionId: params.sessionId });
+            return {
+                status: 'done',
+                output: '',
+                nextStep: '',
+                elapsedMs: Date.now() - startTime,
+                lastOutputGapMs: 0,
+                remains: 0, // 写入操作不涉及读取，剩余数据为0
+            };
+        }
+        let targetSessionId = params.sessionId;
+        if (!targetSessionId) {
+            const sessions = await listBoardUartSessions();
+            const def = sessions.find((s) => s.isDefault);
+            if (def)
+                targetSessionId = def.id;
+            else if (sessions.length > 0)
+                targetSessionId = sessions[0].id;
+            else {
+                throw new Error('No active board uart session to wait for response.');
+            }
+        }
+        const consumerId = `cmd-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        let lastOutputAt = Date.now();
+        let isDone = false;
+        let timeoutTimer;
+        const outputBuffers = [];
+        let totalBytes = 0;
+        const waitPromise = new Promise((resolve, reject) => {
+            const cleanup = () => {
+                if (isDone)
+                    return;
+                isDone = true;
+                if (timeoutTimer)
+                    clearTimeout(timeoutTimer);
+                removeSessionConsumer(targetSessionId, consumerId);
+            };
+            const finalize = (payload) => {
+                cleanup();
+                const gap = typeof payload.lastOutputGapMs === 'number'
+                    ? payload.lastOutputGapMs
+                    : Date.now() - lastOutputAt;
+                // 计算剩余数据：buffer 中还未被读取的数据 + 已读取但未返回的数据
+                const remains = payload.remains ?? (totalBytes > maxOutputBytes ? totalBytes - maxOutputBytes : 0);
+                resolve({ ...payload, lastOutputGapMs: gap, remains });
+            };
+            const onData = (chunk) => {
+                if (isDone)
+                    return;
+                lastOutputAt = Date.now();
+                outputBuffers.push(chunk);
+                totalBytes += chunk.length;
+                const chunkStr = chunk.toString();
+                const outputStr = Buffer.concat(outputBuffers, Math.min(totalBytes, maxOutputBytes)).toString();
+                if (outputStr.includes(params.waitFor)) {
+                    finalize({ status: 'done', output: outputStr, nextStep: '' });
+                    return;
+                }
+                if (totalBytes > maxOutputBytes) {
+                    const truncatedStr = Buffer.concat(outputBuffers, maxOutputBytes).toString();
+                    finalize({
+                        status: 'truncated',
+                        output: truncatedStr,
+                        nextStep: '输出超8KB，建议用 read 获取后续，或发送 signal 中断',
+                    });
+                }
+            };
+            const onError = (err) => {
+                if (isDone)
+                    return;
+                cleanup();
+                reject(err);
+            };
+            addSessionConsumer({
+                consumerId,
+                sessionId: targetSessionId,
+                onData,
+                onError,
+            })
+                .then(() => {
+                timeoutTimer = setTimeout(() => {
+                    if (isDone)
+                        return;
+                    const gap = Date.now() - lastOutputAt;
+                    const status = gap < activeGap ? 'busy' : 'running';
+                    const nextStep = status === 'busy'
+                        ? '持续输出，若需结束请发送 signal（如 Ctrl+C）'
+                        : '未匹配，回车探测/延长等待，或发送 signal 中断';
+                    const outputStr = Buffer.concat(outputBuffers, Math.min(totalBytes, maxOutputBytes)).toString();
+                    finalize({ status, output: outputStr, nextStep, lastOutputGapMs: gap });
+                }, timeoutMs);
+            })
+                .catch((err) => {
+                reject(err);
+            });
+        });
+        await this.write({ data: cmdBuffer, sessionId: targetSessionId });
+        try {
+            const result = await waitPromise;
+            return {
+                status: result.status,
+                output: result.output,
+                nextStep: result.nextStep,
+                elapsedMs: Date.now() - startTime,
+                lastOutputGapMs: result.lastOutputGapMs,
+                remains: result.remains,
+            };
+        }
+        catch (e) {
+            return {
+                status: 'error',
+                output: '',
+                nextStep: `会话异常：${e?.message || String(e)}`,
+                elapsedMs: Date.now() - startTime,
+                lastOutputGapMs: Date.now() - lastOutputAt,
+                remains: 0, // 错误情况下，剩余数据设为0
+            };
+        }
+    }
+    async write(params) {
+        if (this.suspended) {
+            const owner = this.suspendOwner || 'unknown';
+            throw error(ErrorCodes.EL_BOARD_UART_SUSPENDED, `board uart resource is suspended by ${owner}`);
+        }
+        return writeToSession(params.sessionId, params.data);
+    }
+    async read(params) {
+        if (this.suspended) {
+            const owner = this.suspendOwner || 'unknown';
+            throw error(ErrorCodes.EL_BOARD_UART_SUSPENDED, `board uart resource is suspended by ${owner}`);
+        }
+        return readFromSession(params);
+    }
+    async getStatus() {
+        const mgr = getSharedBoardUartManager();
+        const hw = await mgr.status();
+        const sessions = listExistingBoardUartSessions();
+        let status = 'disconnected';
+        if (hw.disabled || !hw.hasModule || !hw.ports.length) {
+            status = 'disconnected';
+        }
+        else {
+            // 当前实现无法精确区分“被其他程序占用”场景，统一视为 connected；
+            // 具体错误通过读写时的错误码暴露。
+            status = 'connected';
+        }
+        const firstSession = sessions[0];
+        const attachedTools = [
+            ...Array.from(this.attached.values()).map((rec) => ({
+                id: rec.id,
+                source: rec.source,
+                sessionId: rec.sessionId,
+                port: rec.port,
+                baud: rec.baud,
+                attachedAt: rec.attachedAt,
+            })),
+            ...Array.from(this.hostLeases.values()).map((rec) => ({
+                id: rec.id,
+                source: rec.source,
+                sessionId: rec.sessionId,
+                port: rec.port,
+                baud: rec.baud,
+                attachedAt: rec.attachedAt,
+            })),
+        ];
+        return {
+            status,
+            disabled: hw.disabled,
+            hasModule: hw.hasModule,
+            ports: hw.ports,
+            port: firstSession?.port ?? null,
+            baud: firstSession?.baud ?? null,
+            sessions,
+            attachedTools,
+            suspended: this.suspended,
+            suspendOwner: this.suspendOwner,
+            suspendedSinceMs: this.suspendedSinceMs,
+            maxSuspendMs: this.maxSuspendMs,
+            autoResumed: this.autoResumed,
+        };
+    }
+    async forceCloseHardware() {
+        await forceCloseAllSessions();
+        this.attached.clear();
+        this.hostLeases.clear();
+    }
+    async setHardwareDisabled(disabled) {
+        const mgr = getSharedBoardUartManager();
+        mgr.setRuntimeDisabled(disabled);
+        if (disabled) {
+            await forceCloseAllSessions();
+            this.attached.clear();
+            this.hostLeases.clear();
+        }
+    }
+    async suspend(params) {
+        const owner = (params.owner || '').trim();
+        const maxSuspendMs = typeof params.maxSuspendMs === 'number' && params.maxSuspendMs > 0
+            ? params.maxSuspendMs
+            : null;
+        if (!owner) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, 'BoardUartResourceManager.suspend: owner is required');
+        }
+        if (this.suspended && this.suspendOwner && this.suspendOwner !== owner) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, `board uart already suspended by ${this.suspendOwner}`);
+        }
+        this.suspended = true;
+        this.suspendOwner = owner;
+        this.suspendedSinceMs = Date.now();
+        this.maxSuspendMs = maxSuspendMs;
+        this.autoResumed = false;
+        if (this.suspendTimer) {
+            clearTimeout(this.suspendTimer);
+            this.suspendTimer = null;
+        }
+        // 关闭所有当前会话底层串口，释放物理资源
+        await forceCloseAllSessions();
+        this.attached.clear();
+        this.hostLeases.clear();
+        if (maxSuspendMs && maxSuspendMs > 0) {
+            this.suspendTimer = setTimeout(() => {
+                if (!this.suspended)
+                    return;
+                if (this.suspendOwner !== owner)
+                    return;
+                this.autoResumed = true;
+                // 自动恢复时忽略错误，避免定时器导致进程崩溃
+                this.resume(owner).catch(() => { });
+            }, maxSuspendMs);
+        }
+    }
+    async resume(owner) {
+        if (!this.suspended)
+            return;
+        if (owner && this.suspendOwner && this.suspendOwner !== owner) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, `board uart suspended by ${this.suspendOwner}, cannot resume as ${owner}`);
+        }
+        const sessionIds = this.firmwareClosedSessionIds;
+        this.firmwareClosedSessionIds = null;
+        // firmware suspend: keep session/attach/lease, only cut hardware; resume should restore hardware.
+        // even if reopen fails, we must unfreeze the system and surface errors via subsequent I/O.
+        if (sessionIds && sessionIds.length) {
+            setBoardUartHardwareSuspended(null);
+            await reopenSessionHardwareByIds(sessionIds);
+        }
+        else {
+            // always clear the hardware-level guard when resuming.
+            setBoardUartHardwareSuspended(null);
+        }
+        this.suspended = false;
+        this.suspendOwner = null;
+        this.suspendedSinceMs = null;
+        this.maxSuspendMs = null;
+        if (this.suspendTimer) {
+            clearTimeout(this.suspendTimer);
+            this.suspendTimer = null;
+        }
+    }
+    async suspendForFirmware(maxSuspendMs) {
+        const owner = 'firmware.burn_recover';
+        const ms = typeof maxSuspendMs === 'number' && maxSuspendMs > 0 ? maxSuspendMs : null;
+        if (this.suspended && this.suspendOwner && this.suspendOwner !== owner) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, `board uart already suspended by ${this.suspendOwner}`);
+        }
+        this.suspended = true;
+        this.suspendOwner = owner;
+        this.suspendedSinceMs = Date.now();
+        this.maxSuspendMs = ms;
+        this.autoResumed = false;
+        setBoardUartHardwareSuspended(owner);
+        if (this.suspendTimer) {
+            clearTimeout(this.suspendTimer);
+            this.suspendTimer = null;
+        }
+        this.firmwareClosedSessionIds = await closeAllSessionHardwarePreserveState();
+        if (ms && ms > 0) {
+            this.suspendTimer = setTimeout(() => {
+                if (!this.suspended)
+                    return;
+                if (this.suspendOwner !== owner)
+                    return;
+                this.autoResumed = true;
+                this.resume(owner).catch(() => { });
+            }, ms);
+        }
+    }
+    async resumeFromFirmware() {
+        await this.resume('firmware.burn_recover');
+    }
+}
+BoardUartResourceManager.instance = null;
+export function getBoardUartResourceManager() {
+    return BoardUartResourceManager.getInstance();
+}