@ai-workbench/network 0.4.1 → 0.4.4

package/lib/network.d.ts

@@ -1,11 +1,12 @@
 import { control } from './control.ts';
 import type { PluginSettings, NetworkChannels, NetworkState } from './api.ts';
+import type { EmployeeRuntime } from './employee-endpoint.ts';
 export interface Executable {
     path: string;
     sha256: string;
     platform: string;
     arch: string;
 }
-export declare function createNetwork(settings: PluginSettings, executable: Executable, emit?: (state: NetworkState) => void, controlIO?: typeof control): NetworkChannels & {
+export declare function createNetwork(settings: PluginSettings, executable: Executable, emit?: (state: NetworkState) => void, controlIO?: typeof control): NetworkChannels & EmployeeRuntime & {
     start(): Promise<void>;
 };

package/lib/network.js

@@ -5,6 +5,9 @@ import { privateFile, verifyExecutable } from "./private.js";
 import { control, jsonResponse, firstFrame } from "./control.js";
 import { fail, ok } from "./api.js";
 import { downloadThroughProxy } from "./download.js";
+import { effectiveConfig, helperPolicyArgs, validHelperPolicy } from "./settings.js";
+import { ObservationExpired, observationNeed } from "./observation.js";
+import { readEmployeeProcess, employeeReady } from "./employee-endpoint.js";
 const seconds = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0.001 && v * 1000 <= 2147483647;
 const integer = (v) => Number.isSafeInteger(v) && Number(v) > 0;
 const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
@@ -39,10 +42,11 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
     let state = { phase: 'starting' }, cfg, child;
     let starting, disposing, disposed = false, online = false;
     let poll;
-    let processFailed = false, startupReceipt, terminalNeed, stoppingChild;
+    let processFailed = false, startupReceipt, terminalNeed, stoppingChild, shutdownNeed;
     const childGone = new AbortController();
     const lifetime = new AbortController(), listeners = new Set(), updates = new Set();
     const leases = new Set();
+    let employeeParent, employeeUmask;
     const snapshot = () => structuredClone(state);
     const publish = (next) => {
         state = next;
@@ -72,9 +76,10 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
         if (!owned?.pid || owned.exitCode !== null || owned.signalCode !== null)
             return false;
         const exit = new Promise(resolve => owned.once('exit', () => resolve()));
+        const started = performance.now();
         owned.kill('SIGTERM');
         let forced = false, timer;
-        await Promise.race([exit, new Promise(resolve => { timer = setTimeout(() => { forced = true; owned.kill('SIGKILL'); resolve(); }, settings.shutdownObservationSeconds * 1000); })]);
+        await Promise.race([exit, new Promise(resolve => { timer = setTimeout(() => { forced = true; shutdownNeed = observationNeed(new ObservationExpired('HELPER_SHUTDOWN_FORCED', 'shutdownObservationSeconds', settings.shutdownObservationSeconds, started, '自有网络组件正常退出', '检查组件退出日志；本次仅强制结束自有进程，不终止未知进程')); owned.kill('SIGKILL'); resolve(); }, settings.shutdownObservationSeconds * 1000); })]);
         if (timer)
             clearTimeout(timer);
         if (forced)
@@ -94,9 +99,14 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
             if (!disposed && alive())
                 publish({ phase: s.enrollment === 'online' && !s.error ? 'online' : s.error ? 'blocked' : 'starting', status: s, ...s.error ? { error: s.error } : {} });
         }
-        catch {
-            if (!disposed && alive())
-                block('CONTROL_UNAVAILABLE', '连接中断，正在等待网络组件恢复；根因未查明。', '等待恢复后自动重新连接；持续无响应时联系管理员');
+        catch (error) {
+            if (!disposed && alive()) {
+                const observed = observationNeed(error);
+                if (observed)
+                    publish({ phase: 'blocked', error: observed });
+                else
+                    block('CONTROL_UNAVAILABLE', '连接中断，正在等待网络组件恢复；根因未查明。', '检查组件私有日志、控制socket和当前网络；状态刷新不是修复，不重启或重交材料');
+            }
         }
         if (!disposed && alive())
             poll = setTimeout(() => void observe(), cfg.statusRefreshIntervalSeconds * 1000);
@@ -119,6 +129,9 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
             finally {
                 await file.close();
             }
+            if (!validHelperPolicy(settings))
+                throw new Error('CONFIG_INVALID');
+            cfg = effectiveConfig(cfg, settings);
             if (normalize(settings.helperLogFile) !== settings.helperLogFile || normalize(settings.configFile) !== settings.configFile)
                 throw new Error('CONFIG_INVALID');
             const canonical = async (p) => { try {
@@ -174,8 +187,20 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
                 await log.close();
                 return;
             }
+            const parent = readEmployeeProcess();
+            employeeParent = parent.ok ? parent.value : undefined;
+            const environment = { ...process.env };
+            delete environment.AW_NET_PARENT_PID;
+            delete environment.AW_NET_PARENT_SHELL;
+            delete environment.AW_NET_PARENT_UMASK;
+            if (employeeParent) {
+                employeeUmask = process.umask();
+                environment.AW_NET_PARENT_PID = String(process.pid);
+                environment.AW_NET_PARENT_SHELL = employeeParent.account.shell;
+                environment.AW_NET_PARENT_UMASK = String(employeeUmask);
+            }
             try {
-                child = spawn(executable.path, ['serve', '--config', settings.configFile], { stdio: ['ignore', 'pipe', log.fd], env: { ...process.env } });
+                child = spawn(executable.path, ['serve', '--config', settings.configFile, ...helperPolicyArgs(settings), '--controlResponseMaxBytes', String(settings.controlResponseMaxBytes)], { stdio: ['ignore', 'pipe', log.fd], env: environment });
             }
             catch (error) {
                 await log.close();
@@ -196,7 +221,8 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
             processChild.once('exit', exited);
             const ready = new Promise((resolve, reject) => {
                 let data = Buffer.alloc(0), settled = false;
-                const timer = setTimeout(() => finish(new Error('HELPER_STARTUP_EXPIRED')), settings.startupObservationSeconds * 1000);
+                const started = performance.now();
+                const timer = setTimeout(() => finish(new ObservationExpired('HELPER_STARTUP_EXPIRED', 'startupObservationSeconds', settings.startupObservationSeconds, started, '自有网络组件ready首帧', '检查组件私有日志、完整性与启动状态；保留身份，不重交开通材料')), settings.startupObservationSeconds * 1000);
                 const aborted = () => finish(new Error('DISPOSED'));
                 const earlyExit = () => finish(new Error('HELPER_EXITED'));
                 const errored = () => finish(new Error('HELPER_START_FAILED'));
@@ -258,10 +284,12 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
             if (disposed)
                 return;
             const code = error instanceof Error && /^(LOCAL_PERMISSION_DENIED|LOCAL_PATH_INVALID|HELPER_[A-Z_]+|CONTROL_[A-Z_]+|CONFIG_INVALID)$/.test(error.message) ? error.message : 'CONFIG_INVALID';
-            terminal(startupNeed ?? needs(code, '网络组件未能启动，根因未查明', '管理员检查安装配置、helper完整性和私有日志'));
+            terminal(startupNeed ?? observationNeed(error) ?? needs(code, '网络组件未能启动，根因未查明', '管理员检查安装配置、helper完整性和私有日志'));
             const forced = await stopOwned();
-            if (forced && terminalNeed)
-                terminalNeed.cause = '自有helper未在shutdownObservationSeconds内退出，已SIGKILL清理';
+            if (forced && terminalNeed) {
+                terminalNeed.cause = [terminalNeed.cause, shutdownNeed?.message, shutdownNeed?.needs].filter(Boolean).join('；');
+                publish({ ...state, error: terminalNeed });
+            }
         }
     })();
     const api = {
@@ -325,16 +353,57 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
                     return fail('DISPOSED', '登录代理已取消', '重新发起登录');
                 return ok(current);
             }
-            catch {
+            catch (error) {
                 owner.abort();
                 signal.removeEventListener('abort', cancel);
                 lifetime.signal.removeEventListener('abort', cancel);
                 childGone.signal.removeEventListener('abort', cancel);
+                diagnostic ??= observationNeed(error);
                 return diagnostic ? { ok: false, error: diagnostic } : fail('PROXY_UNAVAILABLE', '登录代理未能建立，根因未查明', '查看主机网络与信任材料');
             }
         },
         async download(source, signal) { const lease = await api.openLoginProxy(signal); if (!lease.ok)
             return lease; return downloadThroughProxy(source, lease.value, signal, settings.downloadMaxRedirects, cfg.dialTimeoutSeconds, cfg.httpMaxResponseHeaderBytes); },
+        async prepareEmployeeEndpoint(settingsPath, signal) {
+            if (disposed)
+                return fail('DISPOSED', '网络服务已停止。', '重新加载插件');
+            if (signal.aborted)
+                return fail('EMPLOYEE_ENDPOINT_PREPARE_CANCELLED', '员工端点准备等待已取消。', '派发前重新核验来源');
+            if (!cfg || state.phase !== 'online' || !alive())
+                return fail('NETWORK_NOT_READY', '远程主机尚未连接。', '等待原网络连接');
+            const actual = readEmployeeProcess();
+            if (!actual.ok)
+                return actual;
+            if (!employeeParent || employeeUmask !== process.umask() || JSON.stringify(employeeParent) !== JSON.stringify(actual.value))
+                return fail('EMPLOYEE_ENVIRONMENT_UNAVAILABLE', '客户端环境在组件启动后已变化。', '正常重载插件后重新核验，不替换账户或环境');
+            try {
+                const response = await controlIO(socket(), 'POST', '/v1/employee-endpoint', AbortSignal.any([signal, childGone.signal, lifetime.signal]), cfg.dialTimeoutSeconds, cfg.httpMaxHeaderBytes, { version: 1, settingsPath });
+                const value = await jsonResponse(response, settings.controlResponseMaxBytes);
+                if (response.statusCode !== 200) {
+                    const error = value?.error;
+                    if (value?.apiVersion !== 1 || !error || !employeeNeedCodes.has(error.code) || !['message', 'needs', 'actor'].every(k => typeof error[k] === 'string') || (error.cause !== null && error.cause !== undefined && typeof error.cause !== 'string'))
+                        return fail('EMPLOYEE_BRIDGE_PROTOCOL_INVALID', '员工端点控制响应无效。', '核对网络组件版本与合同');
+                    return { ok: false, error: { code: error.code, message: error.message, needs: error.needs, actor: 'network', cause: error.cause ?? null } };
+                }
+                if (value?.apiVersion !== 1 || Object.keys(value).sort().join() !== 'apiVersion,bridge,endpoint')
+                    return fail('EMPLOYEE_BRIDGE_PROTOCOL_INVALID', '员工端点控制帧无效。', '核对网络组件版本');
+                return employeeReady({ endpoint: value.endpoint, bridge: value.bridge }, actual.value, settingsPath);
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return fail('EMPLOYEE_ENDPOINT_PREPARE_CANCELLED', '员工端点准备等待已取消。', '重新核验后派发，不重放旧操作');
+                const observed = observationNeed(error);
+                return observed ? { ok: false, error: observed } : fail('EMPLOYEE_ENDPOINT_UNAVAILABLE', '员工端点控制连接失败，根因未查明。', '检查组件私有日志；普通网络状态不代表端点就绪');
+            }
+        },
+        async closeEmployeeEndpoint() {
+            if (!cfg || !alive())
+                return;
+            const response = await request('DELETE', '/v1/employee-endpoint', lifetime.signal);
+            const value = await jsonResponse(response, settings.controlResponseMaxBytes);
+            if (response.statusCode !== 200 || value?.apiVersion !== 1 || value?.closed !== true)
+                throw Error('EMPLOYEE_ENDPOINT_UNAVAILABLE');
+        },
         dispose() {
             return disposing ??= (async () => {
                 disposed = true;
@@ -346,7 +415,7 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
                 await starting;
                 await Promise.all([...leases].map(x => x.release()));
                 const forced = await stopOwned();
-                publish(forced ? { phase: 'blocked', error: needs('HELPER_SHUTDOWN_FORCED', '网络组件未在配置期限内退出，已终止自有进程', '管理员检查组件退出日志') } : { phase: 'stopped' });
+                publish(forced ? { phase: 'blocked', error: shutdownNeed } : { phase: 'stopped' });
                 listeners.clear();
                 updates.clear();
             })();
@@ -354,3 +423,4 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
     };
     return api;
 }
+const employeeNeedCodes = new Set(['EMPLOYEE_CONTEXT_UNAVAILABLE', 'EMPLOYEE_CONTEXT_INVALID', 'EMPLOYEE_CONTEXT_CHANGED', 'EMPLOYEE_ACCOUNT_UNAVAILABLE', 'EMPLOYEE_ENVIRONMENT_UNAVAILABLE', 'EMPLOYEE_IDENTITY_STATE_INVALID', 'EMPLOYEE_IDENTITY_ACCOUNT_MISMATCH', 'EMPLOYEE_IDENTITY_BUSY_OR_UNSAFE', 'EMPLOYEE_IDENTITY_CREATE_FAILED', 'EMPLOYEE_IDENTITY_STORAGE_FAILED', 'EMPLOYEE_BRIDGE_UNAVAILABLE', 'EMPLOYEE_BRIDGE_PROTOCOL_INVALID', 'EMPLOYEE_BRIDGE_FAILED', 'EMPLOYEE_ENDPOINT_UNAVAILABLE', 'EMPLOYEE_ENDPOINT_PREPARE_CANCELLED', 'HELPER_PLATFORM_UNSUPPORTED', 'HOST_TRUST_REQUIRED', 'HOST_KEY_MISMATCH', 'ENROLLMENT_MISMATCH', 'DIAL_OBSERVATION_EXPIRED', 'LOCAL_PERMISSION_DENIED', 'NETWORK_INTERRUPTED', 'SSH_FAILED', 'NETWORK_NOT_READY', 'DISPOSED']);

package/lib/observation.d.ts

@@ -0,0 +1,6 @@
+import type { Need } from './api.ts';
+export declare class ObservationExpired extends Error {
+    readonly need: Need;
+    constructor(code: string, setting: string, seconds: number, started: number, waitingFor: string, nextStep: string);
+}
+export declare function observationNeed(error: unknown): Need | undefined;

package/lib/observation.js

@@ -0,0 +1,14 @@
+// Only fixed stage descriptions and numeric timings enter public diagnostics.
+export class ObservationExpired extends Error {
+    need;
+    constructor(code, setting, seconds, started, waitingFor, nextStep) {
+        const elapsed = Math.max(0, (performance.now() - started) / 1000);
+        const message = `等待${waitingFor}，已等${elapsed.toFixed(3)}秒（${setting}=${seconds}秒），观察期限已到，根因未查明。`;
+        super(message + ' 下一步：' + nextStep);
+        this.name = 'ObservationExpired';
+        this.need = { code, message, needs: nextStep, actor: 'network', cause: JSON.stringify({ setting, configuredSeconds: seconds, elapsedSeconds: elapsed, waitingFor }) };
+    }
+}
+export function observationNeed(error) {
+    return error instanceof ObservationExpired ? structuredClone(error.need) : undefined;
+}

package/lib/packaged-helper.js

@@ -1,25 +1,29 @@
-import { createRequire } from 'node:module';
-import { readFileSync } from 'node:fs';
+import { readFileSync, lstatSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { fail, ok } from "./api.js";
 export function resolvePackagedHelper(moduleURL, platform = process.platform, arch = process.arch) {
+    if (platform !== 'darwin' || !['arm64', 'x64'].includes(arch))
+        return fail('HELPER_PLATFORM_UNSUPPORTED', `我需要支持 ${platform}-${arch} 的联网助手。`, '当前提供 macOS arm64 和 x64，请管理员核对设备平台');
     const name = `@ai-workbench/net-helper-${platform}-${arch}`;
     let expected;
     try {
         const root = JSON.parse(readFileSync(new URL('../package.json', moduleURL), 'utf8'));
-        expected = root.optionalDependencies?.[name];
-        if (expected === undefined)
-            return fail('HELPER_PLATFORM_UNSUPPORTED', `我需要支持 ${platform}-${arch} 的联网助手包。`, '当前提供 macOS arm64 和 x64 平台包，请管理员核对设备平台');
-        if (expected !== root.version)
-            throw new Error('平台助手依赖必须与主包版本精确一致');
-        const require = createRequire(moduleURL), metadata = JSON.parse(readFileSync(require.resolve(name + '/package.json'), 'utf8'));
-        if (metadata.name !== name || metadata.version !== expected || JSON.stringify(metadata.os) !== JSON.stringify([platform]) || JSON.stringify(metadata.cpu) !== JSON.stringify([arch]))
-            throw new Error('平台助手包的名称、版本或平台不匹配');
-        const manifest = JSON.parse(readFileSync(require.resolve(name + '/helper-manifest.json'), 'utf8'));
+        expected = root.version;
+        if (root.name !== '@ai-workbench/network' || typeof expected !== 'string' || !expected)
+            throw new Error('network主包的名称或版本无效');
+        const dir = new URL(`../helpers/${platform}-${arch}/`, moduleURL);
+        const metadata = JSON.parse(readFileSync(new URL('package.json', dir), 'utf8'));
+        if (metadata.name !== name || metadata.version !== expected || metadata.private !== true || JSON.stringify(metadata.os) !== JSON.stringify([platform]) || JSON.stringify(metadata.cpu) !== JSON.stringify([arch]))
+            throw new Error('内嵌助手的名称、版本或平台不匹配');
+        const manifest = JSON.parse(readFileSync(new URL('helper-manifest.json', dir), 'utf8'));
         if (manifest.platform !== platform || manifest.arch !== arch || typeof manifest.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(manifest.sha256))
-            throw new Error('平台助手 manifest 的架构或摘要无效');
-        return ok({ path: require.resolve(name + '/bin/aw-net'), sha256: manifest.sha256, platform, arch });
+            throw new Error('内嵌助手 manifest 的架构或摘要无效');
+        const path = fileURLToPath(new URL('bin/aw-net', dir)), st = lstatSync(path);
+        if (!st.isFile() || st.isSymbolicLink())
+            throw new Error('内嵌助手不是普通二进制文件');
+        return ok({ path, sha256: manifest.sha256, platform, arch });
     }
     catch (cause) {
-        return { ok: false, error: { code: 'HELPER_NOT_PACKAGED', message: '我需要完整的当前平台联网助手包。', needs: `请管理员安装 ${name}${expected ? '@' + expected : '（与主包同版本）'}；不要切换架构或改用旧助手`, actor: 'network', cause: cause instanceof Error ? cause.message : String(cause) } };
+        return { ok: false, error: { code: 'HELPER_NOT_PACKAGED', message: '我需要完整的当前版本远程主机网络插件。', needs: `请管理员重新安装 @ai-workbench/network${expected ? '@' + expected : ''} 的完整包；不要切换架构或改用旧助手`, actor: 'network', cause: cause instanceof Error ? cause.message : String(cause) } };
     }
 }

package/lib/settings.d.ts

@@ -0,0 +1,10 @@
+import type { PluginSettings, HelperConfig } from './api.ts';
+export declare const helperPolicyFields: readonly ["statusRefreshIntervalSeconds", "dialTimeoutSeconds", "headerTimeoutSeconds", "enrollmentObservationSeconds", "httpMaxHeaderBytes", "httpMaxResponseHeaderBytes"];
+export declare const pluginPolicyFields: readonly ["startupObservationSeconds", "shutdownObservationSeconds", "controlResponseMaxBytes", "downloadMaxRedirects"];
+export declare const settingsFields: readonly ["configFile", "helperLogFile", "startupObservationSeconds", "shutdownObservationSeconds", "controlResponseMaxBytes", "downloadMaxRedirects", "statusRefreshIntervalSeconds", "dialTimeoutSeconds", "headerTimeoutSeconds", "enrollmentObservationSeconds", "httpMaxHeaderBytes", "httpMaxResponseHeaderBytes"];
+export declare const timerSeconds: (v: unknown) => v is number;
+export declare const positiveInteger: (v: unknown) => v is number;
+export declare function validHelperPolicy(settings: PluginSettings): boolean;
+export declare function mergedSettings(initial: PluginSettings, provided: PluginSettings): PluginSettings;
+export declare function effectiveConfig(config: HelperConfig, settings: PluginSettings): HelperConfig;
+export declare function helperPolicyArgs(settings: PluginSettings): string[];

package/lib/settings.js

@@ -0,0 +1,34 @@
+export const helperPolicyFields = ['statusRefreshIntervalSeconds', 'dialTimeoutSeconds', 'headerTimeoutSeconds', 'enrollmentObservationSeconds', 'httpMaxHeaderBytes', 'httpMaxResponseHeaderBytes'];
+export const pluginPolicyFields = ['startupObservationSeconds', 'shutdownObservationSeconds', 'controlResponseMaxBytes', 'downloadMaxRedirects'];
+export const settingsFields = ['configFile', 'helperLogFile', ...pluginPolicyFields, ...helperPolicyFields];
+export const timerSeconds = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0.001 && v * 1000 <= 2147483647;
+export const positiveInteger = (v) => Number.isSafeInteger(v) && Number(v) > 0;
+export function validHelperPolicy(settings) {
+    return helperPolicyFields.every(key => {
+        const v = settings[key];
+        if (v === undefined)
+            return true;
+        if (key === 'httpMaxHeaderBytes' || key === 'httpMaxResponseHeaderBytes')
+            return positiveInteger(v);
+        if (key === 'dialTimeoutSeconds' || key === 'statusRefreshIntervalSeconds')
+            return timerSeconds(v);
+        return typeof v === 'number' && Number.isFinite(v) && v >= 1e-9 && v < 9223372036.854775;
+    });
+}
+export function mergedSettings(initial, provided) {
+    const merged = { ...provided };
+    for (const key of [...pluginPolicyFields, ...helperPolicyFields])
+        if (initial[key] !== undefined)
+            merged[key] = initial[key];
+    return merged;
+}
+export function effectiveConfig(config, settings) {
+    const result = { ...config };
+    for (const key of helperPolicyFields)
+        if (settings[key] !== undefined)
+            result[key] = settings[key];
+    return result;
+}
+export function helperPolicyArgs(settings) {
+    return helperPolicyFields.flatMap(key => settings[key] === undefined ? [] : ['--' + key, String(settings[key])]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-workbench/network",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "type": "module",
   "engines": {
     "node": ">=24.13.1"
@@ -25,7 +25,8 @@
     "lib",
     "NOTICE.md",
     "cordis.patch.yml",
-    "locale"
+    "locale",
+    "helpers"
   ],
   "dsh": {
     "bundle": {
@@ -55,10 +56,6 @@
     "dsh-plugin",
     "deepseek-harness"
   ],
-  "optionalDependencies": {
-    "@ai-workbench/net-helper-darwin-arm64": "0.4.1",
-    "@ai-workbench/net-helper-darwin-x64": "0.4.1"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/yzsnstotz/ai-workbench-network.git"