@ai-workbench/remote-agent 0.8.1 → 0.8.5

package/dist/provider.js

@@ -1,6 +1,8 @@
+import { loginDiagnostic, loginReason } from "./login-diagnostic.js";
 import { NeedError } from "./remote.js";
 import { CONNECTION_REQUIRED, TEST_HOST_NOTICE } from "./presentation.js";
 import { CODEX_AGENT } from "./agents.js";
+import { StageTiming } from "./stage-timing.js";
 export function requireLoginCoordinator(api) {
     if (!['getConnectionState', 'getLoginPromptState', 'requestLoginPrompt', 'refreshLoginPrompts'].every(key => typeof api[key] === 'function'))
         throw new NeedError('CONNECT_API_MISMATCH', '我需要 connect-api 0.6.1 的统一登录询问与连接状态能力', 'L >=0.6.1');
@@ -8,6 +10,8 @@ export function requireLoginCoordinator(api) {
 export function requireLoginState(state) {
     const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
     const need = (v) => object(v) && typeof v.code === 'string' && v.code.length > 0 && ['enrollment', 'network', 'ssh', 'auth', 'integration', 'settings', 'projects'].includes(v.layer) && typeof v.message === 'string' && typeof v.requires === 'string' && ['employee', 'administrator', 'ai-administrator', 'plugin'].includes(v.actor) && object(v.action) && typeof v.action.id === 'string' && typeof v.action.label === 'string' && typeof v.action.available === 'boolean';
+    if (state.queuedProviders !== undefined && (!Array.isArray(state.queuedProviders) || state.queuedProviders.some(p => p !== 'codex' && p !== 'claude') || new Set(state.queuedProviders).size !== state.queuedProviders.length || state.queuedProviders.some(p => state.checkingProviders?.includes(p))))
+        throw new NeedError('CONNECT_API_MISMATCH', '我需要真实的品牌排队与进行中状态', 'L >=0.7.10');
     if (!Array.isArray(state.checkingProviders) || state.checkingProviders.some(p => p !== 'codex' && p !== 'claude') || !object(state.providerNeeds) || Object.entries(state.providerNeeds).some(([p, v]) => !['codex', 'claude'].includes(p) || !need(v)))
         throw new NeedError('CONNECT_API_MISMATCH', '我需要按助手区分的真实登录状态', 'L >=0.6.1');
 }
@@ -32,15 +36,77 @@ function verifiedLogin(api, brand, expected) {
     if (!connection.instanceId || !Number.isSafeInteger(connection.epoch) || connection.epoch < 0 || connection.phase !== 'connected' || expected && (connection.instanceId !== expected.instanceId || connection.epoch !== expected.epoch))
         throw new NeedError('CONNECTION_LOST', 'connection binding changed', 'current employee connection');
     requireLoginState(login);
-    if (login.instanceId !== connection.instanceId || login.checkingProviders.includes(brand) || login.providerNeeds[brand] || login.phase === 'blocked' || login.phase === 'disposed' || login.phase === 'authorizing' && login.provider === brand || typeof login.logins?.[brand] !== 'boolean')
-        throw new NeedError('AUTH_STATUS_INVALID', '无法确认当前品牌的登录状态', 'L核验的本品牌登录状态');
-    if (!login.logins[brand])
-        throw new NeedError('LOGIN_REQUIRED', '需要登录，请到设置 → 远程主机连接 点登录', '本人登录');
+    const reason = loginReason(login, connection, brand);
+    if (reason)
+        throw Object.assign(new NeedError(reason === 'LOGIN_REQUIRED' ? 'LOGIN_REQUIRED' : 'AUTH_STATUS_INVALID', reason === 'LOGIN_REQUIRED' ? '需要登录，请到设置 → 远程主机连接 点登录' : '无法确认当前品牌的登录状态', 'L核验的本品牌登录状态'), { technical: loginDiagnostic('verified-login', reason, brand, connection, login), ...(typeof login.providerNeeds[brand]?.officialReason === 'string' ? { officialReason: login.providerNeeds[brand].officialReason } : {}) });
     return { ...connection };
 }
+/** Wait only for L's explicit in-progress evidence. No timer, polling, refresh or authorization. */
+async function waitForLogin(api, brand, expected, get, signal) {
+    const check = () => {
+        signal?.throwIfAborted();
+        if (get() !== api)
+            throw new NeedError('CONNECTION_LOST', '远程主机连接组件已更换', '当前员工连接');
+        const connection = api.getConnectionState(), state = api.getLoginPromptState();
+        requireLoginState(state);
+        if (connection.phase !== 'connected' || connection.instanceId !== expected.instanceId || connection.epoch !== expected.epoch)
+            return verifiedLogin(api, brand, expected);
+        const pending = state.instanceId === connection.instanceId && state.phase !== 'blocked' && state.phase !== 'disposed' && (state.queuedProviders?.includes(brand) || state.checkingProviders.includes(brand) || state.phase === 'authorizing' && state.provider === brand);
+        return pending ? undefined : verifiedLogin(api, brand, expected);
+    };
+    const ready = check();
+    if (ready)
+        return ready;
+    if (typeof api.onLoginPromptState !== 'function' || typeof api.onConnectionState !== 'function')
+        throw new NeedError('CONNECT_API_MISMATCH', '我需要登录检查状态订阅能力', 'L onLoginPromptState / onConnectionState');
+    return new Promise((resolve, reject) => {
+        let ended = false;
+        const disposers = [];
+        const clear = () => { ended = true; signal?.removeEventListener('abort', abort); for (const off of disposers)
+            off(); };
+        const changed = () => { if (ended)
+            return; try {
+            const value = check();
+            if (value) {
+                clear();
+                resolve(value);
+            }
+        }
+        catch (error) {
+            clear();
+            reject(error);
+        } };
+        const abort = () => { if (ended)
+            return; clear(); reject(new NeedError('ABORTED', 'consumer wait cancelled', 'employee action')); };
+        const register = (off) => { if (ended)
+            off();
+        else
+            disposers.push(off); };
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+            if (signal?.aborted)
+                abort();
+            if (!ended)
+                register(api.onLoginPromptState(changed));
+            if (!ended)
+                register(api.onConnectionState(changed));
+            changed();
+        }
+        catch (error) {
+            clear();
+            reject(error);
+        }
+    });
+}
+async function ensureReady(api, brand, signal) {
+    const result = await awaitL(() => api.ensureReady(brand), signal);
+    if (!result.ok)
+        throw Object.assign(new NeedError(result.error.code, result.error.message, result.error.requires), { technical: loginDiagnostic('ensure-ready', 'L_ENSURE_READY_FAILED', brand, api.getConnectionState(), api.getLoginPromptState(), result.error.officialReason), ...(typeof result.error.officialReason === 'string' ? { officialReason: result.error.officialReason } : {}) });
+    return result.value;
+}
 export function unwrap(result) {
     if (!result.ok)
-        throw new NeedError(result.error.code, result.error.message, result.error.requires);
+        throw Object.assign(new NeedError(result.error.code, result.error.message, result.error.requires), typeof result.error.officialReason === 'string' ? { officialReason: result.error.officialReason } : {});
     return result.value;
 }
 export function validateTarget(t) {
@@ -76,12 +142,12 @@ export async function offerLogin(connect, request, currentApi, agent = CODEX_AGE
     requireNativeWorkspace(connect);
     request.signal?.throwIfAborted();
     const before = connect.getConnectionState();
-    const target = unwrap(await awaitL(() => connect.ensureReady(agent.loginProvider), request.signal));
+    const target = await ensureReady(connect, agent.loginProvider, request.signal);
     validateTarget(target);
     request.signal?.throwIfAborted();
     if (currentApi && currentApi() !== connect)
         throw new NeedError('CONNECTION_LOST', '远程主机连接组件已更换', '当前员工连接');
-    verifiedLogin(connect, agent.loginProvider, before);
+    await waitForLogin(connect, agent.loginProvider, before, currentApi ?? (() => connect), request.signal);
 }
 export function sameTarget(a, b) {
     return identity(a) === identity(b) && a.projectRoot === b.projectRoot && a.knownHostsFile === b.knownHostsFile && a.proxyCommand === b.proxyCommand && a.session.command === b.session.command && a.session.root === b.session.root && a.session.settingsPath === b.session.settingsPath;
@@ -90,6 +156,7 @@ export function connectProvider(get, options = {}) {
     const agent = options.agent ?? CODEX_AGENT;
     const admissions = new WeakMap();
     const preflight = async (request) => {
+        request.timing ??= new StageTiming();
         request.signal?.throwIfAborted();
         const api = get();
         if (!api)
@@ -98,13 +165,16 @@ export function connectProvider(get, options = {}) {
         requireLoginCoordinator(api);
         if (request.mode === 'one-shot' && !agent.oneShot)
             throw new NeedError('MODE_UNSUPPORTED', '此远程模型仅支持会话模式', '使用会话模式');
-        const before = api.getConnectionState();
-        const target = unwrap(await awaitL(() => api.ensureReady(agent.loginProvider), request.signal));
-        validateTarget(target);
-        request.signal?.throwIfAborted();
-        if (get() !== api)
-            throw new NeedError('CONNECTION_LOST', '远程主机连接组件已更换', '当前员工连接');
-        const connection = verifiedLogin(api, agent.loginProvider, before);
+        const { target, connection } = await request.timing.run('login-ready', async () => {
+            const before = api.getConnectionState();
+            const target = await ensureReady(api, agent.loginProvider, request.signal);
+            validateTarget(target);
+            request.signal?.throwIfAborted();
+            if (get() !== api)
+                throw new NeedError('CONNECTION_LOST', '远程主机连接组件已更换', '当前员工连接');
+            const connection = await waitForLogin(api, agent.loginProvider, before, get, request.signal);
+            return { target, connection };
+        });
         if (request.identity && request.identity !== identity(target))
             throw new NeedError('SESSION_CONTEXT_MISMATCH', '员工主机与原会话不一致，请新建会话', '原员工主机');
         admissions.set(request, { api, target, connection });
@@ -115,15 +185,14 @@ export function connectProvider(get, options = {}) {
         const admitted = admissions.get(request);
         admissions.delete(request);
         const { api, target, connection } = admitted;
-        const stable = () => { request.signal?.throwIfAborted(); if (get() !== api)
-            throw new NeedError('CONNECTION_LOST', '远程主机连接组件已更换', '当前员工连接'); verifiedLogin(api, agent.loginProvider, connection); };
-        stable();
+        const stable = () => request.timing.run('connection-confirm', () => waitForLogin(api, agent.loginProvider, connection, get, request.signal));
+        await stable();
         if (!request.sessionId)
             throw new NeedError('PROJECT_BINDING_REQUIRED', '我需要当前会话和已选择的工作区，请使用原生工作区入口', 'DSH会话与原生工作区');
         await options.notice?.reconcile(request, api);
-        stable();
-        const resolved = unwrap(await awaitL(() => api.resolveSessionProject(request.sessionId, { provider: agent.loginProvider, purpose: 'user-turn' }), request.signal));
-        stable();
+        await stable();
+        const resolved = await request.timing.run('workspace-resolve', async () => unwrap(await awaitL(() => api.resolveSessionProject(request.sessionId, { provider: agent.loginProvider, purpose: 'user-turn' }), request.signal)));
+        await stable();
         if (!resolved || resolved.instanceId !== connection.instanceId || resolved.epoch !== connection.epoch)
             throw new NeedError('CONNECTION_LOST', '工作区解析回复已失效', '当前连接代次');
         validateTarget(resolved.target);
@@ -132,32 +201,57 @@ export function connectProvider(get, options = {}) {
             throw new NeedError('PROJECT_BINDING_INVALID', '工作区绑定与当前会话或可信主机不一致', 'L核验的原生工作区绑定');
         if (request.cwd && request.cwd !== project.path || request.bindingId && request.bindingId !== resolved.bindingId || request.workspaceId && request.workspaceId !== resolved.workspaceId)
             throw new NeedError('SESSION_CONTEXT_MISMATCH', '原会话的工作区绑定已改变，请新建会话', '原工作区绑定');
-        const details = await options.details?.(request, api, connection, target);
-        stable();
-        let workspaceNotice = undefined;
-        if (resolved.notice) {
-            if (!options.notice)
-                throw new NeedError('DEPENDENCY_REQUIRED', '我需要官方会话持久记录来确认工作区说明', '官方会话与持久化服务');
-            workspaceNotice = await options.notice.deliver(resolved.notice, resolved, request, api);
-            stable();
-        }
-        if (!options.open)
-            throw new NeedError('RUNTIME_REQUIRED', '我需要主机运行适配器', '主机broker适配');
-        const runtime = await options.open(resolved.target, project, { ...request, agent });
+        const details = await request.timing.run('details-open', async () => options.details?.(request, api, connection, target));
         try {
-            stable();
+            if (details)
+                request.timing.bind(detail => details.record(detail));
+            await stable();
+            let workspaceNotice = undefined;
+            if (resolved.notice) {
+                if (!options.notice)
+                    throw new NeedError('DEPENDENCY_REQUIRED', '我需要官方会话持久记录来确认工作区说明', '官方会话与持久化服务');
+                workspaceNotice = await request.timing.run('workspace-notice', () => options.notice.deliver(resolved.notice, resolved, request, api));
+                await stable();
+            }
+            if (!options.open)
+                throw new NeedError('RUNTIME_REQUIRED', '我需要主机运行适配器', '主机broker适配');
+            const observedBinding = api.getWorkspaceBindingState?.();
+            const validateContext = async (ignoreCancellation = false) => {
+                const check = () => waitForLogin(api, agent.loginProvider, connection, get, ignoreCancellation ? undefined : request.signal);
+                await check();
+                if (observedBinding) {
+                    const current = api.getWorkspaceBindingState();
+                    if (current.instanceId !== observedBinding.instanceId || !current.items.some(item => item.bindingId === resolved.bindingId && item.workspaceId === resolved.workspaceId && item.status === 'ready'))
+                        throw new NeedError('SESSION_CONTEXT_MISMATCH', '当前工作区绑定已改变，原会话操作未执行', '原生会话原绑定');
+                }
+                await check();
+            };
+            const runtime = await options.open(resolved.target, project, { ...request, agent, bindingId: resolved.bindingId, workspaceId: resolved.workspaceId, bindingRevision: resolved.bindingRevision, detailChannel: details, validateContext });
+            try {
+                await stable();
+            }
+            catch (error) {
+                await runtime.dispose?.();
+                throw error;
+            }
+            // The transport can outlive a turn; presentation belongs only to this invocation.
+            runtime.workspaceNotice = workspaceNotice || undefined;
+            runtime.details = details ?? runtime.details;
+            runtime.binding = { bindingId: resolved.bindingId, workspaceId: resolved.workspaceId, revision: resolved.bindingRevision };
+            runtime.connection = { ...connection };
+            runtime.loginRequired = () => offerLogin(api, request, get, agent);
+            return runtime;
         }
         catch (error) {
-            await runtime.dispose?.();
+            try {
+                await details?.flush();
+            }
+            catch (diagnostic) {
+                const code = (value) => value instanceof NeedError && /^[A-Z][A-Z0-9_]*$/.test(value.code) ? value.code : 'UNKNOWN_FAILURE';
+                throw new NeedError('CONVERSATION_DETAILS_FAILED', '技术详情未能保存；本轮已停止', `原错误代码 ${code(error)}；诊断错误代码 ${code(diagnostic)}`);
+            }
             throw error;
         }
-        // The transport can outlive a turn; presentation belongs only to this invocation.
-        runtime.workspaceNotice = workspaceNotice || undefined;
-        runtime.details = details ?? runtime.details;
-        runtime.binding = { bindingId: resolved.bindingId, workspaceId: resolved.workspaceId, revision: resolved.bindingRevision };
-        runtime.connection = { ...connection };
-        runtime.loginRequired = () => offerLogin(api, request, get, agent);
-        return runtime;
     };
     resolve.preflight = preflight;
     return resolve;

package/dist/readiness.js

@@ -32,6 +32,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
+import { loginDiagnostic } from "./login-diagnostic.js";
 import { randomUUID } from 'node:crypto';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { unwrap, awaitL, requireLoginCoordinator, requireLoginState } from "./provider.js";
@@ -56,18 +57,19 @@ function snapshot(api, agent = CODEX_AGENT) {
     if (connection.phase !== 'connected')
         return denied(connection.need?.code ?? (connection.phase === 'disposed' ? 'DISPOSED' : 'CONNECTION_LOST'));
     const state = api.getLoginPromptState();
+    const diagnostic = (reason) => ({ label: '登录检查快照', value: JSON.stringify(loginDiagnostic('readiness', reason, brand, connection, state)) });
     if (!connection.instanceId || state.instanceId !== connection.instanceId)
-        return denied('AUTH_STATUS_INVALID');
+        return denied('AUTH_STATUS_INVALID', [diagnostic('LOGIN_INSTANCE_MISMATCH')]);
     requireLoginState(state);
     const technical = details({ hostContext: state.technicalDetails?.hostContext });
     if (state.phase === 'blocked' || state.phase === 'disposed')
-        return denied(state.technicalDetails?.code ?? 'AUTH_STATUS_INVALID', technical);
-    if (state.checkingProviders.includes(brand) || state.phase === 'authorizing' && state.provider === brand)
+        return denied(state.technicalDetails?.code ?? 'AUTH_STATUS_INVALID', [...technical, diagnostic(state.phase === 'disposed' ? 'LOGIN_PHASE_DISPOSED' : 'LOGIN_PHASE_BLOCKED')]);
+    if (state.queuedProviders?.includes(brand) || state.checkingProviders.includes(brand) || state.phase === 'authorizing' && state.provider === brand)
         return { phase: 'checking', loginStatus: 'unknown', title: `正在检查 ${agent.name.zh} 登录状态`, message: '远程主机连接正在检查登录状态。', technical };
     if (state.providerNeeds[brand])
-        return denied(state.providerNeeds[brand].code, technical);
+        return denied(state.providerNeeds[brand].code, [...technical, diagnostic('LOGIN_PROVIDER_NEED')]);
     if (typeof state.logins?.[brand] !== 'boolean')
-        return denied('AUTH_STATUS_INVALID', technical);
+        return denied('AUTH_STATUS_INVALID', [...technical, diagnostic('LOGIN_VALUE_INVALID')]);
     return state.logins[brand] ? { phase: 'ready', loginStatus: 'logged-in', title: `${agent.name.zh}已登录`, message: '本次远程主机连接和主机登录检查已完成。', technical } : { phase: 'login-required', loginStatus: 'not-logged-in', title: `${agent.name.zh} 尚未登录`, message: '需要登录，请到设置 → 远程主机连接 点登录', technical };
 }
 export function createReadiness(get, agent = CODEX_AGENT) {

package/dist/recovery-checkpoint.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { RuntimeRequest } from './provider.ts';
+/** A step's accepted batch follows step/start in the official event contract. */
+export declare function currentInputIds(ctx: Context, request: RuntimeRequest): Promise<readonly string[]>;
+/** Read only the official persistence API after its awaited durability checkpoint. */
+export declare function verifyRecoveryCheckpoint(ctx: Context, request: RuntimeRequest, provider: string): Promise<boolean>;

package/dist/recovery-checkpoint.js

@@ -0,0 +1,71 @@
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { BlockAssembler, expandAssistantStream } from '@deepseek-ai/dsh-llm';
+import { isDeepStrictEqual } from 'node:util';
+/** A step's accepted batch follows step/start in the official event contract. */
+export async function currentInputIds(ctx, request) {
+    if (!request.sessionId)
+        return [];
+    const id = SessionId(request.sessionId), store = ctx.get('sessions'), session = store?.get(id);
+    const persistence = ctx.get('sessionPersistence');
+    if (!session || !store || !persistence || !await store.flush(session))
+        return [];
+    const handle = await persistence.open(id, 'read');
+    try {
+        if (handle.id !== id || handle.header?.id !== id || handle.access !== 'read')
+            return [];
+        const { events } = await handle.read();
+        if (!Array.isArray(events))
+            return [];
+        let step;
+        let ids = [];
+        for (const event of events) {
+            if (event.type === 'step/start') {
+                step = event;
+                ids = [];
+            }
+            else if (event.type === 'turn/start' || event.type === 'step/end' || event.type === 'turn/end') {
+                step = undefined;
+                ids = [];
+            }
+            else if (event.type === 'user/message' && step)
+                ids.push(event.data.id);
+        }
+        return ids;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Read only the official persistence API after its awaited durability checkpoint. */
+export async function verifyRecoveryCheckpoint(ctx, request, provider) {
+    if (!request.sessionId || !request.recoveryCheckpointId || !request.resumeSessionId)
+        return false;
+    const id = SessionId(request.sessionId), store = ctx.get('sessions'), session = store?.get(id);
+    const persistence = ctx.get('sessionPersistence');
+    if (!session || typeof store?.flush !== 'function' || typeof persistence?.open !== 'function')
+        return false;
+    if (!await store.flush(session))
+        return false;
+    const handle = await persistence.open(id, 'read');
+    try {
+        if (handle?.id !== id || handle.header?.id !== id || handle.access !== 'read')
+            return false;
+        const { events } = await handle.read();
+        if (!Array.isArray(events))
+            return false;
+        const final = events.findLast(e => e.type === 'assistant/message' && e.surfaceOp === 'append');
+        const live = session.deriveMessages().findLast(m => m.role === 'assistant');
+        if (final?.type !== 'assistant/message' || final.data.interrupted || !live || live.id !== final.data.message.id || !isDeepStrictEqual(live, final.data.message))
+            return false;
+        const message = final.data.message, pointer = message.source.replayState?.response;
+        if (message.source.provider !== provider || pointer?.agent !== provider || pointer.dshSessionId !== id || pointer.sessionId !== request.resumeSessionId || pointer.recoveryCheckpointId !== request.recoveryCheckpointId)
+            return false;
+        const assembled = new BlockAssembler();
+        for (const part of expandAssistantStream(final.data.stream))
+            assembled.push(part.chunk);
+        return ['stop', 'max-tokens'].includes(assembled.finish.kind) && isDeepStrictEqual(assembled.replayState, message.source.replayState) && isDeepStrictEqual(assembled.blocks(), message.content);
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/recovery.d.ts

@@ -0,0 +1,34 @@
+import type { AgentCapabilities, SessionConfigOption } from '@agentclientprotocol/sdk/unstable';
+export interface AcpRecovery {
+    sessionId: string;
+    capabilities: AgentCapabilities;
+    modelConfiguration?: {
+        configOptions: SessionConfigOption[];
+        resolvedEvidence?: {
+            modelValue: string;
+            resolvedModel: string;
+        };
+    };
+    configUpdates?: SessionConfigOption[][];
+}
+export interface RecoveryState {
+    version: 1;
+    phase: 'dirty' | 'clean' | 'ended';
+    scope: string;
+    brokerId: string;
+    instanceId?: string;
+    pid?: number;
+    cursor?: number;
+    checkpointId?: string;
+    acp?: AcpRecovery;
+}
+export interface RecoveryJournal {
+    read(): Promise<RecoveryState | undefined>;
+    write(state: RecoveryState): Promise<void>;
+}
+export declare function validateRecovery(value: unknown): RecoveryState;
+/** Only negotiated booleans/known empty capability markers, never agent metadata. */
+export declare function recoveryCapabilities(c: AgentCapabilities): AgentCapabilities;
+export declare function recoveryKey(value: unknown): string;
+/** History is immutable; current is atomically replaced only after fsync. No expiry. */
+export declare function recoveryJournal(profileDir: string, key: string): RecoveryJournal;

package/dist/recovery.js

@@ -0,0 +1,52 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { open, rename } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { privateDirectory, durableWrite, readJournal } from "./remote-details.js";
+import { NeedError } from "./remote.js";
+const invalid = () => new NeedError('RECOVERY_STORAGE_INVALID', '会话恢复记录无效，本轮尚未发送', '有效的私有会话恢复记录');
+export function validateRecovery(value) {
+    const s = value;
+    if (!s || s.version !== 1 || !['dirty', 'clean', 'ended'].includes(s.phase) || !/^[a-f0-9]{64}$/.test(s.scope) || !/^r[a-f0-9]{23}$/.test(s.brokerId))
+        throw invalid();
+    if (s.instanceId !== undefined && !/^[a-f0-9-]{36}$/.test(s.instanceId) || s.pid !== undefined && (!Number.isSafeInteger(s.pid) || s.pid < 1))
+        throw invalid();
+    if (s.phase === 'clean' && (!s.instanceId || !Number.isSafeInteger(s.cursor) || s.cursor < 0 || typeof s.checkpointId !== 'string' || !s.checkpointId || !s.acp || typeof s.acp.sessionId !== 'string' || !s.acp.sessionId || !s.acp.capabilities || typeof s.acp.capabilities !== 'object' || Array.isArray(s.acp.capabilities)))
+        throw invalid();
+    return structuredClone(s);
+}
+/** Only negotiated booleans/known empty capability markers, never agent metadata. */
+export function recoveryCapabilities(c) {
+    return { loadSession: c.loadSession === true, promptCapabilities: { image: c.promptCapabilities?.image === true, audio: c.promptCapabilities?.audio === true, embeddedContext: c.promptCapabilities?.embeddedContext === true }, sessionCapabilities: { ...(c.sessionCapabilities?.resume ? { resume: {} } : {}), ...(c.sessionCapabilities?.systemPrompt ? { systemPrompt: {} } : {}) } };
+}
+export function recoveryKey(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+/** History is immutable; current is atomically replaced only after fsync. No expiry. */
+export function recoveryJournal(profileDir, key) {
+    if (!/^[a-f0-9]{64}$/.test(key))
+        throw invalid();
+    const parent = join(profileDir, 'ai-workbench-remote-agent'), dir = join(parent, 'recovery', key), current = join(dir, 'current.json');
+    let tail = Promise.resolve();
+    const prepare = async () => { await privateDirectory(parent); await privateDirectory(join(parent, 'recovery')); await privateDirectory(dir); };
+    return {
+        async read() { await tail; await prepare(); try {
+            return validateRecovery(await readJournal(current));
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                return;
+            throw error;
+        } },
+        write(state) { const value = validateRecovery(state); const task = tail.then(async () => { await prepare(); const id = randomUUID(); await durableWrite(join(dir, id + '.json'), value); const temp = join(dir, id + '.current'); const file = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); try {
+            await file.writeFile(JSON.stringify(value) + '\n');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        } await rename(temp, current); const directory = await open(dir, 'r'); try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        } }); tail = task; return task; },
+    };
+}

package/dist/remote-details.d.ts

@@ -1,8 +1,9 @@
 import { type DetailObservation } from './conversation-details.ts';
+import type { LoginDiagnostic } from './login-diagnostic.ts';
 import type { ConnectApi as LConnectApi, ConnectionState } from '@ai-workbench/connect/api';
 export type { RemoteConversationDetail as RemoteDetail } from '@ai-workbench/connect/api';
 type Connection = Pick<ConnectionState, 'instanceId' | 'epoch' | 'phase'>;
-export type RemoteDetailsApi = Pick<LConnectApi, 'getConnectionState'> & Partial<Pick<LConnectApi, 'getContractInfo' | 'appendRemoteConversationDetail' | 'getRemoteConversationDetailReceipt' | 'listRemoteConversationDetails'>>;
+export type RemoteDetailsApi = Pick<LConnectApi, 'getConnectionState'> & Partial<Pick<LConnectApi, 'getContractInfo' | 'appendRemoteConversationDetail' | 'getRemoteConversationDetailReceipt' | 'listRemoteConversationDetails' | 'appendLoginDiagnostic' | 'getLoginDiagnosticReceipt' | 'listLoginDiagnostics'>>;
 export interface DetailChannel {
     record(observation: DetailObservation): void;
     beginTurn(ids: {
@@ -18,9 +19,24 @@ export interface DetailRequest {
     identity: string;
     connection: Connection;
 }
+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 declare function createRemoteDetails(options: {
     profileDir: string;
     getApi: () => RemoteDetailsApi | undefined;
 }): {
+    recordLoginFailure(request: {
+        sessionId?: string;
+        code: string;
+        diagnostic: LoginDiagnostic;
+        context?: {
+            turn: string | number | null;
+            step: string | number | null;
+        };
+    }): Promise<{
+        eventId: string;
+        recorded: true;
+    }>;
     open(request: DetailRequest): Promise<DetailChannel>;
 };