@ai-workbench/connect 0.0.0-stage → 0.7.6

package/lib/index.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export type * from './cordis.ts';
+import type { Ports } from './ports.ts';
+import { type ComponentInventory } from './components.ts';
+import type { NetworkSettings } from './network.ts';
+import type { AssemblySettings } from './profile-activation.ts';
+export { writeNetworkConfig, createNetworkClient } from './network.ts';
+export type * from './api.ts';
+export { createConnect } from './connect.ts';
+export { sshArgs } from './ssh.ts';
+export declare const name = "ai-workbench-connect";
+export declare const inject: string[];
+export interface Config {
+    inventory?: ComponentInventory;
+    enrollmentMetadataMaxBytes?: number;
+    enrollmentPackageDir?: string;
+    trustDir?: string;
+    commandOutputMaxBytes?: number;
+    network?: (NetworkSettings & AssemblySettings);
+    helper?: {
+        componentDownloadSource?: 'github' | 'npmmirror';
+        componentObservationIntervalMs?: number;
+        componentDownloadMaxRedirects?: number;
+        remoteKillGraceMs?: number;
+        maxRedirects?: number;
+        source?: string;
+        sha256?: string;
+        cacheDir?: string;
+        maxDownloadBytes?: number;
+        maxExtractedBytes?: number;
+        executable?: string;
+        loginOutputMaxBytes?: number;
+        ipcMaxBytes?: number;
+    };
+}
+export declare const Config: z<Config>;
+export declare function register(ctx: Context, ports: Ports, inventory?: ComponentInventory, extend?: (api: import('./api.ts').ConnectApi) => void): void;
+export declare function apply(ctx: Context, config?: Config): void;
+export { createProfileEnrollment } from './profile-enrollment.ts';
+export { createWorkspaceBindings } from './workspace-bindings.ts';
+export { profileSettings } from './profile-settings.ts';

package/lib/index.js

