@ai-workbench/network 0.4.1 → 0.4.4

package/helpers/darwin-x64/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@ai-workbench/net-helper-darwin-x64",
+  "version": "0.4.4",
+  "description": "远程主机网络助手（macOS x64，仅随network主包内嵌分发）",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yzsnstotz/ai-workbench-network.git"
+  },
+  "private": true
+}

package/lib/activation.d.ts

@@ -1,6 +1,8 @@
 import { createNetwork } from './network.ts';
 import type { Executable } from './network.ts';
 import type { NetworkApi, NetworkState, PluginSettings } from './api.ts';
-export declare function createActivationService(initial: PluginSettings, executable: Executable, emit?: (s: NetworkState) => void, factory?: typeof createNetwork): NetworkApi & {
+import type { EmployeeConnectSource } from './employee-endpoint.ts';
+export declare function createActivationService(initial: PluginSettings, executable: Executable, emit?: (s: NetworkState) => void, factory?: typeof createNetwork, getConnect?: () => EmployeeConnectSource | undefined): NetworkApi & {
     start(): Promise<void>;
+    refreshEmployeeSource(): void;
 };

package/lib/activation.js

@@ -2,7 +2,8 @@ import { randomUUID } from 'node:crypto';
 import { isAbsolute } from 'node:path';
 import { createNetwork } from "./network.js";
 import { fail, ok } from "./api.js";
-const fields = ['configFile', 'helperLogFile', 'startupObservationSeconds', 'shutdownObservationSeconds', 'controlResponseMaxBytes', 'downloadMaxRedirects'];
+import { settingsFields as fields, validHelperPolicy, mergedSettings } from "./settings.js";
+import { createEmployeeEndpointController } from "./employee-endpoint.js";
 function normalized(s) {
     if (!s || typeof s !== 'object' || Object.keys(s).some(k => !fields.includes(k)))
         return;
@@ -13,15 +14,18 @@ function normalized(s) {
             return;
     if (!Number.isSafeInteger(s.controlResponseMaxBytes) || s.controlResponseMaxBytes <= 0 || !Number.isSafeInteger(s.downloadMaxRedirects) || s.downloadMaxRedirects < 0)
         return;
-    return Object.fromEntries(fields.map(k => [k, s[k]]));
+    if (!validHelperPolicy(s))
+        return;
+    return Object.fromEntries(fields.filter(k => s[k] !== undefined).map(k => [k, s[k]]));
 }
 // One stable Cordis service; callers never own, restart or borrow helper processes.
-export function createActivationService(initial, executable, emit = () => { }, factory = createNetwork) {
+export function createActivationService(initial, executable, emit = () => { }, factory = createNetwork, getConnect = () => undefined) {
     let network = { phase: 'blocked', error: { code: 'SETTINGS_REQUIRED', message: '我需要导入连接资料。', needs: '在设置 → 远程主机连接 导入连接资料', actor: 'network' } };
     let activation = { instanceId: randomUUID(), revision: 0, phase: 'unconfigured', receipt: null, error: network.error };
     let runtime, selected, disposed = false, disposing, handoff, generation = 0, handedOff = false, consumerOnline = false;
     const listeners = new Set(), edges = new Set(), updates = new Set();
     const snapshot = () => structuredClone(activation);
+    const employee = createEmployeeEndpointController({ getConnect, getRuntime: () => activation.phase === 'active' ? runtime : undefined, getState: () => network, connect: (target, signal) => api.connect(target, signal) });
     function publish(phase, error, receipt = activation.receipt) {
         activation = { ...activation, revision: activation.revision + 1, phase, error, receipt };
         for (const listener of listeners)
@@ -80,6 +84,8 @@ export function createActivationService(initial, executable, emit = () => { }, f
             return;
         const was = consumerOnline;
         consumerOnline = ready && next.phase === 'online';
+        if (was && !consumerOnline)
+            employee.networkLost();
         if (was !== consumerOnline)
             for (const listener of edges)
                 try {
@@ -103,8 +109,9 @@ export function createActivationService(initial, executable, emit = () => { }, f
             observed({ phase: 'blocked', error: { code: 'HELPER_START_FAILED', message: '网络组件未能启动，根因未查明。', needs: '管理员检查私有日志', actor: 'network' } }); });
     }
     const api = {
+        prepareEmployeeEndpoint: employee.prepare, refreshEmployeeSource: employee.refreshSource,
         async start() { if (disposed)
-            return; if (Object.keys(initial).length)
+            return; if (initial.configFile || initial.helperLogFile)
             await api.activate(initial, new AbortController().signal);
         else
             emit(structuredClone(network)); },
@@ -114,9 +121,9 @@ export function createActivationService(initial, executable, emit = () => { }, f
         async activate(settings, signal) {
             if (disposed || signal.aborted)
                 return fail('ACTIVATION_CANCELLED', '连接激活等待已取消。', '查询当前激活结果；不要重复提交密钥');
-            const config = normalized(settings);
+            const config = normalized(mergedSettings(initial, settings));
             if (!config)
-                return fail('SETTINGS_REQUIRED', '我需要有效的连接配置。', 'L提供六项具名网络设置');
+                return fail('SETTINGS_REQUIRED', '我需要有效的连接配置。', '管理员核对网络插件具名设置及已导入的连接资料');
             const key = JSON.stringify(config);
             if (selected !== undefined && selected !== key)
                 return fail('ACTIVATION_CONFLICT', '已有连接激活，不能替换身份。', '管理员核对当前开通上下文');
@@ -145,7 +152,19 @@ export function createActivationService(initial, executable, emit = () => { }, f
         async download(source, signal) { if (disposed)
             return fail('DISPOSED', '网络服务已停止。', '重新加载插件'); return activation.phase === 'active' && runtime ? runtime.download(source, signal) : { ok: false, error: network.error ?? { code: 'NETWORK_NOT_READY', message: '连接尚未就绪。', needs: '等待N身份交接完成', actor: 'network' } }; },
         dispose() { if (disposing)
-            return disposing; disposed = true; return disposing = Promise.resolve().then(async () => { publish('stopped', activation.error); await runtime?.dispose(); await handoff; network = runtime?.getState() ?? { phase: 'stopped' }; emit(structuredClone(network)); publish('stopped', network.error ?? null); listeners.clear(); edges.clear(); updates.clear(); }); },
+            return disposing; disposed = true; return disposing = Promise.resolve().then(async () => { publish('stopped', activation.error); try {
+            await employee.dispose();
+        }
+        finally {
+            await runtime?.dispose();
+            await handoff;
+            network = runtime?.getState() ?? { phase: 'stopped' };
+            emit(structuredClone(network));
+            publish('stopped', network.error ?? null);
+            listeners.clear();
+            edges.clear();
+            updates.clear();
+        } }); },
     };
     return api;
 }

package/lib/api.d.ts

@@ -69,10 +69,49 @@ export interface ActivationState {
     error: Need | null;
 }
 export interface NetworkApi extends NetworkChannels {
+    prepareEmployeeEndpoint(request: EmployeeEndpointRequest, signal: AbortSignal): Promise<Result<EmployeeEndpointTarget>>;
     activate(settings: PluginSettings, signal: AbortSignal): Promise<Result<ActivationState>>;
     getActivationState(): ActivationState;
     onActivationState(listener: (state: ActivationState) => void): () => void;
 }
+export interface EmployeeEndpointRequest {
+    instanceId: string;
+    epoch: number;
+    workspaceId: string;
+    expectedBindingId: string;
+}
+export interface EmployeeEndpointTarget {
+    version: 1;
+    local: {
+        instanceId: string;
+        epoch: number;
+        workspaceId: string;
+        bindingId: string;
+        directory: {
+            path: string;
+            device: number;
+            inode: number;
+        };
+    };
+    endpoint: {
+        deviceId: string;
+        endpointInstanceId: string;
+        executionContextId: string;
+        remoteUser: string;
+        remoteUid: number;
+        remoteHome: string;
+        endpointCwd: string;
+        endpointShell: string;
+    };
+    bridge: {
+        protocolVersion: 1;
+        command: '/usr/local/aw-host/bin/aw-employee-bridge';
+        settingsPath: string;
+        bridgeInstanceId: string;
+        generation: number;
+    };
+}
+export type EmployeeEndpointReady = Pick<EmployeeEndpointTarget, 'endpoint' | 'bridge'>;
 export interface NetworkChannels {
     getState(): NetworkState;
     connect(target: EnrollmentTarget, signal: AbortSignal): Promise<Result<{
@@ -90,6 +129,12 @@ export interface PluginSettings {
     shutdownObservationSeconds?: number;
     controlResponseMaxBytes?: number;
     downloadMaxRedirects?: number;
+    statusRefreshIntervalSeconds?: number;
+    dialTimeoutSeconds?: number;
+    headerTimeoutSeconds?: number;
+    enrollmentObservationSeconds?: number;
+    httpMaxHeaderBytes?: number;
+    httpMaxResponseHeaderBytes?: number;
 }
 export interface HelperConfig {
     apiVersion: 1;

package/lib/control.d.ts

@@ -1,4 +1,4 @@
 import type { IncomingMessage } from 'node:http';
-export declare function control(socket: string, method: string, path: string, signal: AbortSignal, seconds: number, maxHeaderBytes: number): Promise<IncomingMessage>;
+export declare function control(socket: string, method: string, path: string, signal: AbortSignal, seconds: number, maxHeaderBytes: number, body?: unknown): Promise<IncomingMessage>;
 export declare function jsonResponse(response: IncomingMessage, maxBytes: number): Promise<unknown>;
 export declare function firstFrame(response: IncomingMessage, maxBytes: number): Promise<unknown>;

package/lib/control.js

@@ -1,13 +1,22 @@
 import http from 'node:http';
 import { privateSocket } from "./private.js";
-export async function control(socket, method, path, signal, seconds, maxHeaderBytes) {
+import { ObservationExpired } from "./observation.js";
+export async function control(socket, method, path, signal, seconds, maxHeaderBytes, body) {
     await privateSocket(socket);
     signal.throwIfAborted();
     return new Promise((resolve, reject) => {
         const req = http.request({ socketPath: socket, method, path, agent: false, signal, maxHeaderSize: maxHeaderBytes }, res => { req.setTimeout(0); resolve(res); });
-        req.setTimeout(seconds * 1000, () => req.destroy(new Error('CONTROL_OBSERVATION_EXPIRED')));
+        const started = performance.now();
+        req.setTimeout(seconds * 1000, () => req.destroy(new ObservationExpired('CONTROL_OBSERVATION_EXPIRED', 'dialTimeoutSeconds', seconds, started, path === '/v1/status' ? '网络组件状态响应头' : '本机控制响应头', '检查自有组件私有日志、控制socket和当前网络状态；不要重交开通材料')));
         req.on('error', reject);
-        req.end();
+        if (body === undefined)
+            req.end();
+        else {
+            const data = JSON.stringify(body);
+            req.setHeader('Content-Type', 'application/json');
+            req.setHeader('Content-Length', Buffer.byteLength(data));
+            req.end(data);
+        }
     });
 }
 export async function jsonResponse(response, maxBytes) {

package/lib/download.js

@@ -4,6 +4,7 @@ import tls from 'node:tls';
 import { isIP } from 'node:net';
 import { Readable } from 'node:stream';
 import { fail, ok } from "./api.js";
+import { ObservationExpired, observationNeed } from "./observation.js";
 function sourceURL(source) { const u = new URL(source); if (u.protocol !== 'https:' || u.username || u.password)
     throw new Error('DOWNLOAD_SOURCE_INVALID'); return u; }
 async function requestViaProxy(target, lease, signal, seconds, maxHeaderBytes) {
@@ -14,7 +15,8 @@ async function requestViaProxy(target, lease, signal, seconds, maxHeaderBytes) {
     const authority = (isIP(hostname) === 6 ? '[' + hostname + ']' : hostname) + ':' + (target.port || '443');
     const tunnel = await new Promise((resolve, reject) => {
         const req = http.request({ hostname: proxy.hostname, port: proxy.port, method: 'CONNECT', path: authority, agent: false, signal, maxHeaderSize: maxHeaderBytes, headers: { 'Proxy-Authorization': 'Basic ' + Buffer.from(lease.credentials.username + ':' + lease.credentials.password).toString('base64') } });
-        req.setTimeout(seconds * 1000, () => req.destroy(new Error('DOWNLOAD_CONNECT_EXPIRED')));
+        const started = performance.now();
+        req.setTimeout(seconds * 1000, () => req.destroy(new ObservationExpired('DOWNLOAD_CONNECT_EXPIRED', 'dialTimeoutSeconds', seconds, started, '主机代理CONNECT响应头', '检查网络组件私有日志、主机SSH状态及代理握手；不重试或改走本机出口')));
         req.on('connect', (response, socket, head) => { req.setTimeout(0); if (response.statusCode !== 200) {
             socket.destroy();
             reject(new Error('HOST_PROXY_REJECTED'));
@@ -31,7 +33,8 @@ async function requestViaProxy(target, lease, signal, seconds, maxHeaderBytes) {
     try {
         return await new Promise((resolve, reject) => {
             const req = https.request(target, { agent, signal, maxHeaderSize: maxHeaderBytes }, response => { req.setTimeout(0); response.once('close', () => agent.destroy()); resolve(response); });
-            req.setTimeout(seconds * 1000, () => req.destroy(new Error('DOWNLOAD_HEADERS_EXPIRED')));
+            const started = performance.now();
+            req.setTimeout(seconds * 1000, () => req.destroy(new ObservationExpired('DOWNLOAD_HEADERS_EXPIRED', 'dialTimeoutSeconds', seconds, started, '经主机下载的TLS握手及HTTP响应头', '检查主机出口、TLS与下载源响应；不重试或静默换源')));
             req.on('error', reject);
             req.end();
         });
@@ -116,6 +119,9 @@ export async function downloadThroughProxy(source, lease, signal, maxRedirects,
     }
     catch (error) {
         await lease.release();
+        const observed = observationNeed(error);
+        if (observed)
+            return { ok: false, error: observed };
         const code = error instanceof Error && ['DOWNLOAD_REDIRECT_LIMIT', 'DOWNLOAD_SOURCE_INVALID'].includes(error.message) ? error.message : 'HOST_DOWNLOAD_FAILED';
         return fail(code, '经主机下载失败，根因未查明', '检查主机出口、下载源和具名重定向上限；无本机直出替代');
     }

package/lib/employee-endpoint.d.ts

@@ -0,0 +1,102 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { EmployeeEndpointRequest, EmployeeEndpointTarget, EmployeeEndpointReady, EnrollmentTarget, NetworkState, Result } from './api.ts';
+export interface EmployeeProcess {
+    pid: number;
+    ppid: number;
+    platform: string;
+    arch: string;
+    executable: string;
+    realUid: number;
+    effectiveUid: number;
+    realGid: number;
+    effectiveGid: number;
+    account: {
+        name: string;
+        home: string;
+        shell: string | null;
+    };
+    environment: {
+        HOME: string | null;
+        PATH: string | null;
+        SHELL: string | null;
+    };
+}
+interface LocalContext {
+    instanceId: string;
+    epoch: number;
+    workspaceId: string;
+    version: 1;
+    bindingId: string;
+    source: 'local';
+    provenance: 'official-workspace-registry';
+    directory: {
+        path: string;
+        device: number;
+        inode: number;
+    };
+    process: EmployeeProcess;
+}
+interface LocationState {
+    instanceId: string;
+    epoch: number;
+    phase: string;
+    items: {
+        workspaceId: string;
+        bindingId: string | null;
+        source: string | null;
+        status: string;
+    }[];
+}
+interface Connection {
+    instanceId: string;
+    epoch: number;
+    phase: string;
+}
+interface SshTarget extends EnrollmentTarget {
+    session: {
+        settingsPath: string;
+        protocolVersion: 1;
+    };
+}
+type ForeignResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: unknown;
+};
+export interface EmployeeConnectSource {
+    getContractInfo(): {
+        localWorkspaceContext?: number;
+    };
+    getLocalWorkspaceContext?(request: EmployeeEndpointRequest): Promise<ForeignResult<LocalContext>>;
+    getWorkspaceLocationState?(): LocationState;
+    onWorkspaceLocationState?(listener: (state: LocationState) => void): () => void;
+    getConnectionState(): Connection;
+    onConnectionState(listener: (state: Connection) => void): () => void;
+    getSshTarget(): Promise<ForeignResult<SshTarget>>;
+}
+export interface EmployeeRuntime {
+    prepareEmployeeEndpoint(settingsPath: string, signal: AbortSignal): Promise<Result<EmployeeEndpointReady>>;
+    closeEmployeeEndpoint(): Promise<void>;
+}
+interface Dependencies {
+    getConnect(): EmployeeConnectSource | undefined;
+    getRuntime(): EmployeeRuntime | undefined;
+    getState(): NetworkState;
+    connect(target: EnrollmentTarget, signal: AbortSignal): Promise<Result<{
+        proxyCommand: string;
+    }>>;
+}
+export declare function readEmployeeProcess(): Result<EmployeeProcess>;
+export declare function employeeReady(value: unknown, p: EmployeeProcess, settingsPath: string): Result<EmployeeEndpointReady>;
+export declare function bindEmployeeSourceLifecycle(ctx: Context, controller: {
+    refreshSource(): void;
+}): void;
+export declare function createEmployeeEndpointController(d: Dependencies): {
+    prepare: (r: EmployeeEndpointRequest, signal: AbortSignal) => Promise<Result<EmployeeEndpointTarget>>;
+    refreshSource: () => void;
+    networkLost: () => void;
+    dispose(): Promise<void>;
+};
+export {};

package/lib/employee-endpoint.js

@@ -0,0 +1,230 @@
+import { userInfo } from 'node:os';
+import { isAbsolute, normalize } from 'node:path';
+import { realpath, stat } from 'node:fs/promises';
+import { isDeepStrictEqual } from 'node:util';
+import { fail, ok } from "./api.js";
+const absolute = (v) => typeof v === 'string' && isAbsolute(v) && normalize(v) === v && !/[\0\r\n]/.test(v);
+const nonempty = (v) => typeof v === 'string' && v.length > 0 && !/[\0\r\n]/.test(v);
+const uuid = (v) => typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(v);
+const same = isDeepStrictEqual;
+function shape(v) {
+    const s = v;
+    return !!s && ['getContractInfo', 'getLocalWorkspaceContext', 'getWorkspaceLocationState', 'onWorkspaceLocationState', 'getConnectionState', 'onConnectionState', 'getSshTarget'].every(k => typeof s[k] === 'function') && s.getContractInfo()?.localWorkspaceContext === 1;
+}
+export function readEmployeeProcess() {
+    try {
+        if (process.platform !== 'darwin' || !process.getuid || !process.geteuid || !process.getgid || !process.getegid)
+            return fail('HELPER_PLATFORM_UNSUPPORTED', '当前系统不能提供员工端点。', '使用受支持的Mac客户端');
+        const account = userInfo(), uid = process.getuid(), euid = process.geteuid(), gid = process.getgid(), egid = process.getegid();
+        if (uid < 1 || uid > 4294967294 || uid !== euid || gid !== egid || account.uid !== euid || !nonempty(account.username) || !absolute(account.homedir) || !absolute(account.shell))
+            return fail('EMPLOYEE_ACCOUNT_UNAVAILABLE', '我需要当前员工的真实系统账户与shell。', '核对官方客户端的同用户进程环境');
+        return ok({ pid: process.pid, ppid: process.ppid, platform: process.platform, arch: process.arch, executable: process.execPath, realUid: uid, effectiveUid: euid, realGid: gid, effectiveGid: egid, account: { name: account.username, home: account.homedir, shell: account.shell }, environment: { HOME: process.env.HOME ?? null, PATH: process.env.PATH ?? null, SHELL: process.env.SHELL ?? null } });
+    }
+    catch {
+        return fail('EMPLOYEE_ACCOUNT_UNAVAILABLE', '员工账户信息暂不可用。', '核对官方客户端进程环境');
+    }
+}
+function requestValid(r) {
+    return !!r && Object.keys(r).length === 4 && ['instanceId', 'workspaceId', 'expectedBindingId'].every(k => nonempty(r[k])) && Number.isSafeInteger(r.epoch) && r.epoch >= 0;
+}
+export function employeeReady(value, p, settingsPath) {
+    const v = value, e = v?.endpoint, b = v?.bridge;
+    if (!e || !b || Object.keys(v).sort().join() !== 'bridge,endpoint' || Object.keys(e).sort().join() !== 'deviceId,endpointCwd,endpointInstanceId,endpointShell,executionContextId,remoteHome,remoteUid,remoteUser' || Object.keys(b).sort().join() !== 'bridgeInstanceId,command,generation,protocolVersion,settingsPath' || !/^[0-9a-f]{64}$/.test(e.deviceId) || !uuid(e.endpointInstanceId) || !uuid(e.executionContextId) || e.remoteUid !== p.effectiveUid || e.remoteUser !== p.account.name || e.remoteHome !== p.account.home || e.endpointCwd !== p.account.home || e.endpointShell !== p.account.shell || b.protocolVersion !== 1 || b.command !== '/usr/local/aw-host/bin/aw-employee-bridge' || b.settingsPath !== settingsPath || !uuid(b.bridgeInstanceId) || !Number.isSafeInteger(b.generation) || b.generation < 1)
+        return fail('EMPLOYEE_BRIDGE_PROTOCOL_INVALID', '员工端点返回的身份或代际不符。', '检查同一员工端点与主机桥合同');
+    return ok(structuredClone(v));
+}
+const cancelled = () => fail('EMPLOYEE_ENDPOINT_PREPARE_CANCELLED', '员工端点准备等待已取消。', '再次派发前重新核验当前来源；不要重放旧操作');
+// L can withdraw an optional getter while its ordinary service object remains.
+// Observe the public Cordis service lifecycle, including dependency disposal in
+// the same turn; no polling timer, dependency on L startup, or command retry.
+export function bindEmployeeSourceLifecycle(ctx, controller) {
+    let disposed = false, scheduled;
+    ctx.on('internal/service', () => {
+        controller.refreshSource();
+        scheduled ??= setImmediate(() => { scheduled = undefined; if (!disposed)
+            controller.refreshSource(); });
+    });
+    ctx.effect(() => () => { disposed = true; if (scheduled)
+        clearImmediate(scheduled); });
+    controller.refreshSource();
+}
+export function createEmployeeEndpointController(d) {
+    let source, disposed = false, revision = 0, held;
+    let unsubscribers = [], lifetime = new AbortController(), closing = Promise.resolve(), closeFailed = false;
+    let pending;
+    const detached = () => { for (const off of unsubscribers)
+        off(); unsubscribers = []; };
+    function invalidate() {
+        revision++;
+        lifetime.abort();
+        lifetime = new AbortController();
+        pending = undefined;
+        const old = held;
+        held = undefined;
+        if (old)
+            closing = closing.then(() => old.closeEmployeeEndpoint()).catch(() => { closeFailed = true; console.error('EMPLOYEE_ENDPOINT_CLOSE_FAILED'); });
+    }
+    function localRemains() {
+        const s = source?.getWorkspaceLocationState?.();
+        return !!s && s.phase === 'ready' && s.items.some(i => i.source === 'local' && i.status === 'selected' && nonempty(i.bindingId));
+    }
+    function refreshSource() {
+        if (disposed)
+            return;
+        let current;
+        try {
+            const value = d.getConnect();
+            if (shape(value))
+                current = value;
+        }
+        catch {
+            current = undefined;
+        }
+        if (current === source) {
+            try {
+                if (source && !localRemains())
+                    invalidate();
+            }
+            catch {
+                invalidate();
+            }
+            return;
+        }
+        detached();
+        invalidate();
+        source = current;
+        if (!source)
+            return;
+        try {
+            const own = source;
+            let connection = own.getConnectionState();
+            unsubscribers.push(own.onWorkspaceLocationState(() => { if (source === own) {
+                try {
+                    if (!localRemains())
+                        invalidate();
+                }
+                catch {
+                    invalidate();
+                }
+            } }));
+            unsubscribers.push(own.onConnectionState(next => { if (source !== own)
+                return; const changed = next.phase !== 'connected' || next.instanceId !== connection.instanceId || next.epoch !== connection.epoch; connection = next; if (changed)
+                invalidate(); }));
+        }
+        catch {
+            detached();
+            invalidate();
+            source = undefined;
+        }
+    }
+    async function read(r, s) {
+        try {
+            if (d.getConnect() !== s || !shape(s))
+                return fail('EMPLOYEE_CONTEXT_UNAVAILABLE', '本地工作区上下文已撤回。', '等待当前连接组件提供上下文');
+            const connection = s.getConnectionState(), locations = s.getWorkspaceLocationState();
+            if (connection.instanceId !== r.instanceId || connection.epoch !== r.epoch || connection.phase !== 'connected' || locations.instanceId !== r.instanceId || locations.epoch !== r.epoch || locations.phase !== 'ready' || !locations.items.some(i => i.workspaceId === r.workspaceId && i.bindingId === r.expectedBindingId && i.source === 'local' && i.status === 'selected'))
+                return fail('EMPLOYEE_CONTEXT_CHANGED', '工作区来源或绑定已变化。', '使用当前工作区重新派发');
+            const result = await s.getLocalWorkspaceContext(r);
+            if (!result.ok)
+                return fail('EMPLOYEE_CONTEXT_UNAVAILABLE', '本地工作区上下文暂不可用。', '检查当前工作区来源与目录状态');
+            const c = result.value, actual = readEmployeeProcess();
+            if (!actual.ok)
+                return actual;
+            if (c?.version !== 1 || c.instanceId !== r.instanceId || c.epoch !== r.epoch || c.workspaceId !== r.workspaceId || c.bindingId !== r.expectedBindingId || c.source !== 'local' || c.provenance !== 'official-workspace-registry' || !c.directory || !absolute(c.directory.path) || !Number.isSafeInteger(c.directory.device) || !Number.isSafeInteger(c.directory.inode) || !same(c.process, actual.value))
+                return fail('EMPLOYEE_CONTEXT_INVALID', '工作区上下文与当前客户端进程不一致。', '重新核对同一客户端的来源与账户');
+            const canonical = await realpath(c.directory.path), st = await stat(canonical);
+            if (canonical !== c.directory.path || !st.isDirectory() || st.dev !== c.directory.device || st.ino !== c.directory.inode)
+                return fail('EMPLOYEE_CONTEXT_CHANGED', '工作区目录身份已变化。', '重新选择当前真实工作区');
+            if (d.getConnect() !== s || !shape(s))
+                return fail('EMPLOYEE_CONTEXT_UNAVAILABLE', '工作区上下文已撤回。', '等待当前连接组件');
+            const after = s.getConnectionState(), ls = s.getWorkspaceLocationState();
+            if (after.instanceId !== r.instanceId || after.epoch !== r.epoch || after.phase !== 'connected' || ls.instanceId !== r.instanceId || ls.epoch !== r.epoch || ls.phase !== 'ready' || !ls.items.some(i => i.workspaceId === r.workspaceId && i.bindingId === r.expectedBindingId && i.source === 'local' && i.status === 'selected'))
+                return fail('EMPLOYEE_CONTEXT_CHANGED', '工作区在读取期间已变化。', '重新核验当前来源后派发');
+            return ok(structuredClone(c));
+        }
+        catch {
+            return fail('EMPLOYEE_CONTEXT_INVALID', '本地工作区信息无法核验。', '检查当前目录与连接组件');
+        }
+    }
+    async function prepare(r, signal) {
+        if (signal.aborted)
+            return cancelled();
+        if (disposed)
+            return fail('DISPOSED', '网络服务已停止。', '重新加载插件');
+        if (!requestValid(r))
+            return fail('EMPLOYEE_CONTEXT_INVALID', '工作区上下文请求无效。', '由当前工作区提供完整绑定');
+        refreshSource();
+        const s = source;
+        if (!s)
+            return fail('EMPLOYEE_CONTEXT_UNAVAILABLE', '我需要当前本地工作区上下文。', '等待连接组件提供本地来源');
+        const before = await read(r, s);
+        if (!before.ok)
+            return before;
+        if (signal.aborted)
+            return cancelled();
+        const token = revision, owner = lifetime.signal;
+        const runtime = d.getRuntime();
+        if (!runtime || d.getState().phase !== 'online')
+            return fail('NETWORK_NOT_READY', '远程主机尚未连接。', '等待原网络连接就绪');
+        let remote;
+        try {
+            remote = await s.getSshTarget();
+        }
+        catch {
+            return fail('EMPLOYEE_CONTEXT_UNAVAILABLE', '主机连接上下文暂不可用。', '检查连接组件状态');
+        }
+        if (!remote.ok)
+            return fail('EMPLOYEE_CONTEXT_UNAVAILABLE', '主机连接目标尚未就绪。', '等待当前主机连接');
+        const target = remote.value;
+        if (!target?.session || target.session.protocolVersion !== 1 || !absolute(target.session.settingsPath))
+            return fail('EMPLOYEE_CONTEXT_INVALID', '主机桥设置来源无效。', '检查已开通主机设置');
+        if (signal.aborted)
+            return cancelled();
+        const trusted = await d.connect(target, owner);
+        if (!trusted.ok)
+            return trusted;
+        if (signal.aborted)
+            return cancelled();
+        if (disposed || owner.aborted || revision !== token || d.getConnect() !== s)
+            return fail('EMPLOYEE_CONTEXT_CHANGED', '工作区连接已变化。', '重新核验后派发');
+        await closing;
+        if (closeFailed)
+            return fail('EMPLOYEE_ENDPOINT_UNAVAILABLE', '旧员工端点关闭未能确认。', '检查组件私有日志，正常停止旧实例后再继续；不要重放旧操作');
+        if (disposed || owner.aborted || revision !== token || d.getRuntime() !== runtime)
+            return fail('EMPLOYEE_CONTEXT_CHANGED', '员工端点上下文已变化。', '重新核验后派发');
+        // One shared preparation per actual device context, never per workspace. Each caller revalidates its own L CAS.
+        let work = pending;
+        if (!work || work.runtime !== runtime || work.settingsPath !== target.session.settingsPath || work.revision !== token) {
+            held = runtime;
+            const promise = runtime.prepareEmployeeEndpoint(target.session.settingsPath, owner).catch(() => fail('EMPLOYEE_ENDPOINT_UNAVAILABLE', '员工端点准备失败，根因未查明。', '检查组件私有诊断'));
+            work = { runtime, settingsPath: target.session.settingsPath, revision: token, promise };
+            pending = work;
+            void promise.finally(() => { if (pending === work)
+                pending = undefined; });
+        }
+        const ready = await new Promise(resolve => {
+            const abort = () => { signal.removeEventListener('abort', abort); owner.removeEventListener('abort', withdraw); resolve(cancelled()); };
+            const withdraw = () => { signal.removeEventListener('abort', abort); owner.removeEventListener('abort', withdraw); resolve(fail('EMPLOYEE_CONTEXT_CHANGED', '员工端点来源已撤回。', '重新核验后派发')); };
+            signal.addEventListener('abort', abort, { once: true });
+            owner.addEventListener('abort', withdraw, { once: true });
+            work.promise.then(v => { signal.removeEventListener('abort', abort); owner.removeEventListener('abort', withdraw); resolve(v); });
+            if (signal.aborted)
+                abort();
+            else if (owner.aborted)
+                withdraw();
+        });
+        if (!ready.ok)
+            return ready;
+        const verified = employeeReady(ready.value, before.value.process, target.session.settingsPath);
+        if (!verified.ok)
+            return verified;
+        const after = await read(r, s);
+        if (disposed || owner.aborted || revision !== token || d.getRuntime() !== runtime || !after.ok || !same(before.value, after.value))
+            return fail('EMPLOYEE_CONTEXT_CHANGED', '工作区在端点准备期间已变化。', '重新核验当前来源后派发，不重放旧操作');
+        if (signal.aborted)
+            return cancelled();
+        return ok({ version: 1, local: { instanceId: r.instanceId, epoch: r.epoch, workspaceId: r.workspaceId, bindingId: r.expectedBindingId, directory: structuredClone(after.value.directory) }, ...verified.value });
+    }
+    return { prepare, refreshSource, networkLost: invalidate, async dispose() { if (disposed)
+            return; disposed = true; detached(); invalidate(); await closing; } };
+}

package/lib/index.js

@@ -1,16 +1,24 @@
 import z from '@deepseek-ai/schemastery';
 import { createActivationService } from "./activation.js";
+import { bindEmployeeSourceLifecycle } from "./employee-endpoint.js";
 import { resolvePackagedHelper } from "./packaged-helper.js";
 export const name = 'ai-workbench-network';
-const positive = () => z.number().min(0.001);
+const positive = () => z.number().min(0.001).max(2147483.647);
+const bytes = () => z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER);
 export const Config = z.object({
     configFile: z.string().description('远程主机连接配置文件（由插件提供；无默认值）'),
     helperLogFile: z.string().description('远程主机连接诊断日志文件（无默认值）'),
-    startupObservationSeconds: positive().description('连接组件启动状态的最长观察时间（秒，无默认值）'),
-    shutdownObservationSeconds: positive().description('连接组件正常退出的等待时间（秒，无默认值）；超时后强制结束并报告'),
-    controlResponseMaxBytes: z.number().step(1).min(1).description('本机连接控制响应的最大字节数（无默认值）'),
-    downloadMaxRedirects: z.number().step(1).min(0).description('通过远程主机下载时允许的最大重定向次数（无默认值）'),
-});
+    startupObservationSeconds: positive().description('启动观察 startupObservationSeconds（秒）：默认未设，沿开通值（现值35）；等待组件ready仅为可观测性；增大等更久，减小可能提前报未知；无关闭值，超时给等待事项、已等时长和排查步骤'),
+    shutdownObservationSeconds: positive().description('退出观察 shutdownObservationSeconds（秒）：默认未设，沿开通值（现值10）；等待自有组件正常退出，仅为可观测性；增大清理等更久，减小可能强制结束并报告；无关闭值，不终止未知进程'),
+    controlResponseMaxBytes: bytes().description('控制响应上限 controlResponseMaxBytes（字节）：默认未设，沿开通值（现值65536）；控制JSON、ready及代理首帧，也约束员工端点私有控制请求/响应和主机桥首帧；增大增加内存，减小可能拒绝合法帧；无关闭或无限值，不限制下载或SFTP正文'),
+    downloadMaxRedirects: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).description('下载重定向上限 downloadMaxRedirects：默认未设，沿开通值（现值3）；增大允许更多HTTPS跳转，减小可能拒绝下载，0关闭跳转；不自动换源'),
+    statusRefreshIntervalSeconds: positive().description('状态刷新间隔 statusRefreshIntervalSeconds（秒）：默认沿已开通配置（现值2）；影响组件状态查询及插件轮询；增大提示更迟，减小增加查询开销；无关闭值，不代表失败重试已修复'),
+    dialTimeoutSeconds: positive().description('拨号观察 dialTimeoutSeconds（秒）：默认沿已开通配置（现值20）；远端TCP/SSH、控制响应头、下载CONNECT/响应头；Node请求采用阶段空闲观察，仅为可观测性，增大等更久，减小可能提前中止；无关闭值，超时说明等待事项、已等时长、下一步检查，不是修复'),
+    headerTimeoutSeconds: z.number().min(1e-9).max(9223372036.854774).description('请求头观察 headerTimeoutSeconds（秒）：默认沿已开通配置（现值10）；本机控制与登录代理请求头；仅为可观测性，增大保留连接更久，减小可能拒绝慢请求头；无关闭值，超时在私有日志说明等待事项、已等时长、下一步检查'),
+    enrollmentObservationSeconds: z.number().min(1e-9).max(9223372036.854774).description('首次入网观察 enrollmentObservationSeconds（秒）：默认沿已开通配置（现值30）；仅观察首次开通结果，不用于删除已有身份；增大等更久，减小可能更早报未知；无关闭值，超时说明等待事项、已等时长、下一步检查，不重交开通材料'),
+    httpMaxHeaderBytes: bytes().description('本机HTTP头上限 httpMaxHeaderBytes（字节）：默认沿已开通配置（现值1048576）；控制/登录代理请求头及控制响应头；增大增加解析内存，减小可能拒绝合法头；无关闭或无限值，不是正文上限'),
+    httpMaxResponseHeaderBytes: bytes().description('下载HTTP响应头上限 httpMaxResponseHeaderBytes（字节）：默认沿已开通配置（现值1048576）；主机代理及下载响应头/CONNECT头；增大增加解析内存，减小可能拒绝合法头；无关闭或无限值，不是正文上限'),
+}).description('运行策略优先级：本插件显式值 > 开通方传入值 > 原私有配置；未设置沿用原值，不注入新数值默认。活动连接改策略须正常重载插件，不重交开通材料。固定正确性约束不可关闭：macOS控制socket路径≤103字节、端口1–65535、计时器/整数可表示范围、私有700/600权限、当前用户与单身份隔离、SHA256及加密随机凭据强度。');
 export function register(ctx, api) {
     ctx.provide('aiWorkbenchNetwork', api);
     ctx.effect(() => { void api.start(); return () => api.dispose(); });
@@ -20,8 +28,10 @@ export function apply(ctx, config = {}) {
     if (!executable.ok) {
         const error = executable;
         const state = { phase: 'blocked', ...!error.ok ? { error: error.error } : {} };
-        register(ctx, { async activate() { return error; }, getActivationState: () => ({ instanceId: 'unpackaged', revision: 0, phase: 'blocked', receipt: null, error: !error.ok ? error.error : null }), onActivationState: () => () => { }, async start() { ctx.emit('ai-workbench/network-state', state); }, getState: () => structuredClone(state), async connect() { return error; }, onState: () => () => { }, async openLoginProxy() { return error; }, async download() { return error; }, async dispose() { } });
+        register(ctx, { async prepareEmployeeEndpoint() { return error; }, async activate() { return error; }, getActivationState: () => ({ instanceId: 'unpackaged', revision: 0, phase: 'blocked', receipt: null, error: !error.ok ? error.error : null }), onActivationState: () => () => { }, async start() { ctx.emit('ai-workbench/network-state', state); }, getState: () => structuredClone(state), async connect() { return error; }, onState: () => () => { }, async openLoginProxy() { return error; }, async download() { return error; }, async dispose() { } });
         return;
     }
-    register(ctx, createActivationService(config, executable.value, state => ctx.emit('ai-workbench/network-state', state)));
+    const api = createActivationService(config, executable.value, state => ctx.emit('ai-workbench/network-state', state), undefined, () => ctx.get('aiWorkbenchConnect', false));
+    register(ctx, api);
+    bindEmployeeSourceLifecycle(ctx, { refreshSource: api.refreshEmployeeSource });
 }