@twinsearth/dsh-master 3.3.4 → 3.3.6

package/dist-host/engine/atomic-switch.js

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐。
+/**
+ * 蓝绿指针切换（AtomicSwitcher 的可编译实现）。
+ *
+ * 只做一件事：把 `linkPath` 这个目录指针**原子地**指向 `targetDir`。
+ * 做法是「新链接写临时名 → rename 覆盖」，因为同文件系统内 rename 是原子的：
+ * 读者永远看到旧指针或新指针，不会看到中间态。
+ *
+ * 平台差异（不隐藏）：
+ *   * POSIX：`symlink(target, link, 'dir')`，rename 覆盖。
+ *   * Windows：`symlink(..., 'junction')`。**junction 只能指向目录、不能跨卷**，
+ *     且不需要管理员权限（symlink 需要）。因此这里对 Windows 明确用 junction。
+ *
+ * 不做什么：不删旧目录、不动进程、不看护端口 —— 那些属于调用方（或瓮城的 VM 层）。
+ */
+import fsDefault from 'node:fs/promises';
+import path from 'node:path';
+const noop = () => { };
+function asString(value) { return String(value ?? '').trim(); }
+async function exists(fs, target) {
+    try {
+        await fs.lstat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * @param {{
+ *   linkPath: string, targetDir: string,
+ *   fs?: object, platform?: string,
+ *   now?: () => number,
+ * }} input
+ */
+export async function switchPointer(input = {}) {
+    const fs = input.fs ?? fsDefault;
+    const platform = String(input.platform ?? process.platform);
+    const now = typeof input.now === 'function' ? input.now : () => Date.now();
+    const linkPath = path.resolve(asString(input.linkPath));
+    const targetDir = path.resolve(asString(input.targetDir));
+    if (!asString(input.linkPath))
+        return { ok: false, code: 'link-path-required', error: 'linkPath is required' };
+    if (!asString(input.targetDir))
+        return { ok: false, code: 'target-dir-required', error: 'targetDir is required' };
+    if (linkPath === targetDir)
+        return { ok: false, code: 'self-reference', error: 'linkPath and targetDir must differ' };
+    // 目标必须是真实存在的目录：切换到一个不存在的绿槽比不切换更糟。
+    let targetStat = null;
+    try {
+        targetStat = await fs.stat(targetDir);
+    }
+    catch { /* handled below */ }
+    if (!targetStat || !targetStat.isDirectory()) {
+        return { ok: false, code: 'target-missing', error: `target directory does not exist: ${targetDir}` };
+    }
+    const parent = path.dirname(linkPath);
+    if (!(await exists(fs, parent)))
+        return { ok: false, code: 'parent-missing', error: `parent directory does not exist: ${parent}` };
+    // 现有指针必须是链接（或不存在）；覆盖普通目录/文件会静默毁数据，直接拒绝。
+    if (await exists(fs, linkPath)) {
+        const current = await fs.lstat(linkPath);
+        if (!current.isSymbolicLink() && platform !== 'win32') {
+            return { ok: false, code: 'link-is-not-a-symlink', error: `${linkPath} exists and is not a symlink` };
+        }
+        if (!current.isSymbolicLink() && platform === 'win32') {
+            // Windows 上 junction 在 lstat 里呈现为 symlink；普通目录一律拒绝。
+            return { ok: false, code: 'link-is-not-a-junction', error: `${linkPath} exists and is not a junction` };
+        }
+    }
+    const tempLink = `${linkPath}.${process.pid}.${now()}.tmp`;
+    const type = platform === 'win32' ? 'junction' : 'dir';
+    const startedAt = now();
+    try {
+        await fs.rm(tempLink, { force: true, recursive: true }).catch(noop);
+        await fs.symlink(targetDir, tempLink, type);
+        // rename 覆盖仅在同一文件系统内原子；跨卷时调用方必须自己保证同卷。
+        // Windows 上 rename 不能覆盖已存在的 junction（EPERM），退回“先移开再放”，
+        // 并如实标记 atomic=false —— 这个平台限制是真实存在的，不假装完美。
+        let replaced = 'rename';
+        let atomic = true;
+        try {
+            await fs.rename(tempLink, linkPath);
+        }
+        catch (error) {
+            if (platform !== 'win32' || error?.code !== 'EPERM')
+                throw error;
+            const backup = `${linkPath}.${process.pid}.${now()}.bak`;
+            await fs.rename(linkPath, backup);
+            try {
+                await fs.rename(tempLink, linkPath);
+            }
+            catch (inner) {
+                await fs.rename(backup, linkPath).catch(noop);
+                throw inner;
+            }
+            await fs.rm(backup, { force: true, recursive: true }).catch(noop);
+            replaced = 'move-aside';
+            atomic = false;
+        }
+        let resolved = null;
+        try {
+            resolved = await fs.realpath(linkPath);
+        }
+        catch { /* 读取失败不影响切换结论 */ }
+        return {
+            ok: true,
+            code: 'switched',
+            linkPath,
+            targetDir,
+            linkType: type,
+            replaced,
+            atomic,
+            resolved,
+            resolvedMatchesTarget: resolved ? path.resolve(resolved) === targetDir : null,
+            elapsedMs: Math.max(0, now() - startedAt),
+        };
+    }
+    catch (error) {
+        await fs.rm(tempLink, { force: true, recursive: true }).catch(noop);
+        return { ok: false, code: 'switch-failed', error: String(error?.message ?? error), linkPath, targetDir };
+    }
+}
+/**
+ * 读指针当前指向（只读）。不存在 / 不是链接时给出具名原因，不抛。
+ */
+export async function readPointer(input = {}) {
+    const fs = input.fs ?? fsDefault;
+    const linkPath = path.resolve(asString(input.linkPath));
+    if (!asString(input.linkPath))
+        return { ok: false, code: 'link-path-required', error: 'linkPath is required' };
+    if (!(await exists(fs, linkPath)))
+        return { ok: false, code: 'link-missing', error: `${linkPath} does not exist` };
+    try {
+        const stat = await fs.lstat(linkPath);
+        const target = await fs.readlink(linkPath).catch(() => null);
+        const resolved = await fs.realpath(linkPath).catch(() => null);
+        return { ok: true, linkPath, isSymlink: stat.isSymbolicLink(), target, resolved };
+    }
+    catch (error) {
+        return { ok: false, code: 'read-failed', error: String(error?.message ?? error) };
+    }
+}
+/**
+ * 用「先切到新槽、失败切回旧槽」的方式包装一次切换，失败时保证指针回到原目标。
+ */
+export async function switchWithRollback(input = {}) {
+    const fs = input.fs ?? fsDefault;
+    const previous = await readPointer({ fs, linkPath: input.linkPath });
+    const switched = await switchPointer(input);
+    if (switched.ok)
+        return { ...switched, rollback: null };
+    if (!previous.ok || !previous.resolved)
+        return { ...switched, rollback: null };
+    const restore = await switchPointer({ ...input, targetDir: previous.resolved });
+    return { ...switched, rollback: restore };
+}

package/dist-host/engine/health-probe.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * 健康检查探针（HealthProbe 的可编译实现）。
+ *
+ * 只做「有界轮询 + 明确结论」：
+ *   * 有总超时和最大尝试次数，不会无限等；
+ *   * 任何一次拿到期望状态码即成功（默认 200–299）；
+ *   * 超时/连接失败返回具名原因，**不**把“没连上”当成“健康”。
+ */
+const DEFAULT_INTERVAL_MS = 1_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_ATTEMPTS = 30;
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+function positiveInt(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, Math.max(1, ms)));
+}
+/**
+ * @param {{
+ *   url: string,
+ *   fetchImpl?: typeof fetch,
+ *   timeoutMs?: number, intervalMs?: number, maxAttempts?: number,
+ *   expectStatus?: (status: number) => boolean,
+ *   now?: () => number, sleepImpl?: (ms: number) => Promise<void>,
+ * }} input
+ */
+export async function probeHealth(input = {}) {
+    const url = String(input.url ?? '').trim();
+    if (!url)
+        return { ok: false, code: 'url-required', error: 'url is required', attempts: 0 };
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const timeoutMs = positiveInt(input.timeoutMs, DEFAULT_TIMEOUT_MS);
+    const intervalMs = positiveInt(input.intervalMs, DEFAULT_INTERVAL_MS);
+    const maxAttempts = positiveInt(input.maxAttempts, DEFAULT_MAX_ATTEMPTS);
+    const now = typeof input.now === 'function' ? input.now : () => Date.now();
+    const wait = typeof input.sleepImpl === 'function' ? input.sleepImpl : sleep;
+    const expectStatus = typeof input.expectStatus === 'function'
+        ? input.expectStatus
+        : (status) => status >= 200 && status < 300;
+    const startedAt = now();
+    const deadline = startedAt + timeoutMs;
+    // 单次请求超时必须与轮询间隔分开：拿 intervalMs 当请求超时会把「慢但有响应」误判成 probe-failed
+    const requestTimeoutMs = positiveInt(input.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+    let attempts = 0;
+    let lastStatus = null;
+    let lastError = null;
+    while (attempts < maxAttempts) {
+        if (attempts > 0 && now() >= deadline)
+            break;
+        attempts += 1;
+        try {
+            const controller = typeof AbortController === 'function' ? new AbortController() : null;
+            const timer = controller ? setTimeout(() => controller.abort(), Math.max(1, Math.min(requestTimeoutMs, 30_000))) : null;
+            if (timer && typeof timer.unref === 'function')
+                timer.unref();
+            let response = null;
+            try {
+                response = await fetchImpl(url, { method: 'GET', signal: controller ? controller.signal : undefined });
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+            lastStatus = Number(response?.status ?? 0) || null;
+            lastError = null;
+            if (lastStatus !== null && expectStatus(lastStatus)) {
+                return { ok: true, code: 'healthy', status: lastStatus, attempts, elapsedMs: Math.max(0, now() - startedAt), url };
+            }
+        }
+        catch (error) {
+            lastError = String(error?.message ?? error);
+        }
+        if (now() >= deadline)
+            break;
+        if (attempts < maxAttempts)
+            await wait(intervalMs);
+    }
+    const elapsedMs = Math.max(0, now() - startedAt);
+    // 只要拿到过响应，就以状态码为准——不能因为某次连接失败把「服务返回 503」改写成 probe-failed
+    if (lastStatus !== null)
+        return { ok: false, code: 'unhealthy-status', status: lastStatus, attempts, elapsedMs, url };
+    if (lastError)
+        return { ok: false, code: 'probe-failed', error: lastError, status: lastStatus, attempts, elapsedMs, url };
+    return { ok: false, code: 'probe-timeout', attempts, elapsedMs, url };
+}

package/dist-host/engine/index.js

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * 3.3.5 · 宿主侧引擎原语（不依赖任何 VM / 瓮城代码）。
+ *
+ * 这三个原语回答的是「切换/验证/回滚」的正确性，而不是「怎么管 VM」：
+ *   * `switchPointer` / `switchWithRollback` —— 蓝绿指针原子切换，失败回到旧目标；
+ *   * `probeHealth` —— 有界健康检查，不会把“连不上”当健康；
+ *   * `runSafeUpdate` —— 快照 → 更新 → 冒烟 → 失败回滚，执行能力由调用方注入。
+ *
+ * 没有 `vm_create`/`vm_exec` 这类假设：房主不持有 VM；需要时由宿主或瓮城提供 executor。
+ */
+export { switchPointer, readPointer, switchWithRollback } from "./atomic-switch.js";
+export { probeHealth } from "./health-probe.js";
+export { runSafeUpdate, switchAndVerify } from "./safe-update.js";
+export { createPluginUpdater, buildSmokeScript, shellArgv, UPDATE_PHASES } from "./plugin-updater.js";
+export { createLlmStreamer, llmStreamFn } from "./llm-stream.js";

package/dist-host/engine/llm-stream.js

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * 可中断的 LLM 流（3.3.5）。
+ *
+ * 真实宿主 API 是 `ctx.llm.stream(options)`（不是草案里的 `llm.client.chat.completions.create`）：
+ *   * `options.signal` 原生支持取消；
+ *   * 取消后流会以 `{type:'finish', reason:{kind:'aborted'}}` 收尾；
+ *   * `StreamChunk` 里文本增量是 `{type:'text-delta', text}`。
+ *
+ * 本模块负责「谁在跑、怎么停、停完怎么记账」：
+ *   * 每个 key（会话/消息）最多一条在跑的流，新的一轮会先中止旧的；
+ *   * 中止后**保留已产出的半截文本**（`partial`），供 UI 展示与上下文续写；
+ *   * `dispose()` 中止全部（宿主卸载用）；
+ *   * **不声称**能验证服务端计费已停止——我们只能保证自己停止读取并传了 signal。
+ *
+ * 依赖注入：`streamFn(options) => AsyncIterable<StreamChunk>`，便于测试与替换。
+ */
+import { createAbortRegistry } from "../channel/abort-registry.js";
+const ABORTED = Symbol('aborted');
+function watchAbort(signal) {
+    if (!signal)
+        return { promise: new Promise(() => { }), cancel: () => { } };
+    let listener = null;
+    const promise = new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve(ABORTED);
+            return;
+        }
+        listener = () => resolve(ABORTED);
+        signal.addEventListener('abort', listener, { once: true });
+    });
+    return {
+        promise,
+        cancel: () => { try {
+            if (listener)
+                signal.removeEventListener('abort', listener);
+        }
+        catch { /* ignore */ } },
+    };
+}
+function chunkText(chunk) {
+    if (!chunk || typeof chunk !== 'object')
+        return '';
+    if (chunk.type === 'text-delta')
+        return String(chunk.text ?? '');
+    if (chunk.type === 'reasoning-delta')
+        return '';
+    return '';
+}
+/**
+ * @param {{
+ *   streamFn: (options: object) => AsyncIterable<object>,
+ *   registry?: object,
+ *   onDelta?: (delta: string, meta: object) => void,
+ *   logger?: { info?: Function, warn?: Function, error?: Function },
+ * }} deps
+ */
+export function createLlmStreamer(deps = {}) {
+    if (typeof deps.streamFn !== 'function') {
+        return {
+            available: false,
+            reason: 'streamFn-required',
+            run: async () => ({ ok: false, code: 'streamFn-required', error: 'a streamFn(options) => AsyncIterable is required' }),
+            abort: () => false,
+            abortAll: () => [],
+            activeKeys: () => [],
+            dispose: () => ({ aborted: [] }),
+        };
+    }
+    const registry = deps.registry ?? createAbortRegistry();
+    const log = (level, message) => { try {
+        deps.logger?.[level]?.(message);
+    }
+    catch { /* ignore */ } };
+    const stallTimeoutMs = Number(deps.stallTimeoutMs) > 0 ? Number(deps.stallTimeoutMs) : 0;
+    let disposed = false;
+    /**
+     * 跑一条流并返回结构化结果（永不抛：错误变成 code）。
+     * @param {{key: string, options?: object, signal?: AbortSignal}} input
+     */
+    async function run(input = {}) {
+        const key = String(input.key ?? '').trim();
+        if (!key)
+            return { ok: false, code: 'key-required', error: 'key is required' };
+        if (disposed)
+            return { ok: false, code: 'streamer-disposed', error: 'streamer was disposed' };
+        const entry = registry.begin(key);
+        const signal = entry.signal;
+        const onDelta = typeof input.onDelta === 'function' ? input.onDelta : deps.onDelta;
+        const external = input.signal;
+        const onExternalAbort = () => entry.abort('external-abort');
+        if (external) {
+            if (external.aborted)
+                entry.abort('external-abort');
+            else
+                external.addEventListener('abort', onExternalAbort, { once: true });
+        }
+        let text = '';
+        let finish = null;
+        let aborted = false;
+        let usage = null;
+        const watch = watchAbort(signal);
+        const iteratorRef = { current: null };
+        try {
+            const iterator = deps.streamFn({ ...(input.options ?? {}), signal });
+            iteratorRef.current = iterator?.[Symbol.asyncIterator]?.() ?? null;
+            if (!iteratorRef.current)
+                return { ok: false, code: 'stream-not-async-iterable', error: 'streamFn must return an AsyncIterable', text, aborted: false };
+            while (true) {
+                // 卡住兜底：上游长时间不吐字（连接半死/网关静默）时主动中止，避免句柄挂着烧钱
+                const stall = stallTimeoutMs > 0
+                    ? new Promise((resolve) => { const timer = setTimeout(() => resolve('stalled'), stallTimeoutMs); if (typeof timer.unref === 'function')
+                        timer.unref(); })
+                    : new Promise(() => { });
+                const step = await Promise.race([iteratorRef.current.next(), watch.promise, stall]);
+                if (step === 'stalled') {
+                    entry.abort('stalled');
+                    log('warn', `[llm-stream] upstream stalled >${stallTimeoutMs}ms key=${key}`);
+                    return { ok: false, code: 'stalled', error: `no chunk within ${stallTimeoutMs}ms`, text, aborted: true, finish, usage, savedContent: text };
+                }
+                if (step === ABORTED) {
+                    aborted = true;
+                    break;
+                }
+                if (!step || step.done)
+                    break;
+                const chunk = step.value;
+                if (signal.aborted) {
+                    aborted = true;
+                    break;
+                }
+                if (chunk?.type === 'usage' && chunk.usage)
+                    usage = chunk.usage;
+                if (chunk?.type === 'finish') {
+                    finish = chunk.reason ?? null;
+                    if (finish?.kind === 'aborted')
+                        aborted = true;
+                    if (finish?.kind === 'error') {
+                        return { ok: false, code: 'llm-error', error: finish.failure?.message ?? 'model call failed', failure: finish.failure, text, aborted: false, usage };
+                    }
+                    continue;
+                }
+                const delta = chunkText(chunk);
+                if (delta) {
+                    text += delta;
+                    try {
+                        onDelta?.(delta, { key, text });
+                    }
+                    catch { /* 消费回调异常不影响流 */ }
+                }
+            }
+            if (aborted) {
+                log('info', `[llm-stream] aborted key=${key} after ${text.length} chars`);
+                return { ok: false, code: 'aborted', error: 'generation aborted by caller', text, aborted: true, finish, usage, savedContent: text };
+            }
+            log('info', `[llm-stream] done key=${key} chars=${text.length}`);
+            return { ok: true, code: 'completed', text, aborted: false, finish, usage };
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            const isAbort = signal.aborted || error?.name === 'AbortError' || /abort/iu.test(message);
+            if (isAbort) {
+                log('info', `[llm-stream] abort surfaced as error key=${key}: ${message}`);
+                return { ok: false, code: 'aborted', error: message, text, aborted: true, finish, usage, savedContent: text };
+            }
+            log('error', `[llm-stream] failed key=${key}: ${message}`);
+            return { ok: false, code: 'stream-failed', error: message, text, aborted: false, finish, usage };
+        }
+        finally {
+            watch.cancel();
+            try {
+                external?.removeEventListener?.('abort', onExternalAbort);
+            }
+            catch { /* ignore */ }
+            // 清理上游时**绝不能无限等**：卡死的异步生成器会把 return() 排在未完成的 next() 后面，
+            // await 它会永久挂住（这正是我们要防的僵尸句柄）。这里给一个有界让步。
+            try {
+                const closing = iteratorRef.current?.return?.();
+                if (closing && typeof closing.then === 'function') {
+                    await Promise.race([
+                        closing,
+                        new Promise((resolve) => { const timer = setTimeout(resolve, 50); if (typeof timer.unref === 'function')
+                            timer.unref(); }),
+                    ]);
+                }
+            }
+            catch { /* 尽力关闭上游 */ }
+            entry.end();
+        }
+    }
+    return {
+        available: true,
+        run,
+        abort: (key, reason = 'user-interrupt') => registry.abort(String(key ?? ''), reason),
+        abortAll: (reason = 'shutdown') => registry.abortAll(reason),
+        activeKeys: () => registry.keys(),
+        dispose: () => {
+            if (disposed)
+                return { aborted: [] };
+            disposed = true;
+            return { aborted: registry.abortAll('disposed') };
+        },
+    };
+}
+/**
+ * 把真实 `ctx.llm.stream` 适配成 streamFn。
+ * 之所以包一层：只取需要的字段，且把 method 绑定到服务对象上（避免 this 丢失）。
+ */
+export function llmStreamFn(llm) {
+    if (!llm || typeof llm.stream !== 'function')
+        return null;
+    return (options) => llm.stream(options);
+}