@ai-workbench/remote-agent 0.8.13 → 0.8.15

package/dist/employee-mcp.js

@@ -1,3 +1,4 @@
+import { closeCode } from "./close-diagnostics.js";
 import { createServer } from 'node:net';
 import { mkdtemp, lstat, rm, access } from 'node:fs/promises';
 import { constants } from 'node:fs';
@@ -20,6 +21,7 @@ export const EMPLOYEE_MCP_TOOLS = [
 export class EmployeeSocketTransport {
     socket;
     maxBytes;
+    observeClose;
     onclose;
     onerror;
     onmessage;
@@ -29,9 +31,10 @@ export class EmployeeSocketTransport {
     get error() { return this.failure; }
     lifetime = new AbortController();
     signal = this.lifetime.signal;
-    constructor(socket, maxBytes) {
+    constructor(socket, maxBytes, observeClose) {
         this.socket = socket;
         this.maxBytes = maxBytes;
+        this.observeClose = observeClose;
     }
     failed(error) { try {
         this.onerror?.(error);
@@ -40,11 +43,11 @@ export class EmployeeSocketTransport {
         this.failure = observation instanceof Error ? observation : new Error('EMPLOYEE_MCP_OBSERVATION_FAILED');
     }
     finally {
-        void this.close();
+        void this.close({ layer: 'relay', initiator: 'mcp.socket-failure', reason: closeCode(error, 'EMPLOYEE_MCP_PROTOCOL_OR_SOCKET_ERROR'), action: 'failure' });
     } }
     async start() {
         this.socket.on('error', error => this.failed(error));
-        this.socket.on('close', () => void this.close());
+        this.socket.on('close', () => void this.close({ layer: 'relay', initiator: 'mcp.socket-peer-close', reason: 'MCP_SOCKET_CLOSED', action: 'close' }));
         this.socket.on('data', (bytes) => {
             try {
                 let cursor = 0;
@@ -71,12 +74,12 @@ export class EmployeeSocketTransport {
             throw new Error('EMPLOYEE_MCP_CLOSED');
         const wire = Buffer.from(JSON.stringify(message) + '\n');
         if (wire.length - 1 > this.maxBytes) {
-            await this.close();
+            await this.close({ layer: 'relay', initiator: 'mcp.send-capacity', reason: 'EMPLOYEE_MCP_MESSAGE_TOO_LARGE', action: 'close' });
             throw new Error('EMPLOYEE_MCP_MESSAGE_TOO_LARGE');
         }
         await new Promise((yes, no) => this.socket.write(wire, error => error ? no(error) : yes()));
     }
-    async close() { if (this.ended)
+    async close(cause = { layer: 'relay', initiator: 'mcp.transport-close', reason: 'MCP_TRANSPORT_CLOSED', action: 'close' }) { this.observeClose?.({ ...cause, changes: cause.changes ?? [{ field: 'mcp.ended', before: this.ended, after: true }] }); if (this.ended)
         return; this.ended = true; this.lifetime.abort(); this.socket.destroy(); this.onclose?.(); }
 }
 export async function openEmployeeMcp(options) {
@@ -85,7 +88,7 @@ export async function openEmployeeMcp(options) {
     if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 1)
         throw new NeedError('SETTINGS_REQUIRED', '本机工具消息容量无效。', 'acpMaxMessageBytes');
     await access('/usr/bin/nc', constants.X_OK);
-    const tools = createEmployeeTools({ cwd: options.lease.target.local.directory.path, shell: options.lease.target.endpoint.endpointShell, uid: options.lease.target.endpoint.remoteUid, maxBytes: options.maxBytes, killGraceMs: options.killGraceMs, detail: observe, runShell: options.runShell, validate: signal => options.lease.validate(signal).then(() => { }) });
+    const tools = createEmployeeTools({ closeDiagnostics: options.closeDiagnostics, cwd: options.lease.target.local.directory.path, shell: options.lease.target.endpoint.endpointShell, uid: options.lease.target.endpoint.remoteUid, maxBytes: options.maxBytes, killGraceMs: options.killGraceMs, detail: observe, runShell: options.runShell, validate: signal => options.lease.validate(signal).then(() => { }) });
     const root = await mkdtemp('/private/tmp/aw-x87-'), socketPath = root + '/mcp';
     try {
         const info = await lstat(root);
@@ -93,19 +96,40 @@ export async function openEmployeeMcp(options) {
             throw new NeedError('EMPLOYEE_MCP_STORAGE_INVALID', '本机工具私有通道不可用。', '当前员工的700私有Unix目录');
     }
     catch (error) {
-        await tools.close();
-        await rm(root, { recursive: true });
+        options.closeDiagnostics?.record({ layer: 'relay', initiator: 'mcp.storage-failure', reason: closeCode(error), action: 'failure' });
+        const failures = [error];
+        try {
+            await tools.close({ layer: 'executor', initiator: 'mcp.storage-cleanup', reason: 'MCP_STORAGE_FAILED', action: 'close' });
+        }
+        catch (cleanup) {
+            failures.push(cleanup);
+        }
+        try {
+            await rm(root, { recursive: true });
+        }
+        catch (cleanup) {
+            failures.push(cleanup);
+        }
+        try {
+            options.closeDiagnostics?.assertRecorded();
+        }
+        catch (reporting) {
+            failures.push(reporting);
+        }
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'EMPLOYEE_MCP_STORAGE_AND_CLEANUP_FAILED');
         throw error;
     }
     const clients = new Set(), transports = new Set();
     let closing, diagnosticFailure;
     const failureLifetime = new AbortController();
     const poison = (error) => {
+        options.closeDiagnostics?.record({ layer: 'relay', initiator: 'mcp.poison', reason: closeCode(error, 'CONVERSATION_DETAILS_FAILED'), action: 'invalidate' });
         diagnosticFailure ??= error;
         failureLifetime.abort(error);
         // Close is memoized synchronously: no fresh connection/call can pass the fence.
-        void options.lease.close().catch(failure => { diagnosticFailure ??= failure; });
-        void close().catch(failure => { diagnosticFailure ??= failure; });
+        void options.lease.close({ layer: 'endpoint', initiator: 'mcp.poison-lease', reason: 'CONVERSATION_DETAILS_FAILED', action: 'close' }).catch(failure => { diagnosticFailure ??= failure; });
+        void close({ layer: 'relay', initiator: 'mcp.poison-close', reason: 'CONVERSATION_DETAILS_FAILED', action: 'close' }).catch(failure => { diagnosticFailure ??= failure; });
     };
     function observeUsing(event, sink) { if (diagnosticFailure)
         throw diagnosticFailure; try {
@@ -118,10 +142,12 @@ export async function openEmployeeMcp(options) {
     function observe(event) { observeUsing(event, options.detail); }
     const server = createServer(socket => {
         if (closing || failureLifetime.signal.aborted || options.lease.signal.aborted) {
+            options.closeDiagnostics?.record({ layer: 'relay', initiator: 'mcp.reject-late-socket', reason: 'MCP_CLOSING', action: 'close' });
             socket.destroy();
             return;
         }
-        const mcp = new Server({ name: 'ai-workbench-employee', version: '0.8.13' }, { capabilities: { tools: {} } }), transport = new EmployeeSocketTransport(socket, options.maxBytes);
+        const observeConnection = options.closeDiagnostics?.child().capture();
+        const mcp = new Server({ name: 'ai-workbench-employee', version: '0.8.14' }, { capabilities: { tools: {} } }), transport = new EmployeeSocketTransport(socket, options.maxBytes, observeConnection);
         clients.add(mcp);
         transports.add(transport);
         mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: EMPLOYEE_MCP_TOOLS }));
@@ -133,40 +159,50 @@ export async function openEmployeeMcp(options) {
             const sink = options.captureDetail?.() ?? options.detail;
             return tools.call(request.params.name, request.params.arguments ?? {}, signal, event => observeUsing(event, sink));
         });
-        mcp.onerror = () => { try {
+        mcp.onerror = () => { observeConnection?.({ layer: 'relay', initiator: 'mcp.server-error', reason: 'EMPLOYEE_MCP_PROTOCOL_OR_TRANSPORT_ERROR', action: 'failure' }); try {
             observe({ kind: 'session', severity: 'warning', code: 'CLAUDE_EMPLOYEE_MCP_UNKNOWN', summary: '本机工具连接出现协议或传输错误；在途结果未知，没有重放' });
         }
         catch (error) {
             poison(error);
         } };
-        mcp.onclose = () => { clients.delete(mcp); transports.delete(transport); };
-        void mcp.connect(transport).catch(() => { socket.destroy(); });
+        mcp.onclose = () => { observeConnection?.({ layer: 'relay', initiator: 'mcp.client-closed', reason: 'MCP_CLIENT_CLOSED', action: 'close' }); clients.delete(mcp); transports.delete(transport); };
+        void mcp.connect(transport).catch(error => { observeConnection?.({ layer: 'relay', initiator: 'mcp.connect-failure', reason: closeCode(error, 'MCP_CONNECT_FAILED'), action: 'close' }); socket.destroy(); });
     });
-    const close = () => closing ??= Promise.resolve().then(async () => {
-        options.lease.signal.removeEventListener('abort', aborted);
-        const errors = [], clean = async (operation) => { try {
-            await operation();
-        }
-        catch (error) {
-            if (!errors.includes(error))
+    const close = (cause = { layer: 'relay', initiator: 'mcp.close', reason: 'MCP_CLOSE_REQUESTED', action: 'close' }) => {
+        options.closeDiagnostics?.record({ ...cause, changes: cause.changes ?? [{ field: 'mcp.closing', before: !!closing, after: true }] });
+        return closing ??= Promise.resolve().then(async () => {
+            options.lease.signal.removeEventListener('abort', aborted);
+            const errors = [], clean = async (operation) => { try {
+                await operation();
+            }
+            catch (error) {
+                if (!errors.includes(error))
+                    errors.push(error);
+            } };
+            for (const transport of transports)
+                await clean(() => transport.close({ layer: 'relay', initiator: 'mcp.cleanup-transport', reason: 'MCP_CLEANUP', action: 'close' }));
+            await Promise.all([...clients].map(client => clean(() => client.close())));
+            await clean(() => tools.close({ layer: 'executor', initiator: 'mcp.cleanup-tools', reason: 'MCP_CLEANUP', action: 'close' }));
+            await clean(() => options.lease.close({ layer: 'endpoint', initiator: 'mcp.cleanup-lease', reason: 'MCP_CLEANUP', action: 'close' }));
+            options.closeDiagnostics?.record({ layer: 'relay', initiator: 'mcp.server-close', reason: 'MCP_CLEANUP', action: 'close' });
+            if (server.listening)
+                await clean(() => new Promise((yes, no) => server.close(error => error ? no(error) : yes())));
+            await clean(() => rm(root, { recursive: true }));
+            if (diagnosticFailure && !errors.includes(diagnosticFailure))
+                errors.unshift(diagnosticFailure);
+            try {
+                options.closeDiagnostics?.assertRecorded();
+            }
+            catch (error) {
                 errors.push(error);
-        } };
-        for (const transport of transports)
-            await clean(() => transport.close());
-        await Promise.all([...clients].map(client => clean(() => client.close())));
-        await clean(() => tools.close());
-        await clean(() => options.lease.close());
-        if (server.listening)
-            await clean(() => new Promise((yes, no) => server.close(error => error ? no(error) : yes())));
-        await clean(() => rm(root, { recursive: true }));
-        if (diagnosticFailure && !errors.includes(diagnosticFailure))
-            errors.unshift(diagnosticFailure);
-        if (errors.length === 1)
-            throw errors[0];
-        if (errors.length)
-            throw new AggregateError(errors, 'EMPLOYEE_MCP_CLEANUP_FAILED');
-    });
-    const aborted = () => { void close().catch(error => { diagnosticFailure ??= error; failureLifetime.abort(error); }); };
+            }
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length)
+                throw new AggregateError(errors, 'EMPLOYEE_MCP_CLEANUP_FAILED');
+        });
+    };
+    const aborted = () => { void close({ layer: 'endpoint', initiator: 'mcp.lease-abort', reason: closeCode(options.lease.signal.reason, 'EMPLOYEE_CONTEXT_CHANGED'), action: 'abort' }).catch(error => { diagnosticFailure ??= error; failureLifetime.abort(error); }); };
     try {
         await new Promise((yes, no) => { server.once('error', no); server.listen(socketPath, () => { server.removeListener('error', no); yes(); }); });
         options.lease.signal.addEventListener('abort', aborted, { once: true });
@@ -175,7 +211,7 @@ export async function openEmployeeMcp(options) {
         return { routing: employeeRouting(options.lease.target, socketPath, options.maxBytes), signal: failureLifetime.signal, close };
     }
     catch (error) {
-        await close();
+        await close({ layer: 'relay', initiator: 'mcp.open-failure', reason: closeCode(error, 'MCP_OPEN_FAILED'), action: 'failure' });
         throw error;
     }
 }

package/dist/employee-presentation.d.ts

@@ -0,0 +1,6 @@
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
+export declare const CLAUDE_EMPLOYEE_SCOPE_NOTICE = "\u672C\u8F6E\u516D\u7C7B\u6587\u4EF6\u4E0E\u547D\u4EE4\u5DE5\u5177\u5728\u4F60\u7684\u7535\u8111\u6267\u884C\uFF0C\u4F7F\u7528\u4F60\u9009\u62E9\u7684\u6587\u4EF6\u5939\uFF1BGit\u4E5F\u4F7F\u7528\u672C\u673A\u4ED3\u5E93\u3002\u5B50\u4EE3\u7406\u548C\u5185\u90E8\u76F4\u63A5\u8C03\u7528\u5C1A\u4E0D\u652F\u6301\u672C\u673A\uFF0C\u53EF\u80FD\u4ECD\u5728\u4E3B\u673A\uFF1B\u5DF2\u8BC6\u522B\u7684\u6B64\u7C7B\u5BA1\u6279\u4E0D\u4F1A\u6267\u884C\u3002PDF\u7B49\u4E8C\u8FDB\u5236\u8BFB\u53D6\u3001\u540E\u53F0\u547D\u4EE4\u6682\u4E0D\u652F\u6301\u3002";
+export declare const CODEX_EMPLOYEE_SCOPE_NOTICE = "\u6587\u4EF6\u4E0E\u547D\u4EE4\u5728\u672C\u673A\u9009\u5B9A\u76EE\u5F55\u8FD0\u884C\uFF0CGit \u4F7F\u7528\u672C\u673A\u4ED3\u5E93\uFF1B\u6A21\u578B\u3001\u767B\u5F55\u548C\u5168\u5C40\u52A9\u624B\u8981\u6C42\u4ECD\u5728\u8FDC\u7A0B\u4E3B\u673A\u3002\u672C\u673A\u81EA\u5B9A\u4E49\u7684\u9644\u52A0\u5DE5\u5177\u3001\u81EA\u52A8\u52A8\u4F5C\u3001\u63D2\u4EF6\u53CA\u65AD\u5F00\u540E\u7684\u4F1A\u8BDD\u6062\u590D\u6682\u4E0D\u652F\u6301\u3002\u5B50\u4EFB\u52A1\u88AB\u7CFB\u7EDF\u56DE\u6536\u540E\u80FD\u5426\u7EE7\u7EED\uFF0C\u5C1A\u672A\u9A8C\u8BC1\u3002";
+export declare const EMPLOYEE_EXECUTION_NOTICE = "\u6587\u4EF6\u548C\u547D\u4EE4\u5728\u4F60\u7684\u7535\u8111\u4E0A\u6267\u884C";
+/** Presentation receipt only; it grants no process, workspace or replay authority. */
+export declare function employeeNoticePreviouslyShown(options: Pick<GenerateOptions, 'messages' | 'sessionId'>): boolean;

package/dist/employee-presentation.js

@@ -0,0 +1,16 @@
+import { AGENTS } from "./agents.js";
+export const CLAUDE_EMPLOYEE_SCOPE_NOTICE = '本轮六类文件与命令工具在你的电脑执行，使用你选择的文件夹；Git也使用本机仓库。子代理和内部直接调用尚不支持本机，可能仍在主机；已识别的此类审批不会执行。PDF等二进制读取、后台命令暂不支持。';
+export const CODEX_EMPLOYEE_SCOPE_NOTICE = '文件与命令在本机选定目录运行，Git 使用本机仓库；模型、登录和全局助手要求仍在远程主机。本机自定义的附加工具、自动动作、插件及断开后的会话恢复暂不支持。子任务被系统回收后能否继续，尚未验证。';
+export const EMPLOYEE_EXECUTION_NOTICE = '文件和命令在你的电脑上执行';
+/** Presentation receipt only; it grants no process, workspace or replay authority. */
+export function employeeNoticePreviouslyShown(options) {
+    if (!options.sessionId)
+        return false;
+    return options.messages.some(message => {
+        if (message.role !== 'assistant' || !AGENTS.some(agent => agent.id === message.source.provider))
+            return false;
+        const pointer = message.source.replayState?.response;
+        const sameSession = !!pointer && pointer.version === 2 && pointer.agent === message.source.provider && pointer.dshSessionId === options.sessionId && [pointer.identity, pointer.cwd, pointer.sessionId].every(value => typeof value === 'string' && value.length > 0);
+        return sameSession && (pointer.presentation?.employeeExecutionNotice === 'local-v1' || message.content.some(block => block.type === 'text' && [CLAUDE_EMPLOYEE_SCOPE_NOTICE, CODEX_EMPLOYEE_SCOPE_NOTICE].some(notice => block.text.startsWith(notice + '\n\n'))));
+    });
+}

package/dist/employee-provider.js

@@ -6,6 +6,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { CODEX_EMPLOYEE_SCOPE_NOTICE } from "./employee-presentation.js";
+import { CloseDiagnostics, closeCode, closeErrorCodes } from "./close-diagnostics.js";
 import { createHash } from 'node:crypto';
 import { admitEmployeeLocation } from "./employee-location.js";
 import { EmployeeExecution } from "./employee-exec.js";
@@ -104,7 +106,7 @@ export function createEmployeeProvider(get, options, agent) {
             prior = live.get(sessionId);
         }
         if (prior && (prior.current.api !== api || info?.workspaceLocations !== 1 || info?.localWorkspaceContext !== 1)) {
-            await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'));
+            await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'), { layer: 'endpoint', initiator: 'provider.scope-change', reason: 'EMPLOYEE_CONTEXT_CHANGED', action: 'dispose' });
             throw fail('EMPLOYEE_CONTEXT_CHANGED');
         }
         if (info?.workspaceLocations !== 1 && info?.localWorkspaceContext !== 1)
@@ -121,12 +123,12 @@ export function createEmployeeProvider(get, options, agent) {
             throw fail('EMPLOYEE_CONTEXT_CHANGED');
         if (row.source !== 'local') {
             if (prior)
-                await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'));
+                await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'), { layer: 'endpoint', initiator: 'provider.scope-change', reason: 'EMPLOYEE_CONTEXT_CHANGED', action: 'dispose' });
             if (request.localAcceptance)
                 throw fail('EMPLOYEE_CONTEXT_CHANGED');
             return;
         }
-        let details;
+        let details, closeDiagnostics;
         try {
             const acceptance = request.localAcceptance;
             if (!acceptance || acceptance.instanceId !== connection.instanceId || acceptance.epoch !== connection.epoch || acceptance.sessionId !== sessionId || acceptance.provider !== agent.loginProvider || acceptance.workspaceId !== workspace.id || acceptance.bindingId !== row.bindingId)
@@ -134,6 +136,10 @@ export function createEmployeeProvider(get, options, agent) {
             details = await options.details?.(request, api, connection, target);
             if (details)
                 request.timing?.bind(detail => details.record(detail));
+            const sink = details;
+            closeDiagnostics = prior?.runtime.closeDiagnostics ?? new CloseDiagnostics(event => sink?.record(event));
+            closeDiagnostics.bind(event => sink?.record(event));
+            request.closeDiagnostics = closeDiagnostics;
             const unsupported = request.mode !== 'session' || agent.loginProvider !== 'codex' || !!request.recoveryCheckpointId || !!request.resumeSessionId && !prior;
             if (unsupported)
                 throw fail('EMPLOYEE_OPERATION_UNSUPPORTED');
@@ -145,7 +151,7 @@ export function createEmployeeProvider(get, options, agent) {
             if (!network || typeof network.prepareEmployeeEndpoint !== 'function' || typeof network.onState !== 'function')
                 throw fail('DEPENDENCY_REQUIRED');
             if (prior && prior.network !== network) {
-                await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'));
+                await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'), { layer: 'endpoint', initiator: 'provider.scope-change', reason: 'EMPLOYEE_CONTEXT_CHANGED', action: 'dispose' });
                 throw fail('EMPLOYEE_CONTEXT_CHANGED');
             }
             const admitted = await admitEmployeeLocation({ api: api, network, workspace, connection, expectedLocal: { instanceId: acceptance.instanceId, epoch: acceptance.epoch, workspaceId: acceptance.workspaceId, bindingId: acceptance.bindingId, directory: { ...acceptance.directory } }, settingsPath: target.session.settingsPath, signal: request.signal });
@@ -167,7 +173,7 @@ export function createEmployeeProvider(get, options, agent) {
                 native: { path: native.path, sha256: native.sha256 },
             });
             if (prior && (prior.scope !== scope || prior.ended))
-                await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'));
+                await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'), { layer: 'endpoint', initiator: 'provider.scope-change', reason: 'EMPLOYEE_CONTEXT_CHANGED', action: 'dispose' });
             let entry = prior && prior.scope === scope && !prior.ended ? prior : undefined;
             let candidate = entry;
             const base = async (signal) => {
@@ -177,7 +183,7 @@ export function createEmployeeProvider(get, options, agent) {
                 if (candidate?.ended)
                     throw candidate.reason ?? fail('EMPLOYEE_EXEC_CLOSED');
                 await (candidate?.current ?? input).stable(signal);
-                await admitted.validate(signal);
+                await closeDiagnostics.run('endpoint.prepare', () => admitted.validate(signal));
                 if (get() !== api || employee.getNetwork() !== network)
                     throw fail('EMPLOYEE_CONTEXT_CHANGED');
                 await (candidate?.current ?? input).stable(signal);
@@ -193,25 +199,26 @@ export function createEmployeeProvider(get, options, agent) {
             }
             const io = employee.io ?? sshIo(target, argv, request.acpMaxMessageBytes);
             const scopedIo = { run: (command, signal) => io.run(command, signal), attach: async (command) => {
+                    const observe = closeDiagnostics.capture();
                     const child = await io.attach(command);
-                    child.once('close', () => { if (candidate && !candidate.ended)
-                        void candidate.dispose(fail('EMPLOYEE_EXEC_UNKNOWN')).catch(() => { }); });
+                    child.once('close', (code, signal) => { observe({ layer: 'relay', initiator: 'ssh.process.close', reason: 'EMPLOYEE_EXEC_UNKNOWN', action: 'exit', exitCode: code, signal }); if (candidate && !candidate.ended)
+                        void candidate.dispose(fail('EMPLOYEE_EXEC_UNKNOWN'), { layer: 'runtime', initiator: 'provider.child-close', reason: 'EMPLOYEE_EXEC_UNKNOWN', action: 'dispose' }).catch(() => { }); });
                     return child;
                 } };
-            const ssh = { target, endpoint: admitted.endpoint, employeeBinary: native.path, binarySha256: native.sha256, acpMaxMessageBytes: request.acpMaxMessageBytes, argv: argv ?? (() => []), validate: base, io: scopedIo };
+            const ssh = { closeDiagnostics, target, endpoint: admitted.endpoint, employeeBinary: native.path, binarySha256: native.sha256, acpMaxMessageBytes: request.acpMaxMessageBytes, argv: argv ?? (() => []), validate: base, io: scopedIo };
             const validate = async (signal) => { try {
                 await validateEmployeeSshTarget(ssh, signal);
             }
             catch (error) {
                 if (candidate && errorCode(error) !== 'ABORTED')
-                    await candidate.dispose(asNeed(error));
+                    await candidate.dispose(asNeed(error), { layer: 'endpoint', initiator: 'provider.validation-failure', reason: closeCode(error), action: 'invalidate' });
                 throw error;
             } };
             await validate(request.signal ?? new AbortController().signal);
             if (!options.open)
                 throw fail('RUNTIME_REQUIRED');
             // Host cwd is only the protected agent bootstrap/config directory. Native tools use admitted.cwd.
-            const host = await options.open(target, { name: 'employee', path: target.projectRoot }, { ...request, agent, employeeScope: scope, bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, bindingRevision: state.revision, detailChannel: details, validateContext: async (ignore = false) => {
+            const host = await options.open(target, { name: 'employee', path: target.projectRoot }, { ...request, agent, employeeScope: scope, bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, bindingRevision: state.revision, closeDiagnostics, detailChannel: details, validateContext: async (ignore = false) => {
                     // Disposal addresses only the already-owned host broker instance through its frozen IO/CAS.
                     // A withdrawn local source must prevent dispatch, but cannot forbid that instance's exact kill.
                     if (ignore)
@@ -226,49 +233,65 @@ export function createEmployeeProvider(get, options, agent) {
                     await validate(request.signal ?? new AbortController().signal);
                 }
                 catch (error) {
-                    await entry.dispose(asNeed(error));
+                    await entry.dispose(asNeed(error), { layer: 'endpoint', initiator: 'provider.final-validation', reason: closeCode(error), action: 'dispose' });
                     throw error;
                 }
                 entry.runtime.details = details;
                 entry.runtime.connection = { ...connection };
                 entry.runtime.binding = { bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, revision: state.revision };
+                entry.runtime.restartNotice = host.restartNotice;
+                entry.runtime.restartInputIds = host.restartInputIds;
+                entry.runtime.freshSessionConfirmed = host.freshSessionConfirmed;
                 return entry.runtime;
             }
             const disposers = [];
-            const execution = new EmployeeExecution({ bindingId: admitted.bindingId, acpMaxMessageBytes: request.acpMaxMessageBytes, validate, transport: signal => createEmployeeSshTransport(ssh, signal) });
-            const runtime = { ...host, cwd: admitted.cwd, details, connection: { ...connection }, binding: { bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, revision: state.revision }, saveCheckpoint: undefined, recoveredSession: undefined, restartNotice: undefined, restartInputIds: undefined, employeeExecutionMeta: { version: 1, bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, cwd: admitted.cwd, acpMaxMessageBytes: request.acpMaxMessageBytes }, employeePresentation: '文件与命令在本机选定目录运行，Git 使用本机仓库；模型、登录和全局助手要求仍在远程主机。本机自定义的附加工具、自动动作、插件及断开后的会话恢复暂不支持。子任务被系统回收后能否继续，尚未验证。' };
-            entry = { scope, runtime, current: input, details, execution, network, ended: false, dispose: reason => {
+            const execution = new EmployeeExecution({ closeDiagnostics, bindingId: admitted.bindingId, acpMaxMessageBytes: request.acpMaxMessageBytes, validate, transport: signal => createEmployeeSshTransport(ssh, signal) });
+            const runtime = { ...host, closeDiagnostics, cwd: admitted.cwd, details, connection: { ...connection }, binding: { bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, revision: state.revision }, saveCheckpoint: undefined, recoveredSession: undefined, employeeExecutionMeta: { version: 1, bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, cwd: admitted.cwd, acpMaxMessageBytes: request.acpMaxMessageBytes }, employeePresentation: CODEX_EMPLOYEE_SCOPE_NOTICE };
+            entry = { scope, runtime, current: input, details, execution, network, ended: false, dispose: (reason, cause = { layer: 'runtime', initiator: 'provider.dispose', reason: reason?.code ?? 'EMPLOYEE_EXEC_CLOSED', action: 'dispose' }) => {
+                    closeDiagnostics.record({ ...cause, changes: cause.changes ?? [{ field: 'provider.ended', before: entry.ended, after: true }] });
                     if (entry.closing)
                         return entry.closing;
                     entry.ended = true;
                     entry.reason = reason;
-                    execution.invalidate(reason ?? fail('EMPLOYEE_EXEC_CLOSED'));
+                    execution.invalidate(reason ?? fail('EMPLOYEE_EXEC_CLOSED'), { layer: 'executor', initiator: 'provider.invalidate-executor', reason: reason?.code ?? 'EMPLOYEE_EXEC_CLOSED', action: 'invalidate' });
                     for (const off of disposers)
                         off();
                     host.broker?.fail(reason ?? fail('EMPLOYEE_EXEC_CLOSED'));
                     entry.closing = (async () => {
-                        let cleanup;
+                        const cleanup = [], reporting = [];
                         try {
-                            await execution.dispose();
+                            await execution.dispose({ layer: 'executor', initiator: 'provider.cleanup-executor', reason: 'RUNTIME_CLEANUP', action: 'dispose' });
                         }
                         catch (error) {
-                            cleanup = error;
+                            cleanup.push(...closeErrorCodes(error, 'EXECUTOR_CLEANUP_FAILED'));
                         }
                         try {
-                            await host.dispose?.();
+                            await host.dispose?.({ layer: 'broker', initiator: 'provider.cleanup-host', reason: 'RUNTIME_CLEANUP', action: 'dispose' });
                         }
                         catch (error) {
-                            cleanup = error;
+                            cleanup.push(...closeErrorCodes(error, 'HOST_CLEANUP_FAILED'));
+                        }
+                        const firstReason = String(closeDiagnostics.first?.reason ?? reason?.code ?? 'EMPLOYEE_EXEC_CLOSED');
+                        try {
+                            entry.details?.record({ kind: 'need', severity: 'warning', code: cleanup.length ? 'REMOTE_CLEANUP_UNCONFIRMED' : 'EMPLOYEE_EXEC_UNKNOWN', summary: '员工执行通道已关闭，命令结果 UNKNOWN', payload: { bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, result: 'UNKNOWN', reason: reason?.code ?? 'EMPLOYEE_EXEC_CLOSED', firstReason, cleanup: cleanup.length ? 'unconfirmed' : 'closed', cleanupCodes: cleanup } });
+                        }
+                        catch (error) {
+                            reporting.push(closeCode(error, 'CLOSE_RECORD_FAILED'));
                         }
                         try {
-                            entry.details?.record({ kind: 'need', severity: 'warning', code: cleanup ? 'REMOTE_CLEANUP_UNCONFIRMED' : 'EMPLOYEE_EXEC_UNKNOWN', summary: '员工执行通道已关闭，命令结果 UNKNOWN', payload: { bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, result: 'UNKNOWN', reason: reason?.code ?? 'EMPLOYEE_EXEC_CLOSED', cleanup: cleanup ? 'unconfirmed' : 'closed' } });
                             await entry.details?.flush();
                         }
-                        catch {
-                            throw fail('CONVERSATION_DETAILS_FAILED');
+                        catch (error) {
+                            reporting.push(...closeErrorCodes(error, 'CLOSE_FLUSH_FAILED'));
+                        }
+                        try {
+                            closeDiagnostics.assertRecorded();
+                        }
+                        catch (error) {
+                            reporting.push(closeDiagnostics.recordingFailureCode ?? closeCode(error, 'CLOSE_RECORD_FAILED'));
                         }
-                        if (cleanup)
-                            throw fail('REMOTE_CLEANUP_UNCONFIRMED');
+                        if (cleanup.length || reporting.length)
+                            throw Object.assign(new NeedError(reporting.length ? 'CONVERSATION_DETAILS_FAILED' : 'REMOTE_CLEANUP_UNCONFIRMED', '执行连接已关闭；首次原因 ' + firstReason + '，清理或诊断保存未确认。', '首次关闭 ' + firstReason + '；清理 ' + (cleanup.join(',') || 'closed') + '；保存 ' + (reporting.join(',') || 'recorded')), { cause: new AggregateError([firstReason, ...cleanup, ...reporting].map(code => new NeedError(code, '关闭收尾代码 ' + code, '技术详情中的固定代码')), 'EMPLOYEE_CLOSE_AND_DIAGNOSTIC_FAILURES') });
                         if (live.get(sessionId) === entry)
                             live.delete(sessionId);
                     })();
@@ -279,35 +302,35 @@ export function createEmployeeProvider(get, options, agent) {
                 try {
                     const result = await execution.handle(params, signal);
                     if (result.closed)
-                        await entry.dispose();
+                        await entry.dispose(undefined, { layer: 'runtime', initiator: 'provider.rpc-closed-result', reason: 'EMPLOYEE_EXEC_CLOSED', operation: typeof params === 'object' && params && 'operation' in params && typeof params.operation === 'string' ? params.operation : 'unknown', action: 'dispose' });
                     return { ...result };
                 }
                 catch (error) {
                     // EmployeeExecution reserves ABORTED for an unconsumed read wait. Lost responses are UNKNOWN.
                     if (!(params && typeof params === 'object' && 'operation' in params && params.operation === 'read' && errorCode(error) === 'ABORTED'))
-                        await entry.dispose(asNeed(error));
+                        await entry.dispose(asNeed(error), { layer: 'runtime', initiator: 'provider.rpc-failure', reason: closeCode(error), action: 'dispose' });
                     throw error;
                 }
             };
-            runtime.dispose = () => entry.dispose();
-            runtime.detach = runtime.dispose;
-            const revoke = (reason) => { void entry.dispose(reason).catch(() => { }); };
+            runtime.dispose = cause => entry.dispose(undefined, cause ?? { layer: 'runtime', initiator: 'runtime.dispose', reason: 'RUNTIME_DISPOSE', action: 'dispose' });
+            runtime.detach = cause => entry.dispose(undefined, cause ?? { layer: 'runtime', initiator: 'runtime.detach', reason: 'RUNTIME_DETACH', action: 'detach' });
+            const revoke = (reason, initiator, changes) => { void entry.dispose(reason, { layer: 'endpoint', initiator, reason: reason.code, action: 'invalidate', changes }).catch(() => { }); };
             disposers.push(api.onWorkspaceLocationState(next => {
                 const matches = next.items.filter(item => item.workspaceId === admitted.workspaceId);
                 if (get() !== api || next.phase !== 'ready' || next.instanceId !== connection.instanceId || next.epoch !== connection.epoch || matches.length !== 1 || matches[0].bindingId !== admitted.bindingId || matches[0].source !== 'local' || matches[0].status !== 'selected')
-                    revoke(fail('EMPLOYEE_CONTEXT_CHANGED'));
+                    revoke(fail('EMPLOYEE_CONTEXT_CHANGED'), 'endpoint.workspace-change', [{ field: 'workspace.binding-id', before: admitted.bindingId, after: matches[0]?.bindingId ?? null }, { field: 'workspace.source', before: 'local', after: matches[0]?.source ?? null }, { field: 'workspace.status', before: 'selected', after: matches[0]?.status ?? null }, { field: 'workspace.match-count', before: 1, after: matches.length }]);
             }), api.onConnectionState(next => { if (get() !== api || next.phase !== 'connected' || next.instanceId !== connection.instanceId || next.epoch !== connection.epoch)
-                revoke(fail('CONNECTION_LOST')); }), network.onState(event => { if (event.kind === 'lost' || employee.getNetwork() !== network)
-                revoke(fail('CONNECTION_LOST')); }));
+                revoke(fail('CONNECTION_LOST'), 'endpoint.connection-change', [{ field: 'connection.instance-id', before: connection.instanceId, after: next.instanceId }, { field: 'connection.epoch', before: connection.epoch, after: next.epoch }, { field: 'connection.phase', before: 'connected', after: next.phase }]); }), network.onState(event => { if (event.kind === 'lost' || employee.getNetwork() !== network)
+                revoke(fail('CONNECTION_LOST'), 'endpoint.network-loss', [{ field: 'network.phase', before: null, after: event.state.phase }]); }));
             if (host.broker)
                 disposers.push(host.broker.onChange(() => { if (!host.broker.online)
-                    revoke(fail('EMPLOYEE_EXEC_UNKNOWN')); }));
+                    revoke(fail('EMPLOYEE_EXEC_UNKNOWN'), 'endpoint.broker-offline'); }));
             live.set(sessionId, entry);
             try {
                 await validate(request.signal ?? new AbortController().signal);
             }
             catch (error) {
-                await entry.dispose(asNeed(error));
+                await entry.dispose(asNeed(error), { layer: 'endpoint', initiator: 'provider.final-validation', reason: closeCode(error), action: 'dispose' });
                 throw error;
             }
             return runtime;

package/dist/employee-shell.d.ts

@@ -1,3 +1,4 @@
+import { type CloseDiagnostics } from './close-diagnostics.ts';
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 import type { EmployeeEndpointTarget } from './employee-endpoint.ts';
 export interface EmployeeShellResult {
@@ -13,6 +14,7 @@ export type EmployeeShell = (request: {
     signal: AbortSignal;
 }) => Promise<EmployeeShellResult>;
 interface Options {
+    closeDiagnostics?: CloseDiagnostics;
     target: EmployeeEndpointTarget;
     maxBytes: number;
     killGraceMs: number;

package/dist/employee-shell.js

@@ -1,3 +1,4 @@
+import { closeCode } from "./close-diagnostics.js";
 import { randomUUID } from 'node:crypto';
 import { EMPLOYEE_TARGET_PYTHON, EMPLOYEE_PYTHON_ERRORS } from "./employee-relay.js";
 import { NeedError } from "./remote.js";
@@ -15,11 +16,13 @@ const unknown = (code) => new NeedError(code, '本机命令结果未知；没有
 export function createEmployeeShell(options) {
     return async ({ command, timeout, signal }) => {
         signal.throwIfAborted();
+        const diagnostics = options.closeDiagnostics?.child();
         const executionId = randomUUID(), target = options.target;
         const child = await options.attach({ command: '/usr/bin/python3', args: ['-c', SHELL_PYTHON, JSON.stringify({ endpoint: target.endpoint, bridge: target.bridge, directory: target.local.directory, maxBytes: options.maxBytes, executionId })] });
         return new Promise((yes, no) => {
             let settled = false, bytes = 0, stdout = [], stderr = [], reason, grace, timer;
             const finish = (error, code) => {
+                diagnostics?.record({ layer: 'executor', initiator: 'shell.finish', reason: closeCode(error, 'SHELL_FINISHED'), action: 'close', exitCode: code ?? null, changes: [{ field: 'shell.settled', before: settled, after: true }] });
                 if (settled)
                     return;
                 settled = true;
@@ -62,11 +65,20 @@ export function createEmployeeShell(options) {
                     no(unknown('EMPLOYEE_EXIT_UNKNOWN'));
                     return;
                 }
+                try {
+                    diagnostics?.assertRecorded();
+                }
+                catch (failure) {
+                    no(failure);
+                    return;
+                }
                 yes({ stdout: out, stderr: err.slice(header.length, start) + err.slice(start + started.length), stderrSource: 'combined-ssh-and-command', exitCode: code, signal: null });
             };
-            const stop = (code) => { if (settled || reason)
-                return; reason = unknown(code); child.kill('SIGTERM'); grace = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
-                child.kill('SIGKILL'); finish(reason); }, options.killGraceMs); };
+            const stop = (code) => { diagnostics?.record({ layer: 'executor', initiator: 'shell.stop', reason: code, action: 'terminate', changes: [{ field: 'shell.stop-code', before: reason?.code ?? null, after: settled || reason ? reason?.code ?? null : code }] }); if (settled || reason)
+                return; reason = unknown(code); child.kill('SIGTERM'); grace = setTimeout(() => { if (child.exitCode === null && child.signalCode === null) {
+                diagnostics?.record({ layer: 'executor', initiator: 'shell.kill-grace', reason: reason?.code ?? 'SHELL_CLEANUP', action: 'terminate', signal: 'SIGKILL' });
+                child.kill('SIGKILL');
+            } finish(reason); }, options.killGraceMs); };
             const abort = () => stop('EMPLOYEE_CANCELLED_UNKNOWN');
             const collect = (destination, chunk) => { bytes += chunk.length; if (bytes > options.maxBytes) {
                 stop('EMPLOYEE_OUTPUT_TOO_LARGE_UNKNOWN');
@@ -75,8 +87,8 @@ export function createEmployeeShell(options) {
             child.stdout.on('data', (b) => collect(stdout, b));
             child.stderr.on('data', (b) => collect(stderr, b));
             child.stdin.on('error', () => stop('EMPLOYEE_INPUT_UNKNOWN'));
-            child.once('error', () => { finish(unknown('EMPLOYEE_TRANSPORT_UNKNOWN')); });
-            child.once('close', code => finish(reason, code));
+            child.once('error', () => { diagnostics?.record({ layer: 'relay', initiator: 'shell.process-error', reason: 'EMPLOYEE_TRANSPORT_UNKNOWN', action: 'failure' }); finish(unknown('EMPLOYEE_TRANSPORT_UNKNOWN')); });
+            child.once('close', (code, exitSignal) => { diagnostics?.record({ layer: 'relay', initiator: 'shell.process-close', reason: reason?.code ?? 'PROCESS_EXIT', action: 'exit', exitCode: code, signal: exitSignal }); finish(reason, code); });
             signal.addEventListener('abort', abort, { once: true });
             if (signal.aborted)
                 abort();

package/dist/employee-ssh.d.ts

@@ -1,3 +1,4 @@
+import { type CloseDiagnostics } from './close-diagnostics.ts';
 import type { EmployeeEndpointTarget } from '@ai-workbench/network/api';
 import { type BrokerIo, type SshArgv } from './broker.ts';
 import type { ConnectTarget } from './provider.ts';
@@ -5,6 +6,7 @@ import { type EmployeeExecutionTransport } from './employee-exec.ts';
 export interface EmployeeSshOptions {
     target: ConnectTarget;
     endpoint: EmployeeEndpointTarget;
+    closeDiagnostics?: CloseDiagnostics;
     /** Automatically discovered package binary path on this same employee device. */
     employeeBinary: string;
     binarySha256: string;

package/dist/employee-ssh.js

@@ -1,3 +1,4 @@
+import { closeCode } from "./close-diagnostics.js";
 import { sshIo } from "./broker.js";
 import { createEmployeeProcessTransport } from "./employee-exec.js";
 import { NeedError, shellQuote } from "./remote.js";
@@ -92,7 +93,8 @@ async function currentTarget(options, signal) {
     await gate();
     const b = endpoint.bridge, e = endpoint.endpoint;
     const command = [b.command, 'target', '--settings', b.settingsPath, '--device', e.deviceId, '--if-instance', b.bridgeInstanceId, '--if-generation', String(b.generation), '--if-endpoint', e.endpointInstanceId, '--if-context', e.executionContextId].map(shellQuote).join(' ');
-    const raw = await awaitSignal(io.run(command, signal), signal);
+    const run = () => awaitSignal(io.run(command, signal), signal);
+    const raw = await (options.closeDiagnostics ? options.closeDiagnostics.run('endpoint.target', run) : run());
     const args = readTarget(raw, endpoint, options.acpMaxMessageBytes);
     await gate();
     return { io, args, gate };
@@ -107,9 +109,9 @@ export async function createEmployeeSshTransport(options, signal = new AbortCont
     checkSignal(signal);
     // EmployeeExecution races the user's open wait; this factory retains any late child cleanup.
     const child = await io.attach('exec ' + ['/usr/bin/ssh', ...args, remote].map(shellQuote).join(' '));
-    const transport = createEmployeeProcessTransport(child, options.acpMaxMessageBytes, ['AW_EMPLOYEE_BINARY_UNAVAILABLE', 'AW_EMPLOYEE_BINARY_HASH_FAILED', 'AW_EMPLOYEE_BINARY_HASH_MISMATCH', 'AW_EMPLOYEE_BINARY_VERSION_FAILED', 'AW_EMPLOYEE_BINARY_VERSION_MISMATCH']);
+    const transport = createEmployeeProcessTransport(child, options.acpMaxMessageBytes, ['AW_EMPLOYEE_BINARY_UNAVAILABLE', 'AW_EMPLOYEE_BINARY_HASH_FAILED', 'AW_EMPLOYEE_BINARY_HASH_MISMATCH', 'AW_EMPLOYEE_BINARY_VERSION_FAILED', 'AW_EMPLOYEE_BINARY_VERSION_MISMATCH'], options.closeDiagnostics?.capture());
     if (signal.aborted) {
-        await transport.close();
+        await transport.close({ layer: 'endpoint', initiator: 'ssh.open-abort', reason: 'ABORTED', operation: 'open', action: 'abort' });
         throw fail('ABORTED');
     }
     try {
@@ -117,7 +119,7 @@ export async function createEmployeeSshTransport(options, signal = new AbortCont
         return transport;
     }
     catch (error) {
-        await transport.close();
+        await transport.close({ layer: 'endpoint', initiator: 'ssh.post-open-validation', reason: closeCode(error), operation: 'open', action: 'failure' });
         throw error;
     }
 }

package/dist/employee-tools.d.ts

@@ -1,8 +1,10 @@
+import { type CloseCause, type CloseDiagnostics } from './close-diagnostics.ts';
 import type { DetailObservation } from './conversation-details.ts';
 import type { EmployeeShell } from './employee-shell.ts';
 export declare const EMPLOYEE_TOOL_NAMES: readonly ["Read", "Write", "Edit", "Glob", "Grep", "Bash"];
 export type EmployeeToolName = typeof EMPLOYEE_TOOL_NAMES[number];
 interface Options {
+    closeDiagnostics?: CloseDiagnostics;
     cwd: string;
     shell: string;
     uid: number;
@@ -112,6 +114,6 @@ export declare function createEmployeeTools(options: Options): {
         } | undefined;
         isError?: boolean | undefined;
     }>;
-    close(): Promise<void>;
+    close(cause?: CloseCause): Promise<void>;
 };
 export {};