@ai-workbench/remote-agent 0.8.0 → 0.8.1

package/dist/provider.js

@@ -132,10 +132,13 @@ 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', '我需要官方会话持久记录来确认工作区说明', '官方会话与持久化服务');
-            await options.notice.deliver(resolved.notice, resolved, request, api);
+            workspaceNotice = await options.notice.deliver(resolved.notice, resolved, request, api);
             stable();
         }
         if (!options.open)
@@ -148,6 +151,9 @@ export function connectProvider(get, options = {}) {
             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);

package/dist/remote-details.d.ts

@@ -0,0 +1,26 @@
+import { type DetailObservation } from './conversation-details.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 interface DetailChannel {
+    record(observation: DetailObservation): void;
+    beginTurn(ids: {
+        turn: string | number | null;
+        step: string | number | null;
+    }): void;
+    endTurn(): void;
+    flush(): Promise<void>;
+}
+export interface DetailRequest {
+    sessionId: string;
+    provider: 'claude' | 'codex';
+    identity: string;
+    connection: Connection;
+}
+export declare function createRemoteDetails(options: {
+    profileDir: string;
+    getApi: () => RemoteDetailsApi | undefined;
+}): {
+    open(request: DetailRequest): Promise<DetailChannel>;
+};

package/dist/remote-details.js

