@ai-workbench/remote-agent 0.8.0 → 0.8.2

package/dist/remote.d.ts

@@ -1,3 +1,4 @@
+import type { LoginDiagnostic } from './login-diagnostic.ts';
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 /** Development-only direct SSH. Product transports must consume L's exported sshArgs (v0.2). */
 export interface DevelopmentSshTarget {
@@ -16,6 +17,8 @@ export interface Need {
 export declare class NeedError extends Error {
     code: string;
     requires: string;
+    technical?: LoginDiagnostic;
+    officialReason?: string;
     constructor(code: string, message: string, requires: string);
 }
 export declare function shellQuote(value: string): string;

package/dist/remote.js

@@ -2,6 +2,8 @@ import { spawn } from 'node:child_process';
 export class NeedError extends Error {
     code;
     requires;
+    technical;
+    officialReason;
     constructor(code, message, requires) {
         super(message);
         this.name = 'NeedError';

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>;
 };

package/dist/workspace-notice.js

@@ -1,5 +1,5 @@
 import { SessionId } from '@deepseek-ai/dsh-session';
-import { AssistantStreamAccumulator, BlockAssembler, createAssistantMessage, freezeMessage, expandAssistantStream } from '@deepseek-ai/dsh-llm';
+import { BlockAssembler, expandAssistantStream } from '@deepseek-ai/dsh-llm';
 import { isDeepStrictEqual } from 'node:util';
 import { AGENTS } from "./agents.js";
 import { NeedError } from "./remote.js";
@@ -32,55 +32,86 @@ export function parseWorkspaceNoticeMarker(message) {
 }
 /** Only this plugin's complete, source-bound notice may be excluded from remote model history. */
 export function isWorkspaceNoticeMessage(message) { return parseWorkspaceNoticeMarker(message) !== undefined; }
+function rawPresentation(message) {
+    const response = rawMarker(message), presentation = response && object(response.presentation) ? response.presentation : undefined;
+    return presentation && object(presentation.workspaceNotice) ? presentation.workspaceNotice : undefined;
+}
+function shape(value) {
+    if (!object(value))
+        return false;
+    const agent = AGENTS.find(a => a.id === value.provider);
+    return !!agent && value.kind === 'workspace-notice' && value.version === 2 && value.loginProvider === agent.loginProvider
+        && ['sessionId', 'noticeId', 'claimId', 'bindingId', 'workspaceId'].every(k => string(value[k])) && workspaceName(value.workspaceName)
+        && Number.isSafeInteger(value.turn) && value.turn > 0 && Number.isSafeInteger(value.step) && value.step > 0
+        && value.blockIndex === 0 && value.text === noticeText(value.workspaceName) + '\n\n';
+}
+export function workspaceNoticeFromMessage(message) {
+    if (!object(message) || message.role !== 'assistant' || !object(message.source) || message.source.kind !== 'model')
+        return;
+    const marker = rawPresentation(message), pointer = rawMarker(message);
+    if (!shape(marker) || message.source.provider !== marker.provider || pointer?.agent !== marker.provider || pointer.dshSessionId !== marker.sessionId
+        || pointer.bindingId !== marker.bindingId || pointer.workspaceId !== marker.workspaceId || !Array.isArray(message.content))
+        return;
+    const block = message.content[marker.blockIndex];
+    if (!object(block) || block.type !== 'text' || block.text !== marker.text)
+        return;
+    return marker;
+}
+/** Preserve the model answer and exact remote replay pointer; ordinary text is never searched. */
+export function withoutWorkspaceNotice(message) {
+    const marker = workspaceNoticeFromMessage(message);
+    if (!marker)
+        return message;
+    return { ...message, content: message.content.filter((_block, index) => index !== marker.blockIndex) };
+}
 function unknown(cause) {
-    return Object.assign(new NeedError('PROJECT_NOTICE_DELIVERY_UNKNOWN', '工作区说明的会话持久回执无法核对；请联系管理员核对，本次未继续派发远端请求。', '完整的官方会话持久记录和 L 工作区说明回执'), cause === undefined ? {} : { cause });
+    return Object.assign(new NeedError('PROJECT_NOTICE_DELIVERY_UNKNOWN', '工作区说明的最终回复持久回执无法核对；请联系管理员核对，本次未继续派发远端请求。', '完整的官方最终会话记录和L工作区说明回执'), cause === undefined ? {} : { cause });
 }
 function requireServices(ctx, request) {
     const id = string(request.sessionId) ? SessionId(request.sessionId) : undefined;
-    const registry = ctx.get('agents'), store = ctx.get('sessions');
-    // The persistence definition is an optional host service, not an installed private writer.
-    const persistence = ctx.get('sessionPersistence');
-    const live = id && typeof registry?.get === 'function' ? registry.get(id) : undefined;
-    const session = live?.session;
+    const registry = ctx.get('agents'), store = ctx.get('sessions'), persistence = ctx.get('sessionPersistence');
+    const live = id && typeof registry?.get === 'function' ? registry.get(id) : undefined, session = live?.session;
     if (!id || !live || live.id !== id || !session || session.id !== id || typeof store?.get !== 'function' || store.get(id) !== session
         || typeof session.snapshotEvents !== 'function' || typeof session.append !== 'function' || typeof store.flush !== 'function' || typeof persistence?.open !== 'function') {
-        throw new NeedError('DEPENDENCY_REQUIRED', '我需要当前真实 DSH 会话及其官方持久化读取能力，才能确认工作区说明；本次未启动远端。', 'DSH agents、sessions、sessionPersistence 公共能力');
+        throw new NeedError('DEPENDENCY_REQUIRED', '我需要当前真实会话及官方持久化读取能力，才能确认工作区说明；本次未启动远端。', 'DSH agents、sessions、sessionPersistence公共能力');
     }
     return { session, flush: () => store.flush(session), persistence };
 }
 function requireAcknowledge(api) {
     const method = api.acknowledgeWorkspaceNotice;
     if (typeof method !== 'function')
-        throw new NeedError('DEPENDENCY_REQUIRED', '我需要远程主机连接提供工作区说明回执能力；本次未启动远端。', 'L acknowledgeWorkspaceNotice 公共接口');
+        throw new NeedError('DEPENDENCY_REQUIRED', '我需要工作区说明回执能力；本次未启动远端。', 'L acknowledgeWorkspaceNotice公共接口');
     return method.bind(api);
 }
-async function acknowledge(method, receipt) {
-    const result = await method(receipt);
+function receipt(marker, outcome, deliveryId) {
+    const base = { noticeId: marker.noticeId, surface: 'provider', claimId: marker.claimId, sessionId: marker.sessionId, provider: marker.loginProvider };
+    if (outcome === 'delivered' && string(deliveryId))
+        return { ...base, outcome, deliveryId };
+    return { ...base, outcome: 'unknown' };
+}
+async function acknowledge(method, value) {
+    const result = await method(value);
     if (!object(result) || result.ok !== true)
         throw unknown(result);
 }
-function receipt(marker, outcome) {
-    const base = { noticeId: marker.noticeId, surface: 'provider', claimId: marker.claimId, sessionId: marker.sessionId, provider: marker.loginProvider };
-    return outcome === 'delivered' ? { ...base, outcome, deliveryId: marker.deliveryId } : { ...base, outcome };
-}
-async function reportUnknown(method, marker, cause) {
+async function reportUnknown(api, marker, cause) {
     let failure = cause;
     try {
-        await acknowledge(method, receipt(marker, 'unknown'));
+        await acknowledge(requireAcknowledge(api), receipt(marker, 'unknown'));
     }
-    catch (reportFailure) {
-        failure = new AggregateError([cause, reportFailure], '工作区说明的核对和未知状态记录均未完成');
+    catch (error) {
+        failure = new AggregateError([cause, error], '说明核对和未知状态记录均未完成');
     }
     throw unknown(failure);
 }
-async function readDurable(services, offset, length) {
+async function readDurable(services) {
     if (!await services.flush())
         throw unknown();
     const handle = await services.persistence.open(services.session.id, 'read');
     try {
         if (!handle || handle.id !== services.session.id || handle.header?.id !== services.session.id || handle.access !== 'read' || typeof handle.read !== 'function' || typeof handle.close !== 'function')
             throw unknown();
-        const result = await handle.read(offset, length);
+        const result = await handle.read();
         if (!result || !Array.isArray(result.events))
             throw unknown();
         return result.events;
@@ -90,44 +121,22 @@ async function readDurable(services, offset, length) {
             await handle.close();
     }
 }
-function validateRecord(event, sessionId) {
-    const marker = parseWorkspaceNoticeMarker(event.data.message);
-    if (!marker || marker.sessionId !== sessionId || event.surfaceOp !== 'append' || event.data.interrupted === true || !Array.isArray(event.data.stream))
+function validateFinal(event, marker, events) {
+    if (event.surfaceOp !== 'append' || event.data.interrupted === true || !Array.isArray(event.data.stream)
+        || event.data.turn !== marker.turn || event.data.step !== marker.step || !isDeepStrictEqual(workspaceNoticeFromMessage(event.data.message), marker))
+        throw unknown();
+    // Chat renders the last final for a step. An earlier append is not enough.
+    if (events.some(e => e.type === 'assistant/message' && e.surfaceOp === 'append' && e.seq > event.seq && e.data.turn === marker.turn && e.data.step === marker.step))
         throw unknown();
     const assembler = new BlockAssembler();
     for (const member of expandAssistantStream(event.data.stream))
         assembler.push(member.chunk);
-    if (assembler.finish.kind !== 'stop' || !isDeepStrictEqual(assembler.blocks(), event.data.message.content)
-        || !isDeepStrictEqual(assembler.replayState, event.data.message.source.replayState) || assembler.usage !== undefined || event.data.usage !== undefined)
+    if (!['stop', 'max-tokens'].includes(assembler.finish.kind) || !isDeepStrictEqual(assembler.blocks(), event.data.message.content)
+        || !isDeepStrictEqual(assembler.replayState, event.data.message.source.replayState))
         throw unknown();
-    return marker;
 }
-function ownRecords(events, sessionId, agent) {
-    const found = [];
-    for (const event of events) {
-        if (event.type !== 'assistant/message' || event.data.message.source.provider !== agent.id)
-            continue;
-        const raw = rawMarker(event.data.message);
-        if (raw?.kind !== 'workspace-notice')
-            continue;
-        // A fork may retain an ancestor's notice. It is never this Session's claim.
-        if (string(raw.sessionId) && raw.sessionId !== sessionId)
-            continue;
-        const marker = validateRecord(event, sessionId);
-        if (marker.provider !== agent.id || marker.loginProvider !== agent.loginProvider)
-            throw unknown();
-        found.push({ event, marker });
-    }
-    const notices = new Map();
-    for (const { marker } of found) {
-        if (notices.has(marker.noticeId))
-            throw unknown();
-        notices.set(marker.noticeId, marker.deliveryId);
-    }
-    return found;
-}
-function activeRequest(session, definition) {
-    let turn, step, model, provider;
+function activeRequest(session, agent) {
+    let turn, step, provider;
     for (const event of session.snapshotEvents())
         switch (event.type) {
             case 'turn/start':
@@ -148,107 +157,117 @@ function activeRequest(session, definition) {
                 break;
             case 'request/header':
                 provider = event.data.header.config.provider;
-                model = event.data.header.config.model;
                 break;
         }
-    if (!Number.isSafeInteger(turn) || turn < 1 || !Number.isSafeInteger(step) || step < 1 || provider !== definition.id || !string(model))
+    if (!Number.isSafeInteger(turn) || turn < 1 || !Number.isSafeInteger(step) || step < 1 || provider !== agent.id)
         throw unknown();
-    return { turn: turn, step: step, model };
-}
-function buildRecord(services, definition, notice, resolved) {
-    const { session } = services, { turn, step, model } = activeRequest(session, definition), text = noticeText(notice.workspaceName);
-    const base = createAssistantMessage({ content: [{ type: 'text', text }], source: { provider: definition.id, model } });
-    const marker = { kind: 'workspace-notice', version: 1, provider: definition.id, loginProvider: definition.loginProvider,
-        sessionId: session.id, noticeId: notice.noticeId, claimId: notice.claimId, deliveryId: base.id, messageId: base.id,
-        workspaceName: notice.workspaceName, bindingId: resolved.bindingId, workspaceId: resolved.workspaceId };
-    const chunks = [{ type: 'block-start', index: 0, blockType: 'text' }, { type: 'text-delta', index: 0, text },
-        { type: 'block-end', index: 0, block: { type: 'text', text } }, { type: 'finish', reason: { kind: 'stop' }, replayState: { response: marker } }];
-    const accumulator = new AssistantStreamAccumulator(), assembler = new BlockAssembler();
-    for (const chunk of chunks)
-        assembler.push(accumulator.push({ time: Date.now(), chunk }).chunk);
-    const message = freezeMessage({ ...base, source: { ...base.source, replayState: assembler.replayState } });
-    // This public append is the actual ordinary-reply consumption point, not an emitted-yield guess.
-    const event = session.append('assistant/message', { turn, step, message, stream: [...accumulator.snapshot()] }, { surfaceOp: 'append' });
-    return { event, marker };
+    return { turn: turn, step: step };
 }
 export function createWorkspaceNoticeConsumer(ctx, agent) {
+    const pending = new Map();
     const flights = new Map();
-    const reconcile = async (request, api) => {
-        request.signal?.throwIfAborted();
-        const services = requireServices(ctx, request), method = requireAcknowledge(api);
-        let stored;
+    const failures = new Map();
+    const verify = async (sessionId, api, marker, event) => {
         try {
-            const events = await readDurable(services);
-            stored = ownRecords(events, services.session.id, agent);
-            const live = ownRecords(services.session.snapshotEvents(), services.session.id, agent);
-            if (live.some(item => !stored.some(record => record.marker.deliveryId === item.marker.deliveryId && isDeepStrictEqual(record.event, item.event))))
+            const services = requireServices(ctx, { mode: 'session', sessionId }), events = await readDurable(services);
+            const current = event ? events.find(e => e.seq === event.seq) : undefined;
+            if (!event || current?.type !== 'assistant/message' || !isDeepStrictEqual(current, event))
                 throw unknown();
+            validateFinal(current, marker, events);
+            await acknowledge(requireAcknowledge(api), receipt(marker, 'delivered', current.data.message.id));
+            pending.delete(sessionId);
+            failures.delete(sessionId);
         }
         catch (error) {
-            throw unknown(error);
+            return reportUnknown(api, marker, error);
         }
-        for (const { marker } of stored) {
+    };
+    ctx.on('session/event', (session, event) => {
+        const preparation = pending.get(session.id);
+        if (!preparation)
+            return;
+        const { marker, api } = preparation;
+        let relevant;
+        if (event.type === 'assistant/message' && event.data.turn === marker.turn && event.data.step === marker.step && event.data.message.source.provider === agent.id)
+            relevant = event;
+        else if (event.type === 'turn/end' && event.data.turn === marker.turn && !session.snapshotEvents().some(e => e.type === 'assistant/message' && e.data.turn === marker.turn && e.data.step === marker.step && e.data.message.source.provider === agent.id))
+            relevant = undefined;
+        else
+            return;
+        if (flights.has(session.id))
+            return;
+        // Wait for the synchronous event dispatch to enqueue the writer, then flush.
+        const operation = Promise.resolve().then(() => verify(session.id, api, marker, relevant));
+        flights.set(session.id, operation);
+        void operation.catch(error => { failures.set(session.id, error); });
+    });
+    const reconcile = async (request, api) => {
+        request.signal?.throwIfAborted();
+        const services = requireServices(ctx, request);
+        requireAcknowledge(api);
+        const flight = flights.get(services.session.id);
+        if (flight) {
             try {
-                await acknowledge(method, receipt(marker, 'delivered'));
+                await flight;
+                return;
+            }
+            finally {
+                if (flights.get(services.session.id) === flight)
+                    flights.delete(services.session.id);
+            }
+        }
+        const events = await readDurable(services), seen = new Set();
+        let found = false;
+        for (const event of services.session.snapshotEvents()) {
+            if (event.type !== 'assistant/message')
+                continue;
+            const raw = rawPresentation(event.data.message);
+            if (!shape(raw) || raw.provider !== agent.id || raw.sessionId !== services.session.id)
+                continue;
+            if (seen.has(raw.noticeId))
+                return reportUnknown(api, raw, unknown());
+            seen.add(raw.noticeId);
+            found = true;
+            const durable = events.find(e => e.seq === event.seq);
+            if (durable?.type !== 'assistant/message' || !isDeepStrictEqual(durable, event))
+                return reportUnknown(api, raw, unknown());
+            try {
+                validateFinal(durable, raw, events);
+                await acknowledge(requireAcknowledge(api), receipt(raw, 'delivered', durable.data.message.id));
+                failures.delete(services.session.id);
+                pending.delete(services.session.id);
             }
             catch (error) {
-                await reportUnknown(method, marker, error);
+                return reportUnknown(api, raw, error);
             }
         }
+        if (!found && failures.has(services.session.id))
+            throw unknown(failures.get(services.session.id));
         request.signal?.throwIfAborted();
     };
     const deliver = async (notice, resolved, request, api) => {
         request.signal?.throwIfAborted();
-        const services = requireServices(ctx, request), method = requireAcknowledge(api);
+        const services = requireServices(ctx, request);
+        requireAcknowledge(api);
         if (!notice || !string(notice.noticeId) || !string(notice.claimId) || notice.messageKey !== 'remote-workspace-binding' || !workspaceName(notice.workspaceName)
             || resolved.sessionId !== services.session.id || !string(resolved.bindingId) || !string(resolved.workspaceId) || resolved.project?.name !== notice.workspaceName)
             throw unknown();
-        const key = JSON.stringify([services.session.id, notice.noticeId, notice.claimId]);
-        const current = flights.get(key);
-        if (current)
-            return current;
-        const operation = (async () => {
-            let pending;
-            try {
-                const snapshot = services.session.snapshotEvents();
-                for (const event of snapshot) {
-                    if (event.type !== 'assistant/message' || event.data.message.source.provider === agent.id || !AGENTS.some(item => item.id === event.data.message.source.provider))
-                        continue;
-                    const raw = rawMarker(event.data.message);
-                    if (raw?.kind === 'workspace-notice' && raw.noticeId === notice.noticeId && raw.sessionId === services.session.id)
-                        throw unknown();
-                }
-                const records = ownRecords(snapshot, services.session.id, agent);
-                const prior = records.find(item => item.marker.noticeId === notice.noticeId);
-                if (prior) {
-                    if (prior.marker.claimId !== notice.claimId || prior.marker.workspaceId !== resolved.workspaceId || prior.marker.bindingId !== resolved.bindingId || prior.marker.workspaceName !== notice.workspaceName)
-                        throw unknown();
-                    pending = prior;
-                }
-                else
-                    pending = buildRecord(services, agent, notice, resolved);
-                const persisted = await readDurable(services, pending.event.seq, 1);
-                const event = persisted[0];
-                if (event?.type !== 'assistant/message' || !isDeepStrictEqual(event, pending.event))
-                    throw unknown();
-                validateRecord(event, services.session.id);
-                await acknowledge(method, receipt(pending.marker, 'delivered'));
-            }
-            catch (error) {
-                if (pending)
-                    return reportUnknown(method, pending.marker, error);
-                throw unknown(error);
-            }
-            request.signal?.throwIfAborted();
-        })();
-        flights.set(key, operation);
-        try {
-            await operation;
+        const { turn, step } = activeRequest(services.session, agent);
+        const marker = { kind: 'workspace-notice', version: 2, provider: agent.id, loginProvider: agent.loginProvider, sessionId: services.session.id,
+            noticeId: notice.noticeId, claimId: notice.claimId, workspaceName: notice.workspaceName, bindingId: resolved.bindingId, workspaceId: resolved.workspaceId, turn, step, blockIndex: 0, text: noticeText(notice.workspaceName) + '\n\n' };
+        const prior = pending.get(services.session.id);
+        if (prior) {
+            if (!isDeepStrictEqual(prior.marker, marker))
+                throw unknown();
+            return prior.marker;
         }
-        finally {
-            if (flights.get(key) === operation)
-                flights.delete(key);
+        const recorded = services.session.snapshotEvents().filter((e) => e.type === 'assistant/message').find(e => workspaceNoticeFromMessage(e.data.message)?.noticeId === notice.noticeId);
+        if (recorded) {
+            await reconcile(request, api);
+            return undefined;
         }
+        pending.set(services.session.id, { marker, api });
+        return marker;
     };
     return { reconcile, deliver };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-workbench/remote-agent",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,7 +36,7 @@
     "zod": "4.6.7"
   },
   "devDependencies": {
-    "@ai-workbench/connect": "file:test/fixtures/ai-workbench-connect-0.7.0.tgz",
+    "@ai-workbench/connect": "file:test/fixtures/ai-workbench-connect-0.7.11.tgz",
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/cordis-plugin-group": "1.0.4",
     "@deepseek-ai/cordis-plugin-include": "1.0.9",
@@ -56,7 +56,7 @@
     "@deepseek-ai/dsh-attachment": "0.2.0-rc.2"
   },
   "peerDependencies": {
-    "@ai-workbench/connect": "~0.7.0",
+    "@ai-workbench/connect": "~0.7.11",
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
     "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2",