@syrkos/filaxis 0.1.0-alpha.10

package/src/local-session-manager.ts

@@ -0,0 +1,397 @@
+/**
+ * local-session-manager.ts — 本地长跑会话引擎（spawn 即返 + 双文件落盘 + 热窗口 + watcher）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/session/local-session-manager.ts`
+ * （源锚点：Aethelum-Nexus dev @ 8977ff3 + fix 203a31c），按 REQ-0001 OSS 化改造：
+ * - 剥 SubstrateSecurity（执行网/沙箱属消费方策略——内核不越权预设安全边界）
+ * - SessionNotifier 队列投递 → 纯 onEvent 回调（内核零队列红线）
+ * - 落盘协议改双文件 `<logBase>.out` / `<logBase>.err`（FEAT-04——源版单文件混写）
+ * - 热窗口行对象带 stream 标记；聚合序为到达序（REQ §3.2 跨流顺序契约）
+ * - logger 可注入（缺省 noop）；日志目录/Shell 可配
+ *
+ * 终端语义：start 立即返回，进程长跑（无自动超时——长跑是特性）。
+ * 三级读取：文件全量（完整行落盘，1MB/行防爆 + 64MiB 总量硬顶）＋ 热窗口 ＋ watcher 推送。
+ * 生命周期：退出后句柄保留 ttlMs（默认 10min）供补读，TTL 后回收（timer unref 不撑进程）。
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs/promises";
+import { createWriteStream } from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import * as crypto from "node:crypto";
+import { LineAssembler, OutputRingBuffer, WatchRegistry } from "./session-buffer.js";
+import type {
+    SessionStartOptions,
+    SessionHandleInfo,
+    SessionEvent,
+    WatchOptions,
+    ReadLogOptions,
+    OutputStream,
+} from "./session-types.js";
+import { noopLogger, type FilaxisLogger } from "./logger.js";
+import { resolveLocalShell } from "./shell-discovery.js";
+/** 子串语义转义（与 WatchRegistry.toRegex 同规则） */
+function escapeRegExp(p: string): string {
+    return p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** 文件侧单行上限（防爆盘；窗口侧 maxLineBytes 截断另算） */
+const MAX_FILE_LINE_BYTES = 1_000_000;
+/** 会话日志总量硬顶（两流合计；失控输出防写爆 tmpfs）；超限停写文件，ring/watcher 继续 */
+const MAX_SESSION_LOG_BYTES = 64 * 1024 * 1024;
+/** stop 后 SIGKILL 升级宽限 */
+const KILL_GRACE_MS = 1500;
+
+interface SessionEntry {
+    sessionId: string;
+    command: string;
+    startedAt: number;
+    ownerSessionId?: string;
+    ring: OutputRingBuffer;
+    watchers: WatchRegistry;
+    watcherMeta: Map<string, WatchOptions>;
+    assemblers: Record<OutputStream, LineAssembler>;
+    logStreams: Record<OutputStream, ReturnType<typeof createWriteStream>>;
+    logBase: string;
+    logBytes: number;
+    logCapped: boolean;
+    proc?: ChildProcess;
+    running: boolean;
+    exitCode?: number | null;
+    ttlTimer?: ReturnType<typeof setTimeout>;
+}
+
+export interface LocalSessionManagerOptions {
+    maxLines?: number;
+    maxLineBytes?: number;
+    /** 退出后句柄保留时长，默认 10min */
+    ttlMs?: number;
+    /** 会话日志目录（缺省 os.tmpdir()/filaxis-sessions） */
+    logDir?: string;
+    /** 执行 shell（缺省 "bash"；Windows 需 Git Bash/WSL 提供 bash——平台差异显式声明，不静默切换） */
+    shell?: string;
+    /** spawn 注入（缺省 node:child_process.spawn）——消费方沙箱包装/测试 mock 注入点 */
+    spawnImpl?: (cmd: string, argv: string[], opts: { env: NodeJS.ProcessEnv; cwd?: string; stdio: unknown[] }) => ChildProcess;
+    /** 可注入日志（缺省 noop——SDK 不替调用方往 stdout 喷日志） */
+    logger?: FilaxisLogger;
+}
+
+export class LocalSessionManager {
+    /** 事件回调（FEAT-09：消费方订阅点；缺省 noop）。回调异常被吞并记日志，不杀会话 */
+    onEvent: (ev: SessionEvent) => void = () => undefined;
+
+    private readonly entries = new Map<string, SessionEntry>();
+    private readonly maxLines: number;
+    private readonly maxLineBytes: number;
+    private readonly ttlMs: number;
+    private readonly logDir: string;
+    private readonly shell: string;
+    private readonly log: FilaxisLogger;
+    private readonly spawnImpl: LocalSessionManagerOptions["spawnImpl"];
+
+    constructor(opts: LocalSessionManagerOptions = {}) {
+        this.maxLines = opts.maxLines ?? 50;
+        this.maxLineBytes = opts.maxLineBytes ?? 512;
+        this.ttlMs = opts.ttlMs ?? 10 * 60_000;
+        this.logDir = opts.logDir ?? path.join(tmpdir(), "filaxis-sessions");
+        this.log = opts.logger ?? noopLogger;
+        this.shell = resolveLocalShell(opts.shell, this.log);
+        this.spawnImpl = opts.spawnImpl ?? ((cmd, argv, o) => spawn(cmd, argv, o as never) as ChildProcess);
+    }
+
+    /** 启动长跑会话：立即返回句柄 */
+    async start(command: string, opts: SessionStartOptions = {}): Promise<SessionHandleInfo> {
+        const sessionId =
+            `${opts.name ? opts.name.replace(/[^a-zA-Z0-9_-]/g, "-") + "-" : "sess-"}` +
+            crypto.randomBytes(4).toString("hex");
+
+        await fs.mkdir(this.logDir, { recursive: true });
+        const logBase = path.join(this.logDir, sessionId);
+
+        const entry: SessionEntry = {
+            sessionId,
+            command,
+            startedAt: Date.now(),
+            ownerSessionId: opts.ownerSessionId,
+            ring: new OutputRingBuffer({ maxLines: this.maxLines, maxLineBytes: this.maxLineBytes }),
+            watchers: new WatchRegistry(),
+            watcherMeta: new Map(),
+            assemblers: { stdout: new LineAssembler(), stderr: new LineAssembler() },
+            logStreams: {
+                stdout: createWriteStream(`${logBase}.out`),
+                stderr: createWriteStream(`${logBase}.err`),
+            },
+            logBase,
+            logBytes: 0,
+            logCapped: false,
+            running: true,
+        };
+        this.entries.set(sessionId, entry);
+
+        const env = { ...process.env, ...opts.env };
+        const cwd = opts.cwd || process.cwd();
+        // 注：不 unref——unref 的子进程在 Bun 下不保活事件循环，close/exit 事件会静默丢失
+        const proc = this.spawnImpl!(this.shell, ["-c", command], {
+            env,
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        entry.proc = proc;
+
+        proc.stdout?.on("data", (buf: Buffer) => this.ingestChunk(entry, buf.toString("utf-8"), "stdout"));
+        proc.stderr?.on("data", (buf: Buffer) => this.ingestChunk(entry, buf.toString("utf-8"), "stderr"));
+
+        proc.on("close", (code) => this.finalize(entry, code));
+        proc.on("error", (err) => {
+            this.ingestLine(entry, `[session-error] ${err.message}`, "stderr");
+            this.finalize(entry, null);
+        });
+
+        this.log.info(`[Session ${sessionId}] started: ${command.slice(0, 80)} (pid=${proc.pid})`);
+        return { sessionId, logBase, pid: proc.pid };
+    }
+
+    /** 热窗口快照（最近 n 行 text 投影，默认 50；不碰盘） */
+    tail(sessionId: string, n = 50): string[] {
+        return this.require(sessionId).ring.tail(n);
+    }
+
+    /** 热窗口行对象（带 stream 标记——按流过滤消费） */
+    tailLines(sessionId: string, n = 50) {
+        return this.require(sessionId).ring.tailLines(n);
+    }
+
+    /** 文件全量/大范围读取（窗口滚出的内容在这里；双文件按流分读） */
+    async readLog(sessionId: string, opts: ReadLogOptions = {}): Promise<string> {
+        const entry = this.require(sessionId);
+        const file = opts.stream === "stderr" ? `${entry.logBase}.err` : `${entry.logBase}.out`;
+        let content: string;
+        try {
+            content = await fs.readFile(file, "utf-8");
+        } catch {
+            return ""; // 流文件尚未创建（该流无输出）→ 空而非异常
+        }
+        let lines = content.split("\n");
+        if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+        if (opts.offsetLines) lines = lines.slice(opts.offsetLines);
+        if (opts.lines) lines = lines.slice(-opts.lines);
+        return lines.join("\n");
+    }
+
+    /**
+     * 注册 watcher：**回溯匹配**热窗口已有行（spawn→watch 注册间隙的输出不漏——
+     * 与 ready() 同款语义；真实反馈：bash 冷启热后 GO 常在注册前已进窗口），
+     * 未命中再匹配未来行；命中 → onEvent("match")。
+     */
+    watch(sessionId: string, opts: WatchOptions): { cancel(): void } {
+        const entry = this.require(sessionId);
+        const watcherId = `w-${crypto.randomBytes(3).toString("hex")}`;
+        entry.watchers.add({ id: watcherId, pattern: opts.pattern, once: opts.once });
+        entry.watcherMeta.set(watcherId, opts);
+        // 回溯：窗口已有行命中即发（once 语义保持——命中即摘除）
+        const regex = opts.pattern instanceof RegExp
+            ? opts.pattern
+            : new RegExp(escapeRegExp(String(opts.pattern)));
+        for (const l of entry.ring.tailLines(Infinity)) {
+            if (regex.test(l.text)) {
+                if (opts.once !== false) {
+                    entry.watchers.cancel(watcherId);
+                    entry.watcherMeta.delete(watcherId);
+                }
+                if (opts.thenStop) void this.stop(sessionId).catch(() => undefined);
+                this.emit({
+                    type: "match", sessionId, ownerSessionId: entry.ownerSessionId, watcherId,
+                    pattern: String(opts.pattern), matchedLine: l.text, stream: l.stream,
+                    context: entry.ring.contextAround(entry.ring.size - 1, opts.contextLines ?? 5).map((c) => c.text),
+                });
+                break; // 回溯命中一次即止（未来行交给在线匹配）
+            }
+        }
+        return {
+            cancel: () => {
+                entry.watchers.cancel(watcherId);
+                entry.watcherMeta.delete(watcherId);
+            },
+        };
+    }
+
+    /**
+     * 就绪握手（FEAT-11 / AC-13）：先回溯扫描热窗口已有行（覆盖 spawn→ready
+     * 调用间隙已输出的标记——只监听增量则快输出进程必漏），未命中再监听增量行。
+     * 滚出感知有据：evictedCount===0 → 窗口历史完整，标记确定未出现，安心等待；
+     * >0 → 历史可能不完整，报「标记可能已滚出（可回查落盘日志）」而非死等。
+     * 超时 → 自动 stop 清理（不留孤儿进程）。
+     */
+    async ready(
+        sessionId: string,
+        opts: { pattern: string | RegExp; timeoutMs: number },
+    ): Promise<{ matchedLine: string }> {
+        const entry = this.require(sessionId);
+        const regex = opts.pattern instanceof RegExp
+            ? opts.pattern
+            : new RegExp(opts.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+        // ① 回溯：窗口已有行命中即立即 resolve
+        for (const l of entry.ring.tailLines(Infinity)) {
+            if (regex.test(l.text)) return { matchedLine: l.text };
+        }
+        if (entry.ring.evictedCount > 0) {
+            throw new Error(
+                `就绪标记可能已滚出热窗口（evicted=${entry.ring.evictedCount}，历史不完整）——` +
+                `可经 readLog 回查 ${entry.logBase}.out/.err，或加大窗口后重启会话`,
+            );
+        }
+        // ② 增量监听（一次性内部 watcher）
+        return await new Promise<{ matchedLine: string }>((resolve, reject) => {
+            const w = this.watch(sessionId, { pattern: opts.pattern, once: true });
+            let poll: ReturnType<typeof setInterval> | undefined;
+            const timer = setTimeout(() => {
+                if (poll) clearInterval(poll);
+                w.cancel();
+                // 超时自动清理：不留孤儿进程（AC-13）
+                void this.stop(sessionId).catch(() => undefined);
+                reject(new Error(`ready() 超时（${opts.timeoutMs}ms）未见到就绪标记——会话已自动停止`));
+            }, opts.timeoutMs);
+            poll = setInterval(() => {
+                const e = this.entries.get(sessionId);
+                if (!e) {
+                    clearTimeout(timer); clearInterval(poll!);
+                    reject(new Error(`会话 ${sessionId} 已消失（终态回收）`));
+                    return;
+                }
+                for (const l of e.ring.tailLines(5)) {
+                    if (regex.test(l.text)) {
+                        clearTimeout(timer); clearInterval(poll!); w.cancel();
+                        resolve({ matchedLine: l.text });
+                        return;
+                    }
+                }
+            }, 30);
+            poll.unref?.();
+            if (!entry.running) {
+                clearTimeout(timer); clearInterval(poll);
+                reject(new Error(`会话 ${sessionId} 已退出（exitCode=${entry.exitCode ?? "?"}），就绪标记未出现`));
+            }
+        });
+    }
+
+    /**
+     * 停止会话：SIGTERM → 宽限 → SIGKILL 升级；随后短窗核实终态
+     * （FEAT-04：终止即请求、死亡须核实——close 事件到达=exited 带退出码；
+     *  核实窗内未死=stopped（SIGKILL 升级已安排），返回三态不静默当成功）
+     */
+    async stop(sessionId: string): Promise<{ status: "exited" | "stopped" | "unknown"; exitCode?: number | null }> {
+        const entry = this.require(sessionId);
+        if (!entry.running) {
+            return { status: "exited", exitCode: entry.exitCode };
+        }
+        if (entry.proc?.pid) {
+            try { entry.proc.kill("SIGTERM"); } catch { /* already dead */ }
+            const pid = entry.proc.pid;
+            setTimeout(() => {
+                try { process.kill(pid, "SIGKILL"); } catch { /* gone */ }
+            }, KILL_GRACE_MS).unref();
+        }
+        // 短窗核实（local 子进程 close 可靠；1s 内死亡即带退出码）
+        for (let i = 0; i < 20 && entry.running; i++) {
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        if (!entry.running) return { status: "exited", exitCode: entry.exitCode };
+        return { status: "stopped" }; // SIGTERM 已发、SIGKILL 升级在场——清理请求已核实路径
+    }
+
+    list(): Array<{ sessionId: string; command: string; running: boolean; startedAt: number }> {
+        return Array.from(this.entries.values()).map((e) => ({
+            sessionId: e.sessionId,
+            command: e.command,
+            running: e.running,
+            startedAt: e.startedAt,
+        }));
+    }
+
+    // ── 内部 ─────────────────────────────────────────────
+
+    private require(sessionId: string): SessionEntry {
+        const e = this.entries.get(sessionId);
+        if (!e) throw new Error(`session '${sessionId}' 不存在（可能已终态被 TTL 回收）`);
+        return e;
+    }
+
+    private ingestChunk(entry: SessionEntry, text: string, stream: OutputStream): void {
+        for (const line of entry.assemblers[stream].feed(text)) this.ingestLine(entry, line, stream);
+    }
+
+    private ingestLine(entry: SessionEntry, fullLine: string, stream: OutputStream): void {
+        // 文件侧写完整行（1MB 防爆）+ 总量硬顶（64MiB 两流合计）；窗口侧截断
+        const fileChunk = fullLine.length > MAX_FILE_LINE_BYTES
+            ? fullLine.slice(0, MAX_FILE_LINE_BYTES) + "\n[…file-line-truncated]"
+            : fullLine;
+        if (!entry.logCapped) {
+            entry.logBytes += fileChunk.length + 1;
+            if (entry.logBytes > MAX_SESSION_LOG_BYTES) {
+                entry.logCapped = true;
+                for (const s of ["stdout", "stderr"] as const) {
+                    entry.logStreams[s].end(
+                        s === stream
+                            ? `[log-capped: session log exceeded ${MAX_SESSION_LOG_BYTES} bytes, file writes suppressed; ring buffer continues]\n`
+                            : `[log-capped]\n`,
+                    );
+                }
+            } else {
+                entry.logStreams[stream].write(fileChunk + "\n");
+            }
+        }
+        entry.ring.push({ stream, text: fullLine });
+
+        const anchor = entry.ring.size - 1;
+        for (const watcherId of entry.watchers.match(fullLine)) {
+            const meta = entry.watcherMeta.get(watcherId);
+            entry.watcherMeta.delete(watcherId);
+            // ★ thenStop：命中即收摊——观察对象结束，观察者退场（防遗忘泄漏）
+            if (meta?.thenStop) {
+                void this.stop(entry.sessionId).catch(() => undefined);
+            }
+            this.emit({
+                type: "match",
+                sessionId: entry.sessionId,
+                ownerSessionId: entry.ownerSessionId,
+                watcherId,
+                pattern: String(meta?.pattern ?? "?"),
+                matchedLine: entry.ring.tail(1)[0] ?? fullLine,
+                stream,
+                context: entry.ring.contextAround(anchor, meta?.contextLines ?? 5).map((l) => l.text),
+            });
+        }
+    }
+
+    private finalize(entry: SessionEntry, exitCode: number | null): void {
+        if (!entry.running) return;
+        entry.running = false;
+        entry.exitCode = exitCode;
+
+        for (const s of ["stdout", "stderr"] as const) {
+            for (const line of entry.assemblers[s].flush()) this.ingestLine(entry, line, s);
+            if (!entry.logCapped) entry.logStreams[s].end();
+        }
+        entry.watcherMeta.clear();
+
+        this.emit({
+            type: "exit",
+            sessionId: entry.sessionId,
+            ownerSessionId: entry.ownerSessionId,
+            exitCode,
+            lastLines: entry.ring.tail(20),
+        });
+        this.log.info(`[Session ${entry.sessionId}] exited code=${exitCode}`);
+
+        // TTL 回收（unref：不撑进程）
+        entry.ttlTimer = setTimeout(() => this.entries.delete(entry.sessionId), this.ttlMs).unref();
+    }
+
+    private emit(ev: SessionEvent): void {
+        try {
+            this.onEvent(ev);
+        } catch (err) {
+            this.log.warn(`session event sink threw: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/src/logger.ts

@@ -0,0 +1,19 @@
+/**
+ * logger.ts — 可注入日志接口（REQ-0001 §8.1：内核不绑任何 logger 实现）
+ *
+ * 消费方注入自己的 logger；缺省 noop（静默内核——SDK 不替调用方往 stdout 喷日志）。
+ */
+
+export interface FilaxisLogger {
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+
+export const noopLogger: FilaxisLogger = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};