@@ -0,0 +1,55 @@
+import z from '@deepseek-ai/schemastery';
+import { createConnect } from "./connect.js";
+import { configuredPorts } from "./integration.js";
+import { attachProfileRuntime } from "./profile-runtime.js";
+import { profileSettings } from "./profile-settings.js";
+import { createComponentSources, DEFAULT_SOURCE_REASON } from "./component-source.js";
+import { createComponentProgress } from "./component-download.js";
+import { L_DEFAULTS, NETWORK_DEFAULTS } from "./defaults.js";
+import { registerComponents } from "./components.js";
+export { writeNetworkConfig, createNetworkClient } from "./network.js";
+export { createConnect } from "./connect.js";
+export { sshArgs } from "./ssh.js";
+export const name = 'ai-workbench-connect';
+export const inject = ['aiWorkbenchNetwork'];
+const positive = () => z.number().step(1).min(1);
+// Administrator settings are optional in schema so the loaded service can explain missing prerequisites.
+// aiWorkbenchNetwork itself is a required Cordis injection; missing N holds this module from loading.
+// Own technical defaults use the approved settings record; no global DSH policy is changed.
+export const Config = z.object({
+    enrollmentMetadataMaxBytes: positive().max(2147483647).default(L_DEFAULTS.enrollmentMetadataMaxBytes).description('开通元数据与工作区关联文件字节上限；默认1MiB，可由管理员修改；不读取key内容'),
+    inventory: z.object({ network: z.string(), connect: z.string(), claude: z.string(), codex: z.string() }).description('由bundle真实包版本自动生成，只读交付事实，不是策略默认'),
+    enrollmentPackageDir: z.string().description('开通包目录：由安装交付，员工不手填；owner已定稿，交付显式配置'),
+    trustDir: z.string().description('主机信任缓存目录；owner已定稿，交付显式配置'),
+    commandOutputMaxBytes: positive().default(L_DEFAULTS.commandOutputMaxBytes).description('CLI检查输出内存上限（字节）；owner已定1048576，管理员可改'),
+    network: z.object({ executable: z.string(), runtimeDir: z.string(), stateDir: z.string(), configFile: z.string(), helperLogFile: z.string(), nodeName: z.string(), startupObservationSeconds: z.number().min(0.001).max(2147483.647).default(NETWORK_DEFAULTS.startupObservationSeconds), shutdownObservationSeconds: z.number().min(0.001).max(2147483.647).default(NETWORK_DEFAULTS.shutdownObservationSeconds), controlResponseMaxBytes: positive().default(NETWORK_DEFAULTS.controlResponseMaxBytes), downloadMaxRedirects: z.number().step(1).min(0).default(NETWORK_DEFAULTS.downloadMaxRedirects), proxyListen: z.string().default(NETWORK_DEFAULTS.proxyListen), logUpload: z.boolean().default(NETWORK_DEFAULTS.logUpload), statusRefreshIntervalSeconds: z.number().min(0.001).max(2147483.647).default(NETWORK_DEFAULTS.statusRefreshIntervalSeconds), dialTimeoutSeconds: z.number().min(1e-9).default(NETWORK_DEFAULTS.dialTimeoutSeconds), headerTimeoutSeconds: z.number().min(0.001).max(2147483.647).default(NETWORK_DEFAULTS.headerTimeoutSeconds), enrollmentObservationSeconds: z.number().min(1e-9).default(NETWORK_DEFAULTS.enrollmentObservationSeconds), httpMaxHeaderBytes: positive().default(NETWORK_DEFAULTS.httpMaxHeaderBytes), httpMaxResponseHeaderBytes: positive().default(NETWORK_DEFAULTS.httpMaxResponseHeaderBytes), controlMaxBytes: positive() }).description('N v1 交接设置；沿owner已定技术值自动装配，管理员可改；路径由当前用户/profile派生，员工不填'),
+    helper: z.object({
+        componentDownloadSource: z.union([z.const('github'), z.const('npmmirror')]).description('未保存设置节选择时的初始下载源；未设且无旧source时默认npmmirror（编排leo实测可达），可选github；不自动测速/换源，版本与SHA固定'),
+        componentObservationIntervalMs: z.number().step(1).min(1).max(2147483647).default(L_DEFAULTS.componentObservationIntervalMs).description('无进展观察刷新间隔毫秒，默认1000；只刷新秒数，不超时/重试/换源'),
+        componentDownloadMaxRedirects: z.number().step(1).min(0).default(L_DEFAULTS.componentDownloadMaxRedirects).description('组件直接HTTPS下载的重定向次数上限；默认3，0拒绝重定向；管理员可改，不影响OAuth主机出口'),
+        remoteKillGraceMs: z.number().step(1).min(0).max(2147483647).default(L_DEFAULTS.remoteKillGraceMs).description('远端本轮登录进程组结束宽限毫秒；owner已定1000，0立即KILL，管理员可改'),
+        maxRedirects: z.number().step(1).min(0).description('兼容旧配置；0.5默认路径改由N插件downloadMaxRedirects控制，此项不再生效'),
+        source: z.string().description('兼容初始管理员显式URL；无已保存的设置节选择且未设componentDownloadSource时生效；无隐式换源'), sha256: z.string().description('darwin-arm64默认已定44.0.0下载SHA256；管理员可改，必须校验'),
+        cacheDir: z.string().description('默认从当前profile自动派生ai-workbench-connect/login-component-cache；管理员可改，员工不填路径'), maxDownloadBytes: positive().default(L_DEFAULTS.maxDownloadBytes).description('下载字节上限；owner已定200000000，管理员可改'), maxExtractedBytes: positive().default(L_DEFAULTS.maxExtractedBytes).description('解压字节上限；owner已定600000000，管理员可改'),
+        executable: z.string().description('darwin-arm64默认Electron.app/Contents/MacOS/Electron；其他平台无默认，管理员可改'), loginOutputMaxBytes: positive().default(L_DEFAULTS.loginOutputMaxBytes).description('登录进程输出字节上限；owner已定1048576，管理员可改'), ipcMaxBytes: positive().default(L_DEFAULTS.ipcMaxBytes).description('私有IPC字节上限；owner已定1048576，管理员可改'),
+    }),
+});
+export function register(ctx, ports, inventory, extend) {
+    const api = createConnect(ports, state => ctx.emit('ai-workbench/connect-state', state), { providers: inventory && !inventory.codex ? ['claude'] : ['codex', 'claude'], onConnectionState: state => ctx.emit('ai-workbench/connection-state', state), onPromptState: state => ctx.emit('ai-workbench/login-prompt-state', state), onPromptResult: result => ctx.emit('ai-workbench/login-prompt-result', result) });
+    extend?.(api);
+    ctx.provide('aiWorkbenchConnect', api);
+    ctx.effect(() => { void api.refreshLoginPrompts(); return () => api.dispose(); });
+}
+export function apply(ctx, config = {}) {
+    const sourceReason = config.helper?.componentDownloadSource !== undefined ? '管理员通过 helper.componentDownloadSource 指定此下载源。' : config.helper?.source !== undefined ? '管理员通过 helper.source 指定此下载源。' : DEFAULT_SOURCE_REASON;
+    config = profileSettings(config, ctx.get('profileContext')?.dir);
+    const network = ctx.get('aiWorkbenchNetwork'), component = createComponentProgress();
+    const sources = createComponentSources({ profileDir: ctx.get('profileContext')?.dir, metadataMaxBytes: config.enrollmentMetadataMaxBytes ?? L_DEFAULTS.enrollmentMetadataMaxBytes, source: config.helper?.source, sha256: config.helper?.sha256, reason: sourceReason, busy: () => ['downloading', 'verifying', 'unpacking'].includes(component.getState().phase) || ctx.get('aiWorkbenchConnect')?.getLoginPromptState().phase === 'authorizing' });
+    ctx.effect(() => () => sources.dispose());
+    const ports = configuredPorts(config, network, component, sources);
+    register(ctx, ports, config.inventory, api => attachProfileRuntime(ctx, api, ports, config, network));
+    registerComponents(ctx, config.inventory, config.helper?.cacheDir, component, sources, config.helper?.componentObservationIntervalMs);
+}
+export { createProfileEnrollment } from "./profile-enrollment.js";
+export { createWorkspaceBindings } from "./workspace-bindings.js";
+export { profileSettings } from "./profile-settings.js";

