@ai-workbench/remote-agent 0.8.2 → 0.8.10

package/dist/employee-provider.js

@@ -0,0 +1,326 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createHash } from 'node:crypto';
+import { admitEmployeeLocation } from "./employee-location.js";
+import { EmployeeExecution } from "./employee-exec.js";
+import { createEmployeeSshTransport, validateEmployeeSshTarget } from "./employee-ssh.js";
+import { sshIo } from "./broker.js";
+import { NeedError } from "./remote.js";
+const fail = (code) => new NeedError(code, code === 'EMPLOYEE_OPERATION_UNSUPPORTED' ? '当前本机工作区只支持正在连接的会话；单次运行和断线后的冷恢复暂不支持，请新建会话。' : '本机工作区的执行连接无法继续（' + code + '），本轮没有改用主机执行。', '当前 L 工作区绑定、N/S 员工执行端点与支持本机执行的会话适配器');
+const errorCode = (error) => error instanceof NeedError ? error.code : 'EMPLOYEE_EXEC_UNKNOWN';
+const asNeed = (error) => error instanceof NeedError ? error : fail('EMPLOYEE_EXEC_UNKNOWN');
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const absolute = (value) => typeof value === 'string' && value.startsWith('/') && !value.includes('\0');
+const localApiCurrent = (api) => { const c = api.getContractInfo?.(); return c?.workspaceLocations === 1 && c.localWorkspaceContext === 1 && c.localUserTurnAcceptance === 1 && typeof api.getWorkspaceLocationState === 'function' && typeof api.getLocalWorkspaceContext === 'function' && typeof api.acceptLocalWorkspaceUserTurn === 'function'; };
+/** Read-only local classification and explicit acceptance precede even ensureReady's SSH status. */
+export async function acceptEmployeeUserTurn(get, employee, agent, api, request) {
+    const info = api.getContractInfo?.();
+    if (info?.workspaceLocations !== 1)
+        return;
+    if (typeof api.getWorkspaceLocationState !== 'function')
+        throw fail('DEPENDENCY_REQUIRED');
+    const state = api.getWorkspaceLocationState();
+    if (!state.items.length) {
+        request.localAdmissionCheck = () => { if (get() !== api || typeof api.getWorkspaceLocationState !== 'function' || api.getContractInfo?.().workspaceLocations !== 1 || api.getWorkspaceLocationState().items.length)
+            throw fail('EMPLOYEE_CONTEXT_CHANGED'); };
+        return;
+    }
+    const workspace = { ...await employee.workspace(request) };
+    request.signal?.throwIfAborted();
+    const rows = state.items.filter(row => row.workspaceId === workspace.id), row = rows[0];
+    const stamp = (s) => JSON.stringify([s.instanceId, s.epoch, s.phase, s.items.filter(x => x.workspaceId === workspace.id).map(x => [x.bindingId, x.source, x.status])]);
+    const captured = stamp(state), sourceStable = () => { if (get() !== api || typeof api.getWorkspaceLocationState !== 'function' || api.getContractInfo?.().workspaceLocations !== 1 || row?.source === 'local' && !localApiCurrent(api) || stamp(api.getWorkspaceLocationState()) !== captured)
+        throw fail('EMPLOYEE_CONTEXT_CHANGED'); request.signal?.throwIfAborted(); };
+    request.localAdmissionCheck = sourceStable;
+    sourceStable();
+    if (rows.length !== 1)
+        throw fail('EMPLOYEE_CONTEXT_CHANGED');
+    if (row.source !== 'local')
+        return;
+    if (agent.id !== 'codex-remote' || agent.loginProvider !== 'codex' || state.phase !== 'ready' || row.status !== 'selected' || !row.bindingId || info.localWorkspaceContext !== 1 || info.localUserTurnAcceptance !== 1 || typeof api.getLocalWorkspaceContext !== 'function' || typeof api.acceptLocalWorkspaceUserTurn !== 'function' || typeof employee.currentUserTurn !== 'function')
+        throw fail('DEPENDENCY_REQUIRED');
+    const connection = api.getConnectionState();
+    const stable = () => { sourceStable(); const now = api.getConnectionState(), location = api.getWorkspaceLocationState(), matches = location.items.filter(x => x.workspaceId === workspace.id); if (get() !== api || now.phase !== 'connected' || now.instanceId !== connection.instanceId || now.epoch !== connection.epoch || location.phase !== 'ready' || location.instanceId !== connection.instanceId || location.epoch !== connection.epoch || matches.length !== 1 || matches[0].source !== 'local' || matches[0].status !== 'selected' || matches[0].bindingId !== row.bindingId)
+        throw fail('EMPLOYEE_CONTEXT_CHANGED'); request.signal?.throwIfAborted(); };
+    stable();
+    const context = await api.getLocalWorkspaceContext({ instanceId: connection.instanceId, epoch: connection.epoch, workspaceId: workspace.id, expectedBindingId: row.bindingId });
+    if (!context.ok)
+        throw new NeedError(context.error.code, '无法核验本机工作区，本轮已停止。', '当前本机工作区');
+    stable();
+    const c = context.value, d = { ...c.directory };
+    if (c.version !== 1 || c.source !== 'local' || c.instanceId !== connection.instanceId || c.epoch !== connection.epoch || c.workspaceId !== workspace.id || c.bindingId !== row.bindingId || !absolute(d?.path) || d.path !== workspace.path || ![d.device, d.inode].every(n => Number.isSafeInteger(n) && n >= 0))
+        throw fail('EMPLOYEE_CONTEXT_CHANGED');
+    const expected = { ...employee.currentUserTurn(request) };
+    if (!Number.isSafeInteger(expected.turn) || expected.turn < 0 || typeof expected.userMessageId !== 'string' || !expected.userMessageId.trim())
+        throw fail('LOCAL_USER_TURN_UNCONFIRMED');
+    const response = await api.acceptLocalWorkspaceUserTurn({ instanceId: connection.instanceId, epoch: connection.epoch, sessionId: request.sessionId, provider: agent.loginProvider, purpose: 'user-turn', workspaceId: workspace.id, expectedBindingId: row.bindingId, expectedDirectory: { device: d.device, inode: d.inode }, expectedUserTurn: { ...expected } });
+    if (!response.ok)
+        throw new NeedError(response.error.code, '本次员工输入或工作区无法核验，本轮已停止。', 'L 本地真实输入接纳');
+    stable();
+    const a = response.value;
+    if (!a || a.version !== 1 || typeof a.acceptanceId !== 'string' || !a.acceptanceId.trim() || a.instanceId !== connection.instanceId || a.epoch !== connection.epoch || a.sessionId !== request.sessionId || a.provider !== agent.loginProvider || a.workspaceId !== workspace.id || a.bindingId !== row.bindingId || a.source !== 'local' || a.directory?.path !== d.path || a.directory?.device !== d.device || a.directory?.inode !== d.inode || a.userTurn?.turn !== expected.turn || a.userTurn?.userMessageId !== expected.userMessageId || ![a.userTurn?.startSequence, a.userTurn?.userMessageSequence].every(n => Number.isSafeInteger(n) && n >= 0) || a.userTurn.userMessageSequence <= a.userTurn.startSequence)
+        throw fail('LOCAL_USER_TURN_ACCEPTANCE_INVALID');
+    const accepted = Object.freeze({ ...a, directory: Object.freeze({ ...a.directory }), userTurn: Object.freeze({ ...a.userTurn }) });
+    request.localAdmissionCheck = () => { sourceStable(); const c = api.getConnectionState(); if (c.phase !== 'connected' || c.instanceId !== accepted.instanceId || c.epoch !== accepted.epoch)
+        throw fail('EMPLOYEE_CONTEXT_CHANGED'); const turn = employee.currentUserTurn(request); if (turn.turn !== accepted.userTurn.turn || turn.userMessageId !== accepted.userTurn.userMessageId)
+        throw new NeedError('LOCAL_USER_TURN_CHANGED', '本次输入已变化，本轮已停止。', '当前官方真实员工输入'); };
+    return accepted;
+}
+/** Recheck the admitted read-only facts after readiness awaits, before the catalog command. */
+export async function validateEmployeeUserTurn(get, employee, api, request, connection) {
+    const a = request.localAcceptance;
+    if (!a)
+        return;
+    const stable = () => { if (get() !== api || !localApiCurrent(api))
+        throw fail('EMPLOYEE_CONTEXT_CHANGED'); const c = api.getConnectionState(), state = api.getWorkspaceLocationState(), rows = state.items.filter(x => x.workspaceId === a.workspaceId); if (c.phase !== 'connected' || c.instanceId !== a.instanceId || c.epoch !== a.epoch || connection.instanceId !== a.instanceId || connection.epoch !== a.epoch || state.phase !== 'ready' || state.instanceId !== a.instanceId || state.epoch !== a.epoch || rows.length !== 1 || rows[0].source !== 'local' || rows[0].status !== 'selected' || rows[0].bindingId !== a.bindingId)
+        throw fail('EMPLOYEE_CONTEXT_CHANGED'); request.signal?.throwIfAborted(); };
+    stable();
+    const c = await api.getLocalWorkspaceContext({ instanceId: a.instanceId, epoch: a.epoch, workspaceId: a.workspaceId, expectedBindingId: a.bindingId });
+    stable();
+    if (!c.ok)
+        throw new NeedError(c.error.code, '无法核验本机工作区，本轮已停止。', '当前本机工作区');
+    if (c.value.version !== 1 || c.value.source !== 'local' || c.value.instanceId !== a.instanceId || c.value.epoch !== a.epoch || c.value.workspaceId !== a.workspaceId || c.value.bindingId !== a.bindingId || c.value.directory.path !== a.directory.path || c.value.directory.device !== a.directory.device || c.value.directory.inode !== a.directory.inode)
+        throw fail('EMPLOYEE_CONTEXT_CHANGED');
+    const turn = employee.currentUserTurn(request);
+    if (turn.turn !== a.userTurn.turn || turn.userMessageId !== a.userTurn.userMessageId)
+        throw new NeedError('LOCAL_USER_TURN_CHANGED', '本次输入已变化，本轮已停止。', '当前官方真实员工输入');
+}
+/** Source admission is separate from L's legacy host project resolver. */
+export function createEmployeeProvider(get, options, agent) {
+    const live = new Map();
+    return async (input) => {
+        const { api, target, connection, request } = input, info = api.getContractInfo?.(), sessionId = request.sessionId;
+        let prior = live.get(sessionId);
+        // A failed close remains a session tombstone. Source/endpoint changes cannot authorize a new host.
+        // Wait for an in-progress close before re-admission; its rejected result is intentionally sticky.
+        if (prior?.ended) {
+            await prior.closing;
+            prior = live.get(sessionId);
+        }
+        if (prior && (prior.current.api !== api || info?.workspaceLocations !== 1 || info?.localWorkspaceContext !== 1)) {
+            await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'));
+            throw fail('EMPLOYEE_CONTEXT_CHANGED');
+        }
+        if (info?.workspaceLocations !== 1 && info?.localWorkspaceContext !== 1)
+            return;
+        if (info.workspaceLocations !== 1 || info.localWorkspaceContext !== 1 || typeof api.getWorkspaceLocationState !== 'function' || typeof api.getLocalWorkspaceContext !== 'function' || !options.employee)
+            throw fail('DEPENDENCY_REQUIRED');
+        const employee = options.employee;
+        const workspace = await employee.workspace(request);
+        await input.stable(request.signal);
+        if (!workspace.id || !absolute(workspace.path))
+            throw fail('EMPLOYEE_CONTEXT_CHANGED');
+        const state = api.getWorkspaceLocationState(), rows = state.items.filter(row => row.workspaceId === workspace.id), row = rows[0];
+        if (state.phase !== 'ready' || state.instanceId !== connection.instanceId || state.epoch !== connection.epoch || rows.length !== 1 || row?.status !== 'selected' || !row.bindingId || !['local', 'host', 'legacy-host'].includes(row.source ?? ''))
+            throw fail('EMPLOYEE_CONTEXT_CHANGED');
+        if (row.source !== 'local') {
+            if (prior)
+                await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'));
+            if (request.localAcceptance)
+                throw fail('EMPLOYEE_CONTEXT_CHANGED');
+            return;
+        }
+        let details;
+        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)
+                throw fail('LOCAL_USER_TURN_UNCONFIRMED');
+            details = await options.details?.(request, api, connection, target);
+            if (details)
+                request.timing?.bind(detail => details.record(detail));
+            const unsupported = request.mode !== 'session' || agent.loginProvider !== 'codex' || !!request.recoveryCheckpointId || !!request.resumeSessionId && !prior;
+            if (unsupported)
+                throw fail('EMPLOYEE_OPERATION_UNSUPPORTED');
+            if (!Number.isSafeInteger(request.acpMaxMessageBytes) || request.acpMaxMessageBytes < 1)
+                throw fail('SETTINGS_REQUIRED');
+            if (typeof api.onWorkspaceLocationState !== 'function' || typeof api.onConnectionState !== 'function')
+                throw fail('DEPENDENCY_REQUIRED');
+            const network = employee.getNetwork();
+            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'));
+                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 });
+            if (request.cwd && request.cwd !== admitted.cwd || request.bindingId && request.bindingId !== admitted.bindingId || request.workspaceId && request.workspaceId !== admitted.workspaceId)
+                throw fail('SESSION_CONTEXT_MISMATCH');
+            const native = await employee.native();
+            if (!absolute(native.path) || !/^[a-f0-9]{64}$/.test(native.sha256))
+                throw fail('EMPLOYEE_BINARY_REQUIRED');
+            // Only executable identity belongs in this scope. Diagnostic metadata and object key
+            // insertion order cannot revoke a live binding; every public identity field stays bound.
+            const endpoint = admitted.endpoint, local = endpoint.local, account = endpoint.endpoint, bridge = endpoint.bridge;
+            const scope = digest({
+                target: { host: target.host, username: target.username, port: target.port, proxyCommand: target.proxyCommand, knownHostsFile: target.knownHostsFile, projectRoot: target.projectRoot,
+                    session: { command: target.session.command, root: target.session.root, settingsPath: target.session.settingsPath, protocolVersion: target.session.protocolVersion } },
+                endpoint: { version: endpoint.version,
+                    local: { instanceId: local.instanceId, epoch: local.epoch, workspaceId: local.workspaceId, bindingId: local.bindingId, directory: { path: local.directory.path, device: local.directory.device, inode: local.directory.inode } },
+                    endpoint: { deviceId: account.deviceId, endpointInstanceId: account.endpointInstanceId, executionContextId: account.executionContextId, remoteUser: account.remoteUser, remoteUid: account.remoteUid, remoteHome: account.remoteHome, endpointCwd: account.endpointCwd, endpointShell: account.endpointShell },
+                    bridge: { protocolVersion: bridge.protocolVersion, command: bridge.command, settingsPath: bridge.settingsPath, bridgeInstanceId: bridge.bridgeInstanceId, generation: bridge.generation } },
+                native: { path: native.path, sha256: native.sha256 },
+            });
+            if (prior && (prior.scope !== scope || prior.ended))
+                await prior.dispose(fail('EMPLOYEE_CONTEXT_CHANGED'));
+            let entry = prior && prior.scope === scope && !prior.ended ? prior : undefined;
+            let candidate = entry;
+            const base = async (signal) => {
+                signal.throwIfAborted();
+                if (get() !== api || employee.getNetwork() !== network)
+                    throw fail('EMPLOYEE_CONTEXT_CHANGED');
+                if (candidate?.ended)
+                    throw candidate.reason ?? fail('EMPLOYEE_EXEC_CLOSED');
+                await (candidate?.current ?? input).stable(signal);
+                await admitted.validate(signal);
+                if (get() !== api || employee.getNetwork() !== network)
+                    throw fail('EMPLOYEE_CONTEXT_CHANGED');
+                await (candidate?.current ?? input).stable(signal);
+                signal.throwIfAborted();
+            };
+            let argv = employee.argv;
+            if (!argv && !employee.io) {
+                const name = '@ai-workbench/connect';
+                const supplied = await import(__rewriteRelativeImportExtension(name));
+                if (typeof supplied.sshArgs !== 'function')
+                    throw fail('DEPENDENCY_REQUIRED');
+                argv = supplied.sshArgs;
+            }
+            const io = employee.io ?? sshIo(target, argv, request.acpMaxMessageBytes);
+            const scopedIo = { run: (command, signal) => io.run(command, signal), attach: async (command) => {
+                    const child = await io.attach(command);
+                    child.once('close', () => { if (candidate && !candidate.ended)
+                        void candidate.dispose(fail('EMPLOYEE_EXEC_UNKNOWN')).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 validate = async (signal) => { try {
+                await validateEmployeeSshTarget(ssh, signal);
+            }
+            catch (error) {
+                if (candidate && errorCode(error) !== 'ABORTED')
+                    await candidate.dispose(asNeed(error));
+                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) => {
+                    // 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)
+                        await (candidate?.current ?? input).stable();
+                    else
+                        await validate(request.signal ?? new AbortController().signal);
+                }, resumeSessionId: undefined, recoveryCheckpointId: undefined, verifyRecovery: undefined });
+            if (entry) {
+                entry.current = input;
+                entry.details = details;
+                try {
+                    await validate(request.signal ?? new AbortController().signal);
+                }
+                catch (error) {
+                    await entry.dispose(asNeed(error));
+                    throw error;
+                }
+                entry.runtime.details = details;
+                entry.runtime.connection = { ...connection };
+                entry.runtime.binding = { bindingId: admitted.bindingId, workspaceId: admitted.workspaceId, revision: state.revision };
+                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 => {
+                    if (entry.closing)
+                        return entry.closing;
+                    entry.ended = true;
+                    entry.reason = reason;
+                    execution.invalidate(reason ?? fail('EMPLOYEE_EXEC_CLOSED'));
+                    for (const off of disposers)
+                        off();
+                    host.broker?.fail(reason ?? fail('EMPLOYEE_EXEC_CLOSED'));
+                    entry.closing = (async () => {
+                        let cleanup;
+                        try {
+                            await execution.dispose();
+                        }
+                        catch (error) {
+                            cleanup = error;
+                        }
+                        try {
+                            await host.dispose?.();
+                        }
+                        catch (error) {
+                            cleanup = error;
+                        }
+                        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');
+                        }
+                        if (cleanup)
+                            throw fail('REMOTE_CLEANUP_UNCONFIRMED');
+                        if (live.get(sessionId) === entry)
+                            live.delete(sessionId);
+                    })();
+                    return entry.closing;
+                } };
+            candidate = entry;
+            runtime.employeeExecution = async (params, signal) => {
+                try {
+                    const result = await execution.handle(params, signal);
+                    if (result.closed)
+                        await entry.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));
+                    throw error;
+                }
+            };
+            runtime.dispose = () => entry.dispose();
+            runtime.detach = runtime.dispose;
+            const revoke = (reason) => { void entry.dispose(reason).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'));
+            }), 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')); }));
+            if (host.broker)
+                disposers.push(host.broker.onChange(() => { if (!host.broker.online)
+                    revoke(fail('EMPLOYEE_EXEC_UNKNOWN')); }));
+            live.set(sessionId, entry);
+            try {
+                await validate(request.signal ?? new AbortController().signal);
+            }
+            catch (error) {
+                await entry.dispose(asNeed(error));
+                throw error;
+            }
+            return runtime;
+        }
+        catch (error) {
+            details?.record({ kind: 'need', severity: 'action-required', code: errorCode(error), summary: asNeed(error).message, payload: { result: 'UNKNOWN' } });
+            try {
+                await details?.flush();
+            }
+            catch {
+                throw fail('CONVERSATION_DETAILS_FAILED');
+            }
+            throw error;
+        }
+    };
+}

