@ai-workbench/connect 0.0.0-stage → 0.7.5

package/lib/profile-settings.js

@@ -0,0 +1,10 @@
+import { isAbsolute, join } from 'node:path';
+import { L_DEFAULTS, ELECTRON_PIN } from "./defaults.js";
+// Owner approved technical values, 2026-10-20 settings decision, part two.
+// 组件直接来自自己的官方地址；OAuth网页仍通过N主机出口。
+export function profileSettings(config, profileDir, platform = process.platform, arch = process.arch) {
+    if (typeof profileDir !== 'string' || !isAbsolute(profileDir))
+        return config;
+    const runtime = platform === 'darwin' && arch === 'arm64' ? ELECTRON_PIN : {};
+    return { ...config, commandOutputMaxBytes: config.commandOutputMaxBytes === undefined ? L_DEFAULTS.commandOutputMaxBytes : config.commandOutputMaxBytes, helper: { ...runtime, componentDownloadMaxRedirects: L_DEFAULTS.componentDownloadMaxRedirects, maxDownloadBytes: L_DEFAULTS.maxDownloadBytes, maxExtractedBytes: L_DEFAULTS.maxExtractedBytes, loginOutputMaxBytes: L_DEFAULTS.loginOutputMaxBytes, ipcMaxBytes: L_DEFAULTS.ipcMaxBytes, remoteKillGraceMs: L_DEFAULTS.remoteKillGraceMs, ...config.helper, cacheDir: config.helper?.cacheDir === undefined ? join(profileDir, 'ai-workbench-connect', 'login-component-cache') : config.helper.cacheDir } };
+}

package/lib/projects.d.ts

@@ -0,0 +1,4 @@
+import type { Ports } from './ports.ts';
+import type { Runner } from './ssh.ts';
+export declare function isProjectName(name: string): boolean;
+export declare function createProjects(runner: Runner): NonNullable<Ports['projects']>;

package/lib/projects.js

@@ -0,0 +1,41 @@
+import { readFile } from 'node:fs/promises';
+import { runRemote } from "./ssh.js";
+import { fail, ok } from "./needs.js";
+export function isProjectName(name) { return typeof name === 'string' && name !== '' && name !== '.' && name !== '..' && !/[\\/\x00-\x1f\x7f]/.test(name); }
+const codes = ['PROJECT_ROOT_INVALID', 'PROJECT_EXISTS', 'PROJECT_INIT_FAILED', 'PROJECT_CREATE_FAILED', 'PROJECT_LIST_FAILED', 'PROJECT_NAME_INVALID'];
+const reasons = new Set(['invalid-name', 'symlink', 'not-directory', 'permissions', 'not-git', 'invalid-git', 'outside-root']);
+function validProject(value, root) {
+    return typeof value === 'object' && value !== null && 'name' in value && typeof value.name === 'string' && isProjectName(value.name) && 'path' in value && value.path === root + '/' + value.name;
+}
+export function createProjects(runner) {
+    const request = async (t, operation, signal, name) => {
+        if (operation === 'create' && !isProjectName(name))
+            return fail('PROJECT_NAME_INVALID');
+        try {
+            const source = await readFile(new URL('../helper/projects.cjs', import.meta.url), 'utf8');
+            const command = 'node -e ' + "'" + (source + '\nmain();').replaceAll("'", "'\\''") + "'";
+            const raw = await runRemote(runner, t, command, signal, JSON.stringify({ protocolVersion: 1, operation, root: t.projectRoot, ...(operation === 'create' ? { name } : {}) }));
+            if (signal.aborted)
+                return fail('CONNECTION_LOST');
+            if (raw.exitCode !== 0)
+                return fail(operation === 'list' ? 'PROJECT_LIST_FAILED' : 'PROJECT_CREATE_FAILED');
+            const result = JSON.parse(raw.stdout);
+            if (result.protocolVersion !== 1 || typeof result.ok !== 'boolean')
+                return fail('PROJECT_PROTOCOL_INVALID');
+            if (!result.ok) {
+                const code = codes.find(code => code === result.error?.code);
+                return fail(code ?? 'PROJECT_PROTOCOL_INVALID');
+            }
+            if (operation === 'create')
+                return validProject(result.value, t.projectRoot) && result.value.name === name ? ok(result.value) : fail('PROJECT_PROTOCOL_INVALID');
+            const list = result.value;
+            if (!list || !Array.isArray(list.projects) || !Array.isArray(list.unavailable) || !list.projects.every((p) => validProject(p, t.projectRoot)) || !list.unavailable.every((p) => p && typeof p.name === 'string' && reasons.has(p.reason)))
+                return fail('PROJECT_PROTOCOL_INVALID');
+            return ok(list);
+        }
+        catch {
+            return fail(operation === 'list' ? 'PROJECT_LIST_FAILED' : 'PROJECT_CREATE_FAILED');
+        }
+    };
+    return { list: (t, s) => request(t, 'list', s), create: (t, n, s) => request(t, 'create', s, n) };
+}

