@ai-workbench/remote-agent 0.8.12 → 0.8.14

package/dist/employee-provider.js

@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+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 +105,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 +122,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 +135,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 +150,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 +172,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 +182,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 +198,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 +232,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: '文件与命令在本机选定目录运行，Git 使用本机仓库；模型、登录和全局助手要求仍在远程主机。本机自定义的附加工具、自动动作、插件及断开后的会话恢复暂不支持。子任务被系统回收后能否继续，尚未验证。' };
+            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 +301,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 {};

package/dist/employee-tools.js

@@ -94,13 +94,14 @@ export function createEmployeeTools(options) {
         throw failure('EMPLOYEE_OUTPUT_TOO_LARGE'); };
     async function run(command, args, signal, detail, timeout) {
         signal.throwIfAborted();
+        const diagnostics = options.closeDiagnostics?.child(detail);
         const operation = new Promise((yes, no) => {
             const child = spawn(command, args, { cwd: options.cwd, env: process.env, stdio: ['pipe', 'pipe', 'pipe'] });
             child.stdin.end();
             let bytes = 0, stdout = [], stderr = [], failed, killTimer, timeoutTimer;
-            const kill = (which) => { if (child.exitCode === null && child.signalCode === null)
+            const kill = (which) => { diagnostics?.record({ layer: 'executor', initiator: 'tools.process-kill', reason: failed?.code ?? 'PROCESS_CLEANUP', action: 'terminate', signal: which }); if (child.exitCode === null && child.signalCode === null)
                 child.kill(which); };
-            const stop = (code) => { if (failed)
+            const stop = (code) => { diagnostics?.record({ layer: 'executor', initiator: 'tools.process-stop', reason: code, action: 'terminate', changes: [{ field: 'tools.stop-code', before: failed?.code ?? null, after: failed?.code ?? code }] }); if (failed)
                 return; failed = failure(code); kill('SIGTERM'); killTimer = setTimeout(() => kill('SIGKILL'), options.killGraceMs); killTimer.unref(); };
             const aborted = () => stop('EMPLOYEE_CANCELLED_UNKNOWN');
             const collect = (dest, chunk) => { bytes += chunk.length; if (bytes > options.maxBytes) {
@@ -116,8 +117,8 @@ export function createEmployeeTools(options) {
                 stop('CONVERSATION_DETAILS_FAILED');
             } if (signal.aborted)
                 aborted(); });
-            child.on('error', e => { failed ??= failure(e.code === 'ENOENT' ? 'EMPLOYEE_COMMAND_UNAVAILABLE' : 'EMPLOYEE_PROCESS_FAILED'); });
-            child.on('close', (exitCode, exitSignal) => { signal.removeEventListener('abort', aborted); if (killTimer)
+            child.on('error', e => { diagnostics?.record({ layer: 'executor', initiator: 'tools.process-error', reason: e.code === 'ENOENT' ? 'EMPLOYEE_COMMAND_UNAVAILABLE' : 'EMPLOYEE_PROCESS_FAILED', action: 'failure' }); failed ??= failure(e.code === 'ENOENT' ? 'EMPLOYEE_COMMAND_UNAVAILABLE' : 'EMPLOYEE_PROCESS_FAILED'); });
+            child.on('close', (exitCode, exitSignal) => { diagnostics?.record({ layer: 'executor', initiator: 'tools.process-close', reason: failed?.code ?? 'PROCESS_EXIT', action: 'exit', exitCode, signal: exitSignal }); signal.removeEventListener('abort', aborted); if (killTimer)
                 clearTimeout(killTimer); if (timeoutTimer)
                 clearTimeout(timeoutTimer); failed ? no(failed) : yes({ stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8'), exitCode, signal: exitSignal }); });
             signal.addEventListener('abort', aborted, { once: true });
@@ -287,6 +288,6 @@ export function createEmployeeTools(options) {
     }
     return {
         call(name, input, requestSignal, observer) { const operation = call(name, input, requestSignal, observer); calls.add(operation); void operation.then(() => calls.delete(operation), () => calls.delete(operation)); return operation; },
-        async close() { lifetime.abort(); await Promise.allSettled([...calls, ...children]); },
+        async close(cause = { layer: 'executor', initiator: 'tools.close', reason: 'EMPLOYEE_TOOLS_CLOSED', action: 'close' }) { options.closeDiagnostics?.record({ ...cause, changes: cause.changes ?? [{ field: 'tools.aborted', before: lifetime.signal.aborted, after: true }] }); lifetime.abort(); await Promise.allSettled([...calls, ...children]); },
     };
 }

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type CloseChange } from './close-diagnostics.ts';
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
 import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm';
@@ -74,6 +75,7 @@ export declare class CodexRemoteAdapter extends LlmAdapter {
     private shuttingDown;
     private detached;
     private cleanups;
+    private preparationFailures;
     constructor(config: PluginConfig | (() => PluginConfig), resolveRuntime: RuntimeProvider, approve?: InvocationApproval | undefined, providerName?: () => string, agent?: AgentDefinition, readImage?: ImageReader | undefined, reportLoginFailure?: LoginFailureReporter | undefined, directory?: ModelDirectory | undefined, preflightDiagnostics?: PreflightDiagnostics | undefined);
     providerInfo(provider: string): {
         id: string;
@@ -86,6 +88,7 @@ export declare class CodexRemoteAdapter extends LlmAdapter {
     resolveModel(provider: string, id: string, signal?: AbortSignal): Promise<import("@deepseek-ai/dsh-llm").LlmResolvedModelInfo & {
         catalog: HostModel;
     }>;
+    observeModelInvalidation(fields: readonly string[], changes?: readonly CloseChange[]): void;
     invalidateModelState(): Promise<void>;
     invalidateEmployeeState(): Promise<void>;
     providerRetryPolicy(): {
@@ -118,6 +121,7 @@ export declare class RemoteAgentsAdapter extends LlmAdapter {
     resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<import("@deepseek-ai/dsh-llm").LlmResolvedModelInfo & {
         catalog: HostModel;
     }>;
+    observeModelInvalidation(fields: readonly string[], changes?: readonly CloseChange[]): void;
     invalidateModelState(): Promise<void>;
     invalidateEmployeeState(): Promise<void>;
     providerRetryPolicy(): {