@tencent-ai/agent-sdk 0.3.206 → 0.3.209

package/cli/vendor/shim/node-brokered-fs-shim.cjs

@@ -0,0 +1,932 @@
+/**
+ * CodeBuddy Node brokered fs shim
+ *
+ * Loaded by node-language-shim.cjs. Installs brokered file-token and host-op hooks.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const url = require('url');
+const brokerIpc = require('./broker-ipc-client.cjs');
+
+const SESSION_ID = process.env.CODEBUDDY_SESSION_ID
+    || process.env.CLAUDE_SESSION_ID;
+
+if (!SESSION_ID) {
+    return;
+}
+
+const BROKERED_FS_HOOK_ENABLED = process.env.CODEBUDDY_BROKERED_FS_HOOK_ENABLED === '1'
+    || process.env.CODEBUDDY_SAFE_DELETE_SANDBOX === '1';
+
+if (!BROKERED_FS_HOOK_ENABLED) {
+    return;
+}
+
+if (global.__CODEBUDDY_NODE_BROKERED_FS_SHIM_LOADED__) {
+    return;
+}
+global.__CODEBUDDY_NODE_BROKERED_FS_SHIM_LOADED__ = true;
+
+const PLATFORM = process.platform; // 'darwin' | 'win32' | 'linux' | ...
+const BROKER_HOST_OP_DEFAULT_TIMEOUT_MS = 5_000;
+const SHIM_DIR = __dirname;
+const BROKER_FALLBACK_DEBUG = process.env.CODEBUDDY_SANDBOX_BROKER_DEBUG === '1';
+let brokerRequestSeq = 0;
+let brokerNativeAddonLoaded = false;
+let brokerNativeAddon;
+
+// broker 连接失败会静默退化为原生 fs 调用（fail-open）。默认不打印，避免污染被
+// hook 的任意子进程的 stdout/stderr；排查问题时可设 CODEBUDDY_SANDBOX_BROKER_DEBUG=1 开启。
+function logBrokerFallback(kind, operation, filePath, error) {
+    if (!BROKER_FALLBACK_DEBUG) { return; }
+    const reason = error && error.message ? error.message : String(error);
+    process.stderr.write(`[CodeBuddy][brokered-fs] fallback to native fs: kind=${kind} operation=${operation} path=${filePath == null ? '' : filePath} reason=${reason}\n`);
+}
+
+// 保存原始引用（必须在所有 patch 之前）
+const origMkdirSync = fs.mkdirSync.bind(fs);
+const origRenameSync = fs.renameSync.bind(fs);
+const origCopyFileSync = fs.copyFileSync.bind(fs);
+const origCpSync = fs.cpSync ? fs.cpSync.bind(fs) : null;
+const origChmodSync = fs.chmodSync.bind(fs);
+const origLinkSync = fs.linkSync.bind(fs);
+const origSymlinkSync = fs.symlinkSync.bind(fs);
+const origExistsSync = fs.existsSync.bind(fs);
+
+const origMkdir = fs.mkdir.bind(fs);
+const origRename = fs.rename.bind(fs);
+const origCopyFile = fs.copyFile.bind(fs);
+const origCp = fs.cp ? fs.cp.bind(fs) : null;
+const origChmod = fs.chmod.bind(fs);
+const origLink = fs.link.bind(fs);
+const origSymlink = fs.symlink.bind(fs);
+
+const origPromisesMkdir = fs.promises ? fs.promises.mkdir.bind(fs.promises) : null;
+const origPromisesRename = fs.promises ? fs.promises.rename.bind(fs.promises) : null;
+const origPromisesCopyFile = fs.promises ? fs.promises.copyFile.bind(fs.promises) : null;
+const origPromisesCp = fs.promises && fs.promises.cp ? fs.promises.cp.bind(fs.promises) : null;
+const origPromisesChmod = fs.promises ? fs.promises.chmod.bind(fs.promises) : null;
+const origPromisesLink = fs.promises ? fs.promises.link.bind(fs.promises) : null;
+const origPromisesSymlink = fs.promises ? fs.promises.symlink.bind(fs.promises) : null;
+
+const origOpenSync = fs.openSync.bind(fs);
+const origReadFileSync = fs.readFileSync.bind(fs);
+const origWriteFileSync = fs.writeFileSync.bind(fs);
+const origAppendFileSync = fs.appendFileSync.bind(fs);
+const origCreateReadStream = fs.createReadStream.bind(fs);
+const origCreateWriteStream = fs.createWriteStream.bind(fs);
+
+const origOpen = fs.open.bind(fs);
+const origReadFile = fs.readFile.bind(fs);
+const origWriteFile = fs.writeFile.bind(fs);
+const origAppendFile = fs.appendFile.bind(fs);
+
+const origPromisesOpen = fs.promises ? fs.promises.open.bind(fs.promises) : null;
+const origPromisesReadFile = fs.promises ? fs.promises.readFile.bind(fs.promises) : null;
+const origPromisesWriteFile = fs.promises ? fs.promises.writeFile.bind(fs.promises) : null;
+const origPromisesAppendFile = fs.promises ? fs.promises.appendFile.bind(fs.promises) : null;
+
+/**
+ * 将 fs API 的 filePath 参数转为绝对路径。
+ * 处理 URL 对象（如 new URL('file:///tmp/x')），避免 String(URL) 产生无效路径绕过 shim。
+ * @param {string|Buffer|URL} filePath
+ * @returns {string} 绝对路径
+ */
+function toAbsPath(filePath) {
+    if (filePath instanceof URL) {
+        return url.fileURLToPath(filePath);
+    }
+    // 防御跨 VM context 的 URL 对象（instanceof 跨 realm 返回 false）
+    if (filePath && typeof filePath === 'object' && filePath.href && typeof filePath.protocol === 'string') {
+        return url.fileURLToPath(filePath);
+    }
+    return path.resolve(String(filePath));
+}
+
+
+function isBrokerHostOperationEnabled() {
+    return PLATFORM === 'darwin'
+        && BROKERED_FS_HOOK_ENABLED
+        && !!process.env.CODEBUDDY_SANDBOX_BROKER_IPC_ADDRESS
+        && !!process.env.CODEBUDDY_SANDBOX_BROKER_SESSION_ID
+        && !!process.env.CODEBUDDY_SANDBOX_HOST_FILE_OPERATION_COMMAND;
+}
+
+function loadBrokerNativeAddon() {
+    if (process.env.CODEBUDDY_SANDBOX_NATIVE_ADDON_DISABLED === '1') {
+        return undefined;
+    }
+    if (brokerNativeAddonLoaded) {
+        return brokerNativeAddon;
+    }
+    brokerNativeAddonLoaded = true;
+
+    const candidates = [
+        process.env.CODEBUDDY_SANDBOX_NATIVE_ADDON_PATH,
+        path.join(__dirname, 'native', `${process.platform}-${process.arch}`, 'brokered-sandbox-native.node'),
+        path.join(__dirname, 'native', 'brokered-sandbox-native.node'),
+    ].filter(Boolean);
+
+    for (const candidate of candidates) {
+        try {
+            const loaded = require(candidate);
+            if (loaded
+                && typeof loaded.consumeSandboxExtension === 'function'
+                && typeof loaded.requestBrokerSync === 'function') {
+                brokerNativeAddon = loaded;
+                return brokerNativeAddon;
+            }
+        } catch (_) {
+            // Optional native support. Without it, token-based Node fs access falls back to the OS sandbox.
+        }
+    }
+    return undefined;
+}
+
+function isBrokerFileTokenEnabled() {
+    return PLATFORM === 'darwin'
+        && BROKERED_FS_HOOK_ENABLED
+        && !!process.env.CODEBUDDY_SANDBOX_BROKER_IPC_ADDRESS
+        && !!process.env.CODEBUDDY_SANDBOX_BROKER_SESSION_ID
+        && !!process.env.CODEBUDDY_SANDBOX_FILE_TOKEN_OPERATION_COMMAND
+        && !!loadBrokerNativeAddon();
+}
+
+function brokerTimeoutMs() {
+    return brokerIpc.brokerTimeoutMs ? brokerIpc.brokerTimeoutMs() : BROKER_HOST_OP_DEFAULT_TIMEOUT_MS;
+}
+
+function buildBrokerHostOperationRequest(operation, fields) {
+    const request = {
+        id: `node-${process.pid}-${++brokerRequestSeq}`,
+        runtime: 'node',
+        command: process.env.CODEBUDDY_SANDBOX_HOST_FILE_OPERATION_COMMAND || 'HostFileOperation',
+        operation,
+        sessionId: process.env.CODEBUDDY_SANDBOX_BROKER_SESSION_ID || SESSION_ID,
+        ...fields,
+    };
+    if (process.env.CODEBUDDY_SANDBOX_BROKER_TOOL_CALL_ID) {
+        request.toolCallId = process.env.CODEBUDDY_SANDBOX_BROKER_TOOL_CALL_ID;
+    }
+    if (process.env.CODEBUDDY_SANDBOX_BROKER_TRACE_ID) {
+        request.brokerTraceId = process.env.CODEBUDDY_SANDBOX_BROKER_TRACE_ID;
+    }
+    return request;
+}
+
+function buildBrokerFileTokenRequest(operation, filePath) {
+    const request = {
+        id: `node-${process.pid}-${++brokerRequestSeq}`,
+        runtime: 'node',
+        command: process.env.CODEBUDDY_SANDBOX_FILE_TOKEN_OPERATION_COMMAND || 'FileTokenRequest',
+        operation,
+        path: toAbsPath(filePath),
+        sessionId: process.env.CODEBUDDY_SANDBOX_BROKER_SESSION_ID || SESSION_ID,
+    };
+    if (process.env.CODEBUDDY_SANDBOX_BROKER_TOOL_CALL_ID) {
+        request.toolCallId = process.env.CODEBUDDY_SANDBOX_BROKER_TOOL_CALL_ID;
+    }
+    if (process.env.CODEBUDDY_SANDBOX_BROKER_TRACE_ID) {
+        request.brokerTraceId = process.env.CODEBUDDY_SANDBOX_BROKER_TRACE_ID;
+    }
+    return request;
+}
+
+function buildBrokerFileWriteCompletedRequest(filePath) {
+    const request = {
+        id: `node-${process.pid}-${++brokerRequestSeq}`,
+        runtime: 'node',
+        command: 'FileWriteCompleted',
+        operation: 'write',
+        path: toAbsPath(filePath),
+        sessionId: process.env.CODEBUDDY_SANDBOX_BROKER_SESSION_ID || SESSION_ID,
+    };
+    if (process.env.CODEBUDDY_SANDBOX_BROKER_TOOL_CALL_ID) {
+        request.toolCallId = process.env.CODEBUDDY_SANDBOX_BROKER_TOOL_CALL_ID;
+    }
+    if (process.env.CODEBUDDY_SANDBOX_BROKER_TRACE_ID) {
+        request.brokerTraceId = process.env.CODEBUDDY_SANDBOX_BROKER_TRACE_ID;
+    }
+    return request;
+}
+
+function createBrokerPolicyError(response) {
+    const message = response && response.error
+        ? String(response.error)
+        : `Brokered Node host operation refused: ${response && response.operation ? response.operation : 'unknown'}`;
+    const error = new Error(message);
+    error.code = 'CODEBUDDY_BROKER_DENY';
+    error.decision = response && response.decision;
+    error.__codebuddyBrokerPolicyError = true;
+    return error;
+}
+
+function handleBrokerHostOperationResponse(response) {
+    if (response && response.ok === true) {
+        return true;
+    }
+    if (response && response.decision === 'sandbox') {
+        return false;
+    }
+    throw createBrokerPolicyError(response);
+}
+
+function handleBrokerFileTokenResponse(response) {
+    if (response && response.ok === true && typeof response.token === 'string' && response.token) {
+        const nativeAddon = loadBrokerNativeAddon();
+        if (!nativeAddon) {
+            return false;
+        }
+        nativeAddon.consumeSandboxExtension(response.token);
+        return true;
+    }
+    if (response && response.decision === 'sandbox') {
+        return false;
+    }
+    throw createBrokerPolicyError(response);
+}
+
+function parseBrokerHostOperationResponse(line) {
+    return brokerIpc.parseBrokerResponse(line);
+}
+
+function requestBrokerHostOperation(request) {
+    return brokerIpc.sendBrokerRequest(request);
+}
+
+function isPathLikeFileAccessTarget(filePath) {
+    return typeof filePath !== 'number';
+}
+
+function existedBeforeWrite(filePath) {
+    if (!isPathLikeFileAccessTarget(filePath)) {
+        return true;
+    }
+    try {
+        return origExistsSync(toAbsPath(filePath));
+    } catch (_) {
+        return true;
+    }
+}
+
+function isUnderShimDir(absPath) {
+    const rel = path.relative(SHIM_DIR, absPath);
+    return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+// Avoid broker file-token interception while require() reads sibling shim modules.
+function shouldBypassBrokerFileToken(operation, filePath) {
+    return operation === 'read'
+        && isPathLikeFileAccessTarget(filePath)
+        && isUnderShimDir(toAbsPath(filePath));
+}
+
+function tryBrokerFileTokenSync(operation, filePath) {
+    if (!isPathLikeFileAccessTarget(filePath)
+        || shouldBypassBrokerFileToken(operation, filePath)
+        || !isBrokerFileTokenEnabled()) {
+        return false;
+    }
+    const nativeAddon = loadBrokerNativeAddon();
+    const request = buildBrokerFileTokenRequest(operation, filePath);
+    try {
+        const responseLine = nativeAddon.requestBrokerSync(
+            process.env.CODEBUDDY_SANDBOX_BROKER_IPC_ADDRESS,
+            JSON.stringify(request),
+            brokerTimeoutMs(),
+        );
+        return handleBrokerFileTokenResponse(parseBrokerHostOperationResponse(responseLine));
+    } catch (error) {
+        if (error && error.__codebuddyBrokerPolicyError) {
+            throw error;
+        }
+        logBrokerFallback('file-token-sync', operation, filePath, error);
+        return false;
+    }
+}
+
+async function tryBrokerFileToken(operation, filePath) {
+    if (!isPathLikeFileAccessTarget(filePath)
+        || shouldBypassBrokerFileToken(operation, filePath)
+        || !isBrokerFileTokenEnabled()) {
+        return false;
+    }
+    const request = buildBrokerFileTokenRequest(operation, filePath);
+    try {
+        return handleBrokerFileTokenResponse(await requestBrokerHostOperation(request));
+    } catch (error) {
+        if (error && error.__codebuddyBrokerPolicyError) {
+            throw error;
+        }
+        logBrokerFallback('file-token', operation, filePath, error);
+        return false;
+    }
+}
+
+function isBrokerFileWriteCompletedEnabled(filePath) {
+    return PLATFORM === 'darwin'
+        && BROKERED_FS_HOOK_ENABLED
+        && isPathLikeFileAccessTarget(filePath)
+        && !!process.env.CODEBUDDY_SANDBOX_BROKER_IPC_ADDRESS
+        && !!process.env.CODEBUDDY_SANDBOX_BROKER_SESSION_ID;
+}
+
+function notifyBrokerFileWriteCompletedSync(filePath, existedBefore) {
+    if (existedBefore) {
+        return;
+    }
+    if (!isBrokerFileWriteCompletedEnabled(filePath)) {
+        return;
+    }
+    try {
+        requestBrokerHostOperationSync(buildBrokerFileWriteCompletedRequest(filePath));
+    } catch (error) {
+        logBrokerFallback('file-write-completed-sync', 'write', filePath, error);
+    }
+}
+
+async function notifyBrokerFileWriteCompleted(filePath, existedBefore) {
+    if (existedBefore) {
+        return;
+    }
+    if (!isBrokerFileWriteCompletedEnabled(filePath)) {
+        return;
+    }
+    try {
+        await requestBrokerHostOperation(buildBrokerFileWriteCompletedRequest(filePath));
+    } catch (error) {
+        logBrokerFallback('file-write-completed', 'write', filePath, error);
+    }
+}
+
+function requestBrokerHostOperationSync(request) {
+    return brokerIpc.sendBrokerRequestSync(request, { nativeAddon: loadBrokerNativeAddon() });
+}
+
+function tryBrokerHostOperationSync(operation, fields) {
+    if (!isBrokerHostOperationEnabled()) {
+        return false;
+    }
+    const request = buildBrokerHostOperationRequest(operation, fields);
+    try {
+        return handleBrokerHostOperationResponse(requestBrokerHostOperationSync(request));
+    } catch (error) {
+        if (error && error.__codebuddyBrokerPolicyError) {
+            throw error;
+        }
+        logBrokerFallback('host-op-sync', operation, fields && (fields.path || fields.to || fields.from), error);
+        return false;
+    }
+}
+
+async function tryBrokerHostOperation(operation, fields) {
+    if (!isBrokerHostOperationEnabled()) {
+        return false;
+    }
+    const request = buildBrokerHostOperationRequest(operation, fields);
+    try {
+        return handleBrokerHostOperationResponse(await requestBrokerHostOperation(request));
+    } catch (error) {
+        if (error && error.__codebuddyBrokerPolicyError) {
+            throw error;
+        }
+        logBrokerFallback('host-op', operation, fields && (fields.path || fields.to || fields.from), error);
+        return false;
+    }
+}
+
+function normalizeMode(mode) {
+    if (typeof mode === 'number' && Number.isFinite(mode)) {
+        return mode;
+    }
+    if (typeof mode === 'string' && mode.trim()) {
+        const parsed = Number.parseInt(mode, 8);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+
+function normalizeMkdirOptions(options) {
+    if (typeof options === 'number' || typeof options === 'string') {
+        return { mode: normalizeMode(options) };
+    }
+    if (options && typeof options === 'object') {
+        return {
+            recursive: !!options.recursive,
+            mode: normalizeMode(options.mode),
+        };
+    }
+    return {};
+}
+
+function brokerOperationForOpenFlags(flags) {
+    const value = flags === undefined ? 'r' : flags;
+    if (typeof value === 'number') {
+        const constants = fs.constants || {};
+        const writeMask = (constants.O_WRONLY || 0)
+            | (constants.O_RDWR || 0)
+            | (constants.O_CREAT || 0)
+            | (constants.O_TRUNC || 0)
+            | (constants.O_APPEND || 0);
+        return (value & writeMask) ? 'write' : 'read';
+    }
+    const text = String(value);
+    return /[wa+]/.test(text) ? 'write' : 'read';
+}
+
+function buildMkdirBrokerFields(filePath, options) {
+    const normalized = normalizeMkdirOptions(options);
+    return {
+        path: toAbsPath(filePath),
+        recursive: normalized.recursive,
+        ...(normalized.mode !== undefined ? { mode: normalized.mode } : {}),
+    };
+}
+
+function shouldBrokerCopyFileMode(mode) {
+    return mode === undefined || mode === 0;
+}
+
+function isSimpleCpOptions(options) {
+    if (options === undefined) {
+        return true;
+    }
+    if (!options || typeof options !== 'object') {
+        return false;
+    }
+    return Object.keys(options).every(key => key === 'recursive');
+}
+
+
+// ----- brokered file tokens（当前 Node 进程消费 sandbox token 后继续原生 fs）-----
+
+function wrappedOpenSync(filePath, flags, mode) {
+    tryBrokerFileTokenSync(brokerOperationForOpenFlags(flags), filePath);
+    return origOpenSync(filePath, flags, mode);
+}
+
+function wrappedOpen(filePath, flags, mode, callback) {
+    const originalArgs = Array.prototype.slice.call(arguments);
+    let openFlags = flags;
+    let cb = callback;
+    if (typeof flags === 'function') {
+        openFlags = undefined;
+        cb = flags;
+    } else if (typeof mode === 'function') {
+        cb = mode;
+    }
+    if (typeof cb !== 'function') {
+        return origOpen(...originalArgs);
+    }
+    tryBrokerFileToken(brokerOperationForOpenFlags(openFlags), filePath)
+        .then(() => origOpen(...originalArgs))
+        .catch(error => process.nextTick(() => cb(error)));
+    return undefined;
+}
+
+async function wrappedPromisesOpen(filePath, flags, mode) {
+    await tryBrokerFileToken(brokerOperationForOpenFlags(flags), filePath);
+    return origPromisesOpen(filePath, flags, mode);
+}
+
+function wrappedReadFileSync(filePath, options) {
+    tryBrokerFileTokenSync('read', filePath);
+    return origReadFileSync(filePath, options);
+}
+
+function wrappedReadFile(filePath, options, callback) {
+    const originalArgs = Array.prototype.slice.call(arguments);
+    const cb = typeof options === 'function' ? options : callback;
+    if (typeof cb !== 'function') {
+        return origReadFile(...originalArgs);
+    }
+    tryBrokerFileToken('read', filePath)
+        .then(() => origReadFile(...originalArgs))
+        .catch(error => process.nextTick(() => cb(error)));
+    return undefined;
+}
+
+async function wrappedPromisesReadFile(filePath, options) {
+    await tryBrokerFileToken('read', filePath);
+    return origPromisesReadFile(filePath, options);
+}
+
+// Node's real appendFileSync/appendFile implementations delegate internally to
+// fs.writeFileSync/fs.writeFile (the same mutable exported properties this shim
+// patches), so a naive append wrapper that also instruments would double-fire
+// the broker token/write-completed calls. This depth counter lets the write
+// wrappers detect "we're already inside an append call we instrumented" and
+// fall back to the un-instrumented original, regardless of whether a given
+// Node version happens to implement append via delegation or not.
+let suppressWriteInstrumentationDepth = 0;
+
+function wrappedWriteFileSync(filePath, data, options) {
+    if (suppressWriteInstrumentationDepth > 0) {
+        return origWriteFileSync(filePath, data, options);
+    }
+    const existedBefore = existedBeforeWrite(filePath);
+    tryBrokerFileTokenSync('write', filePath);
+    const result = origWriteFileSync(filePath, data, options);
+    notifyBrokerFileWriteCompletedSync(filePath, existedBefore);
+    return result;
+}
+
+function wrappedWriteFile(filePath, data, options, callback) {
+    const cb = typeof options === 'function' ? options : callback;
+    if (typeof cb !== 'function') {
+        return origWriteFile.apply(fs, arguments);
+    }
+    if (suppressWriteInstrumentationDepth > 0) {
+        return origWriteFile.apply(fs, arguments);
+    }
+    const existedBefore = existedBeforeWrite(filePath);
+    const wrappedCallback = error => {
+        if (error) {
+            cb(error);
+            return;
+        }
+        void notifyBrokerFileWriteCompleted(filePath, existedBefore);
+        cb(null);
+    };
+    tryBrokerFileToken('write', filePath)
+        .then(() => {
+            if (typeof options === 'function') {
+                origWriteFile(filePath, data, wrappedCallback);
+            } else {
+                origWriteFile(filePath, data, options, wrappedCallback);
+            }
+        })
+        .catch(error => process.nextTick(() => cb(error)));
+    return undefined;
+}
+
+async function wrappedPromisesWriteFile(filePath, data, options) {
+    const existedBefore = existedBeforeWrite(filePath);
+    await tryBrokerFileToken('write', filePath);
+    const result = await origPromisesWriteFile(filePath, data, options);
+    void notifyBrokerFileWriteCompleted(filePath, existedBefore);
+    return result;
+}
+
+function wrappedAppendFileSync(filePath, data, options) {
+    const existedBefore = existedBeforeWrite(filePath);
+    tryBrokerFileTokenSync('write', filePath);
+    suppressWriteInstrumentationDepth++;
+    let result;
+    try {
+        result = origAppendFileSync(filePath, data, options);
+    } finally {
+        suppressWriteInstrumentationDepth--;
+    }
+    notifyBrokerFileWriteCompletedSync(filePath, existedBefore);
+    return result;
+}
+
+function wrappedAppendFile(filePath, data, options, callback) {
+    const cb = typeof options === 'function' ? options : callback;
+    if (typeof cb !== 'function') {
+        return origAppendFile.apply(fs, arguments);
+    }
+    const existedBefore = existedBeforeWrite(filePath);
+    const wrappedCallback = error => {
+        if (error) {
+            cb(error);
+            return;
+        }
+        void notifyBrokerFileWriteCompleted(filePath, existedBefore);
+        cb(null);
+    };
+    tryBrokerFileToken('write', filePath)
+        .then(() => {
+            suppressWriteInstrumentationDepth++;
+            try {
+                if (typeof options === 'function') {
+                    origAppendFile(filePath, data, wrappedCallback);
+                } else {
+                    origAppendFile(filePath, data, options, wrappedCallback);
+                }
+            } finally {
+                suppressWriteInstrumentationDepth--;
+            }
+        })
+        .catch(error => process.nextTick(() => cb(error)));
+    return undefined;
+}
+
+async function wrappedPromisesAppendFile(filePath, data, options) {
+    const existedBefore = existedBeforeWrite(filePath);
+    await tryBrokerFileToken('write', filePath);
+    const result = await origPromisesAppendFile(filePath, data, options);
+    void notifyBrokerFileWriteCompleted(filePath, existedBefore);
+    return result;
+}
+
+function wrappedCreateReadStream(filePath, options) {
+    tryBrokerFileTokenSync('read', filePath);
+    return origCreateReadStream(filePath, options);
+}
+
+function wrappedCreateWriteStream(filePath, options) {
+    tryBrokerFileTokenSync('write', filePath);
+    return origCreateWriteStream(filePath, options);
+}
+
+// ----- brokered host operations（非删除类文件变更）-----
+
+function wrappedMkdirSync(filePath, options) {
+    if (tryBrokerHostOperationSync('mkdir', buildMkdirBrokerFields(filePath, options))) {
+        return undefined;
+    }
+    return origMkdirSync(filePath, options);
+}
+
+function wrappedMkdir(filePath, options, callback) {
+    let opts = options;
+    let cb = callback;
+    if (typeof options === 'function') {
+        opts = undefined;
+        cb = options;
+    }
+    if (typeof cb !== 'function') {
+        return origMkdir(filePath, options, callback);
+    }
+    tryBrokerHostOperation('mkdir', buildMkdirBrokerFields(filePath, opts))
+        .then(handled => {
+            if (handled) {
+                process.nextTick(() => cb(null));
+                return;
+            }
+            origMkdir(filePath, options, callback);
+        })
+        .catch(error => process.nextTick(() => cb(error)));
+    return undefined;
+}
+
+async function wrappedPromisesMkdir(filePath, options) {
+    if (await tryBrokerHostOperation('mkdir', buildMkdirBrokerFields(filePath, options))) {
+        return undefined;
+    }
+    return origPromisesMkdir(filePath, options);
+}
+
+function wrappedRenameSync(from, to) {
+    if (tryBrokerHostOperationSync('rename', { from: toAbsPath(from), to: toAbsPath(to) })) {
+        return undefined;
+    }
+    return origRenameSync(from, to);
+}
+
+function wrappedRename(from, to, callback) {
+    if (typeof callback !== 'function') {
+        return origRename(from, to, callback);
+    }
+    tryBrokerHostOperation('rename', { from: toAbsPath(from), to: toAbsPath(to) })
+        .then(handled => {
+            if (handled) {
+                process.nextTick(() => callback(null));
+                return;
+            }
+            origRename(from, to, callback);
+        })
+        .catch(error => process.nextTick(() => callback(error)));
+    return undefined;
+}
+
+async function wrappedPromisesRename(from, to) {
+    if (await tryBrokerHostOperation('rename', { from: toAbsPath(from), to: toAbsPath(to) })) {
+        return undefined;
+    }
+    return origPromisesRename(from, to);
+}
+
+function wrappedCopyFileSync(from, to, mode) {
+    if (shouldBrokerCopyFileMode(mode)
+        && tryBrokerHostOperationSync('copy', { from: toAbsPath(from), to: toAbsPath(to), recursive: false })) {
+        return undefined;
+    }
+    return origCopyFileSync(from, to, mode);
+}
+
+function wrappedCopyFile(from, to, mode, callback) {
+    let copyMode = mode;
+    let cb = callback;
+    if (typeof mode === 'function') {
+        copyMode = undefined;
+        cb = mode;
+    }
+    if (typeof cb !== 'function' || !shouldBrokerCopyFileMode(copyMode)) {
+        return origCopyFile(from, to, mode, callback);
+    }
+    tryBrokerHostOperation('copy', { from: toAbsPath(from), to: toAbsPath(to), recursive: false })
+        .then(handled => {
+            if (handled) {
+                process.nextTick(() => cb(null));
+                return;
+            }
+            origCopyFile(from, to, mode, callback);
+        })
+        .catch(error => process.nextTick(() => cb(error)));
+    return undefined;
+}
+
+async function wrappedPromisesCopyFile(from, to, mode) {
+    if (shouldBrokerCopyFileMode(mode)
+        && await tryBrokerHostOperation('copy', { from: toAbsPath(from), to: toAbsPath(to), recursive: false })) {
+        return undefined;
+    }
+    return origPromisesCopyFile(from, to, mode);
+}
+
+function wrappedCpSync(from, to, options) {
+    if (isSimpleCpOptions(options)
+        && tryBrokerHostOperationSync('copy', { from: toAbsPath(from), to: toAbsPath(to), recursive: !!(options && options.recursive) })) {
+        return undefined;
+    }
+    return origCpSync(from, to, options);
+}
+
+function wrappedCp(from, to, options, callback) {
+    let opts = options;
+    let cb = callback;
+    if (typeof options === 'function') {
+        opts = undefined;
+        cb = options;
+    }
+    if (typeof cb !== 'function' || !isSimpleCpOptions(opts)) {
+        return origCp(from, to, options, callback);
+    }
+    tryBrokerHostOperation('copy', { from: toAbsPath(from), to: toAbsPath(to), recursive: !!(opts && opts.recursive) })
+        .then(handled => {
+            if (handled) {
+                process.nextTick(() => cb(null));
+                return;
+            }
+            origCp(from, to, options, callback);
+        })
+        .catch(error => process.nextTick(() => cb(error)));
+    return undefined;
+}
+
+async function wrappedPromisesCp(from, to, options) {
+    if (isSimpleCpOptions(options)
+        && await tryBrokerHostOperation('copy', { from: toAbsPath(from), to: toAbsPath(to), recursive: !!(options && options.recursive) })) {
+        return undefined;
+    }
+    return origPromisesCp(from, to, options);
+}
+
+function wrappedChmodSync(filePath, mode) {
+    const normalizedMode = normalizeMode(mode);
+    if (normalizedMode !== undefined
+        && tryBrokerHostOperationSync('chmod', { path: toAbsPath(filePath), mode: normalizedMode })) {
+        return undefined;
+    }
+    return origChmodSync(filePath, mode);
+}
+
+function wrappedChmod(filePath, mode, callback) {
+    const normalizedMode = normalizeMode(mode);
+    if (typeof callback !== 'function' || normalizedMode === undefined) {
+        return origChmod(filePath, mode, callback);
+    }
+    tryBrokerHostOperation('chmod', { path: toAbsPath(filePath), mode: normalizedMode })
+        .then(handled => {
+            if (handled) {
+                process.nextTick(() => callback(null));
+                return;
+            }
+            origChmod(filePath, mode, callback);
+        })
+        .catch(error => process.nextTick(() => callback(error)));
+    return undefined;
+}
+
+async function wrappedPromisesChmod(filePath, mode) {
+    const normalizedMode = normalizeMode(mode);
+    if (normalizedMode !== undefined
+        && await tryBrokerHostOperation('chmod', { path: toAbsPath(filePath), mode: normalizedMode })) {
+        return undefined;
+    }
+    return origPromisesChmod(filePath, mode);
+}
+
+function wrappedLinkSync(from, to) {
+    if (tryBrokerHostOperationSync('link', { from: toAbsPath(from), to: toAbsPath(to), symbolic: false })) {
+        return undefined;
+    }
+    return origLinkSync(from, to);
+}
+
+function wrappedLink(from, to, callback) {
+    if (typeof callback !== 'function') {
+        return origLink(from, to, callback);
+    }
+    tryBrokerHostOperation('link', { from: toAbsPath(from), to: toAbsPath(to), symbolic: false })
+        .then(handled => {
+            if (handled) {
+                process.nextTick(() => callback(null));
+                return;
+            }
+            origLink(from, to, callback);
+        })
+        .catch(error => process.nextTick(() => callback(error)));
+    return undefined;
+}
+
+async function wrappedPromisesLink(from, to) {
+    if (await tryBrokerHostOperation('link', { from: toAbsPath(from), to: toAbsPath(to), symbolic: false })) {
+        return undefined;
+    }
+    return origPromisesLink(from, to);
+}
+
+function wrappedSymlinkSync(from, to, type) {
+    if (tryBrokerHostOperationSync('link', { from: String(from), to: toAbsPath(to), symbolic: true })) {
+        return undefined;
+    }
+    return origSymlinkSync(from, to, type);
+}
+
+function wrappedSymlink(from, to, type, callback) {
+    let linkType = type;
+    let cb = callback;
+    if (typeof type === 'function') {
+        linkType = undefined;
+        cb = type;
+    }
+    if (typeof cb !== 'function') {
+        return origSymlink(from, to, type, callback);
+    }
+    tryBrokerHostOperation('link', { from: String(from), to: toAbsPath(to), symbolic: true })
+        .then(handled => {
+            if (handled) {
+                process.nextTick(() => cb(null));
+                return;
+            }
+            origSymlink(from, to, linkType, cb);
+        })
+        .catch(error => process.nextTick(() => cb(error)));
+    return undefined;
+}
+
+async function wrappedPromisesSymlink(from, to, type) {
+    if (await tryBrokerHostOperation('link', { from: String(from), to: toAbsPath(to), symbolic: true })) {
+        return undefined;
+    }
+    return origPromisesSymlink(from, to, type);
+}
+
+
+// ---------------------------------------------------------------------------
+// 安装 brokered fs patch
+// ---------------------------------------------------------------------------
+
+fs.openSync = wrappedOpenSync;
+fs.readFileSync = wrappedReadFileSync;
+fs.writeFileSync = wrappedWriteFileSync;
+fs.appendFileSync = wrappedAppendFileSync;
+fs.createReadStream = wrappedCreateReadStream;
+fs.createWriteStream = wrappedCreateWriteStream;
+
+fs.open = wrappedOpen;
+fs.readFile = wrappedReadFile;
+fs.writeFile = wrappedWriteFile;
+fs.appendFile = wrappedAppendFile;
+fs.mkdirSync = wrappedMkdirSync;
+fs.renameSync = wrappedRenameSync;
+fs.copyFileSync = wrappedCopyFileSync;
+if (origCpSync) fs.cpSync = wrappedCpSync;
+fs.chmodSync = wrappedChmodSync;
+fs.linkSync = wrappedLinkSync;
+fs.symlinkSync = wrappedSymlinkSync;
+
+fs.mkdir = wrappedMkdir;
+fs.rename = wrappedRename;
+fs.copyFile = wrappedCopyFile;
+if (origCp) fs.cp = wrappedCp;
+fs.chmod = wrappedChmod;
+fs.link = wrappedLink;
+fs.symlink = wrappedSymlink;
+
+if (fs.promises) {
+    fs.promises.open = wrappedPromisesOpen;
+    fs.promises.readFile = wrappedPromisesReadFile;
+    fs.promises.writeFile = wrappedPromisesWriteFile;
+    fs.promises.appendFile = wrappedPromisesAppendFile;
+    fs.promises.mkdir = wrappedPromisesMkdir;
+    fs.promises.rename = wrappedPromisesRename;
+    fs.promises.copyFile = wrappedPromisesCopyFile;
+    if (origPromisesCp) fs.promises.cp = wrappedPromisesCp;
+    fs.promises.chmod = wrappedPromisesChmod;
+    fs.promises.link = wrappedPromisesLink;
+    fs.promises.symlink = wrappedPromisesSymlink;
+}
+
+try {
+    require('module').syncBuiltinESMExports?.();
+} catch (_) {
+    // Best-effort only. CommonJS fs patching above remains active.
+}