package/dist/employee-relay.d.ts

@@ -0,0 +1,18 @@
+import type { EmployeeEndpointTarget } from './employee-endpoint.ts';
+/** Runs on the host. Only target discovery and SSH stdio forwarding; never user tools. */
+export declare const EMPLOYEE_TARGET_PYTHON: string;
+export declare const EMPLOYEE_PYTHON_ERRORS: string;
+export declare const EMPLOYEE_RELAY_PYTHON: string;
+export interface EmployeeRouting {
+    mcpServers: {
+        name: string;
+        command: string;
+        args: string[];
+        env: {
+            name: string;
+            value: string;
+        }[];
+    }[];
+    toolAliases: Record<string, string>;
+}
+export declare function employeeRouting(target: EmployeeEndpointTarget, socketPath: string, maxBytes: number): EmployeeRouting;

package/dist/employee-relay.js

@@ -0,0 +1,49 @@
+/** Runs on the host. Only target discovery and SSH stdio forwarding; never user tools. */
+export const EMPLOYEE_TARGET_PYTHON = String.raw `
+import os,sys,json,subprocess,selectors,shlex,re
+def fail(code):
+ sys.stderr.write(json.dumps({"code":code})+"\n");sys.exit(254)
+try:
+ x=json.loads(sys.argv[1]);e=x["endpoint"];b=x["bridge"];maximum=x["maxBytes"]
+ if not isinstance(maximum,int) or isinstance(maximum,bool) or maximum<1:fail("EMPLOYEE_RELAY_SETTINGS_INVALID")
+ if b["command"]!="/usr/local/aw-host/bin/aw-employee-bridge":fail("EMPLOYEE_RELAY_TARGET_INVALID")
+ argv=[b["command"],"target","--settings",b["settingsPath"],"--device",e["deviceId"],"--if-instance",b["bridgeInstanceId"],"--if-generation",str(b["generation"]),"--if-endpoint",e["endpointInstanceId"],"--if-context",e["executionContextId"]]
+ p=subprocess.Popen(argv,stdin=subprocess.DEVNULL,stdout=subprocess.PIPE,stderr=subprocess.PIPE)
+ selector=selectors.DefaultSelector();selector.register(p.stdout,selectors.EVENT_READ,"out");selector.register(p.stderr,selectors.EVENT_READ,"err")
+ data={"out":bytearray(),"err":bytearray()}
+ while selector.get_map():
+  for key,_ in selector.select():
+   chunk=os.read(key.fileobj.fileno(),maximum+1)
+   if not chunk:selector.unregister(key.fileobj);continue
+   data[key.data].extend(chunk)
+   if len(data["out"])+len(data["err"])>maximum:
+    p.kill();p.wait();fail("EMPLOYEE_RELAY_CONTROL_TOO_LARGE")
+ selector.close()
+ if p.wait()!=0:
+  reason=re.fullmatch(r"BRIDGE_ERROR ([A-Z][A-Z0-9_]{0,63})\s*",data["err"].decode("utf-8",errors="strict"))
+  fail(reason.group(1) if reason else "EMPLOYEE_BRIDGE_TARGET_FAILED")
+ t=json.loads(data["out"])
+ if t.get("type")!="target" or t.get("protocolVersion")!=1 or t.get("endpoint",{}).get("state")!="online":fail("EMPLOYEE_BRIDGE_PROTOCOL_INVALID")
+ expected=dict(e,bridgeInstanceId=b["bridgeInstanceId"],generation=b["generation"])
+ if any(t["endpoint"].get(k)!=v for k,v in expected.items()):fail("EMPLOYEE_CONTEXT_CHANGED")
+ args=t.get("sshArgs")
+ if not isinstance(args,list) or not args or any(not isinstance(v,str) or "\x00" in v for v in args):fail("EMPLOYEE_BRIDGE_PROTOCOL_INVALID")
+`;
+export const EMPLOYEE_PYTHON_ERRORS = String.raw `
+except (KeyError,ValueError,TypeError,OSError):
+ fail("EMPLOYEE_RELAY_FAILED")
+`;
+export const EMPLOYEE_RELAY_PYTHON = EMPLOYEE_TARGET_PYTHON + String.raw `
+ socket=x["socketPath"]
+ if not isinstance(socket,str) or not socket.startswith("/") or "\x00" in socket:fail("EMPLOYEE_RELAY_SOCKET_INVALID")
+ command=shlex.join(["/usr/bin/nc","-U",socket])
+ os.execv("/usr/bin/ssh",["/usr/bin/ssh","-T"]+args+[command])
+` + EMPLOYEE_PYTHON_ERRORS;
+export function employeeRouting(target, socketPath, maxBytes) {
+    const names = ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash'];
+    return {
+        // ACP0.94.0 uses absence of "type" to recognize stdio. Do not add type:"stdio".
+        mcpServers: [{ name: 'employee', command: '/usr/bin/python3', args: ['-c', EMPLOYEE_RELAY_PYTHON, JSON.stringify({ endpoint: target.endpoint, bridge: target.bridge, socketPath, maxBytes })], env: [] }],
+        toolAliases: Object.fromEntries(names.map(name => [name, 'mcp__employee__' + name])),
+    };
+}