@@ -0,0 +1,250 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+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 { NeedError } from "./remote.js";
+const failure = (code, message = '技术详情未能持久记录，本轮已停止。') => new NeedError(code, message, '可用的远程主机连接技术详情');
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+function unwrap(result) {
+    if (!object(result))
+        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+    if (result.ok === false && object(result.error) && typeof result.error.code === 'string')
+        throw failure(result.error.code);
+    if (result.ok !== true)
+        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+    return result.value;
+}
+function identifier(value) { return value === null || typeof value === 'string' && value.trim().length > 0 || typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; }
+function kind(observation) {
+    if (/UNKNOWN|UNSUPPORTED|FOREIGN/.test(observation.code))
+        return observation.severity === 'action-required' ? 'action-required' : 'unknown';
+    return { extension: 'extensions', tool: 'tools', need: 'action-required', notice: 'extensions', session: 'extensions' }[observation.kind] ?? observation.kind;
+}
+async function privateDirectory(path) {
+    if (!isAbsolute(path))
+        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+    // Existing parent/profile ownership is the host's responsibility; reject symlinks
+    // along the full path before creating our own private child directories.
+    let part = parse(path).root;
+    for (const member of path.slice(part.length).split('/').filter(Boolean)) {
+        part = join(part, member);
+        try {
+            const info = await lstat(part);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+        }
+        catch (error) {
+            if (error?.code !== 'ENOENT')
+                throw error;
+            try {
+                await mkdir(part, { mode: 0o700 });
+            }
+            catch (creation) {
+                if (creation?.code !== 'EEXIST')
+                    throw creation;
+                const info = await lstat(part);
+                if (!info.isDirectory() || info.isSymbolicLink())
+                    throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+            }
+        }
+    }
+    if (await realpath(path) !== path)
+        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+    const info = await lstat(path);
+    if ((info.mode & 0o077) !== 0 || (process.getuid && info.uid !== process.getuid()))
+        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+}
+async function durableWrite(path, value) {
+    const file = await open(path, 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();
+    }
+    const parent = await open(join(path, '..'), 'r');
+    try {
+        await parent.sync();
+    }
+    finally {
+        await parent.close();
+    }
+}
+async function readJournal(path) {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await file.stat();
+        if (!info.isFile() || (info.mode & 0o077) !== 0 || (process.getuid && info.uid !== process.getuid()))
+            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+        return JSON.parse(await file.readFile('utf8'));
+    }
+    finally {
+        await file.close();
+    }
+}
+export function createRemoteDetails(options) {
+    const root = join(options.profileDir, 'ai-workbench-remote-agent', 'diagnostics');
+    const scopes = new Map();
+    const initialize = async () => { await privateDirectory(join(options.profileDir, 'ai-workbench-remote-agent')); await privateDirectory(root); };
+    return { async open(request) {
+            if (!request.sessionId || !request.identity || !request.connection.instanceId || !Number.isSafeInteger(request.connection.epoch) || request.connection.epoch < 0 || !['claude', 'codex'].includes(request.provider))
+                throw failure('REMOTE_DETAIL_SCOPE_INVALID');
+            try {
+                await initialize();
+            }
+            catch {
+                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+            }
+            const api = options.getApi();
+            const stable = () => {
+                const now = api?.getConnectionState();
+                if (!api || options.getApi() !== api || now?.phase !== 'connected' || now.instanceId !== request.connection.instanceId || now.epoch !== request.connection.epoch)
+                    throw failure('CONNECTION_LOST');
+            };
+            stable();
+            const capability = api.getContractInfo?.();
+            if (!object(capability) || capability.remoteConversationDetails !== 1 || !['appendRemoteConversationDetail', 'getRemoteConversationDetailReceipt', 'listRemoteConversationDetails'].every(key => typeof api[key] === 'function')) {
+                await durableWrite(join(root, randomUUID() + '.json'), { version: 1, code: 'TECHNICAL_DETAILS_UNAVAILABLE', summary: '技术详情暂不可用', session: hash(request.sessionId), provider: request.provider });
+                throw failure('TECHNICAL_DETAILS_UNAVAILABLE', '技术详情暂不可用，请更新远程主机连接组件。');
+            }
+            const key = hash(request.identity + '\0' + request.sessionId + '\0' + request.provider), dir = join(root, key);
+            await privateDirectory(dir);
+            const scope = scopes.get(key) ?? { tail: Promise.resolve(), maximum: 0, loaded: false };
+            scopes.set(key, scope);
+            // Serialize open and appends in this host-user/session/brand scope.
+            const load = scope.tail.then(async () => {
+                stable();
+                const generation = request.connection.instanceId + '\0' + request.connection.epoch;
+                if (scope.loaded && scope.generation === generation)
+                    return;
+                const names = await readdir(dir);
+                for (const name of names) {
+                    const match = /^(\d+)-([0-9a-f-]+)\.json$/.exec(name);
+                    if (!match)
+                        continue;
+                    const n = Number(match[1]);
+                    if (!Number.isSafeInteger(n))
+                        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                    scope.maximum = Math.max(scope.maximum, n);
+                    const saved = await readJournal(join(dir, name));
+                    if (!object(saved) || !object(saved.detail) || saved.detail.eventId !== match[2] || saved.detail.sequence !== n || saved.detail.sessionId !== request.sessionId || saved.detail.provider !== request.provider)
+                        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                    const settled = 'settled-' + match[2] + '.json';
+                    if (names.includes(settled)) {
+                        const result = await readJournal(join(dir, settled));
+                        if (!object(result) || result.eventId !== match[2] || !['recorded', 'rejected'].includes(result.state))
+                            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                        continue;
+                    }
+                    // An interrupted append is reconciled by pure read, with the original
+                    // event's epoch intact. Missing receipts stay unknown and never trigger append.
+                    stable();
+                    const receipt = unwrap(await api.getRemoteConversationDetailReceipt({ eventId: match[2], sessionId: request.sessionId, provider: request.provider }));
+                    stable();
+                    if (receipt.eventId !== match[2])
+                        throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                    if (!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' });
+                }
+                let cursor, previous = -1;
+                const seen = new Set();
+                let expected;
+                let count = 0;
+                do {
+                    stable();
+                    const page = unwrap(await api.listRemoteConversationDetails({ sessionId: request.sessionId, provider: request.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 !== request.sessionId || entry.provider !== request.provider || !Number.isSafeInteger(entry.sequence) || 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;
+            });
+            scope.tail = load.then(() => { }, () => { });
+            await load;
+            let turn = null, step = null;
+            let tail = Promise.resolve(), firstFailure;
+            const enqueue = (operation) => {
+                const task = scope.tail.then(operation);
+                scope.tail = task.then(() => { }, () => { });
+                tail = task.catch(error => { scope.loaded = false; firstFailure ??= { error }; });
+            };
+            return {
+                beginTurn(ids) { if (!identifier(ids.turn) || !identifier(ids.step))
+                    throw failure('REMOTE_DETAIL_SCOPE_INVALID'); turn = ids.turn; step = ids.step; },
+                endTurn() { turn = null; step = null; },
+                record(observation) {
+                    const safe = sanitizeObservation(observation, true);
+                    const wire = (value) => Array.isArray(value) ? value.map(wire) : object(value) ? isSanitizedRedaction(value) ? (typeof value.valueType === 'string' ? { redacted: true, valueType: value.valueType, value: '已脱敏' } : '已脱敏') : Object.fromEntries(Object.entries(value).map(([key, child]) => [key, wire(child)])) : value;
+                    const sequence = scope.maximum + 1;
+                    if (!Number.isSafeInteger(sequence))
+                        throw failure('REMOTE_DETAIL_SEQUENCE_INVALID');
+                    scope.maximum = sequence;
+                    const detail = Object.freeze({ ...safe, payload: wire(safe.payload), version: 1, eventId: randomUUID(), instanceId: request.connection.instanceId, epoch: request.connection.epoch, sessionId: request.sessionId, provider: request.provider, turn, step, sequence, kind: kind(observation) });
+                    enqueue(async () => {
+                        // A private X journal is retained even if L is disconnected or rejects it.
+                        const file = join(dir, sequence + '-' + detail.eventId + '.json');
+                        try {
+                            await durableWrite(file, { state: 'pending', detail });
+                        }
+                        catch {
+                            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                        }
+                        stable();
+                        let response;
+                        try {
+                            response = await api.appendRemoteConversationDetail(structuredClone(detail));
+                        }
+                        catch {
+                            stable();
+                            const receipt = unwrap(await api.getRemoteConversationDetailReceipt({ eventId: detail.eventId, sessionId: detail.sessionId, provider: detail.provider }));
+                            stable();
+                            if (receipt.eventId !== detail.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-' + detail.eventId + '.json'), { eventId: detail.eventId, state: 'recorded' });
+                            return;
+                        }
+                        stable();
+                        if (response?.ok === false) {
+                            await durableWrite(join(dir, 'settled-' + detail.eventId + '.json'), { eventId: detail.eventId, state: 'rejected', code: response.error.code });
+                        }
+                        const ack = unwrap(response);
+                        if (ack.eventId !== detail.eventId || ack.recorded !== true)
+                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                        await durableWrite(join(dir, 'settled-' + detail.eventId + '.json'), { eventId: detail.eventId, state: 'recorded' });
+                    });
+                },
+                async flush() { await tail; if (firstFailure)
+                    throw firstFailure.error; stable(); },
+            };
+        } };
+}

package/dist/workspace-notice.d.ts

@@ -1,4 +1,5 @@
 import type { Context } from '@deepseek-ai/cordis';
+import { type RequestMessage } from '@deepseek-ai/dsh-llm';
 import { type AgentDefinition } from './agents.ts';
 import type { ConnectApi, RuntimeRequest } from './provider.ts';
 import type { WorkspaceNotice, SessionProjectTarget } from './connect-contract.ts';
@@ -20,7 +21,27 @@ export interface WorkspaceNoticeMarker {
 export declare function parseWorkspaceNoticeMarker(message: unknown): WorkspaceNoticeMarker | undefined;
 /** Only this plugin's complete, source-bound notice may be excluded from remote model history. */
 export declare function isWorkspaceNoticeMessage(message: unknown): boolean;
+/** A verified first block in the actual model reply, never a second final message. */
+export interface WorkspaceNoticePresentation {
+    readonly kind: 'workspace-notice';
+    readonly version: 2;
+    readonly provider: string;
+    readonly loginProvider: 'claude' | 'codex';
+    readonly sessionId: string;
+    readonly noticeId: string;
+    readonly claimId: string;
+    readonly workspaceName: string;
+    readonly bindingId: string;
+    readonly workspaceId: string;
+    readonly turn: number;
+    readonly step: number;
+    readonly blockIndex: 0;
+    readonly text: string;
+}
+export declare function workspaceNoticeFromMessage(message: unknown): WorkspaceNoticePresentation | undefined;
+/** Preserve the model answer and exact remote replay pointer; ordinary text is never searched. */
+export declare function withoutWorkspaceNotice<T extends RequestMessage>(message: T): T;
 export declare function createWorkspaceNoticeConsumer(ctx: Context, agent: AgentDefinition): {
     reconcile: (request: RuntimeRequest, api: ConnectApi) => Promise<void>;
-    deliver: (notice: WorkspaceNotice, resolved: SessionProjectTarget, request: RuntimeRequest, api: ConnectApi) => Promise<void>;
+    deliver: (notice: WorkspaceNotice, resolved: SessionProjectTarget, request: RuntimeRequest, api: ConnectApi) => Promise<WorkspaceNoticePresentation | undefined>;
 };