@ai-workbench/remote-agent 0.8.11 → 0.8.13

package/dist/index.js

@@ -1,3 +1,5 @@
+import { runCatalog } from "./catalog-ssh.js";
+import { createCatalogDiagnostics, CatalogDiagnosticsRemote } from "./catalog-diagnostics.js";
 import { SessionId } from '@deepseek-ai/dsh-session';
 import Schema from '@deepseek-ai/schemastery';
 import { LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm';
@@ -31,6 +33,7 @@ import { createClaudeLocalProvider } from "./claude-local.js";
 import { readLocalUserTurn } from "./local-user-turn.js";
 import { readEmployeeWorkspace } from "./employee-workspace.js";
 import { createModelDefaults, createDefaultSelectionWriter } from "./model-defaults.js";
+import { createPreflightDiagnostics } from "./preflight-diagnostic.js";
 import { installModelInputRetention, markModelPreparationFailure } from "./model-input-retention.js";
 export const name = 'ai-workbench-remote-agent';
 export const settingsNamespace = 'ai-workbench-codex';
@@ -68,6 +71,23 @@ function readPointer(options, agent) {
         throw new NeedError('SESSION_CONTEXT_DIGEST_INVALID', '原Codex会话的初建上下文摘要未知或无效，不能猜测是否相同，本轮未发送', '原会话合法的64位十六进制初建上下文摘要');
     return pointer;
 }
+// A reporting failure can wrap the original admission error. Preserve its
+// already-safe login snapshot even when a newer preflight delivery is unknown.
+function originalLoginFailure(error) {
+    const pending = [error], seen = new Set();
+    while (pending.length) {
+        const current = pending.pop();
+        if (!current || typeof current !== 'object' || seen.has(current))
+            continue;
+        seen.add(current);
+        if (current instanceof NeedError && current.technical)
+            return current;
+        if (current instanceof AggregateError)
+            pending.push(...current.errors);
+        if (current instanceof Error && current.cause !== undefined)
+            pending.push(current.cause);
+    }
+}
 export class CodexRemoteAdapter extends LlmAdapter {
     resolveRuntime;
     approve;
@@ -76,6 +96,7 @@ export class CodexRemoteAdapter extends LlmAdapter {
     readImage;
     reportLoginFailure;
     directory;
+    preflightDiagnostics;
     config;
     sessions = new Map();
     turns = new Map();
@@ -83,7 +104,7 @@ export class CodexRemoteAdapter extends LlmAdapter {
     shuttingDown = false;
     detached = new Set();
     cleanups = new WeakMap();
-    constructor(config, resolveRuntime, approve, providerName = () => PROVIDER_NAMES.en, agent = CODEX_AGENT, readImage, reportLoginFailure, directory) {
+    constructor(config, resolveRuntime, approve, providerName = () => PROVIDER_NAMES.en, agent = CODEX_AGENT, readImage, reportLoginFailure, directory, preflightDiagnostics) {
         super();
         this.resolveRuntime = resolveRuntime;
         this.approve = approve;
@@ -92,6 +113,7 @@ export class CodexRemoteAdapter extends LlmAdapter {
         this.readImage = readImage;
         this.reportLoginFailure = reportLoginFailure;
         this.directory = directory;
+        this.preflightDiagnostics = preflightDiagnostics;
         this.config = typeof config === 'function' ? config : () => config;
     }
     providerInfo(provider) { return { id: provider, name: this.providerName() }; }
@@ -187,10 +209,11 @@ export class CodexRemoteAdapter extends LlmAdapter {
             if (error instanceof NeedError) {
                 const rpc = /RPC 错误码 (-?\d+)/u.exec(error.requires)?.[1];
                 const message = employeeFailure(error.code, this.agent.loginProvider) + (rpc ? `（技术详情：RPC 错误码 ${rpc}）` : '');
-                let diagnostic = error.technical ? JSON.stringify(error.technical) : '';
-                if (error.technical && this.reportLoginFailure) {
+                const login = originalLoginFailure(error);
+                let diagnostic = login?.technical ? JSON.stringify(login.technical) : '';
+                if (login?.technical && this.reportLoginFailure) {
                     try {
-                        const receipt = await this.reportLoginFailure(options.sessionId, error.code, error.technical);
+                        const receipt = await this.reportLoginFailure(options.sessionId, login.code, login.technical);
                         diagnostic += '；诊断 eventId=' + receipt.eventId;
                     }
                     catch (failure) {
@@ -230,6 +253,10 @@ export class CodexRemoteAdapter extends LlmAdapter {
         let modelConfiguration;
         const config = this.config();
         const mode = this.agent.oneShot ? config.mode : 'session';
+        request = { sessionId: options.sessionId, mode: mode ?? 'session', timing, signal };
+        this.preflightDiagnostics?.begin(request, this.agent.loginProvider);
+        if (this.preflightDiagnostics)
+            request.recordEarlyFailure = (error, stage) => this.preflightDiagnostics.failure(request, this.agent.loginProvider, error, stage);
         try {
             if (!mode || (mode === 'session' && (!Number.isSafeInteger(config.acpMaxMessageBytes) || config.acpMaxMessageBytes < 1)))
                 throw new NeedError('SETTINGS_REQUIRED', '远程模型连接设置无效，请联系管理员检查', '有效的mode/acpMaxMessageBytes');
@@ -248,11 +275,13 @@ export class CodexRemoteAdapter extends LlmAdapter {
             const configuration = JSON.stringify([mode, config.acpMaxMessageBytes, config.brokerMaxFrameBytes, config.brokerControlMaxBytes, config.employeeShellKillGraceMs]);
             if (live && live.configuration !== configuration)
                 throw new NeedError('SESSION_CONTEXT_MISMATCH', '会话运行设置已改变，请新建会话', '原会话运行设置');
-            request = { timing, acpMaxMessageBytes: config.acpMaxMessageBytes, resumeSessionId: previous?.sessionId, recoveryCheckpointId: previous?.recoveryCheckpointId, sessionId: options.sessionId, mode, cwd: previous?.cwd, identity: previous?.identity, bindingId: previous?.bindingId, workspaceId: previous?.workspaceId, agent: this.agent, retainProcess: !!key && mode === 'session', signal, brokerSettings: Object.freeze({ brokerMaxFrameBytes: config.brokerMaxFrameBytes, brokerControlMaxBytes: config.brokerControlMaxBytes }) };
+            Object.assign(request, { timing, acpMaxMessageBytes: config.acpMaxMessageBytes, resumeSessionId: previous?.sessionId, recoveryCheckpointId: previous?.recoveryCheckpointId, sessionId: options.sessionId, mode, cwd: previous?.cwd, identity: previous?.identity, bindingId: previous?.bindingId, workspaceId: previous?.workspaceId, agent: this.agent, retainProcess: !!key && mode === 'session', signal, brokerSettings: Object.freeze({ brokerMaxFrameBytes: config.brokerMaxFrameBytes, brokerControlMaxBytes: config.brokerControlMaxBytes }) });
             const after = options.messages.findLastIndex(message => message.role === 'assistant' && !isWorkspaceNoticeMessage(message));
             request.userInputIds = Object.freeze(options.messages.slice(after + 1).flatMap(message => message.role === 'user' && message.source?.kind === 'user' && typeof message.id === 'string' ? [message.id] : []));
             request.userMessageIds = request.userInputIds;
+            earlyStage = 'source-context';
             await this.resolveRuntime.preflight?.(request);
+            earlyStage = 'input-prepare';
             let input = await timing.run('input-prepare', () => prepareInput(options, this.readImage));
             const contextSha256 = createHash('sha256').update(input.systemPrompt ?? '').digest('hex');
             request.contextSha256 = contextSha256;
@@ -525,7 +554,7 @@ export class CodexRemoteAdapter extends LlmAdapter {
                 request.recordEarlyFailure = undefined;
                 const code = error instanceof NeedError || error instanceof ModelConfigurationError ? error.code : error instanceof LlmError ? error.failure.code : signal.aborted ? 'ABORTED' : 'WORKSPACE_SOURCE_CONFIRMATION_FAILED';
                 try {
-                    await record(new NeedError(code, '来源确认后本轮在执行前失败。', '白名单阶段与错误代码'), earlyStage);
+                    await record(Object.assign(new NeedError(code, '本轮在执行前失败。', '白名单阶段与错误代码'), { cause: error }), earlyStage);
                 }
                 catch (failure) {
                     reportingFailure = { cause: failure };
@@ -576,8 +605,8 @@ export class CodexRemoteAdapter extends LlmAdapter {
 /** One official registration owns both routes, preserving opaque replay ownership. */
 export class RemoteAgentsAdapter extends LlmAdapter {
     adapters = new Map();
-    constructor(config, makeRuntime, approve, nameFor, readImage, reportLoginFailure, directory) { super(); for (const agent of AGENTS)
-        this.adapters.set(agent.id, new CodexRemoteAdapter(config, makeRuntime(agent), approve, () => nameFor(agent), agent, readImage, reportLoginFailure, directory)); }
+    constructor(config, makeRuntime, approve, nameFor, readImage, reportLoginFailure, directory, preflightDiagnostics) { super(); for (const agent of AGENTS)
+        this.adapters.set(agent.id, new CodexRemoteAdapter(config, makeRuntime(agent), approve, () => nameFor(agent), agent, readImage, reportLoginFailure, directory, preflightDiagnostics)); }
     adapter(provider) { const adapter = this.adapters.get(provider); if (!adapter)
         throw new LlmError('远程模型未注册', 'PROVIDER_NOT_FOUND'); return adapter; }
     providerInfo(provider) { return this.adapter(provider).providerInfo(provider); }
@@ -615,7 +644,8 @@ export function apply(ctx, live) {
         }
         return manager;
     };
-    let changed = () => { }, publishDiagnostics = () => { };
+    const preflightDiagnostics = createPreflightDiagnostics({ ctx, getApi: get, manager: managerForProfile });
+    let changed = () => { };
     const diagnostics = new Map();
     const diagnostic = (scope, provider, message) => {
         let entry = diagnostics.get(provider);
@@ -629,10 +659,13 @@ export function apply(ctx, live) {
             entry.delete(scope);
         else
             entry.set(scope, message);
-        publishDiagnostics();
     };
     let defaults;
-    const modelDirectory = new ModelCatalog(get, () => config().acpMaxMessageBytes, undefined, () => changed(), (brand, message) => {
+    const catalogDiagnostics = createCatalogDiagnostics(() => { const profile = ctx.get('profileContext'); return profile?.dir; });
+    // Public Loader Entry.options.id; optional when mounted without Loader.
+    const actualSettingsNamespace = ctx.fiber.entry?.options.id;
+    new CatalogDiagnosticsRemote(ctx, async () => ({ ...await catalogDiagnostics.snapshot(), settingsNamespace: actualSettingsNamespace ?? null, providers: AGENTS.map(agent => ({ provider: agent.id, name: agent.name[language], messages: [...(diagnostics.get(agent.id)?.values() ?? [])] })) }));
+    const modelDirectory = new ModelCatalog(get, () => config().acpMaxMessageBytes, (...args) => { const state = get()?.getConnectionState(); const connection = state ? { instanceId: state.instanceId, epoch: state.epoch, phase: state.phase } : null; return runCatalog(...args, event => catalogDiagnostics.record({ ...event, connection })); }, () => changed(), (brand, message) => {
         diagnostic('catalog', AGENTS.find(agent => agent.loginProvider === brand).id, message);
     }, (agent, models, assertCurrent) => defaults?.observe(agent, models, assertCurrent));
     const adapter = new RemoteAgentsAdapter(config, agent => {
@@ -668,7 +701,7 @@ export function apply(ctx, live) {
             };
             return runtime;
         };
-        const local = agent.loginProvider === 'claude' ? createClaudeLocalProvider({ getConnect: get, getNetwork: () => ctx.get('aiWorkbenchNetwork'), readWorkspace: id => readEmployeeWorkspace(ctx, id), readUserTurn: request => readLocalUserTurn(ctx, { sessionId: request.sessionId, route: agent.id, userMessageIds: request.userMessageIds ?? [] }), reportAdmissionFailure: (request, code) => managerForProfile().recordLocalFailure({ sessionId: request.sessionId, provider: 'claude', code }), recordUnscoped: (request, observation) => managerForProfile().recordLocalFailure({ sessionId: request.sessionId, provider: 'claude', code: observation.code, observation }), configuration: config, details, open }) : undefined;
+        const local = agent.loginProvider === 'claude' ? createClaudeLocalProvider({ getConnect: get, getNetwork: () => ctx.get('aiWorkbenchNetwork'), readWorkspace: id => readEmployeeWorkspace(ctx, id), readUserTurn: request => readLocalUserTurn(ctx, { sessionId: request.sessionId, route: agent.id, userMessageIds: request.userMessageIds ?? [] }), reportAdmissionFailure: (request, code) => preflightDiagnostics.failure(request, 'claude', code, 'local-admission'), recordUnscoped: (request, observation) => managerForProfile().recordLocalFailure({ sessionId: request.sessionId, provider: 'claude', code: observation.code, observation }), configuration: config, details, open }) : undefined;
         const workspace = async (request) => {
             const services = ctx;
             const registry = services.get('workspaceRegistry');
@@ -677,7 +710,7 @@ export function apply(ctx, live) {
         };
         return connectProvider(get, { agent, workspaceSource: {
                 workspace, currentUserTurn: request => localTurns.current(request), confirm: nativeWorkspaceSourceConfirmation(ctx),
-                record: (request, observation) => managerForProfile().recordLocalFailure({ sessionId: request.sessionId, provider: agent.loginProvider, code: observation.code, observation }),
+                record: (request, observation) => preflightDiagnostics.record(request, agent.loginProvider, observation),
             }, ...(agent.loginProvider === 'codex' ? { employee: {
                     currentUserTurn: request => localTurns.current(request),
                     getNetwork: () => ctx.get('aiWorkbenchNetwork'),
@@ -701,14 +734,13 @@ export function apply(ctx, live) {
                 step = null;
         }
         return managerForProfile().recordLoginFailure({ sessionId, code, diagnostic, context: { turn, step } });
-    }, modelDirectory);
+    }, modelDirectory, preflightDiagnostics);
     const ids = AGENTS.map(agent => agent.id);
-    const entries = () => AGENTS.map(agent => ({ provider: agent.id, displayName: agent.name[language], settingsNs: settingsNamespace, settingsPath: [], ...(diagnostics.get(agent.id)?.size ? { error: [...diagnostics.get(agent.id).values()].join('\n') } : {}) }));
+    const entries = () => AGENTS.map(agent => ({ provider: agent.id, displayName: agent.name[language], settingsNs: actualSettingsNamespace ?? settingsNamespace, settingsPath: [] }));
     const directory = ctx.llm.registerConfigurableProviders(entries());
     const registration = ctx.llm.registerAdapter(ids, adapter);
-    installModelInputRetention(ctx, { isOurProvider: provider => ids.includes(provider), diagnostic: (provider, message) => diagnostic('input', provider, message) });
+    installModelInputRetention(ctx, { isOurProvider: provider => ids.includes(provider), diagnosticForAttempt: position => preflightDiagnostics.forPreparation(position.sessionId, position), preflightDiagnostic: (provider, message) => diagnostic('preflight', provider, message), diagnostic: (provider, message) => diagnostic('input', provider, message) });
     const serviceValue = (name) => ctx.get(name);
-    publishDiagnostics = () => directory.replace(entries());
     const refreshDefault = () => {
         const service = serviceValue('agentDefaultModel');
         const selected = service?.currentSelection();

package/dist/local-user-turn.js

@@ -1,4 +1,5 @@
 import { SessionId } from '@deepseek-ai/dsh-session';
+import { sameStoredSessionHeader } from "./session-header.js";
 import { isDeepStrictEqual } from 'node:util';
 import { NeedError } from "./remote.js";
 const failure = (code = 'REMOTE_DETAIL_SCOPE_INVALID') => new NeedError(code, '本轮输入无法核对，已停止本次处理。', '官方当前员工输入与所选远程品牌');
@@ -20,7 +21,7 @@ export async function readLocalUserTurn(ctx, request) {
     let proof, firstFailure;
     try {
         assertCurrent();
-        if (handle.id !== id || handle.access !== 'read' || !isDeepStrictEqual(handle.header, header) || handle.inheritedEventCount !== session.inheritedEventCount)
+        if (handle.id !== id || handle.access !== 'read' || !sameStoredSessionHeader(handle.header, header) || handle.inheritedEventCount !== session.inheritedEventCount)
             throw failure();
         const { events } = await handle.read();
         assertCurrent();

package/dist/model-catalog.d.ts

@@ -2,6 +2,7 @@ import { type LlmResolvedModelInfo } from '@deepseek-ai/dsh-llm';
 import type { ModelCatalogTarget } from '@ai-workbench/connect/api';
 import type { AgentDefinition } from './agents.ts';
 import { type ConnectApi, type ConnectTarget } from './provider.ts';
+export { runCatalog } from './catalog-ssh.ts';
 export interface HostModel {
     id: string;
     value: string;
@@ -41,9 +42,7 @@ export declare function catalogDiagnostic(issues: readonly CatalogIssue[]): stri
 /** Defaults are provider declarations, never catalog order or display names. */
 export declare function declaredDefault(agent: AgentDefinition, models: readonly HostModel[]): HostModel | undefined;
 export declare function parseHostCatalog(input: string, provider: string, username: string): ParsedCatalog;
-/** Only the public L sshArgs function chooses SSH trust and transport arguments. */
-export declare const runCatalog: CatalogRunner;
-/** No cache: every query binds to L's current object, host-user and generation. */
+/** Share only pending work; settled results are never cached. */
 export declare class ModelCatalog implements ModelDirectory {
     private get;
     private maxBytes;
@@ -58,11 +57,15 @@ export declare class ModelCatalog implements ModelDirectory {
     private disposed;
     private initialized;
     private active;
+    private flights;
     private serial;
     private latest;
     constructor(get: () => ConnectApi | undefined, maxBytes: () => number | undefined, run?: CatalogRunner, changed?: () => void, diagnostic?: (provider: 'claude' | 'codex', message: string | undefined) => void, loaded?: (agent: AgentDefinition, models: readonly HostModel[], assertCurrent: () => void) => void | Promise<void>);
     refresh(): void;
     private trusted;
+    private assertFlight;
+    private failure;
+    private start;
     read(agent: AgentDefinition, signal?: AbortSignal): Promise<CatalogLease>;
     dispose(): void;
 }

package/dist/model-catalog.js

@@ -1,23 +1,15 @@
-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 { spawn } from 'node:child_process';
 import { LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
 import { sameTarget, validateTarget } from "./provider.js";
 import { ModelConfigurationError } from "./model-configuration.js";
-import { sanitizeObservation } from "./conversation-details.js";
+import { runCatalog, CatalogSshError, catalogSafeText } from "./catalog-ssh.js";
+export { runCatalog } from "./catalog-ssh.js";
 const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
 const text = (value) => typeof value === 'string' && value.trim().length > 0;
 class CatalogError extends LlmError {
     diagnostic;
     constructor(reason, diagnostic) { super('无法获取模型列表：' + reason, 'MODEL_CATALOG_UNAVAILABLE'); this.diagnostic = diagnostic + '（诊断代码：MODEL_CATALOG_UNAVAILABLE）'; }
 }
-const safe = (value) => sanitizeObservation({ kind: 'session', severity: 'warning', code: 'MODEL_CATALOG_DIAGNOSTIC', summary: value, payload: {} }).summary;
+const safe = catalogSafeText;
 function fail(reason, diagnostic = reason) { throw new CatalogError(reason, diagnostic); }
 function freeze(value) { if (value && typeof value === 'object') {
     for (const item of Object.values(value))
@@ -100,79 +92,7 @@ export function parseHostCatalog(input, provider, username) {
     }
     return freeze(structuredClone({ models, issues }));
 }
-/** Only the public L sshArgs function chooses SSH trust and transport arguments. */
-export const runCatalog = async (target, command, signal, maxBytes) => {
-    let argv;
-    try {
-        const moduleName = '@ai-workbench/connect';
-        const l = await import(__rewriteRelativeImportExtension(moduleName));
-        if (typeof l.sshArgs !== 'function')
-            fail('远程主机连接组件缺少可信 SSH 能力');
-        argv = l.sshArgs(target);
-    }
-    catch (error) {
-        if (error instanceof LlmError)
-            throw error;
-        fail('远程主机连接组件缺少可信 SSH 能力');
-    }
-    signal.throwIfAborted();
-    return new Promise((resolve, reject) => {
-        const child = spawn('ssh', ['-n', ...argv, command], { stdio: ['ignore', 'pipe', 'pipe'] });
-        const parts = [];
-        let total = 0, stderr = 0;
-        let failure;
-        const abort = () => { failure = new ModelConfigurationError('连接已改变或目录查询已取消'); child.kill('SIGTERM'); };
-        signal.addEventListener('abort', abort, { once: true });
-        const receive = (buffer, output) => { if (failure)
-            return; total += buffer.length; if (total > maxBytes) {
-            failure = new ModelConfigurationError('目录响应超过 acpMaxMessageBytes，未截断返回');
-            child.kill('SIGTERM');
-            return;
-        } if (output)
-            parts.push(buffer);
-        else
-            stderr += buffer.length; };
-        child.stdout.on('data', (b) => receive(b, true));
-        child.stderr.on('data', (b) => receive(b, false));
-        child.on('error', () => { failure = new ModelConfigurationError('可信 SSH 进程启动失败'); });
-        child.on('close', code => {
-            signal.removeEventListener('abort', abort);
-            if (failure) {
-                reject(failure);
-                return;
-            }
-            let output;
-            try {
-                output = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts));
-            }
-            catch {
-                reject(new ModelConfigurationError('主机目录响应不是有效 UTF-8，未替换模型值'));
-                return;
-            }
-            // S publishes its typed failure JSON on stdout even on nonzero exit.
-            if (code !== 0) {
-                try {
-                    const wire = JSON.parse(output);
-                    if (wire?.ok === false) {
-                        resolve(output);
-                        return;
-                    }
-                }
-                catch { }
-                reject(new ModelConfigurationError('可信 SSH 或主机目录命令失败（退出码 ' + String(code) + '）'));
-                return;
-            }
-            if (stderr) {
-                reject(new ModelConfigurationError('目录命令返回了非预期诊断输出'));
-                return;
-            }
-            resolve(output);
-        });
-        if (signal.aborted)
-            abort();
-    });
-};
-/** No cache: every query binds to L's current object, host-user and generation. */
+/** Share only pending work; settled results are never cached. */
 export class ModelCatalog {
     get;
     maxBytes;
@@ -187,6 +107,7 @@ export class ModelCatalog {
     disposed = false;
     initialized = false;
     active = new Set();
+    flights = new Map();
     serial = 0;
     latest = new Map();
     constructor(get, maxBytes, run = runCatalog, changed = () => { }, diagnostic = () => { }, loaded = () => { }) {
@@ -203,11 +124,10 @@ export class ModelCatalog {
         const state = api?.getConnectionState?.();
         const info = api?.getContractInfo?.();
         const targets = info?.modelCatalogTarget === 1 && api?.getModelCatalogTarget ? ['codex', 'claude'].map(brand => api.getModelCatalogTarget(brand)) : undefined;
-        const login = api?.getLoginPromptState?.();
         // L's same-epoch recovery wording is presentation metadata, not an execution change.
         const executionState = state && { instanceId: state.instanceId, epoch: state.epoch, phase: state.phase, needCode: state.need?.code };
         const executionTargets = targets?.map(result => result.ok ? result : { ok: false, code: result.error.code });
-        const signature = JSON.stringify({ state: executionState, capability: info?.modelCatalogTarget, targets: executionTargets, logins: login?.logins, authorizing: login?.phase === 'authorizing' });
+        const signature = JSON.stringify({ state: executionState, capability: info?.modelCatalogTarget, targets: executionTargets });
         const switched = api !== this.api;
         const changed = this.initialized && (switched || signature !== this.signature);
         this.initialized = true;
@@ -256,61 +176,118 @@ export class ModelCatalog {
         }
         return structuredClone(target);
     }
+    assertFlight(flight) {
+        if (flight.controller.signal.aborted || this.disposed || this.get() !== flight.api || flight.revision !== this.revision)
+            fail('连接已改变，原模型目录已失效');
+        const agent = { loginProvider: flight.target.provider }, current = this.trusted(agent, flight.api);
+        if (current.instanceId !== flight.target.instanceId || current.epoch !== flight.target.epoch || current.provider !== flight.target.provider || !sameTarget(current.target, flight.target.target))
+            fail('可信目标或连接代次已改变，原模型目录已失效');
+    }
+    failure(error) {
+        // Each consumer needs its own Error identity for its original input/signal proof.
+        return new CatalogError(error instanceof CatalogError || error instanceof ModelConfigurationError ? error.message.replace(/^无法获取模型列表：/, '') : '目录查询失败，请到设置 → 模型查看诊断。', error instanceof CatalogError ? error.diagnostic : error instanceof CatalogSshError ? error.diagnostic : error instanceof Error ? `${error instanceof LlmError ? error.code : 'MODEL_CATALOG_QUERY_FAILED'}：${safe(error.message)}` : 'MODEL_CATALOG_QUERY_FAILED：目录查询失败，根因未查明');
+    }
+    start(agent, api, target, max, key) {
+        const deferred = Promise.withResolvers(), controller = new AbortController();
+        const flight = { key, api, target, revision: this.revision, serial: ++this.serial, controller, pending: true, users: 0, promise: deferred.promise };
+        this.latest.set(agent.loginProvider, flight.serial);
+        this.flights.set(key, flight);
+        this.active.add(controller);
+        const current = () => !this.disposed && flight.revision === this.revision && api === this.get() && this.latest.get(agent.loginProvider) === flight.serial && !controller.signal.aborted;
+        const query = async () => {
+            try {
+                this.assertFlight(flight);
+                const output = await this.run(target.target, '/usr/local/aw-host/bin/aw-model-catalog --provider ' + agent.loginProvider, controller.signal, max);
+                this.assertFlight(flight);
+                const parsed = parseHostCatalog(output, agent.loginProvider, target.target.username), diagnostic = catalogDiagnostic(parsed.issues);
+                if (!parsed.models.length)
+                    fail('当前没有可选模型，请到设置 → 模型查看诊断。', diagnostic ?? '主机返回的完整模型目录为空（诊断代码：MODEL_CATALOG_EMPTY）');
+                if (current())
+                    this.diagnostic(agent.loginProvider, diagnostic);
+                if (current())
+                    await this.loaded(agent, parsed.models, () => this.assertFlight(flight));
+                this.assertFlight(flight);
+                return parsed.models;
+            }
+            catch (error) {
+                const failure = this.failure(error);
+                if (current())
+                    this.diagnostic(agent.loginProvider, failure.diagnostic);
+                throw failure;
+            }
+        };
+        const settled = () => { flight.pending = false; if (this.flights.get(key) === flight)
+            this.flights.delete(key); if (!flight.users)
+            this.active.delete(controller); };
+        void query().then(models => { settled(); deferred.resolve(models); }, error => { settled(); deferred.reject(error); });
+        return flight;
+    }
     async read(agent, signal) {
-        let controller;
-        let api;
-        let revision = this.revision;
-        const serial = ++this.serial;
-        this.latest.set(agent.loginProvider, serial);
-        const current = () => !this.disposed && revision === this.revision && api === this.get() && this.latest.get(agent.loginProvider) === serial;
-        let reported = false;
-        const report = (message) => { if (current()) {
-            reported = true;
-            this.diagnostic(agent.loginProvider, message);
+        let flight, released = false;
+        const release = () => { if (released || !flight)
+            return; released = true; flight.users--; if (!flight.users) {
+            if (flight.pending)
+                flight.controller.abort();
+            else
+                this.active.delete(flight.controller);
         } };
         try {
             if (this.disposed)
                 fail('远程模型插件已关闭');
+            signal?.throwIfAborted();
             this.refresh();
-            api = this.get();
-            revision = this.revision;
+            const api = this.get();
             if (!api)
                 fail('远程主机连接组件没有装好');
-            // refresh may clear reads from the previous connection generation.
-            this.latest.set(agent.loginProvider, serial);
-            const trustedApi = api, target = freeze(this.trusted(agent, trustedApi));
-            const max = this.maxBytes();
+            const target = freeze(this.trusted(agent, api)), max = this.maxBytes();
             if (!Number.isSafeInteger(max) || max < 1)
                 fail('acpMaxMessageBytes 设置无效');
-            controller = new AbortController();
-            this.active.add(controller);
-            const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
-            const assertCurrent = () => { if (combined.aborted || this.disposed || this.get() !== trustedApi || revision !== this.revision)
-                fail('连接已改变，原模型目录已失效'); const current = this.trusted(agent, trustedApi); if (current.instanceId !== target.instanceId || current.epoch !== target.epoch || current.provider !== target.provider || !sameTarget(current.target, target.target))
-                fail('可信目标或连接代次已改变，原模型目录已失效'); };
-            assertCurrent();
-            const output = await this.run(target.target, '/usr/local/aw-host/bin/aw-model-catalog --provider ' + agent.loginProvider, combined, max);
-            assertCurrent();
-            const parsed = parseHostCatalog(output, agent.loginProvider, target.target.username), diagnostic = catalogDiagnostic(parsed.issues);
-            if (!parsed.models.length)
-                fail('当前没有可选模型，请到设置 → 模型查看诊断。', diagnostic ?? '主机返回的完整模型目录为空（诊断代码：MODEL_CATALOG_EMPTY）');
-            report(diagnostic);
-            if (current())
-                await this.loaded(agent, parsed.models, assertCurrent);
+            const key = JSON.stringify([agent.loginProvider, target.instanceId, target.epoch]);
+            flight = this.flights.get(key);
+            if (flight && (flight.api !== api || flight.revision !== this.revision || !sameTarget(flight.target.target, target.target) || flight.controller.signal.aborted)) {
+                const closing = flight;
+                closing.controller.abort();
+                flight = undefined;
+                // Closing work owns the tuple until SSH/runner actually settles. This new
+                // caller waits for cleanup, then begins its own query; it never uses old data.
+                const waiting = new AbortController(), revision = this.revision;
+                this.active.add(waiting);
+                const waitSignal = signal ? AbortSignal.any([signal, waiting.signal]) : waiting.signal;
+                try {
+                    await new Promise((resolve, reject) => { const abort = () => { waitSignal.removeEventListener('abort', abort); reject(new ModelConfigurationError('目录查询已取消')); }; waitSignal.addEventListener('abort', abort, { once: true }); closing.promise.then(() => { }, () => { }).then(() => { waitSignal.removeEventListener('abort', abort); resolve(); }); if (waitSignal.aborted)
+                        abort(); });
+                }
+                finally {
+                    this.active.delete(waiting);
+                }
+                if (revision !== this.revision || this.get() !== api)
+                    fail('连接已改变，原模型目录已失效');
+                return this.read(agent, signal);
+            }
+            flight ??= this.start(agent, api, target, max, key);
+            flight.users++;
+            const own = flight, combined = signal ? AbortSignal.any([signal, own.controller.signal]) : own.controller.signal;
+            const assertCurrent = () => { if (combined.aborted)
+                fail('目录查询已取消'); this.assertFlight(own); };
+            const models = await new Promise((resolve, reject) => {
+                const abort = () => { combined.removeEventListener('abort', abort); reject(new ModelConfigurationError('目录查询已取消')); };
+                combined.addEventListener('abort', abort, { once: true });
+                own.promise.then(value => { combined.removeEventListener('abort', abort); resolve(value); }, error => { combined.removeEventListener('abort', abort); reject(error); });
+                if (combined.aborted)
+                    abort();
+            });
             assertCurrent();
-            const own = controller;
-            return { target, models: parsed.models, signal: combined, assertCurrent, release: () => this.active.delete(own) };
+            return { target: own.target, models, signal: combined, assertCurrent, release };
         }
         catch (error) {
-            if (controller)
-                this.active.delete(controller);
-            const failure = error instanceof CatalogError ? error : new CatalogError(error instanceof ModelConfigurationError ? error.message.replace(/^无法获取模型列表：/, '') : '目录查询失败，请到设置 → 模型查看诊断。', error instanceof Error ? `${error instanceof LlmError ? error.code : 'MODEL_CATALOG_QUERY_FAILED'}：${safe(error.message)}` : 'MODEL_CATALOG_QUERY_FAILED：目录查询失败，根因未查明');
-            if (!reported)
-                report(failure.diagnostic);
+            release();
+            const failure = this.failure(error);
+            if (!flight && !this.disposed)
+                this.diagnostic(agent.loginProvider, failure.diagnostic);
             throw failure;
         }
     }
-    dispose() { this.disposed = true; this.unsubscribe?.(); for (const controller of this.active)
+    dispose() { this.disposed = true; this.unsubscribe?.(); this.flights.clear(); for (const controller of this.active)
         controller.abort(); this.active.clear(); }
 }
 export function modelInfo(provider, model) {

package/dist/model-input-retention.d.ts

@@ -2,6 +2,12 @@ import type { Context } from '@deepseek-ai/cordis';
 export interface ModelInputRetentionOptions {
     isOurProvider: (provider: string) => boolean;
     diagnostic: (provider: string, message: string | undefined) => void;
+    diagnosticForAttempt?: (position: {
+        sessionId: string;
+        turn: number;
+        step: number;
+    }) => ((provider: string, code: string) => Promise<void>);
+    preflightDiagnostic?: (provider: string, message: string | undefined) => void;
 }
 /** Mark only at the actual X adapter's preparation catch, then rethrow the same
  * error. One error object can prove only its first preparation, for that signal.

package/dist/model-input-retention.js

@@ -26,7 +26,7 @@ function committed(events, messages) {
  * admission failures; it never manufactures transcript messages or model routes.
  */
 export function installModelInputRetention(ctx, options) {
-    const attempts = new Map();
+    const attempts = new Map(), pending = new Set();
     let disposed = false;
     const live = (a) => !disposed && attempts.get(a.agent) === a && !a.signal.aborted
         && ctx.get('agents')?.get(a.agent.id) === a.agent && ctx.get('sessions')?.get(a.session.id) === a.session && a.agent.session === a.session;
@@ -94,7 +94,7 @@ export function installModelInputRetention(ctx, options) {
             attempts.delete(payload.agent);
             return decision;
         }
-        attempts.set(payload.agent, { agent: payload.agent, session: payload.agent.session, turn: payload.turn, step: payload.step, signal: payload.signal, messages, offset: payload.agent.session.snapshotEvents().length, scheduled: false, dispatched: false });
+        attempts.set(payload.agent, { agent: payload.agent, session: payload.agent.session, turn: payload.turn, step: payload.step, signal: payload.signal, messages, offset: payload.agent.session.snapshotEvents().length, scheduled: false, dispatched: false, preflight: options.diagnosticForAttempt?.({ sessionId: payload.agent.session.id, turn: payload.turn, step: payload.step }) });
         return decision;
     });
     ctx.on('agent/request', async (payload, next) => {
@@ -118,12 +118,20 @@ export function installModelInputRetention(ctx, options) {
         // Consume before further checks: canceled/unsafe attempts must not leave a
         // reusable proof that could authorize a later failure of the same object.
         proof.consumed = true;
-        if (a.scheduled || !code || !preparationCodes.has(code) || !live(a) || !safe(a))
+        if (a.scheduled || !live(a) || !safe(a))
             return;
         a.provider = proof.provider;
+        if (a.preflight) {
+            const writing = a.preflight(proof.provider, code ?? 'PREFLIGHT_FAILED').catch(error => { if (!disposed)
+                options.preflightDiagnostic?.(proof.provider, `连接前诊断保存未能确认；没有自动重发。（原诊断代码：${code ?? 'PREFLIGHT_FAILED'}；保存诊断代码：${codeOf(error) ?? 'DIAGNOSTIC_WRITE_FAILED'}）`); });
+            pending.add(writing);
+            void writing.finally(() => pending.delete(writing));
+        }
+        if (!code || !preparationCodes.has(code))
+            return;
         a.scheduled = true;
         void restore(a, code);
     });
     ctx.on('agent/disposed', ({ agent }) => { attempts.delete(agent); });
-    ctx.effect(() => () => { disposed = true; attempts.clear(); });
+    ctx.effect(() => async () => { disposed = true; attempts.clear(); await Promise.allSettled(pending); });
 }

package/dist/preflight-diagnostic.d.ts

@@ -0,0 +1,22 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ConnectApi, RuntimeRequest } from './provider.ts';
+import type { DetailObservation } from './conversation-details.ts';
+import type { createRemoteDetails } from './remote-details.ts';
+import type { SourceAdmissionStage } from './workspace-source.ts';
+type Position = {
+    turn: string | number | null;
+    step: string | number | null;
+};
+export declare function preflightCode(error: unknown): string;
+export declare function createPreflightDiagnostics(options: {
+    ctx: Pick<Context, 'get'>;
+    getApi: () => ConnectApi | undefined;
+    manager: () => Pick<ReturnType<typeof createRemoteDetails>, 'recordPreflightCheck'>;
+}): {
+    begin(request: RuntimeRequest, _provider: "claude" | "codex"): void;
+    record: (request: RuntimeRequest, provider: "claude" | "codex", observation: DetailObservation) => Promise<void>;
+    failure(request: RuntimeRequest, provider: "claude" | "codex", error: unknown, stage: SourceAdmissionStage): Promise<void>;
+    forPreparation(sessionId: string, context: Position): (provider: string, code: string) => Promise<void>;
+};
+export type PreflightDiagnostics = ReturnType<typeof createPreflightDiagnostics>;
+export {};