package/dist/employee-shell.d.ts

@@ -0,0 +1,26 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import type { EmployeeEndpointTarget } from './employee-endpoint.ts';
+export interface EmployeeShellResult {
+    stdout: string;
+    stderr: string;
+    stderrSource: 'combined-ssh-and-command';
+    exitCode: number;
+    signal: null;
+}
+export type EmployeeShell = (request: {
+    command: string;
+    timeout?: number;
+    signal: AbortSignal;
+}) => Promise<EmployeeShellResult>;
+interface Options {
+    target: EmployeeEndpointTarget;
+    maxBytes: number;
+    killGraceMs: number;
+    attach: (spec: {
+        command: '/usr/bin/python3';
+        args: string[];
+    }) => Promise<ChildProcessWithoutNullStreams>;
+}
+/** Every invocation re-discovers the exact S target. Cancellation cannot prove remote exit. */
+export declare function createEmployeeShell(options: Options): EmployeeShell;
+export {};

package/dist/employee-shell.js

@@ -0,0 +1,89 @@
+import { randomUUID } from 'node:crypto';
+import { EMPLOYEE_TARGET_PYTHON, EMPLOYEE_PYTHON_ERRORS } from "./employee-relay.js";
+import { NeedError } from "./remote.js";
+const SHELL_PYTHON = EMPLOYEE_TARGET_PYTHON + String.raw `
+ cwd=x["directory"]["path"];device=x["directory"]["device"];inode=x["directory"]["inode"]
+ # User source is stdin, never argv. The sentinel preserves trailing newlines.
+ wrapper="cd -- "+shlex.quote(cwd)+" || exit 254; "+'test "$(/usr/bin/stat -f '+shlex.quote('%d %i')+' .)" = '+shlex.quote(str(device)+' '+str(inode))+" || exit 254; "+'test "$(/usr/bin/id -u)" = '+shlex.quote(str(e['remoteUid']))+" || exit 254; "+"printf '%s\\n' "+shlex.quote('AW_EMPLOYEE_SHELL_STARTED '+x['executionId'])+" >&2; "+'aw_x_source=$(/bin/cat; printf x); aw_x_source='+chr(36)+'{aw_x_source%?}; eval "'+chr(36)+'aw_x_source"'
+ command=shlex.join([e["endpointShell"],"-c",wrapper])
+ sys.stderr.write("AW_EMPLOYEE_SHELL_READY "+x["executionId"]+"\n");sys.stderr.flush()
+ p=subprocess.Popen(["/usr/bin/ssh","-T"]+args+[command],stdin=sys.stdin,stdout=sys.stdout,stderr=sys.stderr)
+ code=p.wait();sys.exit(code if code>=0 else 255)
+` + EMPLOYEE_PYTHON_ERRORS;
+const unknown = (code) => new NeedError(code, '本机命令结果未知；没有重放，也未改在主机执行。', '员工端真实退出回执');
+/** Every invocation re-discovers the exact S target. Cancellation cannot prove remote exit. */
+export function createEmployeeShell(options) {
+    return async ({ command, timeout, signal }) => {
+        signal.throwIfAborted();
+        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) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener('abort', abort);
+                if (grace)
+                    clearTimeout(grace);
+                if (timer)
+                    clearTimeout(timer);
+                child.stdin.destroy();
+                child.stdout.destroy();
+                child.stderr.destroy();
+                if (error) {
+                    no(error);
+                    return;
+                }
+                let out, err;
+                try {
+                    out = new TextDecoder('utf8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(stdout));
+                    err = new TextDecoder('utf8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(stderr));
+                }
+                catch {
+                    no(unknown('EMPLOYEE_OUTPUT_BINARY_UNSUPPORTED'));
+                    return;
+                }
+                const header = 'AW_EMPLOYEE_SHELL_READY ' + executionId + '\n', started = 'AW_EMPLOYEE_SHELL_STARTED ' + executionId + '\n';
+                const start = err.indexOf(started, header.length);
+                if (!err.startsWith(header) || start < header.length || start > header.length && err[start - 1] !== '\n') {
+                    const raw = err.startsWith(header) ? err.slice(header.length) : err;
+                    let source;
+                    try {
+                        const parsed = JSON.parse(raw);
+                        if (typeof parsed.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(parsed.code))
+                            source = parsed.code;
+                    }
+                    catch { /* Never expose arbitrary transport diagnostics. */ }
+                    no(unknown(source ?? 'EMPLOYEE_EXIT_UNKNOWN'));
+                    return;
+                }
+                if (code === null || code === undefined || code === 255) {
+                    no(unknown('EMPLOYEE_EXIT_UNKNOWN'));
+                    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 abort = () => stop('EMPLOYEE_CANCELLED_UNKNOWN');
+            const collect = (destination, chunk) => { bytes += chunk.length; if (bytes > options.maxBytes) {
+                stop('EMPLOYEE_OUTPUT_TOO_LARGE_UNKNOWN');
+                return;
+            } destination.push(chunk); };
+            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));
+            signal.addEventListener('abort', abort, { once: true });
+            if (signal.aborted)
+                abort();
+            if (timeout !== undefined)
+                timer = setTimeout(() => stop('EMPLOYEE_TIMEOUT_UNKNOWN'), timeout);
+            if (!reason)
+                child.stdin.end(command);
+        });
+    };
+}