package/lib/provider.d.ts

@@ -0,0 +1,73 @@
+import type { Ports } from './ports.ts';
+import type { ProxyLease } from './login.ts';
+interface NNeed {
+    code: string;
+}
+type NResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: NNeed;
+};
+export interface ActivationSettings {
+    configFile: string;
+    helperLogFile: string;
+    startupObservationSeconds: number;
+    shutdownObservationSeconds: number;
+    controlResponseMaxBytes: number;
+    downloadMaxRedirects: number;
+}
+export interface ActivationState {
+    instanceId: string;
+    revision: number;
+    phase: 'unconfigured' | 'activating' | 'active' | 'blocked' | 'stopped';
+    receipt: {
+        apiVersion: 1;
+        session: 'key' | 'identity';
+        key: 'not-required' | 'unattempted' | 'attempted' | 'confirmed' | 'unknown';
+        identity: 'unconfirmed' | 'resumable';
+        cleanup: 'not-required' | 'pending' | 'complete';
+    } | null;
+    error: NNeed | null;
+}
+export interface NetworkProvider {
+    activate?(settings: ActivationSettings, signal: AbortSignal): Promise<NResult<ActivationState>>;
+    getActivationState?(): ActivationState;
+    onActivationState?(listener: (state: ActivationState) => void): () => void;
+    getState(): {
+        phase: string;
+        error?: NNeed;
+        status?: {
+            host: {
+                lastSeenAt: string | null;
+            };
+        };
+    };
+    connect(target: {
+        host: string;
+        username: string;
+        port: number;
+        knownHostsFile: string;
+    }, signal: AbortSignal): Promise<NResult<{
+        proxyCommand: string;
+    }>>;
+    onState(listener: (event: {
+        kind: 'lost' | 'restored';
+    }) => void): () => void;
+    openLoginProxy(signal: AbortSignal): Promise<NResult<{
+        credentials: {
+            url: string;
+            username: string;
+            password: string;
+        };
+        release(): Promise<void>;
+    }>>;
+    download(source: string, signal: AbortSignal): Promise<NResult<Response>>;
+}
+export declare function mapNetworkNeed(value: NNeed): import("./api.ts").ConnectNeed;
+export declare function adaptNetwork(provider: NetworkProvider): NonNullable<Ports['network']> & {
+    acquireProxy(signal: AbortSignal): Promise<ProxyLease>;
+    download(source: string, signal: AbortSignal): Promise<Response>;
+};
+export {};

package/lib/provider.js