package/lib/integration.d.ts

@@ -0,0 +1,6 @@
+import type { ComponentSources } from './component-source.ts';
+import type { Config } from './index.ts';
+import type { Ports } from './ports.ts';
+import { type NetworkProvider } from './provider.ts';
+import { type ComponentProgressStore } from './component-download.ts';
+export declare function configuredPorts(config: Config, provider?: NetworkProvider, component?: ComponentProgressStore, sources?: ComponentSources): Ports;

package/lib/integration.js

@@ -0,0 +1,56 @@
+import { ComponentDownloadError } from "./component-download.js";
+import { fileURLToPath } from 'node:url';
+import { readEnrollment } from "./enrollment.js";
+import { adaptNetwork } from "./provider.js";
+import { createRunner, createRemoteLogin } from "./processes.js";
+import { createSsh, sshArgs } from "./ssh.js";
+import { createProjects } from "./projects.js";
+import { remoteLoginCommand } from "./remote-login.js";
+import { runLogin } from "./login.js";
+import { ensureHelper } from "./cache.js";
+import { launchElectron } from "./electron.js";
+import { need, fail } from "./needs.js";
+import { createComponentProgress, downloadComponent } from "./component-download.js";
+export function configuredPorts(config, provider, component = createComponentProgress(), sources) {
+    const ports = {};
+    const network = provider ? adaptNetwork(provider) : undefined;
+    if (config.enrollmentPackageDir && config.trustDir)
+        ports.enrollment = { read: () => readEnrollment(config.enrollmentPackageDir, config.trustDir) };
+    else if (provider)
+        ports.enrollment = { read: async () => fail('SETTINGS_REQUIRED') };
+    if (config.commandOutputMaxBytes !== undefined) {
+        const runner = createRunner(config.commandOutputMaxBytes);
+        ports.ssh = createSsh(runner, config.commandOutputMaxBytes);
+        ports.projects = createProjects(runner);
+    }
+    else if (provider)
+        ports.ssh = { verify: async () => fail('SETTINGS_REQUIRED'), status: async () => fail('SETTINGS_REQUIRED') };
+    if (network) {
+        ports.network = network;
+        ports.login = { run: async (target, provider, signal) => {
+                const h = config.helper;
+                if (!h || !Number.isSafeInteger(h.remoteKillGraceMs) || h.remoteKillGraceMs < 0 || h.remoteKillGraceMs > 2147483647 || ![h.source, h.sha256, h.cacheDir, h.executable].every(x => typeof x === 'string' && x) || !Number.isSafeInteger(h.componentDownloadMaxRedirects) || h.componentDownloadMaxRedirects < 0 || ![h.maxDownloadBytes, h.maxExtractedBytes, h.loginOutputMaxBytes, h.ipcMaxBytes].every(x => Number.isSafeInteger(x) && x > 0))
+                    return { ok: false, error: need('SETTINGS_REQUIRED') };
+                let selection;
+                try {
+                    selection = await sources?.resolve();
+                }
+                catch (e) {
+                    return { ok: false, error: { ...need('SETTINGS_REQUIRED'), officialReason: e instanceof ComponentDownloadError ? e.message : 'COMPONENT_SOURCE_STATE_INVALID' } };
+                }
+                const cancellation = new AbortController(), downloadSignal = AbortSignal.any([signal, cancellation.signal]);
+                const attempt = component.begin(selection, () => cancellation.abort());
+                const result = await ensureHelper({ ...h, source: selection?.source ?? h.source }, { download: source => downloadComponent(source, downloadSignal, h.componentDownloadMaxRedirects), signal: downloadSignal, onProgress: attempt.update });
+                if (!result.ok)
+                    return result;
+                if (signal.aborted)
+                    return fail('LOGIN_FAILED');
+                return runLogin(target, provider, {
+                    start: (t, p, s) => createRemoteLogin('ssh', [...sshArgs(t), remoteLoginCommand(p, h.remoteKillGraceMs)], p, h.loginOutputMaxBytes, s, 'remote-control'),
+                    acquireProxy: (_t, s) => network.acquireProxy(s),
+                    open: (boot, onCode, s) => launchElectron({ executable: result.value, entry: fileURLToPath(new URL('../helper/main.cjs', import.meta.url)), cacheDir: h.cacheDir, ipcMaxBytes: h.ipcMaxBytes }, boot, onCode, s),
+                }, signal);
+            } };
+    }
+    return ports;
+}

