@ai-workbench/remote-agent 0.8.11 → 0.8.12

package/dist/preflight-diagnostic.js

@@ -0,0 +1,112 @@
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import { isDeepStrictEqual } from 'node:util';
+import { NeedError } from "./remote.js";
+import { ModelConfigurationError } from "./model-configuration.js";
+import { officialEmployeeWorkspace } from "./employee-workspace.js";
+import { AGENTS } from "./agents.js";
+import { validPreflightPayload } from "./preflight-payload.js";
+const unknownSource = () => ({ workspaceId: null, bindingId: null, source: null, status: null });
+export function preflightCode(error) {
+    if (typeof error === 'string' && /^[A-Z][A-Z0-9_]*$/.test(error))
+        return error;
+    if (error instanceof NeedError || error instanceof LlmError || error instanceof ModelConfigurationError)
+        return error.code;
+    return error instanceof Error && error.name === 'AbortError' ? 'ABORTED' : 'PREFLIGHT_FAILED';
+}
+export function createPreflightDiagnostics(options) {
+    const scopes = new WeakMap();
+    function capture(sessionId, position) {
+        const api = options.getApi();
+        let connection, session, header, source = unknownSource(), captureError;
+        let context = position ? { ...position } : { turn: null, step: null };
+        try {
+            connection = api?.getConnectionState();
+            session = sessionId ? options.ctx.get('sessions')?.get(SessionId(sessionId)) : undefined;
+            header = session && structuredClone(session.header);
+            if (!position)
+                for (const event of session?.snapshotEvents() ?? []) {
+                    if (event.type === 'turn/start')
+                        context = { turn: event.data.turn, step: null };
+                    else if (event.type === 'turn/end')
+                        context = { turn: null, step: null };
+                    else if (event.type === 'step/start' && event.data.turn === context.turn)
+                        context.step = event.data.step;
+                    else if (event.type === 'step/end')
+                        context.step = null;
+                }
+            if (sessionId && session) {
+                let workspace;
+                try {
+                    workspace = officialEmployeeWorkspace(sessionId, options.ctx.get('workspaceRegistry'), session.header);
+                }
+                catch (error) {
+                    if (!(error instanceof NeedError && error.code === 'EMPLOYEE_WORKSPACE_UNAVAILABLE'))
+                        throw error;
+                }
+                if (workspace) {
+                    source.workspaceId = workspace.id;
+                    const state = api?.getWorkspaceLocationState?.();
+                    const rows = state?.items.filter(row => row.workspaceId === workspace.id) ?? [];
+                    if (state?.phase === 'ready' && state.instanceId === connection?.instanceId && state.epoch === connection.epoch && rows.length === 1) {
+                        const row = rows[0];
+                        source = { workspaceId: row.workspaceId, bindingId: row.bindingId, source: row.source, status: row.status };
+                    }
+                }
+            }
+        }
+        catch (error) {
+            captureError = error;
+        }
+        const assertScope = () => {
+            if (captureError !== undefined)
+                throw Object.assign(new NeedError('REMOTE_DETAIL_SCOPE_INVALID', '连接前诊断上下文无法核对。', '真实官方会话与连接快照'), { cause: captureError });
+            if (!sessionId || !session || options.ctx.get('sessions')?.get(SessionId(sessionId)) !== session || !isDeepStrictEqual(session.header, header))
+                throw new NeedError('REMOTE_DETAIL_SCOPE_INVALID', '连接前诊断所属会话已变化。', '原官方session/header');
+        };
+        return { sessionId, binding: { api, connection }, context, source, assertScope };
+    }
+    const scopeFor = (request) => { let scope = scopes.get(request); if (!scope) {
+        scope = capture(request.sessionId);
+        scopes.set(request, scope);
+    } return scope; };
+    const write = (scope, provider, observation) => options.manager().recordPreflightCheck({ sessionId: scope.sessionId, provider, observation, context: scope.context, binding: scope.binding, assertScope: scope.assertScope });
+    async function record(request, provider, observation) {
+        const scope = scopeFor(request), payload = observation.payload;
+        if (validPreflightPayload(payload) && ['failed', 'declined', 'cancelled'].includes(payload.outcome))
+            request.preflightFailureRecorded = true;
+        try {
+            await write(scope, provider, observation);
+            if (validPreflightPayload(payload) && payload.outcome === 'confirmed')
+                scope.source = { workspaceId: payload.workspaceId, bindingId: payload.bindingId, source: payload.source, status: payload.status };
+        }
+        catch (error) {
+            request.preflightFailureRecorded = true;
+            throw error;
+        }
+    }
+    return {
+        begin(request, _provider) { scopeFor(request); }, record,
+        async failure(request, provider, error, stage) {
+            if (request.preflightFailureRecorded)
+                return;
+            request.preflightFailureRecorded = true;
+            const scope = scopeFor(request), code = preflightCode(error);
+            try {
+                await record(request, provider, { kind: 'need', severity: 'action-required', code, summary: '本轮在连接前准备阶段停止；原始请求保留，未重发。', payload: { phase: 'workspace-source-admission', stage, ...scope.source, outcome: code === 'ABORTED' ? 'cancelled' : 'failed' } });
+            }
+            catch (diagnostic) {
+                throw Object.assign(new NeedError('CONVERSATION_DETAILS_FAILED', '本轮连接前诊断未能保存，已停止。', '原错误代码 ' + code + '；诊断错误代码 ' + preflightCode(diagnostic)), { cause: new AggregateError([error, diagnostic], 'PREFLIGHT_AND_DIAGNOSTIC_FAILED') });
+            }
+        },
+        forPreparation(sessionId, context) {
+            const scope = capture(sessionId, context);
+            return async (provider, code) => {
+                const brand = AGENTS.find(agent => agent.id === provider)?.loginProvider;
+                if (!brand)
+                    throw new NeedError('REMOTE_DETAIL_SCOPE_INVALID', '不是本插件的远程品牌。', '真实X品牌');
+                await write(scope, brand, { kind: 'need', severity: 'action-required', code, summary: '模型准备在派发前失败；没有自动重发任务。', payload: { phase: 'workspace-source-admission', stage: code === 'MODEL_REQUIRED' ? 'input-prepare' : 'model-catalog', ...scope.source, outcome: code === 'ABORTED' ? 'cancelled' : 'failed' } });
+            };
+        },
+    };
+}