@@ -0,0 +1,39 @@
+import { NeedError, need } from "./needs.js";
+export function mapNetworkNeed(value) {
+    const code = { NEED_ENROLLMENT: 'ENROLLMENT_REQUIRED', ENROLLMENT_REJECTED: 'ENROLLMENT_REJECTED', ENROLLMENT_RESULT_UNKNOWN: 'ENROLLMENT_RESULT_UNKNOWN', LOCAL_STATE_INVALID: 'ENROLLMENT_INVALID', HOST_OFFLINE: 'HOST_OFFLINE', HOST_TRUST_REQUIRED: 'HOST_TRUST_REQUIRED', HOST_KEY_MISMATCH: 'HOST_KEY_MISMATCH', ENROLLMENT_MISMATCH: 'ENROLLMENT_INVALID', CONFIG_INVALID: 'SETTINGS_REQUIRED', SETTINGS_REQUIRED: 'SETTINGS_REQUIRED', SSH_FAILED: 'SSH_FAILED', NETWORK_INTERRUPTED: 'CONNECTION_LOST', CONTROL_UNAVAILABLE: 'CONNECTION_LOST', NETWORK_NOT_READY: 'CONNECTION_LOST', DISPOSED: 'DISPOSED' }[value.code] ?? 'DEPENDENCY_REQUIRED';
+    const direct = ['ACTIVATION_CONFLICT', 'ACTIVATION_CANCELLED', 'ENROLLMENT_CLEANUP_UNBOUND', 'ENROLLMENT_CLEANUP_FAILED', 'ENROLLMENT_MISMATCH', 'LOCAL_STATE_INVALID', 'ALREADY_RUNNING', 'ENROLLMENT_RECEIPT_REQUIRED', 'CONTROL_PROTOCOL_INVALID', 'HELPER_HANDOFF_FAILED', 'HELPER_SHUTDOWN_FORCED'];
+    const result = need(direct.includes(value.code) ? value.code : code);
+    result.officialReason = /^[A-Z][A-Z0-9_]*$/.test(value.code) ? value.code : 'NETWORK_NEED_INVALID';
+    return result;
+}
+export function adaptNetwork(provider) {
+    return {
+        async connect(e, signal) {
+            const result = await provider.connect({ host: e.host, username: e.username, port: e.port, knownHostsFile: e.knownHostsFile }, signal);
+            if (result.ok)
+                return result;
+            const error = mapNetworkNeed(result.error), lastSeen = provider.getState().status?.host.lastSeenAt;
+            if (error.code === 'HOST_OFFLINE' && typeof lastSeen === 'string' && !Number.isNaN(Date.parse(lastSeen)))
+                error.lastSeen = lastSeen;
+            return { ok: false, error };
+        },
+        onState(listener) { return provider.onState(event => { if (event.kind === 'lost' || event.kind === 'restored')
+            listener({ kind: event.kind }); }); },
+        async acquireProxy(signal) {
+            const result = await provider.openLoginProxy(signal);
+            if (!result.ok)
+                throw new NeedError(mapNetworkNeed(result.error));
+            const source = result.value, credentials = source.credentials;
+            let release;
+            return { url: credentials.url, get username() { return credentials.username; }, get password() { return credentials.password; }, release: () => release ??= (async () => { try {
+                    await source.release();
+                }
+                finally {
+                    credentials.username = '';
+                    credentials.password = '';
+                } })() };
+        },
+        async download(source, signal) { const result = await provider.download(source, signal); if (!result.ok)
+            throw new NeedError(mapNetworkNeed(result.error)); return result.value; },
+    };
+}

package/lib/remote-login.d.ts

@@ -0,0 +1,2 @@
+import type { Provider } from './api.ts';
+export declare function remoteLoginCommand(provider: Provider, killGraceMs: number, probeIsolate?: boolean): string;

package/lib/remote-login.js

@@ -0,0 +1,9 @@
+import { readFileSync } from 'node:fs';
+export function remoteLoginCommand(provider, killGraceMs, probeIsolate = false) {
+    if (provider !== 'claude' && provider !== 'codex')
+        throw Error('LOGIN_PROVIDER_INVALID');
+    if (!Number.isSafeInteger(killGraceMs) || killGraceMs < 0 || killGraceMs > 2147483647)
+        throw Error('REMOTE_KILL_GRACE_REQUIRED');
+    const source = readFileSync(new URL('../helper/remote-login.cjs', import.meta.url), 'utf8');
+    return "node -e '" + source.replaceAll("'", "'\\''") + "' -- " + provider + ' ' + killGraceMs + (probeIsolate ? ' --probe-isolate' : '');
+}

package/lib/ssh.d.ts

