@ai-workbench/network 0.4.3 → 0.4.4

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

@@ -3,6 +3,7 @@ import { isAbsolute } from 'node:path';
 import { createNetwork } from "./network.js";
 import { fail, ok } from "./api.js";
 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;
@@ -18,12 +19,13 @@ function normalized(s) {
     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)
@@ -82,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 {
@@ -105,6 +109,7 @@ 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 (initial.configFile || initial.helperLogFile)
             await api.activate(initial, new AbortController().signal);
@@ -147,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<{

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,7 +1,7 @@
 import http from 'node:http';
 import { privateSocket } from "./private.js";
 import { ObservationExpired } from "./observation.js";
-export async function control(socket, method, path, signal, seconds, maxHeaderBytes) {
+export async function control(socket, method, path, signal, seconds, maxHeaderBytes, body) {
     await privateSocket(socket);
     signal.throwIfAborted();
     return new Promise((resolve, reject) => {
@@ -9,7 +9,14 @@ export async function control(socket, method, path, signal, seconds, maxHeaderBy
         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/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,5 +1,6 @@
 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).max(2147483.647);
@@ -9,7 +10,7 @@ export const Config = z.object({
     helperLogFile: z.string().description('远程主机连接诊断日志文件（无默认值）'),
     startupObservationSeconds: positive().description('启动观察 startupObservationSeconds（秒）：默认未设，沿开通值（现值35）；等待组件ready仅为可观测性；增大等更久，减小可能提前报未知；无关闭值，超时给等待事项、已等时长和排查步骤'),
     shutdownObservationSeconds: positive().description('退出观察 shutdownObservationSeconds（秒）：默认未设，沿开通值（现值10）；等待自有组件正常退出，仅为可观测性；增大清理等更久，减小可能强制结束并报告；无关闭值，不终止未知进程'),
-    controlResponseMaxBytes: bytes().description('控制响应上限 controlResponseMaxBytes（字节）：默认未设，沿开通值（现值65536）；控制JSON、ready及代理首帧；增大增加内存，减小可能拒绝合法帧；无关闭或无限值，不限制下载正文'),
+    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请求采用阶段空闲观察，仅为可观测性，增大等更久，减小可能提前中止；无关闭值，超时说明等待事项、已等时长、下一步检查，不是修复'),
@@ -27,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 });
 }

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

@@ -7,6 +7,7 @@ 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("'", "'\\''") + "'";
@@ -45,6 +46,7 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
     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;
@@ -185,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, ...helperPolicyArgs(settings)], { 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();
@@ -350,6 +364,46 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
         },
         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;
@@ -369,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-workbench/network",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "type": "module",
   "engines": {
     "node": ">=24.13.1"