@ai-workbench/remote-agent 0.8.5 → 0.8.11

package/dist/broker-runtime.js

@@ -39,6 +39,9 @@ export function brokerFactory(get, _ask, configuration, provided) {
         const agent = request.agent ?? CODEX_AGENT;
         if (!request.sessionId)
             throw need('SESSION_REQUIRED');
+        const employeeScope = request.employeeScope;
+        if (employeeScope && (request.mode !== 'session' || request.resumeSessionId || request.recoveryCheckpointId))
+            throw need('EMPLOYEE_OPERATION_UNSUPPORTED');
         if (request.mode === 'one-shot') {
             const key = 'one-shot/' + identity(target) + '/' + agent.id + '/' + request.sessionId;
             if (active.has(key))
@@ -49,8 +52,18 @@ export function brokerFactory(get, _ask, configuration, provided) {
         }
         if (![settings.brokerMaxFrameBytes, settings.brokerControlMaxBytes].every(n => Number.isSafeInteger(n) && n > 0))
             throw need('SETTINGS_REQUIRED');
-        const key = recoveryKey([identity(target), agent.id, request.sessionId]);
-        const scope = recoveryKey([target.host, target.username, target.port, target.proxyCommand, target.knownHostsFile, target.projectRoot, target.session, project.path, agent.id, settings, request.bindingId, request.workspaceId, request.contextSha256]);
+        const key = recoveryKey([identity(target), agent.id, request.sessionId, ...(employeeScope ? [employeeScope] : [])]);
+        // New employee scopes compare execution values, independent of JSON key insertion order.
+        // Legacy journals retain their historical serialization bytes.
+        const scopedSession = employeeScope ? { command: target.session.command, root: target.session.root, settingsPath: target.session.settingsPath, protocolVersion: target.session.protocolVersion } : target.session;
+        const scopedSettings = employeeScope ? { brokerMaxFrameBytes: settings.brokerMaxFrameBytes, brokerControlMaxBytes: settings.brokerControlMaxBytes } : settings;
+        const scopeParts = [target.host, target.username, target.port, target.proxyCommand, target.knownHostsFile, target.projectRoot, scopedSession, project.path, agent.id, scopedSettings, request.bindingId, request.workspaceId];
+        if (employeeScope)
+            scopeParts.push(employeeScope);
+        const contextBoundScope = recoveryKey([...scopeParts, request.contextSha256]);
+        // A Codex ACP process can own several immutable native sessions. D18's durable
+        // pointer controls their context; the broker still binds every transport identity.
+        const scope = agent.loginProvider === 'codex' ? recoveryKey([...scopeParts, undefined]) : contextBoundScope;
         const existing = request.retainProcess ? retained.get(key) : undefined;
         if (existing) {
             if (existing.scope !== scope)
@@ -70,8 +83,11 @@ export function brokerFactory(get, _ask, configuration, provided) {
             if (!journal)
                 throw need('RECOVERY_STORAGE_REQUIRED');
             let state = await journal.read();
-            if (state && state.scope !== scope)
-                throw need('SESSION_CONTEXT_MISMATCH');
+            const legacyContextScope = !!state && state.scope !== scope && agent.loginProvider === 'codex' && state.scope === contextBoundScope;
+            if (state && state.scope !== scope && !legacyContextScope)
+                throw need(agent.loginProvider === 'codex' ? 'RECOVERY_CONTEXT_POLICY_UNSUPPORTED' : 'SESSION_CONTEXT_MISMATCH');
+            if (legacyContextScope && state?.phase !== 'clean')
+                throw need('RECOVERY_CONTEXT_POLICY_UNSUPPORTED');
             let argv = provided?.argv;
             if (!provided?.io && !argv) {
                 const name = '@ai-workbench/connect';
@@ -91,7 +107,7 @@ export function brokerFactory(get, _ask, configuration, provided) {
             const list = async (cleanup = false) => timing.run('broker-list', async () => { const rows = controlJson(await io.run(command(['list']), cleanup ? undefined : request.signal)); if (!Array.isArray(rows) || rows.some(row => typeof row?.id !== 'string'))
                 throw need('BROKER_PROTOCOL_INVALID'); return rows; });
             let rows = await list();
-            const id = brokerId(request.sessionId, agent.id), oldId = legacyBrokerId(request.sessionId, agent.id);
+            const id = brokerId(request.sessionId, employeeScope ? agent.id + '/employee/' + employeeScope : agent.id), oldId = legacyBrokerId(request.sessionId, agent.id);
             let restarted = false;
             const attachArgs = (entry, after) => ['attach', entry.id, '--after', String(after), '--framed', ...(modern(entry) ? ['--leased', '--if-instance', entry.instanceId] : [])];
             const connectWithLease = async (transport, entry, cleanup = false) => {
@@ -170,12 +186,14 @@ export function brokerFactory(get, _ask, configuration, provided) {
                     probe.close();
                 }
             };
-            const legacy = rows.find(row => row.id === oldId);
+            const legacy = employeeScope ? undefined : rows.find(row => row.id === oldId);
             if (legacy)
                 await report('PRE_0410_TEST_SESSION_NOT_RESUMED', { brokerId: legacy.id, observedPid: legacy.pid, state: legacy.state, instanceId: legacy.instanceId ?? null, reason: 'OLD_TEST_SESSION_COORDINATOR_CLEANUP', decision: '2026-10-22-00:05', approvalReplies: 0 });
             let entry = rows.find(row => row.id === id);
             if (entry)
                 validEntry(entry);
+            if (legacyContextScope && !entry)
+                throw need('RECOVERY_CONTEXT_POLICY_UNSUPPORTED');
             if (legacy && !entry)
                 restarted = true;
             let transport;
@@ -189,6 +207,8 @@ export function brokerFactory(get, _ask, configuration, provided) {
                             throw need('RECOVERY_MODEL_CONFIGURATION_INVALID');
                         (recovery.configUpdates ??= []).push(structuredClone(params.update.configOptions));
                     } request.detailChannel?.record({ kind: 'session', severity: 'info', code: 'ACP_IDLE_UPDATE', summary: '恢复期间的远端状态轨迹', method: 'session/update', payload: message.params }); } } : {}), attach: after => io.attach(command(attachArgs(entry, after))), onDisconnect: async () => {
+                    if (employeeScope)
+                        throw need('EMPLOYEE_EXEC_UNKNOWN');
                     const api = get();
                     if (!provided?.io) {
                         if (!api)
@@ -205,7 +225,9 @@ export function brokerFactory(get, _ask, configuration, provided) {
             if (entry) {
                 if (!modern(entry))
                     throw need('BROKER_CAPABILITY_REQUIRED');
-                const clean = state?.phase === 'clean' && state.instanceId === entry.instanceId && state.acp?.sessionId === request.resumeSessionId && state.checkpointId === request.recoveryCheckpointId && state.cursor >= entry.firstSequence - 1 && state.cursor <= entry.lastSequence && entry.state === 'running' && await request.verifyRecovery?.() !== false;
+                const clean = !employeeScope && state?.phase === 'clean' && state.instanceId === entry.instanceId && state.acp?.sessionId === request.resumeSessionId && state.checkpointId === request.recoveryCheckpointId && state.cursor >= entry.firstSequence - 1 && state.cursor <= entry.lastSequence && entry.state === 'running' && (legacyContextScope ? await request.verifyRecovery?.() === true : await request.verifyRecovery?.() !== false);
+                if (legacyContextScope && !clean)
+                    throw need('RECOVERY_CONTEXT_POLICY_UNSUPPORTED');
                 if (clean) {
                     transport = build(entry, state.cursor, state.acp);
                     try {
@@ -213,11 +235,17 @@ export function brokerFactory(get, _ask, configuration, provided) {
                         await transport.replayThrough(entry.lastSequence, request.signal);
                         await request.detailChannel?.flush();
                         await validate();
+                        if (legacyContextScope) {
+                            const migrated = { ...state, scope };
+                            await report('CODEX_RECOVERY_SCOPE_MIGRATED', { oldScope: state.scope, newScope: scope, sessionId: state.acp.sessionId, checkpointId: state.checkpointId, instanceId: entry.instanceId, cursor: state.cursor });
+                            await journal.write(migrated);
+                            state = migrated;
+                        }
                         resume = state.acp;
                     }
                     catch (error) {
                         transport.close();
-                        if (error instanceof NeedError && ['ATTACH_BUSY', 'SESSION_IN_USE', 'SESSION_INSTANCE_MISMATCH', 'ABORTED'].includes(error.code))
+                        if (legacyContextScope || error instanceof NeedError && ['ATTACH_BUSY', 'SESSION_IN_USE', 'SESSION_INSTANCE_MISMATCH', 'ABORTED'].includes(error.code))
                             throw error;
                         await report('SESSION_REPLAY_UNRECOVERABLE', { brokerId: id, instanceId: entry.instanceId, reason: error instanceof NeedError ? error.code : 'UNKNOWN_FAILURE', recordedCursor: state?.cursor ?? null, firstSequence: entry.firstSequence, lastSequence: entry.lastSequence });
                     }
@@ -289,6 +317,10 @@ export function brokerFactory(get, _ask, configuration, provided) {
                     active.delete(key);
                     retained.delete(key);
                 } })(), };
+            if (employeeScope) {
+                runtime.saveCheckpoint = undefined;
+                runtime.detach = runtime.dispose;
+            }
             if (request.retainProcess)
                 retained.set(key, { runtime, scope, update: next => { request = next; timing = next.timing ?? new StageTiming(); } });
             return runtime;

package/dist/broker.js

@@ -354,7 +354,11 @@ export function controlNeed(stderr) {
         if (typeof result?.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(result.code))
             code = result.code;
     }
-    catch { /* Only the declared JSON error code is public, never raw stderr. */ }
+    catch {
+        const bridge = /^BRIDGE_ERROR ([A-Z][A-Z0-9_]{0,63})\n?$/.exec(stderr);
+        if (bridge)
+            code = bridge[1]; /* Exact S0411 CLI reason only, never mixed/raw stderr. */
+    }
     return new NeedError(code, code === 'EACCES' ? '我需要管理员让该员工可读、不可写主机会话配置；当前路径访问被拒绝' : `主机会话控制失败（${code}）；根因${code === 'BROKER_CONTROL_FAILED' ? '未查明' : '见错误代码'}，没有重试或新建替代进程`, code === 'EACCES' ? '员工可读且员工不可写的 session.settingsPath' : '恢复原员工 broker 连接并确认会话状态');
 }
 export function sshIo(target, argv, maxControlBytes) {

package/dist/claude-local.d.ts

@@ -0,0 +1,37 @@
+import { type EmployeeLease, type EmployeeLeaseOptions, type EmployeeNetworkApi, type EmployeeWorkspace } from './employee-endpoint.ts';
+import { type EmployeeMcpOptions } from './employee-mcp.ts';
+import { createEmployeeShell, type EmployeeShell } from './employee-shell.ts';
+import type { EmployeeRouting } from './employee-relay.ts';
+import { type ConnectApi, type ConnectTarget, type Project, type Runtime, type RuntimeRequest, type LocalRuntimeProvider, type ConnectionState } from './provider.ts';
+import type { DetailChannel } from './remote-details.ts';
+import type { LocalTurnProof } from './local-user-turn.ts';
+import type { DetailObservation } from './conversation-details.ts';
+interface Configuration {
+    acpMaxMessageBytes?: number;
+    brokerControlMaxBytes?: number;
+    employeeShellKillGraceMs?: number;
+}
+interface Options {
+    getConnect: () => ConnectApi | undefined;
+    getNetwork: () => EmployeeNetworkApi | undefined;
+    readWorkspace: (sessionId: string) => Promise<EmployeeWorkspace>;
+    configuration: () => Configuration;
+    readUserTurn: (request: RuntimeRequest) => Promise<LocalTurnProof>;
+    reportAdmissionFailure: (request: RuntimeRequest, code: string) => Promise<void>;
+    recordUnscoped: (request: RuntimeRequest, event: DetailObservation) => Promise<void>;
+    details: (request: RuntimeRequest, api: ConnectApi, connection: ConnectionState, target: ConnectTarget) => Promise<DetailChannel>;
+    open: (target: ConnectTarget, project: Project, request: RuntimeRequest) => Promise<Runtime>;
+    /** Explicit component-test ports only. Production supplies none. */
+    ports?: {
+        lease: (options: EmployeeLeaseOptions, signal?: AbortSignal) => Promise<EmployeeLease>;
+        mcp: (options: EmployeeMcpOptions) => Promise<{
+            routing: EmployeeRouting;
+            signal?: AbortSignal;
+            close(): Promise<void>;
+        }>;
+        shell: (options: Parameters<typeof createEmployeeShell>[0]) => EmployeeShell;
+    };
+}
+/** Local source only. Host and legacy-host remain with the original provider. */
+export declare function createClaudeLocalProvider(options: Options): LocalRuntimeProvider;
+export {};

package/dist/claude-local.js

@@ -0,0 +1,207 @@
+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 { isDeepStrictEqual } from 'node:util';
+import { openEmployeeLease } from "./employee-endpoint.js";
+import { openEmployeeMcp } from "./employee-mcp.js";
+import { createEmployeeShell } from "./employee-shell.js";
+import { sameTarget, unwrap } from "./provider.js";
+import { sshIo } from "./broker.js";
+import { NeedError, shellQuote } from "./remote.js";
+import { awaitL } from "./provider.js";
+const failure = (code) => new NeedError(code, '当前本机执行上下文无法确认，本轮已停止；没有改在主机执行。', 'L当前本地绑定、N员工端点与S同代桥');
+const NOTICE = '本轮六类文件与命令工具在你的电脑执行，使用你选择的文件夹；Git也使用本机仓库。子代理和内部直接调用尚不支持本机，可能仍在主机；已识别的此类审批不会执行。PDF等二进制读取、后台命令暂不支持。';
+/** Local source only. Host and legacy-host remain with the original provider. */
+export function createClaudeLocalProvider(options) {
+    const entries = new Map();
+    const admitted = new WeakMap();
+    const admit = async (request, api, connection, target) => {
+        if (admitted.has(request))
+            return;
+        try {
+            if (api.getContractInfo?.().workspaceLocations !== 1)
+                return;
+            const local = api;
+            if (typeof local.getWorkspaceLocationState !== 'function')
+                throw failure('EMPLOYEE_CONTEXT_UNAVAILABLE');
+            const workspace = await options.readWorkspace(request.sessionId), state = local.getWorkspaceLocationState(), matches = state.items.filter(row => row.workspaceId === workspace.workspaceId);
+            if (matches.length !== 1 || state.phase !== 'ready' || state.instanceId !== connection.instanceId || state.epoch !== connection.epoch)
+                throw failure('EMPLOYEE_CONTEXT_CHANGED');
+            const item = matches[0];
+            if (item.source !== 'local')
+                return;
+            if (item.status !== 'selected' || !item.bindingId || api.getContractInfo?.().localUserTurnAcceptance !== 1 || typeof api.acceptLocalWorkspaceUserTurn !== 'function' || typeof local.getLocalWorkspaceContext !== 'function')
+                throw failure('EMPLOYEE_CONTEXT_UNAVAILABLE');
+            const context = unwrap(await awaitL(() => local.getLocalWorkspaceContext({ instanceId: connection.instanceId, epoch: connection.epoch, workspaceId: workspace.workspaceId, expectedBindingId: item.bindingId }), request.signal));
+            if (context.instanceId !== connection.instanceId || context.epoch !== connection.epoch || context.workspaceId !== workspace.workspaceId || context.bindingId !== item.bindingId || context.source !== 'local' || !isDeepStrictEqual(context.directory, workspace.directory))
+                throw failure('EMPLOYEE_CONTEXT_CHANGED');
+            const proof = await options.readUserTurn(request);
+            proof.assertCurrent();
+            const accepted = unwrap(await awaitL(() => api.acceptLocalWorkspaceUserTurn({ instanceId: connection.instanceId, epoch: connection.epoch, sessionId: request.sessionId, provider: 'claude', purpose: 'user-turn', workspaceId: workspace.workspaceId, expectedBindingId: item.bindingId, expectedDirectory: { device: workspace.directory.device, inode: workspace.directory.inode }, expectedUserTurn: { ...proof.expectedUserTurn } }), request.signal));
+            proof.assertCurrent();
+            request.signal?.throwIfAborted();
+            const now = api.getConnectionState();
+            if (options.getConnect() !== api || now.phase !== 'connected' || now.instanceId !== connection.instanceId || now.epoch !== connection.epoch)
+                throw failure('CONNECTION_LOST');
+            if (!accepted || accepted.version !== 1 || typeof accepted.acceptanceId !== 'string' || !accepted.acceptanceId.trim() || accepted.instanceId !== connection.instanceId || accepted.epoch !== connection.epoch || accepted.sessionId !== request.sessionId || accepted.provider !== 'claude' || accepted.workspaceId !== workspace.workspaceId || accepted.bindingId !== item.bindingId || accepted.source !== 'local' || !isDeepStrictEqual(accepted.directory, workspace.directory) || accepted.userTurn?.turn !== proof.expectedUserTurn.turn || accepted.userTurn.userMessageId !== proof.expectedUserTurn.userMessageId || accepted.userTurn.startSequence !== proof.startSequence || accepted.userTurn.userMessageSequence !== proof.userMessageSequence)
+                throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+            Object.defineProperty(request, 'localAcceptanceId', { value: accepted.acceptanceId, enumerable: true });
+            request.detailChannel = await options.details(request, api, connection, target);
+            admitted.set(request, { api, workspace: structuredClone(workspace), bindingId: item.bindingId, connection: structuredClone(connection) });
+        }
+        catch (error) {
+            const code = error instanceof NeedError ? error.code : 'LOCAL_ADMISSION_FAILED';
+            try {
+                await options.reportAdmissionFailure(request, code);
+            }
+            catch {
+                throw new NeedError(code, '本轮输入无法核对，已停止本次处理；诊断保存也未完成。', '原原因 ' + code + '；私有诊断 REMOTE_DETAIL_STORAGE_FAILED');
+            }
+            throw error;
+        }
+    };
+    const resolve = async (request, api, connection, target) => {
+        if (api.getContractInfo?.().workspaceLocations !== 1)
+            return;
+        const local = api;
+        if (typeof local.getWorkspaceLocationState !== 'function')
+            throw failure('EMPLOYEE_CONTEXT_UNAVAILABLE');
+        const workspace = await options.readWorkspace(request.sessionId), state = local.getWorkspaceLocationState(), matches = state.items.filter(row => row.workspaceId === workspace.workspaceId);
+        if (state.phase !== 'ready' || state.instanceId !== connection.instanceId || state.epoch !== connection.epoch || matches.length !== 1)
+            throw failure('EMPLOYEE_CONTEXT_CHANGED');
+        const item = matches[0];
+        if (item.source !== 'local')
+            return;
+        if (!admitted.has(request))
+            await admit(request, api, connection, target);
+        const acceptance = admitted.get(request);
+        if (!acceptance || acceptance.api !== api || acceptance.bindingId !== item.bindingId || acceptance.connection.instanceId !== connection.instanceId || acceptance.connection.epoch !== connection.epoch || !isDeepStrictEqual(acceptance.workspace, workspace))
+            throw failure('EMPLOYEE_CONTEXT_CHANGED');
+        if (item.status !== 'selected' || !item.bindingId || local.getContractInfo().localWorkspaceContext !== 1)
+            throw failure('EMPLOYEE_CONTEXT_UNAVAILABLE');
+        if (request.cwd && request.cwd !== workspace.directory.path || request.bindingId && request.bindingId !== item.bindingId || request.workspaceId && request.workspaceId !== workspace.workspaceId)
+            throw failure('SESSION_CONTEXT_MISMATCH');
+        const configuration = options.configuration(), maximum = request.acpMaxMessageBytes ?? configuration.acpMaxMessageBytes, control = request.brokerSettings?.brokerControlMaxBytes ?? configuration.brokerControlMaxBytes, grace = configuration.employeeShellKillGraceMs;
+        if (![maximum, control, grace].every(n => Number.isSafeInteger(n) && n >= 0) || !maximum || !control)
+            throw failure('SETTINGS_REQUIRED');
+        const scope = { target, workspace, bindingId: item.bindingId, instanceId: connection.instanceId, epoch: connection.epoch, maximum, control, grace };
+        let entry = entries.get(request.sessionId);
+        if (entry && (entry.closing || !isDeepStrictEqual(entry.scope, scope) || entry.lease.signal.aborted))
+            throw failure('EMPLOYEE_CONTEXT_CHANGED');
+        const details = request.detailChannel;
+        request.timing?.bind(observation => details.record(observation));
+        const trusted = async (ignoreCancellation = false) => {
+            if (!ignoreCancellation)
+                request.signal?.throwIfAborted();
+            if (options.getConnect() !== api)
+                throw failure('CONNECTION_LOST');
+            const now = api.getConnectionState();
+            if (now.phase !== 'connected' || now.instanceId !== connection.instanceId || now.epoch !== connection.epoch || !sameTarget(unwrap(await api.getSshTarget()), target))
+                throw failure('CONNECTION_LOST');
+        };
+        const openRequest = (row, cold = false) => ({ ...request, detailChannel: details, bindingId: item.bindingId, workspaceId: workspace.workspaceId, bindingRevision: state.revision, ...cold ? { recoveryCheckpointId: undefined } : {}, validateContext: async (cleanup = false) => { await trusted(cleanup); if (!cleanup)
+                await row.lease.validate(request.signal); } });
+        if (entry) {
+            entry.details = details;
+            entry.request = request;
+            await entry.lease.validate(request.signal);
+            const base = await options.open(target, { name: workspace.workspaceId, path: target.session.root }, openRequest(entry));
+            if (base.acpTransport !== entry.runtime.acpTransport)
+                throw failure('SESSION_TRANSPORT_MISMATCH');
+            entry.runtime.details = details;
+            entry.runtime.restartNotice = base.restartNotice;
+            entry.runtime.restartInputIds = base.restartInputIds;
+            return entry.runtime;
+        }
+        let io;
+        const transport = async () => { if (!io) {
+            const name = '@ai-workbench/connect';
+            const l = await import(__rewriteRelativeImportExtension(name));
+            if (typeof l.sshArgs !== 'function')
+                throw failure('DEPENDENCY_REQUIRED');
+            io = sshIo(target, l.sshArgs, control);
+        } return io; };
+        let lease, mcp, base;
+        let privateFailure, privateTail = Promise.resolve();
+        try {
+            const unscoped = (observation) => { if (privateFailure)
+                throw privateFailure; privateTail = privateTail.then(() => options.recordUnscoped(request, observation)).catch(error => { privateFailure ??= error; void lease?.close().catch(failure => { privateFailure ??= failure; }); }); };
+            lease = await (options.ports?.lease ?? openEmployeeLease)({ getConnect: () => options.getConnect(), getNetwork: options.getNetwork, readWorkspace: () => options.readWorkspace(request.sessionId), host: target, sessionId: request.sessionId, control: async (_target, command, signal) => (await transport()).run(command, signal), detail: unscoped }, request.signal);
+            const shell = (options.ports?.shell ?? createEmployeeShell)({ target: lease.target, maxBytes: maximum, killGraceMs: grace, attach: async (spec) => (await transport()).attach([spec.command, ...spec.args].map(shellQuote).join(' ')) });
+            mcp = await (options.ports?.mcp ?? openEmployeeMcp)({ lease, maxBytes: maximum, killGraceMs: grace, runShell: shell, activeSignal: () => entry?.active?.signal, captureDetail: () => { const sink = entry?.active?.details; if (!sink)
+                    throw failure('EMPLOYEE_NO_ACTIVE_TURN'); return observation => sink.record(observation); }, detail: unscoped });
+            entry = { runtime: undefined, scope, lease, details, request };
+            const row = entry;
+            base = await options.open(target, { name: workspace.workspaceId, path: target.session.root }, openRequest(row, true));
+            const underlying = base, endpoint = mcp;
+            const close = (detach) => row.closing ??= Promise.resolve().then(async () => {
+                row.active = undefined;
+                const errors = [];
+                try {
+                    await endpoint.close();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+                await privateTail;
+                if (privateFailure)
+                    errors.push(privateFailure);
+                try {
+                    await (detach ? underlying.detach?.() : underlying.dispose?.());
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+                if (errors.length)
+                    throw new AggregateError(errors, 'EMPLOYEE_CLEANUP_UNCONFIRMED');
+                if (entries.get(request.sessionId) === row)
+                    entries.delete(request.sessionId);
+            });
+            const executionSignal = AbortSignal.any([lease.signal, ...mcp.signal ? [mcp.signal] : []]);
+            row.runtime = { ...underlying, cwd: workspace.directory.path, details, connection: { ...connection }, binding: { bindingId: item.bindingId, workspaceId: workspace.workspaceId, revision: state.revision }, execution: { hostCwd: target.session.root, routing: mcp.routing, notice: NOTICE, signal: executionSignal, scope: { source: 'local', cwd: workspace.directory.path, hostCwd: target.session.root, uid: lease.target.endpoint.remoteUid, claudeAcpVersion: '0.94.0', sdkVersion: '0.3.303', unsupported: ['subagents', 'internal-direct-calls', 'binary-read', 'background-shell'] }, validate: async (signal) => { executionSignal.throwIfAborted(); await row.lease.validate(signal); }, beginTurn: async (signal) => { executionSignal.throwIfAborted(); if (row.closing || row.active)
+                        throw failure('TURN_BUSY'); await row.lease.validate(signal); executionSignal.throwIfAborted(); row.active = { signal, details: row.details }; }, endTurn: () => { row.active = undefined; } }, dispose: () => close(false), detach: () => close(true) };
+            entries.set(request.sessionId, row);
+            lease.signal.addEventListener('abort', () => { void close(false).catch(() => { }); }, { once: true });
+            if (lease.signal.aborted) {
+                await close(false);
+                throw failure('EMPLOYEE_CONTEXT_CHANGED');
+            }
+            return row.runtime;
+        }
+        catch (error) {
+            const cleanup = [];
+            try {
+                await mcp?.close();
+                await lease?.close();
+            }
+            catch (e) {
+                cleanup.push(e);
+            }
+            try {
+                await base?.dispose?.();
+            }
+            catch (e) {
+                cleanup.push(e);
+            }
+            await privateTail;
+            if (privateFailure)
+                cleanup.push(privateFailure);
+            try {
+                await details.flush();
+            }
+            catch (e) {
+                cleanup.push(e);
+            }
+            if (cleanup.length)
+                throw new AggregateError([error, ...cleanup], 'EMPLOYEE_OPEN_CLEANUP_UNCONFIRMED');
+            throw error;
+        }
+    };
+    resolve.admit = admit;
+    return resolve;
+}

package/dist/client.js

@@ -1,7 +1,76 @@
 /* Official locale and provider-registration updates only; no custom UI or refresh. */
-window.__ModuleLoader__.load({id:'@ai-workbench/remote-agent',factory(){
-  const messages={"en":{"administratorNote":"Administrators: use Settings → Open configuration file to edit the existing plugin entry. See README for the six fields and approved defaults.","providerName":"Codex (Remote Host)"},"zh":{"administratorNote":"管理员：从设置使用“打开配置文件”，修改已有插件条目；六个字段和已批准默认值见 README。","providerName":"Codex（远程主机）"}};
+window.__ModuleLoader__.load({id:'@ai-workbench/remote-agent',factory(require){
+  const messages={"en":{"administratorNote":"Settings → Built-in plugins → 远程助手参数. Seven named settings with defaults, scope and effects.","providerName":"Codex (Remote Host)"},"zh":{"administratorNote":"管理员：设置 → 内置插件 → 远程助手参数。七项设置含默认值、范围、生效和后果说明。","providerName":"Codex（远程主机）"}};
+  const settingsFields=[{"key":"mode","name":"Codex 运行方式","kind":"select","options":[{"value":"session","name":"会话模式"},{"value":"one-shot","name":"单次模式（当前版本不可运行）"}],"range":"session / one-shot","scope":"仅 Codex；Claude 始终使用会话模式。","when":"当前轮不变；更改后原会话下一轮会拒绝继续，需新建会话。","consequence":"会话模式保留连续对话；当前单次模式会明确拒绝运行，不会发给模型。不提供关闭会话身份核对的选项。","defaultValue":"session"},{"key":"acpMaxMessageBytes","name":"完整消息与工具输出容量（字节）","kind":"number","min":1,"max":9007199254740991,"range":"1～9007199254740991 的整数；0不能关闭上限","scope":"两位远程助手的完整会话消息；也用于模型目录、本机 MCP、员工执行 RPC 和工具输出容量。","when":"当轮快照不变；下一次独立目录查询读取新值；已有会话需新建后使用。","consequence":"调大可接收更大消息、占用更多内存；调小更早拒绝超限。超限明确停止，不截断、不自动重试；不能用0取消完整消息保护。","defaultValue":4194304},{"key":"brokerMaxFrameBytes","name":"主机会话回传单段容量（字节）","kind":"number","min":1,"max":9007199254740991,"range":"1～9007199254740991 的整数；0不能关闭上限","scope":"本插件接收主机会话单段输出的容量；不会替主机修改它自己的输出策略。","when":"当轮快照不变；更改后已有会话需新建。","consequence":"调大允许更大回传段、占用更多内存；调小可能拒绝主机合法输出。超限停止，不截断；不能关闭协议帧核验。","defaultValue":2097152},{"key":"brokerControlMaxBytes","name":"主机会话管理回复容量（字节）","kind":"number","min":1,"max":9007199254740991,"range":"1～9007199254740991 的整数；0不能关闭上限","scope":"主机会话管理命令的标准输出、标准错误各自容量；也用于本机执行桥的管理回复。","when":"当轮快照不变；更改后已有会话需新建。","consequence":"调大允许更长管理回复、占用更多内存；调小可能无法核实状态。超限明确停止，不能把不完整回复当成功；0不表示无限。","defaultValue":1048576},{"key":"oneShotSandbox","name":"Codex 单次任务权限模式","kind":"select","options":[{"value":"read-only","name":"只读"},{"value":"workspace-write","name":"工作区内可写"},{"value":"danger-full-access","name":"完全访问（高权限）"}],"range":"read-only / workspace-write / danger-full-access","scope":"仅 Codex 单次通道；不改变会话模式、本机工具或员工账号的系统权限。","when":"仅单次任务启动时适用；当前版本单次任务被拒绝，因此目前不生效。","consequence":"只读不允许单次任务写入；工作区内可写允许该目录写入；完全访问放宽单次沙箱。此项不是员工目录的权限开关，也不会解锁当前不可用的单次模式。","defaultValue":"workspace-write"},{"key":"oneShotApproval","name":"Codex 单次任务审批方式","kind":"fixed","readOnly":true,"range":"固定 never；不能切换","scope":"仅 Codex 单次通道；不改变会话模式的员工审批。","when":"仅单次启动参数；当前单次模式不可运行。","consequence":"单次通道没有中途交互审批能力，所以必须固定为无中途交互；不表示自动批准或允许所有操作。不能切换为自动回答旧审批。","defaultValue":"never"},{"key":"employeeShellKillGraceMs","name":"本机命令外层连接清理宽限（毫秒）","kind":"number","min":0,"max":2147483647,"range":"0～2147483647 的整数","scope":"仅 Claude 本机 Bash 取消后，本插件自己的外层 SSH 进程清理；不控制员工命令或 Codex 执行器。","when":"当轮快照不变；更改后已有会话需新建。","consequence":"大于0时先请求外层连接退出，再等待所设毫秒后强制清理；0表示不留宽限、立即强制清理外层连接，不是关闭取消。没有员工端退出确认时结果仍未知，不能据此自动重放或声称命令已停止。","defaultValue":1000}];
+  /* Public settings.plugins.tab + shared ConfigForms. No private client services. */
+function mountRuntimeSettings(ctx,React,fields){
+ const h=React.createElement;
+ const invariants=[
+  ['员工、主机和文件夹核对','始终开启，不可关闭','每次派发前核对当前连接、员工与工作区，避免操作到别人的文件或旧位置；核对失败即停止。'],
+  ['本轮输入与技术详情归属','始终开启，不可关闭','真实输入须先接纳，技术详情须确认保存；迟到结果仍属于原轮次，不能借下一轮的记录继续执行。'],
+  ['模型选择确认','始终开启，不可关闭','主机须完整确认所选模型和推理等级，不能静默换模型继续。'],
+  ['完整消息与精确整数','始终开启，不可关闭','容量不能用0关闭，超限明确停止、不截断；整数必须能精确表示，防止消息缺失或容量计算失真。'],
+  ['未知结果与旧审批保护','始终开启，不可关闭','断线或取消不等于员工命令已结束；不自动重放未知操作，不代答旧审批，清理未确认时不擅自重开。'],
+  ['本机执行位置','始终开启，不可关闭','已提供的本机工具通道不悄悄回退主机；文件夹不是权限隔离根，也不新增目录白名单。Claude子代理及内部直接调用尚未完整覆盖，可能仍在主机，每轮另有范围提示。']
+ ];
+ function Panel({form}){
+  const snapshot=React.useSyncExternalStore(fn=>form.subscribe(fn),()=>form.getSnapshot(),()=>form.getSnapshot());
+  const [draft,setDraft]=React.useState({}),[busy,setBusy]=React.useState(false),[notice,setNotice]=React.useState('');
+  const revision=React.useRef(undefined),saving=React.useRef(false),alive=React.useRef(true),prefix=React.useId();
+  React.useEffect(()=>{alive.current=true;return()=>{alive.current=false;};},[]);
+  const ready=snapshot.status==='ready',writable=ready&&snapshot.writable===true&&snapshot.mode==='host'&&snapshot.revision!==undefined;
+  const changed=Object.keys(draft).length>0,stale=changed&&revision.current!==snapshot.revision;
+  const edit=(key,value)=>{if(saving.current||!writable)return;if(!changed)revision.current=snapshot.revision;setDraft(previous=>({...previous,[key]:value}));setNotice('修改尚未保存。');};
+  const discard=()=>{if(saving.current)return;setDraft({});revision.current=undefined;setNotice('已放弃未保存修改，显示当前配置。');};
+  const save=async()=>{
+   if(saving.current||!writable||!changed||stale)return;
+   const ops=[];
+   for(const field of fields){const entry=draft[field.key];if(!entry)continue;
+    if(field.readOnly){setNotice('固定约束不能修改。');return;}
+    if(entry.op==='unset'){ops.push({op:'unset',path:[field.key]});continue;}
+    const raw=entry.value,value=field.kind==='number'?Number(raw):raw;
+    if(field.kind==='number'&&(String(raw).trim()===''||!Number.isSafeInteger(value)||value<field.min||value>field.max)||field.kind==='select'&&!field.options.some(option=>option.value===value)){setNotice(field.name+'的值不在所列范围内，未保存。');return;}
+    ops.push({op:'set',path:[field.key],value});
+   }
+   saving.current=true;setBusy(true);setNotice('正在保存，请稍候。');
+   try{
+    const accepted=await form.mutate(ops,revision.current);
+    if(!alive.current)return;
+    if(accepted===true){setDraft({});revision.current=undefined;setNotice('已保存。运行中的这一轮不变；请按各项生效说明使用新会话。');}
+    else setNotice('未保存：配置已变化或官方设置服务拒绝了修改。草稿已保留；核对当前值后可放弃草稿重新修改，不会自动重试。');
+   }catch{if(alive.current)setNotice('保存失败，草稿已保留。请检查连接及官方配置状态；不会自动重试。');}
+   finally{saving.current=false;if(alive.current)setBusy(false);}
+  };
+  const stateMessage=snapshot.mode!=='host'?'当前连接不提供持久配置写入，本页不能保存。':!ready?'尚未取得官方配置，当前不能修改。':!snapshot.writable?'当前配置由更高层覆盖或不可写，本页不能修改。':stale?'其他地方已更新配置；本页草稿保留。请放弃草稿后按最新值重新修改。':'';
+  return h('section',{'aria-label':'远程助手参数',style:{maxWidth:850}},
+   h('h2',null,'远程助手参数'),
+   h('p',null,'这些参数用于本客户端当前配置下的 Claude（远程主机）和 Codex（远程主机），不改变其他模型或主机账号权限。没有总开关；关闭整个插件请使用官方插件管理。'),
+   stateMessage&&h('p',{role:'status'},stateMessage),
+   h('form',{onSubmit:event=>{event.preventDefault();void save();}},
+    ...fields.map(field=>{
+     const entry=draft[field.key],accepted=ready?snapshot.value?.[field.key]:undefined;
+     const base=snapshot.base,hasBase=base!==null&&typeof base==='object'&&Object.hasOwn(base,field.key)&&base[field.key]!==undefined;
+     const value=entry?.op==='set'?entry.value:entry?.op==='unset'&&hasBase?base[field.key]:accepted;
+     const id=prefix+'-'+field.key,description=id+'-description';
+     const control=field.readOnly?h('p',{'aria-label':field.name+'当前值'},String(value??'尚未读取')+'（固定，不可切换）'):field.kind==='select'?h('select',{id,value:value??'',disabled:!writable||busy,'aria-describedby':description,onChange:event=>edit(field.key,{op:'set',value:event.target.value})},value===undefined&&h('option',{value:'',disabled:true},'尚未读取'),...field.options.map(option=>h('option',{key:option.value,value:option.value},option.name))):h('input',{id,type:'number',step:1,min:field.min,max:field.max,value:value??'',disabled:!writable||busy,'aria-describedby':description,onChange:event=>edit(field.key,{op:'set',value:event.target.value})});
+     return h('fieldset',{key:field.key,style:{marginBottom:18,padding:14,border:'1px solid currentColor',borderRadius:6}},
+      h('legend',null,field.name),h('label',{htmlFor:field.readOnly?undefined:id},field.name+'（'+field.key+'）'),
+      h('div',null,control),h('div',{id:description},
+       h('p',null,'默认值：'+field.defaultValue+'；范围：'+field.range),
+       h('p',null,'生效范围：'+field.scope),h('p',null,'生效时间：'+field.when),h('p',null,'调整或关闭的后果：'+field.consequence)),
+      entry?.op==='unset'&&h('p',null,hasBase?'将移除本项覆盖，恢复所示继承值；尚未保存。':'将移除本项覆盖；继承层未设此项，保存后由官方配置确定（默认值：'+field.defaultValue+'）。输入框仍显示保存前值，尚未保存。'),
+      !field.readOnly&&h('button',{type:'button',disabled:!writable||busy,onClick:()=>edit(field.key,{op:'unset'})},'恢复继承值：'+field.name));
+    }),
+    h('div',null,h('button',{type:'submit',disabled:!writable||!changed||busy||stale},busy?'正在保存…':'保存修改'),h('button',{type:'button',disabled:!changed||busy,onClick:discard},'放弃未保存修改'))),
+   h('p',{role:'status','aria-live':'polite'},notice),h('h3',null,'必须保持的正确性约束'),
+   h('p',null,'以下保护默认开启且不能关闭。关闭会使输入、审批、执行位置或记录失去可信归属，并非可以放宽的偏好。'),
+   h('dl',null,...invariants.flatMap(([name,state,why])=>[h('dt',{key:name},name+'：'+state),h('dd',{key:name+'-why'},why)])));
+ }
+ ctx.effect(()=>ctx.configForms.whileServed(['ai-workbench-codex'],()=>ctx.slots.inject('settings.plugins.tab',()=>ctx.slots.register({name:'settings.plugins.tab',id:'ai-workbench-remote-parameters',order:90,label:()=> '远程助手参数',inject:()=>({form:ctx.configForms.get('ai-workbench-codex')})},Panel))));
+}
+
   return{inject:['locale','connection'],apply(ctx){
+    ctx.inject(['slots','configForms'],settings=>mountRuntimeSettings(settings,require('react'),settingsFields));
     ctx.effect(()=>ctx.locale.register('ai-workbench-codex',messages),'Codex official translations');
     ctx.effect(()=>{
       let disposed=false,connected=false,previous,generation=0,request=new AbortController(),queue=Promise.resolve();

package/dist/conversation-details.d.ts

@@ -32,7 +32,6 @@ export type DetailSink = {
 /** Only objects created by this module are trusted as redaction markers. */
 export declare function isSanitizedRedaction(value: unknown): boolean;
 export declare function sanitizeDisplayLabel(value: string): string;
-/** Sanitize an internal observation without attaching any L wire semantics. */
 export declare function sanitizeObservation(observation: DetailObservation, protectModelMaterial?: boolean): Readonly<SanitizedObservation>;
 /** Internal diagnostic recorder; a sink is not an assertion that an L wire API exists. */
 export declare class ConversationDetails {

package/dist/conversation-details.js

@@ -303,6 +303,34 @@ function modelConfigurationStructure(value, level = 'root') {
     }));
 }
 /** Sanitize an internal observation without attaching any L wire semantics. */
+function contextTransitionStructure(value, history = false) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value) || isSanitizedRedaction(value))
+        return opaqueStructure(value);
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+        if (!history && key === 'history')
+            return [key, contextTransitionStructure(child, true)];
+        if (!history && typeof child === 'string' && (['oldSessionId', 'newSessionId'].includes(key) || (['oldContextSha256', 'newContextSha256'].includes(key) && /^[a-fA-F0-9]{64}$/u.test(child)) || (key === 'reason' && child === 'system-context-changed')))
+            return [key, child];
+        if (history && ((key === 'scope' && child === 'visible-user-assistant-text-and-images') || (key === 'reasoningOmissionReason' && child === 'dsh-internal-reasoning') || (['textBlocks', 'imageBlocks', 'offloadedImagePlaceholders', 'omittedReasoningBlocks'].includes(key) && typeof child === 'number' && Number.isSafeInteger(child) && child >= 0)))
+            return [key, child];
+        return [key, opaqueStructure(child)];
+    }));
+}
+function employeeStructure(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return opaqueStructure(value);
+    const strings = new Set(['executionId', 'workspaceId', 'bindingId', 'instanceId', 'deviceId', 'endpointInstanceId', 'executionContextId', 'bridgeInstanceId', 'cwd', 'hostCwd', 'remoteUser', 'operation', 'status', 'reason', 'source', 'claudeAcpVersion', 'sdkVersion']);
+    const numbers = new Set(['uid', 'pid', 'childPid', 'generation', 'epoch', 'device', 'inode', 'killGraceMs', 'maxBytes']);
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+        if (strings.has(key) && typeof child === 'string')
+            return [key, child];
+        if (numbers.has(key) && typeof child === 'number' && Number.isSafeInteger(child) && child >= 0)
+            return [key, child];
+        if (['supported', 'unsupported'].includes(key) && Array.isArray(child))
+            return [key, child.map(x => typeof x === 'string' ? x : opaqueStructure(x))];
+        return [key, opaqueStructure(child)];
+    }));
+}
 export function sanitizeObservation(observation, protectModelMaterial = false) {
     const payload = snapshotPayload(observation.payload, new Set(), protectModelMaterial && observation.kind !== 'commands');
     return freezeDeep({
@@ -310,13 +338,15 @@ export function sanitizeObservation(observation, protectModelMaterial = false) {
         code: sanitizeDisplayLabel(observation.code), summary: sanitizeDisplayLabel(observation.summary),
         ...(observation.method === undefined ? {} : { method: sanitizeDisplayLabel(observation.method) }),
         payload: !protectModelMaterial ? payload
-            : observation.kind === 'session' && ['MODEL_CONFIGURATION_CONFIRMED', 'MODEL_CONFIGURATION_FAILED'].includes(observation.code) ? modelConfigurationStructure(payload)
-                : observation.kind === 'commands' ? catalogStructure(payload)
-                    : observation.kind === 'usage' ? usageStructure(payload)
-                        : observation.kind === 'session' && observation.code === 'REMOTE_STAGE_TIMING' ? timingStructure(payload)
-                            : observation.kind === 'need' ? payload
-                                : observation.kind === 'tool' || ['SDK_ITEM', 'SDK_TOOL', 'ACP_SESSION_UPDATE', 'ACP_IDLE_UPDATE'].includes(observation.code) ? toolStructure(payload)
-                                    : opaqueStructure(payload),
+            : observation.kind === 'session' && observation.code === 'CODEX_CONTEXT_SESSION_REPLACED' ? contextTransitionStructure(payload)
+                : observation.kind === 'session' && ['MODEL_CONFIGURATION_CONFIRMED', 'MODEL_CONFIGURATION_FAILED'].includes(observation.code) ? modelConfigurationStructure(payload)
+                    : observation.kind === 'commands' ? catalogStructure(payload)
+                        : observation.kind === 'usage' ? usageStructure(payload)
+                            : observation.kind === 'session' && observation.code === 'REMOTE_STAGE_TIMING' ? timingStructure(payload)
+                                : observation.kind === 'session' && ['CLAUDE_EMPLOYEE_OPERATION', 'CLAUDE_EMPLOYEE_PROCESS', 'CLAUDE_EMPLOYEE_REVOKED', 'CLAUDE_EMPLOYEE_SCOPE'].includes(observation.code) ? employeeStructure(payload)
+                                    : observation.kind === 'need' ? payload
+                                        : observation.kind === 'tool' || ['SDK_ITEM', 'SDK_TOOL', 'ACP_SESSION_UPDATE', 'ACP_IDLE_UPDATE'].includes(observation.code) ? toolStructure(payload)
+                                            : opaqueStructure(payload),
     });
 }
 function validatedScope(scope) {