package/lib/login.d.ts

@@ -0,0 +1,35 @@
+import type { Provider, Result, SshTarget } from './api.ts';
+export interface ProxyLease {
+    url: string;
+    username: string;
+    password: string;
+    closed?: Promise<void>;
+    release(): Promise<void>;
+}
+export interface LoginBoot {
+    provider: Provider;
+    url: string;
+    proxy: Pick<ProxyLease, 'url' | 'username' | 'password'>;
+}
+export interface RemoteLogin {
+    ownership?: Promise<{
+        pid: number;
+        group: number;
+        provider: string;
+    }>;
+    url: Promise<Result<string>>;
+    completion: Promise<Result<void>>;
+    writeCode(code: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface LoginWindow {
+    closed: Promise<void>;
+    close(): Promise<void>;
+}
+export interface LoginPorts {
+    start(t: SshTarget, p: Provider, s: AbortSignal): Promise<RemoteLogin>;
+    acquireProxy(t: SshTarget, s: AbortSignal): Promise<ProxyLease>;
+    open(boot: LoginBoot, onCode: (code: string) => Promise<void>, s: AbortSignal): Promise<LoginWindow>;
+}
+export declare function extractLoginUrl(provider: Provider, text: string): string | undefined;
+export declare function runLogin(t: SshTarget, p: Provider, ports: LoginPorts, parentSignal: AbortSignal): Promise<Result<void>>;

package/lib/login.js

@@ -0,0 +1,81 @@
+import { createRequire } from 'node:module';
+const { isClaudeAuthorizeUrl, validateClaudePaste } = createRequire(import.meta.url)('../helper/claude-callback.cjs');
+import { fail, NeedError, need } from "./needs.js";
+export function extractLoginUrl(provider, text) {
+    for (const match of text.matchAll(/https:\/\/[^\s<>"']+/g)) {
+        try {
+            const u = new URL(match[0]);
+            if (!u.username && !u.password && u.protocol === 'https:' && ((provider === 'codex' && u.origin === 'https://auth.openai.com' && u.pathname === '/oauth/authorize') || (provider === 'claude' && isClaudeAuthorizeUrl(u))))
+                return u.href;
+        }
+        catch { /* not a complete URL yet */ }
+    }
+    return undefined;
+}
+export async function runLogin(t, p, ports, parentSignal) {
+    const controller = new AbortController(), signal = controller.signal;
+    const parentAbort = () => controller.abort();
+    parentSignal.addEventListener('abort', parentAbort, { once: true });
+    if (parentSignal.aborted)
+        controller.abort();
+    let remote, lease, window, remove = () => { };
+    let result = fail('LOGIN_FAILED'), leaseLost = false, releasing = false;
+    try {
+        if (signal.aborted)
+            return result;
+        const cancelled = new Promise(resolve => { const abort = () => resolve(fail('LOGIN_FAILED')); signal.addEventListener('abort', abort, { once: true }); remove = () => signal.removeEventListener('abort', abort); });
+        remote = await ports.start(t, p, signal);
+        const url = await Promise.race([remote.url, cancelled]);
+        if (!url.ok)
+            return url;
+        if (typeof url.value !== 'string' || extractLoginUrl(p, url.value) !== url.value)
+            return result;
+        lease = await ports.acquireProxy(t, signal);
+        const lost = () => { if (!releasing) {
+            leaseLost = true;
+            controller.abort();
+        } };
+        void lease.closed?.then(lost, lost);
+        if (signal.aborted)
+            throw new NeedError(need(leaseLost ? 'CONNECTION_LOST' : 'LOGIN_FAILED'));
+        let codeSent = false, codeError = () => { };
+        const failedCode = new Promise(r => codeError = r);
+        window = await ports.open({ provider: p, url: url.value, proxy: { url: lease.url, username: lease.username, password: lease.password } }, async (code) => {
+            if (p !== 'claude' || codeSent || signal.aborted || !validateClaudePaste(url.value, code)) {
+                codeError(fail('LOGIN_FAILED'));
+                return;
+            }
+            codeSent = true;
+            try {
+                await remote.writeCode(code);
+            }
+            catch {
+                codeError(fail('LOGIN_FAILED'));
+            }
+        }, signal);
+        result = await Promise.race([remote.completion, window.closed.then(() => fail('LOGIN_FAILED')), failedCode, cancelled]);
+    }
+    catch (error) {
+        result = error instanceof NeedError ? { ok: false, error: error.need } : fail('LOGIN_FAILED');
+    }
+    finally {
+        remove();
+        parentSignal.removeEventListener('abort', parentAbort);
+        // Attempt every cleanup even when one resource fails; surface failure instead of success.
+        const cleanup = await Promise.allSettled([window?.close(), remote?.close()]);
+        if (cleanup.some(r => r.status === 'rejected'))
+            result = fail('LOGIN_FAILED');
+        releasing = true;
+        if (lease) {
+            try {
+                await lease.release();
+            }
+            catch (error) {
+                result = error instanceof NeedError ? { ok: false, error: error.need } : fail('LOGIN_FAILED');
+            }
+        }
+        if (leaseLost)
+            result = fail('CONNECTION_LOST');
+    }
+    return result;
+}

package/lib/native-import-picker.d.ts

@@ -0,0 +1,11 @@
+export interface DirectoryPicker {
+    capability(): {
+        kind: string;
+        pick?: (signal: AbortSignal) => Promise<string | null>;
+    };
+}
+interface NativeExports {
+    pickNativeDirectory?: (signal: AbortSignal) => Promise<string | null>;
+}
+export declare function createNativeImportPicker(service: () => DirectoryPicker | undefined, loadNative?: () => Promise<NativeExports>): (signal: AbortSignal) => Promise<string | null>;
+export {};

package/lib/native-import-picker.js

@@ -0,0 +1,49 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { NeedError, need } from "./needs.js";
+const officialModule = '@deepseek-ai/dsh-host-directory-picker-native';
+const loadOfficial = async () => import(__rewriteRelativeImportExtension(officialModule));
+const unavailable = (requires, officialReason) => new NeedError({
+    ...need('DEPENDENCY_REQUIRED'), requires, ...(officialReason ? { officialReason } : {}),
+});
+// L的导入入口固定使用系统目录窗口，不修改DSH自动选择器或工作区流程。
+// 本地原生能力直接消费；SSH启动等上下文选择browse时，调用同一官方
+// 原生后端的公开函数。该分支在调用前确定，失败后绝不换后端或重试。
+export function createNativeImportPicker(service, loadNative = loadOfficial) {
+    return async (signal) => {
+        const capability = service()?.capability();
+        let pick;
+        if (capability?.kind === 'native') {
+            if (typeof capability.pick !== 'function')
+                throw unavailable('官方原生目录选择服务的pick方法');
+            pick = signal => capability.pick(signal);
+        }
+        else {
+            let native;
+            try {
+                native = await loadNative();
+            }
+            catch {
+                throw unavailable('已安装官方原生目录选择组件 ' + officialModule);
+            }
+            if (typeof native.pickNativeDirectory !== 'function')
+                throw unavailable('官方原生目录选择组件的pickNativeDirectory公开导出');
+            pick = signal => native.pickNativeDirectory(signal);
+        }
+        try {
+            return await pick(signal);
+        }
+        catch (error) {
+            const code = error?.code;
+            const officialReason = typeof code === 'number' && Number.isSafeInteger(code) ? 'EXIT_' + code :
+                typeof code === 'string' && ['EACCES', 'EPERM', 'ENOENT', 'ENOTDIR', 'ECANCELED', 'ABORT_ERR'].includes(code) ? code : undefined;
+            throw unavailable('系统目录选择窗口成功返回结果；未取得结果时不会读取或提交开通资料', officialReason);
+        }
+    };
+}

package/lib/needs.d.ts

@@ -0,0 +1,9 @@
+import type { ConnectNeed, NeedCode, Result } from './api.ts';
+export declare const ok: <T>(value: T) => Result<T>;
+export declare const need: (code: NeedCode) => ConnectNeed;
+export declare const fail: <T = never>(code: NeedCode) => Result<T>;
+export declare function dependency(requires: string): Result<never>;
+export declare class NeedError extends Error {
+    readonly need: ConnectNeed;
+    constructor(value: ConnectNeed);
+}

package/lib/needs.js

@@ -0,0 +1,52 @@
+const entries = {
+    ACTIVATION_CONFLICT: { layer: 'network', message: '已有另一项开通正在进行，已停止重复开通，请联系管理员。', requires: '唯一的开通请求', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    ACTIVATION_CANCELLED: { layer: 'network', message: '本次网络开通已取消。', requires: '完成明确的开通操作', actor: 'plugin', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    ENROLLMENT_CLEANUP_UNBOUND: { layer: 'network', message: '连接资料与已保存的入网身份不匹配，已停止清理，请联系管理员。', requires: '匹配的入网身份与原始连接资料', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    ENROLLMENT_CLEANUP_FAILED: { layer: 'network', message: '入网身份已保存；连接资料清理未完成，请联系管理员。', requires: '精确清理已消费的连接资料', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    ENROLLMENT_MISMATCH: { layer: 'network', message: '当前连接资料与已登记的入网身份不符，请联系管理员。', requires: '一致的连接资料与入网身份', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    LOCAL_STATE_INVALID: { layer: 'network', message: '本机网络身份记录无法核实，已停止开通，请联系管理员。', requires: '完整可信的本机网络身份记录', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    ALREADY_RUNNING: { layer: 'network', message: '网络组件已在运行，无法确认其归属，请联系管理员。', requires: '唯一且归属明确的网络组件', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    ENROLLMENT_RECEIPT_REQUIRED: { layer: 'network', message: '缺少可核验的入网回执，请联系管理员。', requires: '持久且匹配的入网回执', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    CONTROL_PROTOCOL_INVALID: { layer: 'network', message: '网络组件接口不匹配，已停止操作，请联系管理员。', requires: '匹配版本的网络组件接口', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    HELPER_HANDOFF_FAILED: { layer: 'network', message: '网络组件交接未完成，请联系管理员。', requires: '完成网络组件交接', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    HELPER_SHUTDOWN_FORCED: { layer: 'network', message: '网络组件未能正常退出，请联系管理员核实状态。', requires: '核实网络组件退出状态', actor: 'administrator', action: { id: 'inspect-network-enrollment', label: '联系管理员', available: false } },
+    ENROLLMENT_RESULT_UNKNOWN: { layer: 'enrollment', message: '上次开通结果无法确认，请联系管理员核实。已停止再次提交开通资料。', requires: '管理员核实上次开通结果', actor: 'administrator', action: { id: 'check-enrollment-result', label: '联系管理员', available: false } },
+    ENROLLMENT_REJECTED: { layer: 'enrollment', message: '开通资料已失效，请联系管理员处理。已停止再次提交。', requires: '管理员处理已失效的设备身份', actor: 'administrator', action: { id: 'check-enrollment-result', label: '联系管理员', available: false } },
+    ENROLLMENT_REQUIRED: { layer: 'enrollment', message: '我需要开通链接，请联系管理员发放。', requires: '开通文件', actor: 'administrator', action: { id: 'request-enrollment', label: '联系管理员开通', available: false } },
+    ENROLLMENT_INVALID: { layer: 'enrollment', message: '开通文件无效，我需要管理员重新发放。', requires: '有效开通文件', actor: 'administrator', action: { id: 'request-enrollment', label: '重新开通', available: false } },
+    NETWORK_KEY_INVALID: { layer: 'network', message: '员工开通已失效，请联系管理员重新发放开通链接。', requires: '新的开通链接', actor: 'administrator', action: { id: 'request-enrollment', label: '联系管理员', available: false } },
+    HOST_OFFLINE: { layer: 'network', message: '主机离线，请联系管理员；最后在线时间未提供时为未知。', requires: '在线的公司主机', actor: 'administrator', action: { id: 'contact-administrator', label: '联系管理员', available: false } },
+    EMPLOYEE_MISSING: { layer: 'ssh', message: '主机上没有你的员工账号，需要管理员运行开通。', requires: '员工主机账号', actor: 'administrator', action: { id: 'provision-employee', label: '管理员开通账号', available: false } },
+    SSH_FAILED: { layer: 'ssh', message: '远程主机连接暂时连不上，请联系管理员。', requires: '可用且身份匹配的员工 SSH 连接', actor: 'administrator', action: { id: 'inspect-ssh', label: '检查主机连接', available: false } },
+    LOGIN_PROMPT_INVALID: { layer: 'auth', message: '这个登录询问已经更新，请使用当前提示。', requires: '当前登录询问', actor: 'employee', action: { id: 'current-login-prompt', label: '查看当前提示', available: false } },
+    LOGIN_REQUIRED: { layer: 'auth', message: '需要登录，请到设置 → 远程主机连接 点登录', requires: 'AI 账号授权', actor: 'employee', action: { id: 'open-login', label: '前往远程主机连接设置', available: true } },
+    POLICY_DENIED: { layer: 'auth', message: '公司的 AI 席位设置不允许此操作，需要 AI 账号管理员开启。', requires: '允许此操作的 AI 席位设置', actor: 'ai-administrator', action: { id: 'contact-ai-administrator', label: '联系 AI 账号管理员', available: false } },
+    CONNECTION_LOST: { layer: 'network', message: '连接中断，正在等待网络恢复信号，恢复后将重新连接。', requires: '网络恢复', actor: 'plugin', action: { id: 'await-network', label: '等待网络恢复', available: false } },
+    DEPENDENCY_REQUIRED: { layer: 'integration', message: '远程主机连接的连接组件没有装好，请联系管理员。', requires: '提供方契约与适配器', actor: 'administrator', action: { id: 'supply-dependency', label: '提供集成前置条件', available: false } },
+    SETTINGS_REQUIRED: { layer: 'settings', message: '远程主机连接还没有设置好，请联系管理员。', requires: '已确认的连接设置', actor: 'administrator', action: { id: 'configure-settings', label: '确认具名设置', available: false } },
+    AUTH_STATUS_INVALID: { layer: 'auth', message: '暂时无法确认登录状态，请联系管理员。', requires: '有效的官方 CLI 登录状态', actor: 'administrator', action: { id: 'inspect-auth-status', label: '检查官方 CLI', available: false } },
+    LOGIN_FAILED: { layer: 'auth', message: '登录未完成，窗口已关闭或助手失败，可以重新授权。', requires: '完成 AI 授权', actor: 'employee', action: { id: 'open-login', label: '重新授权', available: true } },
+    HOST_TRUST_REQUIRED: { layer: 'ssh', message: '远程主机连接还缺少可信的连接信息，请联系管理员。', requires: 'host.knownHosts', actor: 'administrator', action: { id: 'supply-host-trust', label: '提供主机信任材料', available: false } },
+    HOST_KEY_MISMATCH: { layer: 'ssh', message: '主机身份与已开通的信任材料不符，需要管理员检查。', requires: '匹配的主机公钥', actor: 'administrator', action: { id: 'verify-host-trust', label: '检查主机身份', available: false } },
+    PROJECT_NAME_INVALID: { layer: 'projects', message: '工作区名必须是单个目录名称，不能是路径、点目录或控制字符。', requires: '有效工作区名', actor: 'employee', action: { id: 'rename-project', label: '修改工作区名', available: true } },
+    PROJECT_ROOT_INVALID: { layer: 'projects', message: '工作区暂时无法打开，请联系管理员。', requires: 'S 开通的 700 工作区根目录', actor: 'administrator', action: { id: 'check-project-root', label: '检查开通目录', available: false } },
+    PROJECT_EXISTS: { layer: 'projects', message: '同名工作区或文件已经存在，请换一个工作区名。', requires: '未被占用的工作区名', actor: 'employee', action: { id: 'rename-project', label: '修改工作区名', available: true } },
+    PROJECT_INIT_FAILED: { layer: 'projects', message: '工作区创建没有完成，已保留现有文件，请联系管理员。', requires: '可用的主机 Git 与目录检查', actor: 'administrator', action: { id: 'inspect-project-init', label: '检查 Git 初始化', available: false } },
+    PROJECT_CREATE_FAILED: { layer: 'projects', message: '工作区创建没有完成，请联系管理员。', requires: '可用的工作区目录与 Git', actor: 'administrator', action: { id: 'inspect-project-create', label: '检查新建工作区', available: false } },
+    PROJECT_LIST_FAILED: { layer: 'projects', message: '工作区列表暂时打不开，请联系管理员。', requires: '可读的工作区目录与 Git', actor: 'administrator', action: { id: 'inspect-project-list', label: '检查工作区目录', available: false } },
+    PROJECT_PROTOCOL_INVALID: { layer: 'projects', message: '工作区暂时无法打开，已停止操作，请联系管理员。', requires: '匹配版本的工作区服务', actor: 'administrator', action: { id: 'inspect-project-protocol', label: '检查工作区接口', available: false } },
+    PROJECT_BINDING_INVALID: { layer: 'projects', message: '工作区关联与当前目录或主机身份不符，已停止操作，请联系管理员。', requires: '原工作区与可信主机身份', actor: 'administrator', action: { id: 'check-workspace-binding', label: '联系管理员', available: false } },
+    PROJECT_BINDING_BUSY: { layer: 'projects', message: '此工作区正在关联或说明正在投递，请联系管理员核实。', requires: '完成当前关联或投递', actor: 'administrator', action: { id: 'check-workspace-binding', label: '联系管理员', available: false } },
+    PROJECT_CREATE_UNKNOWN: { layer: 'projects', message: '远程工作区创建结果无法确认，已保留现场，请联系管理员。', requires: '核实上次远程工作区创建结果', actor: 'administrator', action: { id: 'check-workspace-create', label: '联系管理员', available: false } },
+    PROJECT_NOTICE_DELIVERY_UNKNOWN: { layer: 'projects', message: '工作区说明的投递结果无法确认，已停止远程派发，请联系管理员核实。', requires: '官方会话回复的持久投递证据', actor: 'administrator', action: { id: 'check-workspace-notice', label: '联系管理员', available: false } },
+    PROJECT_BINDING_REQUIRED: { layer: 'projects', message: '请在会话中选择已关联的远程工作区。', requires: '当前会话的可信远程工作区关联', actor: 'employee', action: { id: 'select-workspace', label: '选择工作区', available: true } },
+    DISPOSED: { layer: 'integration', message: '连接插件已卸载，需要重新启用插件。', requires: '已启用的连接插件', actor: 'employee', action: { id: 'enable-plugin', label: '启用插件', available: false } },
+};
+export const ok = (value) => ({ ok: true, value });
+export const need = (code) => structuredClone({ code, ...entries[code] });
+export const fail = (code) => ({ ok: false, error: need(code) });
+export function dependency(requires) { const error = need('DEPENDENCY_REQUIRED'); error.requires = requires; error.message = '远程主机连接的连接组件没有装好，请联系管理员。'; return { ok: false, error }; }
+export class NeedError extends Error {
+    need;
+    constructor(value) { super(value.code); this.need = value; }
+}

package/lib/network.d.ts

@@ -0,0 +1,26 @@
+import type { Enrollment, NetworkEvent } from './ports.ts';
+import type { Result } from './api.ts';
+import type { ProxyLease } from './login.ts';
+export interface NetworkSettings {
+    executable?: string;
+    runtimeDir?: string;
+    stateDir?: string;
+    proxyListen?: string;
+    logUpload?: boolean;
+    statusRefreshIntervalSeconds?: number;
+    dialTimeoutSeconds?: number;
+    headerTimeoutSeconds?: number;
+    enrollmentObservationSeconds?: number;
+    httpMaxHeaderBytes?: number;
+    httpMaxResponseHeaderBytes?: number;
+    controlMaxBytes?: number;
+}
+export declare function writeNetworkConfig(file: string, e: Enrollment, s: NetworkSettings): Promise<Result<void>>;
+export declare function createNetworkClient(s: NetworkSettings): {
+    connect(e: Enrollment, signal: AbortSignal): Promise<Result<{
+        proxyCommand: string;
+    }>>;
+    onState(listener: (event: NetworkEvent) => void): () => void;
+    acquireProxy(signal: AbortSignal): Promise<ProxyLease>;
+    dispose(): void;
+};