package/dist/preflight-payload.d.ts

@@ -0,0 +1,11 @@
+import type { SourceAdmissionStage } from './workspace-source.ts';
+export interface PreflightPayload {
+    phase: 'workspace-source-admission';
+    stage: SourceAdmissionStage;
+    workspaceId: string | null;
+    bindingId: string | null;
+    source: 'local' | 'host' | 'legacy-host' | null;
+    status: 'unselected' | 'selected' | 'legacy-confirmation-required' | 'invalid' | null;
+    outcome: 'confirmation-required' | 'confirmed' | 'declined' | 'cancelled' | 'failed';
+}
+export declare function validPreflightPayload(value: unknown): value is PreflightPayload;

package/dist/preflight-payload.js

@@ -0,0 +1,11 @@
+export function validPreflightPayload(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const p = value, keys = ['phase', 'stage', 'workspaceId', 'bindingId', 'source', 'status', 'outcome'];
+    const id = (v) => v === null || typeof v === 'string' && v.length > 0 && !/[\x00-\x1f\x7f]/.test(v);
+    return Object.keys(p).length === keys.length && keys.every(key => Object.hasOwn(p, key)) && p.phase === 'workspace-source-admission'
+        && ['source-context', 'source-confirmation', 'input-acceptance', 'login-readiness', 'local-admission', 'input-prepare', 'model-catalog', 'runtime-resolve'].includes(p.stage)
+        && id(p.workspaceId) && id(p.bindingId) && [null, 'local', 'host', 'legacy-host'].includes(p.source)
+        && [null, 'unselected', 'selected', 'legacy-confirmation-required', 'invalid'].includes(p.status)
+        && ['confirmation-required', 'confirmed', 'declined', 'cancelled', 'failed'].includes(p.outcome);
+}