@@ -0,0 +1,10 @@
+import type { SshTarget } from './api.ts';
+import type { CommandResult, Ports } from './ports.ts';
+export declare function shellQuote(s: string): string;
+export declare function proxyCommand(binary: string, runtimeDir: string): string;
+export declare function sshArgs(t: SshTarget): string[];
+export interface Runner {
+    run(cmd: string, args: string[], signal: AbortSignal, input?: string): Promise<CommandResult>;
+}
+export declare function runRemote(runner: Runner, t: SshTarget, command: string, signal: AbortSignal, input?: string): Promise<CommandResult>;
+export declare function createSsh(runner: Runner, maxOutputBytes?: number): NonNullable<Ports['ssh']>;

package/lib/ssh.js

@@ -0,0 +1,78 @@
+import { readFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { fail, ok } from "./needs.js";
+export function shellQuote(s) {
+    if (/[\x00-\x1f\x7f%]/.test(s))
+        throw new Error('INVALID_PROXY_PATH');
+    return "'" + s.replaceAll("'", "'\\''") + "'";
+}
+export function proxyCommand(binary, runtimeDir) {
+    if (!binary.startsWith('/') || !runtimeDir.startsWith('/'))
+        throw new Error('ABSOLUTE_PROXY_PATH_REQUIRED');
+    return `${shellQuote(binary)} ssh-proxy --runtime-dir ${shellQuote(runtimeDir)} %h %p`;
+}
+export function sshArgs(t) {
+    return ['-F', '/dev/null', '-T', '-o', 'IdentityAgent=none', '-o', 'PubkeyAuthentication=no', '-o', 'PasswordAuthentication=no', '-o', 'KbdInteractiveAuthentication=no', '-o', 'PreferredAuthentications=none', '-o', 'UpdateHostKeys=no', '-o', 'CanonicalizeHostname=no', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'GlobalKnownHostsFile=/dev/null', '-o', 'UserKnownHostsFile=' + JSON.stringify(t.knownHostsFile.replaceAll('%', '%%')), '-o', 'ProxyCommand=' + t.proxyCommand, '-p', String(t.port), '-l', t.username, t.host];
+}
+export async function runRemote(runner, t, command, signal, input) {
+    const nonce = randomUUID(), source = await readFile(new URL('../helper/remote-command.cjs', import.meta.url), 'utf8');
+    const remote = 'node -e ' + "'" + source.replaceAll("'", "'\\''") + "'";
+    const raw = await runner.run('ssh', [...sshArgs(t), remote], signal, JSON.stringify({ protocolVersion: 1, nonce, command, ...input === undefined ? {} : { input } }));
+    if (signal.aborted || raw.exitCode !== 0 || raw.stderr !== '')
+        throw Error('REMOTE_RESULT_INVALID');
+    const lines = raw.stdout.split('\n');
+    if (lines.pop() !== '')
+        throw Error('REMOTE_RESULT_INVALID');
+    let started = false, ended = false, exitCode = null;
+    const out = [], err = [];
+    for (const line of lines) {
+        const v = JSON.parse(line);
+        if (!v || typeof v !== 'object' || v.protocolVersion !== 1 || v.nonce !== nonce || ended)
+            throw Error('REMOTE_RESULT_INVALID');
+        const keys = Object.keys(v).sort().join(',');
+        if (v.type === 'start' && !started && keys === 'nonce,protocolVersion,type') {
+            started = true;
+            continue;
+        }
+        if (!started)
+            throw Error('REMOTE_RESULT_INVALID');
+        if ((v.type === 'stdout' || v.type === 'stderr') && keys === 'data,nonce,protocolVersion,type' && typeof v.data === 'string') {
+            const bytes = Buffer.from(v.data, 'base64');
+            if (bytes.toString('base64') !== v.data)
+                throw Error('REMOTE_RESULT_INVALID');
+            (v.type === 'stdout' ? out : err).push(bytes);
+            continue;
+        }
+        if (v.type === 'end' && keys === 'exitCode,nonce,protocolVersion,signal,type' && Number.isInteger(v.exitCode) && v.exitCode >= 0 && v.exitCode <= 255 && v.signal === null) {
+            ended = true;
+            exitCode = v.exitCode;
+            continue;
+        }
+        throw Error('REMOTE_RESULT_INVALID');
+    }
+    if (!ended || exitCode === null)
+        throw Error('REMOTE_RESULT_INVALID');
+    return { exitCode, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8') };
+}
+export function createSsh(runner, maxOutputBytes) {
+    return {
+        verify: async (t, signal) => { try {
+            const r = await runRemote(runner, t, 'id -un', signal);
+            return r.exitCode === 0 && r.stdout.trim() === t.username ? ok(undefined) : fail('SSH_FAILED');
+        }
+        catch {
+            return fail('SSH_FAILED');
+        } },
+        status: async (t, p, signal) => {
+            try {
+                if (!['codex', 'claude'].includes(p) || !Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1)
+                    return fail('AUTH_STATUS_INVALID');
+                const source = await readFile(new URL('../helper/auth-status.cjs', import.meta.url), 'utf8');
+                return ok(await runRemote(runner, t, 'node -e ' + "'" + source.replaceAll("'", "'\\''") + "' -- " + p + ' ' + maxOutputBytes, signal));
+            }
+            catch {
+                return fail('AUTH_STATUS_INVALID');
+            }
+        },
+    };
+}

package/lib/startup.d.ts

@@ -0,0 +1,18 @@
+import type { ConnectApi, ConnectionState, LoginPromptState, LoginPromptResult, Provider, NeedCode, Result } from './api.ts';
+export type StartupState = LoginPromptState;
+export declare function employeeMessage(code?: NeedCode): string;
+type Operations = Pick<ConnectApi, 'connect' | 'checkLogin' | 'login' | 'getState'>;
+export declare function createStartup(api: Operations, providers: Provider[], emit?: (s: LoginPromptState) => void, result?: (r: LoginPromptResult) => void, instanceId?: string): {
+    getState: () => LoginPromptState;
+    check: () => Promise<void>;
+    subscribe(listener: (s: LoginPromptState) => void): () => void;
+    request(provider: Provider, intent: "automatic" | "user"): Promise<Result<LoginPromptState>>;
+    respond: (requestId: string, action: "authorize" | "defer") => Promise<Result<LoginPromptState>>;
+    defer(provider: Provider): void;
+    authorize(provider: Provider): Promise<void>;
+    connectionChanged(next: ConnectionState): void;
+    stop(): void;
+    dispose(): Promise<void>;
+};
+export type Startup = ReturnType<typeof createStartup>;
+export {};

package/lib/startup.js

@@ -0,0 +1,211 @@
+import { randomUUID } from 'node:crypto';
+import { fail, need, ok } from "./needs.js";
+export function employeeMessage(code) {
+    if (code === 'ENROLLMENT_RESULT_UNKNOWN' || code === 'ENROLLMENT_REJECTED')
+        return need(code).message;
+    if (code === 'DEPENDENCY_REQUIRED')
+        return '远程主机连接尚未准备好，请联系管理员。';
+    if (code === 'ENROLLMENT_REQUIRED' || code === 'ENROLLMENT_INVALID' || code === 'NETWORK_KEY_INVALID')
+        return '我需要连接资料，请联系管理员发放。';
+    if (code === 'SETTINGS_REQUIRED')
+        return '远程主机连接还没有设置好，请联系管理员。';
+    if (code === 'LOGIN_FAILED')
+        return '登录没有完成。你可以再次请求登录，或稍后再试。';
+    if (code === 'POLICY_DENIED')
+        return '这个账号暂时不能使用，请联系公司账号管理员。';
+    return '远程主机暂时连不上，请联系管理员。';
+}
+export function createStartup(api, providers, emit = () => { }, result = () => { }, instanceId = randomUUID()) {
+    let disposed = false, revision = 0, serial = 0, generation = 0, checkSerial = 0, connectionPhase = 'unavailable', observedConnected = false;
+    let flight, authorization, authorizationId;
+    const pending = new Set(), listeners = new Set(), deferred = new Set();
+    let state = { instanceId, revision: 0, phase: 'checking', message: '正在连接远程主机…', logins: {}, checkingProviders: [], providerNeeds: {}, technicalDetails: {} };
+    const publish = (next) => { state = { ...next, instanceId, revision: ++revision }; emit(structuredClone(state)); for (const listener of listeners)
+        listener(structuredClone(state)); };
+    const track = (p) => { pending.add(p); void p.then(() => pending.delete(p), () => pending.delete(p)); return p; };
+    const close = (outcome, code) => { if (state.requestId && state.provider)
+        result({ requestId: state.requestId, provider: state.provider, outcome, ...(code ? { need: need(code) } : {}) }); };
+    const blocked = (code) => { close('invalidated', code); publish({ phase: 'blocked', message: employeeMessage(code), logins: {}, checkingProviders: [], providerNeeds: {}, technicalDetails: { ...state.technicalDetails, code } }); };
+    const snapshot = () => state.phase === 'disposed' ? fail('DISPOSED') : state.phase === 'blocked' ? fail(state.technicalDetails.code ?? 'AUTH_STATUS_INVALID') : ok(structuredClone(state));
+    const ask = () => {
+        const provider = state.requestId && state.provider && state.logins[state.provider] === false && !deferred.has(state.provider) ? state.provider : providers.find(p => state.logins[p] === false && !deferred.has(p));
+        const same = provider && state.provider === provider && state.requestId && state.phase === 'login-required';
+        publish({ ...state, phase: provider ? 'login-required' : 'idle', provider, requestId: provider ? (same ? state.requestId : 'login-' + instanceId + '-' + (++serial)) : undefined, message: provider ? '需要登录，请到设置 → 远程主机连接 点登录' : Object.keys(state.providerNeeds).length ? Object.keys(state.providerNeeds).map(p => p === 'claude' ? 'Claude' : 'Codex').join('、') + ' 登录状态无法确认，请联系管理员。' : '远程主机连接检查完成。' });
+    };
+    const check = () => {
+        if (disposed)
+            return Promise.resolve();
+        if (authorization)
+            return Promise.resolve();
+        if (flight)
+            return flight;
+        const mine = generation, checkMine = ++checkSerial;
+        const run = async () => {
+            try {
+                // Preserve an existing question while gathering fresh evidence, so duplicate requests keep its ticket.
+                publish({ ...state, ...(!state.requestId ? { phase: 'checking', message: '正在检查登录状态…' } : {}), checkingProviders: [] });
+                const connected = await api.connect();
+                if (disposed || mine !== generation || checkMine !== checkSerial)
+                    return;
+                if (!connected.ok) {
+                    blocked(connected.error.code);
+                    return;
+                }
+                const logins = { ...state.logins }, providerNeeds = { ...state.providerNeeds };
+                for (const provider of providers) {
+                    publish({ ...state, checkingProviders: [provider] });
+                    const status = await api.checkLogin(provider);
+                    if (disposed || mine !== generation || checkMine !== checkSerial)
+                        return;
+                    if (!status.ok) {
+                        if (status.error.layer !== 'auth' && !['AUTH_STATUS_INVALID', 'LOGIN_FAILED', 'POLICY_DENIED'].includes(status.error.code)) {
+                            blocked(status.error.code);
+                            return;
+                        }
+                        delete logins[provider];
+                        providerNeeds[provider] = status.error;
+                    }
+                    else {
+                        logins[provider] = status.value.loggedIn;
+                        delete providerNeeds[provider];
+                    }
+                    if (state.requestId && state.provider === provider && logins[provider] !== false) {
+                        close(logins[provider] === true ? 'logged-in' : 'invalidated', providerNeeds[provider]?.code);
+                        publish({ ...state, requestId: undefined, provider: undefined, phase: 'checking', message: '正在检查登录状态…' });
+                    }
+                    publish({ ...state, logins: { ...logins }, providerNeeds: { ...providerNeeds }, checkingProviders: state.checkingProviders.filter(p => p !== provider) });
+                }
+                if (state.requestId && state.provider && logins[state.provider] === true) {
+                    close('logged-in');
+                    publish({ ...state, requestId: undefined, provider: undefined, phase: 'checking', message: '正在检查登录状态…' });
+                }
+                publish({ ...state, logins, providerNeeds, checkingProviders: [], technicalDetails: connected.value.hostContext ? { hostContext: structuredClone(connected.value.hostContext) } : {} });
+                ask();
+            }
+            catch {
+                if (!disposed && mine === generation && checkMine === checkSerial)
+                    blocked('DEPENDENCY_REQUIRED');
+            }
+        };
+        const promise = track(run());
+        flight = promise;
+        void promise.then(() => { if (flight === promise)
+            flight = undefined; });
+        return promise;
+    };
+    const providerFailed = (provider, code, sourceNeed = need(code)) => {
+        const logins = { ...state.logins };
+        delete logins[provider];
+        publish({ ...state, phase: 'idle', requestId: undefined, provider: undefined, logins, checkingProviders: [], providerNeeds: { ...state.providerNeeds, [provider]: structuredClone(sourceNeed) } });
+        ask();
+    };
+    const respond = (requestId, action) => {
+        if (disposed)
+            return Promise.resolve(fail('DISPOSED'));
+        if (action === 'authorize' && authorization && authorizationId === requestId)
+            return authorization;
+        if (!requestId || state.requestId !== requestId || state.phase !== 'login-required' || !state.provider || !['authorize', 'defer'].includes(action))
+            return Promise.resolve(fail('LOGIN_PROMPT_INVALID'));
+        const provider = state.provider;
+        if (action === 'defer') {
+            close('deferred');
+            deferred.add(provider);
+            publish({ ...state, requestId: undefined, provider: undefined });
+            ask();
+            return Promise.resolve(snapshot());
+        }
+        if (authorization)
+            return Promise.resolve(fail('LOGIN_PROMPT_INVALID'));
+        const mine = generation;
+        checkSerial++;
+        authorizationId = requestId;
+        publish({ ...state, phase: 'authorizing', checkingProviders: [provider], message: '请在授权窗口完成本人登录。' });
+        const run = async () => {
+            try {
+                await flight;
+                if (disposed || mine !== generation)
+                    return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+                const current = await api.checkLogin(provider);
+                if (disposed || mine !== generation)
+                    return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+                const verified = current.ok && current.value.loggedIn ? current : current.ok ? await api.login(provider) : current;
+                if (disposed || mine !== generation)
+                    return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+                if (!verified.ok || !verified.value.loggedIn) {
+                    const code = verified.ok ? 'LOGIN_FAILED' : verified.error.code;
+                    result({ requestId, provider, outcome: 'failed', need: need(code) });
+                    providerFailed(provider, code, verified.ok ? need(code) : verified.error);
+                    return verified.ok ? fail(code) : verified;
+                }
+                result({ requestId, provider, outcome: 'logged-in' });
+                deferred.delete(provider);
+                const providerNeeds = { ...state.providerNeeds };
+                delete providerNeeds[provider];
+                publish({ ...state, requestId: undefined, provider: undefined, logins: { ...state.logins, [provider]: true }, providerNeeds, checkingProviders: [], phase: 'idle' });
+                ask();
+                return snapshot();
+            }
+            catch {
+                if (disposed || mine !== generation)
+                    return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+                result({ requestId, provider, outcome: 'failed', need: need('LOGIN_FAILED') });
+                providerFailed(provider, 'LOGIN_FAILED');
+                return fail('LOGIN_FAILED');
+            }
+        };
+        const promise = track(run());
+        authorization = promise;
+        void promise.then(() => { if (authorization === promise) {
+            authorization = undefined;
+            authorizationId = undefined;
+        } });
+        return promise;
+    };
+    return { getState: () => structuredClone(state), check,
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        async request(provider, intent) {
+            if (!providers.includes(provider) || !['automatic', 'user'].includes(intent))
+                return fail('AUTH_STATUS_INVALID');
+            const mine = generation;
+            if (intent === 'user')
+                deferred.delete(provider);
+            if (authorization)
+                return state.providerNeeds[provider] ? { ok: false, error: structuredClone(state.providerNeeds[provider]) } : snapshot();
+            await check();
+            if (disposed || mine !== generation)
+                return fail(disposed ? 'DISPOSED' : 'CONNECTION_LOST');
+            if (intent === 'user' && !authorization && state.logins[provider] === false && !state.providerNeeds[provider] && !state.checkingProviders.includes(provider) && state.phase !== 'blocked' && state.phase !== 'disposed' && state.provider !== provider) {
+                close('invalidated', 'LOGIN_PROMPT_INVALID');
+                publish({ ...state, phase: 'login-required', provider, requestId: 'login-' + instanceId + '-' + (++serial), message: '需要登录，请到设置 → 远程主机连接 点登录' });
+            }
+            return state.providerNeeds[provider] ? { ok: false, error: structuredClone(state.providerNeeds[provider]) } : snapshot();
+        }, respond,
+        // Internal compatibility facade. HTTP and public API must use ticketed responses.
+        defer(provider) { if (state.provider === provider && state.requestId)
+            void respond(state.requestId, 'defer'); },
+        async authorize(provider) { if (state.provider === provider && state.requestId)
+            await respond(state.requestId, 'authorize'); },
+        connectionChanged(next) {
+            if (disposed)
+                return;
+            const prior = connectionPhase;
+            connectionPhase = next.phase;
+            if (next.phase === 'unavailable' || next.phase === 'disposed') {
+                generation++;
+                flight = undefined;
+                blocked(next.need?.code ?? (next.phase === 'disposed' ? 'DISPOSED' : 'CONNECTION_LOST'));
+            }
+            else if (next.phase === 'connected' && prior !== 'connected') {
+                const restored = observedConnected;
+                observedConnected = true;
+                if (restored) {
+                    const mine = generation;
+                    queueMicrotask(() => { void Promise.resolve(authorization).then(() => { if (!disposed && mine === generation && connectionPhase === 'connected')
+                        void check(); }); });
+                }
+            }
+        },
+        stop() { if (disposed)
+            return; disposed = true; generation++; close('invalidated', 'DISPOSED'); publish({ phase: 'disposed', message: '远程主机连接已关闭。', logins: {}, checkingProviders: [], providerNeeds: {}, technicalDetails: { code: 'DISPOSED' } }); listeners.clear(); },
+        async dispose() { this.stop(); await Promise.allSettled([...pending]); }, };
+}

package/lib/workspace-bindings.d.ts

@@ -0,0 +1,32 @@
+import type { ConnectApi, SessionProjectTarget, Result, ConnectionState, WorkspaceBindingState, WorkspaceNoticeReceipt, WorkspaceUse } from './api.ts';
+export interface NativeWorkspace {
+    id: string;
+    path: string;
+    title: string;
+    sessionIds: string[];
+}
+export interface NativeWorkspaceRegistry {
+    get(id: string): NativeWorkspace | undefined;
+    list(): NativeWorkspace[];
+}
+export interface WorkspaceBindingOptions {
+    profileDir: string;
+    metadataMaxBytes: number;
+    api: Pick<ConnectApi, 'getConnectionState' | 'getSshTarget' | 'listProjects' | 'createProject' | 'ensureReady'>;
+    registry: NativeWorkspaceRegistry;
+    readHeader: (sessionId: string) => Promise<{
+        id: string;
+        cwd?: string;
+    } | undefined>;
+    nextRevision?: () => number;
+    onState?: (state: WorkspaceBindingState) => void;
+    diagnostic?: (error: unknown) => void;
+}
+export declare function createWorkspaceBindings(options: WorkspaceBindingOptions): {
+    observeConnection(state: ConnectionState): void;
+    dispose(): Promise<unknown>;
+    getWorkspaceBindingState: () => WorkspaceBindingState;
+    onWorkspaceBindingState(listener: (state: WorkspaceBindingState) => void): () => void;
+    acknowledgeWorkspaceNotice: (receipt: WorkspaceNoticeReceipt) => Promise<Result<void>>;
+    resolveSessionProject: (sessionId: string, use: WorkspaceUse) => Promise<Result<SessionProjectTarget>>;
+};