package/dist/employee-ssh.d.ts

@@ -0,0 +1,22 @@
+import type { EmployeeEndpointTarget } from '@ai-workbench/network/api';
+import { type BrokerIo, type SshArgv } from './broker.ts';
+import type { ConnectTarget } from './provider.ts';
+import { type EmployeeExecutionTransport } from './employee-exec.ts';
+export interface EmployeeSshOptions {
+    target: ConnectTarget;
+    endpoint: EmployeeEndpointTarget;
+    /** Automatically discovered package binary path on this same employee device. */
+    employeeBinary: string;
+    binarySha256: string;
+    acpMaxMessageBytes: number;
+    argv: SshArgv;
+    validate(signal: AbortSignal): Promise<void>;
+    /** Fixture seam only. Production uses L's exported argv through sshIo. */
+    io?: BrokerIo;
+}
+/** Fixed bootstrap only; cwd for every native operation remains in its original RPC. */
+export declare function employeeExecServerCommand(binary: string, binarySha256: string): string;
+/** Invoke this in EmployeeExecution.validate before and after each native RPC write. */
+export declare function validateEmployeeSshTarget(options: EmployeeSshOptions, signal?: AbortSignal): Promise<void>;
+/** Outer L-authenticated host SSH, then S-authenticated employee SSH; no host execution fallback. */
+export declare function createEmployeeSshTransport(options: EmployeeSshOptions, signal?: AbortSignal): Promise<EmployeeExecutionTransport>;