package/dist/provider.d.ts

@@ -65,6 +65,7 @@ export interface Runtime {
     employeePresentation?: string;
 }
 export interface RuntimeRequest extends Invocation {
+    preflightFailureRecorded?: boolean;
     recordEarlyFailure?: (error: unknown, stage: SourceAdmissionStage) => Promise<void>;
     userInputIds?: readonly string[];
     localAcceptance?: Readonly<LocalUserTurnAcceptance>;

package/dist/provider.js

@@ -171,7 +171,7 @@ export function connectProvider(get, options = {}) {
             throw new NeedError('MODE_UNSUPPORTED', '此远程模型仅支持会话模式', '使用会话模式');
         const confirmedSource = options.workspaceSource ? await confirmLegacyWorkspaceSource(get, api, request, options.workspaceSource) : undefined;
         let sourceStage = 'input-acceptance';
-        if (confirmedSource)
+        if (confirmedSource && !request.recordEarlyFailure)
             request.recordEarlyFailure = (error, stage) => confirmedSource.recordFailure(error, stage);
         try {
             confirmedSource?.assertCurrent();
@@ -208,8 +208,12 @@ export function connectProvider(get, options = {}) {
         }
         catch (error) {
             admissions.delete(request);
+            const record = request.recordEarlyFailure;
             request.recordEarlyFailure = undefined;
-            await confirmedSource?.recordFailure(error, sourceStage);
+            if (record)
+                await record(error, sourceStage);
+            else
+                await confirmedSource?.recordFailure(error, sourceStage);
             throw error;
         }
     };

package/dist/remote-details.d.ts

@@ -23,6 +23,10 @@ export interface DetailRequest {
 export declare function privateDirectory(path: string): Promise<void>;
 export declare function durableWrite(path: string, value: unknown): Promise<void>;
 export declare function readJournal(path: string): Promise<unknown>;
+export interface DiagnosticBinding {
+    api: RemoteDetailsApi | undefined;
+    connection: Connection | undefined;
+}
 export declare function createRemoteDetails(options: {
     profileDir: string;
     getApi: () => RemoteDetailsApi | undefined;
@@ -45,5 +49,19 @@ export declare function createRemoteDetails(options: {
         eventId: string;
         recorded: true;
     }>;
+    recordPreflightCheck(request: {
+        sessionId?: string;
+        provider: "claude" | "codex";
+        observation: DetailObservation;
+        context?: {
+            turn: string | number | null;
+            step: string | number | null;
+        };
+        binding?: DiagnosticBinding;
+        assertScope?: () => void;
+    }): Promise<{
+        eventId: string;
+        recorded: true;
+    }>;
     open(request: DetailRequest): Promise<DetailChannel>;
 };

package/dist/remote-details.js

@@ -4,6 +4,7 @@ import { mkdir, open, lstat, realpath, readdir } from 'node:fs/promises';
 import { isAbsolute, join, parse } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { sanitizeObservation, isSanitizedRedaction } from "./conversation-details.js";
+import { validPreflightPayload } from "./preflight-payload.js";
 import { NeedError } from "./remote.js";
 const failure = (code, message = '技术详情未能持久记录，本轮已停止。') => new NeedError(code, message, '可用的远程主机连接技术详情');
 const hash = (value) => createHash('sha256').update(value).digest('hex');
@@ -90,141 +91,155 @@ export function createRemoteDetails(options) {
     const root = join(options.profileDir, 'ai-workbench-remote-agent', 'diagnostics');
     const scopes = new Map(), loginScopes = new Map();
     const initialize = async () => { await privateDirectory(join(options.profileDir, 'ai-workbench-remote-agent')); await privateDirectory(root); };
-    return {
-        async recordLocalFailure(request) {
-            await initialize();
-            if (!/^[A-Z][A-Z0-9_]*$/.test(request.code))
-                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
-            await durableWrite(join(root, randomUUID() + '.json'), { version: 1, kind: 'local-admission', code: request.code, provider: request.provider, sessionHash: request.sessionId ? hash(request.sessionId) : null, ...request.observation ? { observation: sanitizeObservation(request.observation, true) } : {} });
-        },
-        async recordLoginFailure(request) {
-            await initialize();
-            const eventId = randomUUID(), diagnostic = request.diagnostic;
-            // The original observed IDs and full approved snapshot are durable before any L call.
-            await durableWrite(join(root, eventId + '.json'), { version: 1, eventId, kind: 'login-check', code: request.code, sessionHash: request.sessionId ? hash(request.sessionId) : null, diagnostic, delivery: 'pending' });
-            if (!request.sessionId)
-                throw failure('REMOTE_DETAIL_SCOPE_INVALID');
-            const sessionId = request.sessionId, provider = diagnostic.provider, api = options.getApi(), connection = diagnostic.connection;
-            const stable = () => { const now = api?.getConnectionState(); if (!api || options.getApi() !== api || now?.phase !== 'connected' || now.instanceId !== connection.instanceId || now.epoch !== connection.epoch)
-                throw failure('CONNECTION_LOST'); };
+    async function recordConnectionDiagnostic(request) {
+        request = { ...request, connection: request.connection && structuredClone(request.connection), payload: structuredClone(request.payload), snapshot: structuredClone(request.snapshot), context: request.context && { ...request.context } };
+        await initialize();
+        const eventId = randomUUID();
+        await durableWrite(join(root, eventId + '.json'), { version: 1, eventId, kind: request.kind, code: request.code, provider: request.provider, sessionHash: request.sessionId ? hash(request.sessionId) : null, ...request.snapshot, delivery: 'pending' });
+        if (!request.sessionId)
+            throw failure('REMOTE_DETAIL_SCOPE_INVALID');
+        const sessionId = request.sessionId, provider = request.provider, api = request.binding ? request.binding.api : options.getApi(), connection = request.connection;
+        if (!connection)
+            throw failure('CONNECTION_LOST');
+        const stable = () => { request.assertScope?.(); const now = api?.getConnectionState(); if (!api || options.getApi() !== api || connection.phase !== 'connected' || now?.phase !== 'connected' || now.instanceId !== connection.instanceId || now.epoch !== connection.epoch)
+            throw failure('CONNECTION_LOST'); };
+        stable();
+        const info = api.getContractInfo?.();
+        if ((request.kind === 'login-check' ? info?.loginDiagnostics : info?.preflightDiagnostics) !== 1 || !['appendLoginDiagnostic', 'getLoginDiagnosticReceipt', 'listLoginDiagnostics'].every(key => typeof api[key] === 'function'))
+            throw failure('TECHNICAL_DETAILS_UNAVAILABLE', '技术详情暂不可用，请更新远程主机连接组件。');
+        const parent = join(root, 'login');
+        await privateDirectory(parent);
+        const key = hash(sessionId + '\0' + provider), dir = join(parent, key);
+        await privateDirectory(dir);
+        const scope = loginScopes.get(key) ?? { tail: Promise.resolve(), maximum: 0, loaded: false };
+        loginScopes.set(key, scope);
+        const operation = scope.tail.then(async () => {
             stable();
-            if (api.getContractInfo?.().loginDiagnostics !== 1 || !['appendLoginDiagnostic', 'getLoginDiagnosticReceipt', 'listLoginDiagnostics'].every(key => typeof api[key] === 'function'))
-                throw failure('TECHNICAL_DETAILS_UNAVAILABLE', '技术详情暂不可用，请更新远程主机连接组件。');
-            const parent = join(root, 'login');
-            await privateDirectory(parent);
-            const key = hash(sessionId + '\0' + provider), dir = join(parent, key);
-            await privateDirectory(dir);
-            const scope = loginScopes.get(key) ?? { tail: Promise.resolve(), maximum: 0, loaded: false };
-            loginScopes.set(key, scope);
-            const operation = scope.tail.then(async () => {
-                stable();
-                const generation = connection.instanceId + '\0' + connection.epoch;
-                if (!scope.loaded || scope.generation !== generation) {
-                    const names = await readdir(dir);
-                    for (const name of names) {
-                        const match = /^(\d+)-([0-9a-f-]+)\.json$/.exec(name);
-                        if (!match)
-                            continue;
-                        const sequence = Number(match[1]);
-                        if (!Number.isSafeInteger(sequence))
-                            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
-                        scope.maximum = Math.max(scope.maximum, sequence);
-                        const saved = await readJournal(join(dir, name));
-                        if (!object(saved) || !object(saved.detail) || saved.detail.sequence !== sequence || saved.detail.eventId !== match[2] || saved.detail.sessionId !== sessionId || saved.detail.provider !== provider)
+            const generation = connection.instanceId + '\0' + connection.epoch;
+            if (!scope.loaded || scope.generation !== generation) {
+                const names = await readdir(dir);
+                for (const name of names) {
+                    const match = /^(\d+)-([0-9a-f-]+)\.json$/.exec(name);
+                    if (!match)
+                        continue;
+                    const sequence = Number(match[1]);
+                    if (!Number.isSafeInteger(sequence))
+                        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                    scope.maximum = Math.max(scope.maximum, sequence);
+                    const saved = await readJournal(join(dir, name));
+                    if (!object(saved) || !object(saved.detail) || saved.detail.sequence !== sequence || saved.detail.eventId !== match[2] || saved.detail.sessionId !== sessionId || saved.detail.provider !== provider)
+                        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                    const settled = 'settled-' + match[2] + '.json';
+                    if (names.includes(settled)) {
+                        const receipt = await readJournal(join(dir, settled));
+                        if (!object(receipt) || receipt.eventId !== match[2] || !['recorded', 'rejected'].includes(receipt.state))
                             throw failure('REMOTE_DETAIL_STORAGE_FAILED');
-                        const settled = 'settled-' + match[2] + '.json';
-                        if (names.includes(settled)) {
-                            const receipt = await readJournal(join(dir, settled));
-                            if (!object(receipt) || receipt.eventId !== match[2] || !['recorded', 'rejected'].includes(receipt.state))
-                                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
-                            continue;
-                        }
-                        stable();
-                        const receipt = unwrap(await api.getLoginDiagnosticReceipt({ eventId: match[2], sessionId, provider }));
-                        stable();
-                        if (receipt.eventId !== match[2] || !receipt.recorded)
-                            throw failure('REMOTE_DETAIL_DELIVERY_UNKNOWN');
-                        if (!isDeepStrictEqual(receipt.detail, saved.detail))
-                            throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
-                        await durableWrite(join(dir, settled), { eventId: match[2], state: 'recorded' });
+                        continue;
                     }
-                    let cursor, previous = -1, count = 0, expected;
-                    const seen = new Set();
-                    do {
-                        stable();
-                        const page = unwrap(await api.listLoginDiagnostics({ sessionId, provider, ...(cursor ? { cursor } : {}) }));
-                        stable();
-                        if (!object(page) || !Array.isArray(page.items) || ![page.total, page.unknownCount, page.actionRequiredCount].every(n => Number.isSafeInteger(n) && n >= 0))
-                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
-                        const counts = { total: page.total, unknownCount: page.unknownCount, actionRequiredCount: page.actionRequiredCount };
-                        if (expected && !isDeepStrictEqual(expected, counts))
-                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
-                        expected = counts;
-                        for (const entry of page.items) {
-                            if (entry.sessionId !== sessionId || entry.provider !== provider || !Number.isSafeInteger(entry.sequence) || entry.sequence < 0 || entry.sequence <= previous)
-                                throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
-                            previous = entry.sequence;
-                            scope.maximum = Math.max(scope.maximum, entry.sequence);
-                            count++;
-                        }
-                        cursor = page.nextCursor;
-                        if (cursor !== undefined && (typeof cursor !== 'string' || !cursor || seen.has(cursor)))
-                            throw failure('REMOTE_DETAIL_CURSOR_INVALID');
-                        if (cursor)
-                            seen.add(cursor);
-                    } while (cursor);
-                    if (count !== expected?.total)
-                        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
-                    scope.loaded = true;
-                    scope.generation = generation;
-                }
-                const mismatch = diagnostic.reason === 'LOGIN_INSTANCE_MISMATCH', unsupported = !!diagnostic.officialReasonRejected;
-                const reason = mismatch ? 'LOGIN_INSTANCE_MISMATCH' : unsupported ? 'OFFICIAL_REASON_UNSUPPORTED' : diagnostic.reason;
-                // L 0.7.11: observed evidence never changes the current connection scope.
-                const login = { phase: diagnostic.login.phase, instanceId: diagnostic.login.instanceId, logins: Object.fromEntries(Object.entries(diagnostic.login.logins).filter(([, v]) => typeof v === 'boolean' || v === 'absent')), queuedProviders: diagnostic.login.queuedProviders, checkingProviders: diagnostic.login.checkingProviders };
-                const payload = { reason, connection: { ...connection }, login, ...(mismatch ? { observedLoginInstanceId: diagnostic.login.instanceId } : {}), ...(diagnostic.officialReason ? { officialReason: diagnostic.officialReason } : {}), ...(unsupported && !mismatch ? { officialReasonRejected: diagnostic.officialReasonRejected } : {}) };
-                // The two payload reasons are exclusive in L's contract. Preserve both facts
-                // using the approved fixed summary and full digest, without inventing a field.
-                const rejected = diagnostic.officialReasonRejected;
-                const summary = '登录检查：' + diagnostic.reason + (rejected ? '; OFFICIAL_REASON_UNSUPPORTED; bytes=' + rejected.bytes + '; SHA256=' + rejected.sha256 : '');
-                const context = request.context ?? { turn: null, step: null };
-                if (!identifier(context.turn) || !identifier(context.step))
-                    throw failure('REMOTE_DETAIL_SCOPE_INVALID');
-                const sequence = scope.maximum + 1;
-                if (!Number.isSafeInteger(sequence))
-                    throw failure('REMOTE_DETAIL_SEQUENCE_INVALID');
-                scope.maximum = sequence;
-                const detail = { version: 1, eventId, instanceId: connection.instanceId, epoch: connection.epoch, sessionId, provider, turn: context.turn, step: context.step, sequence, kind: 'login-check', severity: 'action-required', code: request.code, summary, method: diagnostic.source, payload };
-                await durableWrite(join(dir, sequence + '-' + eventId + '.json'), { state: 'pending', detail });
-                stable();
-                let response;
-                try {
-                    response = await api.appendLoginDiagnostic(structuredClone(detail));
-                }
-                catch {
                     stable();
-                    const receipt = unwrap(await api.getLoginDiagnosticReceipt({ eventId, sessionId, provider }));
+                    const receipt = unwrap(await api.getLoginDiagnosticReceipt({ eventId: match[2], sessionId, provider }));
                     stable();
-                    if (receipt.eventId !== eventId)
-                        throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
-                    if (!receipt.recorded)
+                    if (receipt.eventId !== match[2] || !receipt.recorded)
                         throw failure('REMOTE_DETAIL_DELIVERY_UNKNOWN');
-                    if (!isDeepStrictEqual(receipt.detail, detail))
+                    if (!isDeepStrictEqual(receipt.detail, saved.detail))
                         throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
-                    await durableWrite(join(dir, 'settled-' + eventId + '.json'), { eventId, state: 'recorded' });
-                    return;
+                    await durableWrite(join(dir, settled), { eventId: match[2], state: 'recorded' });
                 }
-                stable();
-                if (response?.ok === false)
-                    await durableWrite(join(dir, 'settled-' + eventId + '.json'), { eventId, state: 'rejected', code: response.error.code });
-                const ack = unwrap(response);
-                if (ack.eventId !== eventId || ack.recorded !== true)
+                let cursor, previous = -1, count = 0, expected;
+                const seen = new Set();
+                do {
+                    stable();
+                    const page = unwrap(await api.listLoginDiagnostics({ sessionId, provider, ...(cursor ? { cursor } : {}) }));
+                    stable();
+                    if (!object(page) || !Array.isArray(page.items) || ![page.total, page.unknownCount, page.actionRequiredCount].every(n => Number.isSafeInteger(n) && n >= 0))
+                        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                    const counts = { total: page.total, unknownCount: page.unknownCount, actionRequiredCount: page.actionRequiredCount };
+                    if (expected && !isDeepStrictEqual(expected, counts))
+                        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                    expected = counts;
+                    for (const entry of page.items) {
+                        if (entry.sessionId !== sessionId || entry.provider !== provider || !Number.isSafeInteger(entry.sequence) || entry.sequence < 0 || entry.sequence <= previous)
+                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                        previous = entry.sequence;
+                        scope.maximum = Math.max(scope.maximum, entry.sequence);
+                        count++;
+                    }
+                    cursor = page.nextCursor;
+                    if (cursor !== undefined && (typeof cursor !== 'string' || !cursor || seen.has(cursor)))
+                        throw failure('REMOTE_DETAIL_CURSOR_INVALID');
+                    if (cursor)
+                        seen.add(cursor);
+                } while (cursor);
+                if (count !== expected?.total)
                     throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                scope.loaded = true;
+                scope.generation = generation;
+            }
+            const context = request.context ?? { turn: null, step: null };
+            if (!identifier(context.turn) || !identifier(context.step))
+                throw failure('REMOTE_DETAIL_SCOPE_INVALID');
+            const sequence = scope.maximum + 1;
+            if (!Number.isSafeInteger(sequence))
+                throw failure('REMOTE_DETAIL_SEQUENCE_INVALID');
+            scope.maximum = sequence;
+            const detail = { version: 1, eventId, instanceId: connection.instanceId, epoch: connection.epoch, sessionId, provider, turn: context.turn, step: context.step, sequence, kind: request.kind, severity: request.severity, code: request.code, summary: request.summary, method: request.method, payload: request.payload };
+            await durableWrite(join(dir, sequence + '-' + eventId + '.json'), { state: 'pending', detail });
+            stable();
+            let response;
+            try {
+                response = await api.appendLoginDiagnostic(structuredClone(detail));
+            }
+            catch {
+                stable();
+                const receipt = unwrap(await api.getLoginDiagnosticReceipt({ eventId, sessionId, provider }));
+                stable();
+                if (receipt.eventId !== eventId)
+                    throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                if (!receipt.recorded)
+                    throw failure('REMOTE_DETAIL_DELIVERY_UNKNOWN');
+                if (!isDeepStrictEqual(receipt.detail, detail))
+                    throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
                 await durableWrite(join(dir, 'settled-' + eventId + '.json'), { eventId, state: 'recorded' });
-            });
-            scope.tail = operation.then(() => { }, () => { scope.loaded = false; });
-            await operation;
-            return { eventId, recorded: true };
+                return;
+            }
+            stable();
+            if (response?.ok === false)
+                await durableWrite(join(dir, 'settled-' + eventId + '.json'), { eventId, state: 'rejected', code: response.error.code });
+            const ack = unwrap(response);
+            if (ack.eventId !== eventId || ack.recorded !== true)
+                throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+            await durableWrite(join(dir, 'settled-' + eventId + '.json'), { eventId, state: 'recorded' });
+        });
+        scope.tail = operation.then(() => { }, () => { scope.loaded = false; });
+        await operation;
+        return { eventId, recorded: true };
+    }
+    return {
+        async recordLocalFailure(request) {
+            await initialize();
+            if (!/^[A-Z][A-Z0-9_]*$/.test(request.code))
+                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+            await durableWrite(join(root, randomUUID() + '.json'), { version: 1, kind: 'local-admission', code: request.code, provider: request.provider, sessionHash: request.sessionId ? hash(request.sessionId) : null, ...request.observation ? { observation: sanitizeObservation(request.observation, true) } : {} });
+        },
+        async recordLoginFailure(request) {
+            const diagnostic = request.diagnostic, connection = diagnostic.connection;
+            const mismatch = diagnostic.reason === 'LOGIN_INSTANCE_MISMATCH', unsupported = !!diagnostic.officialReasonRejected;
+            const reason = mismatch ? 'LOGIN_INSTANCE_MISMATCH' : unsupported ? 'OFFICIAL_REASON_UNSUPPORTED' : diagnostic.reason;
+            // L 0.7.11: observed evidence never changes the current connection scope.
+            const login = { phase: diagnostic.login.phase, instanceId: diagnostic.login.instanceId, logins: Object.fromEntries(Object.entries(diagnostic.login.logins).filter(([, v]) => typeof v === 'boolean' || v === 'absent')), queuedProviders: diagnostic.login.queuedProviders, checkingProviders: diagnostic.login.checkingProviders };
+            const payload = { reason, connection: { ...connection }, login, ...(mismatch ? { observedLoginInstanceId: diagnostic.login.instanceId } : {}), ...(diagnostic.officialReason ? { officialReason: diagnostic.officialReason } : {}), ...(unsupported && !mismatch ? { officialReasonRejected: diagnostic.officialReasonRejected } : {}) };
+            // The two payload reasons are exclusive in L's contract. Preserve both facts
+            // using the approved fixed summary and full digest, without inventing a field.
+            const rejected = diagnostic.officialReasonRejected;
+            const summary = '登录检查：' + diagnostic.reason + (rejected ? '; OFFICIAL_REASON_UNSUPPORTED; bytes=' + rejected.bytes + '; SHA256=' + rejected.sha256 : '');
+            return recordConnectionDiagnostic({ ...request, provider: diagnostic.provider, connection: diagnostic.connection, kind: 'login-check', severity: 'action-required', summary, method: diagnostic.source, payload, snapshot: { diagnostic } });
+        },
+        async recordPreflightCheck(request) {
+            const observation = sanitizeObservation(request.observation, true);
+            if (!/^[A-Z][A-Z0-9_]*$/.test(observation.code) || !validPreflightPayload(observation.payload))
+                throw failure('REMOTE_DETAIL_SCOPE_INVALID');
+            const api = request.binding ? request.binding.api : options.getApi(), connection = request.binding ? request.binding.connection : api?.getConnectionState();
+            return recordConnectionDiagnostic({ ...request, connection, binding: { api, connection }, kind: 'preflight-check', code: observation.code, summary: observation.summary, method: observation.payload.stage, severity: observation.severity, payload: observation.payload, snapshot: { observation } });
         },
         async open(request) {
             request = structuredClone(request);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-workbench/remote-agent",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -39,7 +39,7 @@
     "zod": "4.6.7"
   },
   "devDependencies": {
-    "@ai-workbench/connect": "file:test/fixtures/ai-workbench-connect-0.7.17.tgz",
+    "@ai-workbench/connect": "file:test/fixtures/ai-workbench-connect-0.7.18.tgz",
     "@ai-workbench/network": "file:test/fixtures/ai-workbench-network-0.4.4.tgz",
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/cordis-plugin-group": "1.0.4",
@@ -68,7 +68,7 @@
     "zustand": "4.4.7"
   },
   "peerDependencies": {
-    "@ai-workbench/connect": "~0.7.17",
+    "@ai-workbench/connect": "~0.7.18",
     "@ai-workbench/network": "~0.4.4",
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/dsh-agent": "0.2.0-rc.2",