@ai-workbench/remote-agent 0.8.2 → 0.8.10

package/dist/acp.js

@@ -1,6 +1,11 @@
 import * as acp from '@agentclientprotocol/sdk/unstable';
 import { NeedError } from "./remote.js";
+import { employeeFailure } from "./presentation.js";
+import { StageTiming } from "./stage-timing.js";
+import { isolateRpcIds } from "./rpc-namespace.js";
+import { recoveryCapabilities, supportsCodexContextPolicy } from "./recovery.js";
 import { sanitizeObservation } from "./conversation-details.js";
+import { ModelConfiguration, ModelConfigurationError } from "./model-configuration.js";
 /** ACP v1 with explicitly negotiated SDK 2.0 lifecycle/context extensions. */
 export class AcpSession {
     connection;
@@ -16,35 +21,136 @@ export class AcpSession {
     updating = false;
     cwd;
     systemPrompt = '';
+    codexNewSessionOnly = false;
+    creatingReplacement = false;
+    employeeMeta;
+    employeeNegotiated = false;
+    configuration;
+    configRevision = 0;
+    selected;
+    selecting = false;
+    resolvedEvidence;
+    pendingConfigurations = new Map();
+    get modelConfiguration() { return this.configuration?.snapshot; }
+    get resolvedModelEvidence() { return this.resolvedEvidence; }
+    get models() { if (!this.configuration)
+        throw new ModelConfigurationError('远端没有提供完整配置列表'); return this.configuration.models; }
+    receiveConfiguration(options) {
+        this.configRevision++;
+        if (this.configuration)
+            this.configuration.update(options);
+        else
+            this.configuration = new ModelConfiguration(options, async (configId, value) => {
+                const result = await this.connection.agent.request(acp.methods.agent.session.setConfigOption, { sessionId: this.sessionId, configId, value }, { cancellationSignal: this.turnSignal });
+                if (this.resolvedEvidence && (this.configuration?.snapshot.model !== this.resolvedEvidence.modelValue || (configId === this.configuration?.snapshot.modelConfigId && value !== this.resolvedEvidence.modelValue)))
+                    this.resolvedEvidence = undefined;
+                this.hooks.broker?.acknowledge(acp.methods.agent.session.setConfigOption);
+                return result;
+            });
+        if (this.resolvedEvidence && this.configuration.snapshot.model !== this.resolvedEvidence.modelValue)
+            this.resolvedEvidence = undefined;
+    }
+    resetConfiguration() {
+        this.selected = undefined;
+        this.resolvedEvidence = undefined;
+        if (this.configuration) {
+            try {
+                this.receiveConfiguration([]);
+            }
+            catch { /* Invalidated until this lifecycle operation supplies new evidence. */ }
+        }
+        return this.configRevision;
+    }
+    lifecycleConfiguration(result, revision) {
+        const pending = this.pendingConfigurations.get(this.sessionId);
+        this.pendingConfigurations.clear();
+        if (pending)
+            this.receiveConfiguration(pending);
+        // A notification observed during the operation is newer than its in-flight response.
+        else if (this.configRevision === revision && result.configOptions)
+            this.receiveConfiguration(result.configOptions);
+        const model = this.configuration?.snapshot.model;
+        if (!pending && this.configRevision === revision + 1 && model && typeof result.models?.currentModelId === 'string' && result.models.currentModelId)
+            this.resolvedEvidence = { modelValue: model, resolvedModel: result.models.currentModelId };
+    }
+    async selectModel(model, effort, signal) {
+        if (!this.ready || !this.sessionId)
+            throw new ModelConfigurationError('远端会话尚未建立');
+        if (this.busy || this.updating || this.selecting)
+            throw new ModelConfigurationError('上一项会话操作尚未完成');
+        signal?.throwIfAborted();
+        this.checkReporting();
+        this.selecting = true;
+        this.selected = { model, ...(effort === undefined ? {} : { effort }) };
+        this.turnSignal = signal;
+        try {
+            if (!this.configuration)
+                throw new ModelConfigurationError('远端没有提供完整配置列表');
+            const state = await this.configuration.select(model, effort);
+            signal?.throwIfAborted();
+            this.checkReporting();
+            return state;
+        }
+        finally {
+            this.turnSignal = undefined;
+            this.selecting = false;
+        }
+    }
+    assertModelSelection(model, effort) {
+        if (!this.configuration)
+            throw new ModelConfigurationError('远端没有提供完整配置列表');
+        this.configuration.assertSelection(model, effort);
+    }
     reports = [];
     reportingFailure;
+    timing = new StageTiming();
+    stage(phase, operation) { return (this.hooks.timing ?? this.timing).run(phase, operation); }
     get diagnostics() { return this.reports.map(entry => sanitizeObservation(entry)); }
-    detail(observation) {
+    detail(observation, hooks = this.hooks) {
         const safe = sanitizeObservation(observation);
         this.reports.push(safe);
         try {
-            this.hooks.onDetail?.(safe);
+            hooks.onDetail?.(safe);
         }
         catch (cause) {
             this.reportingFailure ??= { cause };
             this.connection?.close();
         }
     }
-    need(need) {
-        this.detail({ kind: 'need', severity: 'action-required', code: need.code, summary: need.message, payload: { requires: need.requires } });
-        this.hooks.onNeed?.(need);
+    need(need, hooks = this.hooks) {
+        this.detail({ kind: 'need', severity: 'action-required', code: need.code, summary: need.message, payload: { requires: need.requires } }, hooks);
+        hooks.onNeed?.(need);
     }
     checkReporting() { if (this.reportingFailure)
         throw new NeedError('CONVERSATION_DETAILS_FAILED', '技术详情未能记录；本轮未继续发送', '可用的技术详情记录渠道'); }
     constructor(transport, hooks) {
         this.hooks = hooks;
+        this.timing.bind(detail => this.detail(detail));
         const app = acp.client({ name: '@ai-workbench/remote-agent' })
             .onNotification(acp.methods.client.session.update, ({ params: notification }) => {
+            if (this.creatingReplacement) {
+                if (notification.sessionId !== this.sessionId && notification.update.sessionUpdate === 'config_option_update')
+                    this.pendingConfigurations.set(notification.sessionId, notification.update.configOptions);
+                this.detail({ kind: 'session', severity: 'info', code: 'ACP_IDLE_UPDATE', summary: '新会话建立期间的轨迹，未作为正文处理', method: 'session/update', payload: notification });
+                return;
+            }
             if (this.sessionId && notification.sessionId !== this.sessionId) {
                 this.detail({ kind: 'session', severity: 'warning', code: 'ACP_FOREIGN_SESSION_UPDATE', summary: '收到不属于当前远端会话的通知，未作为正文处理', method: 'session/update', payload: notification });
                 return;
             }
             const meta = record(notification._meta);
+            if (notification.update.sessionUpdate === 'config_option_update') {
+                this.resolvedEvidence = undefined;
+                if (!this.sessionId)
+                    this.pendingConfigurations.set(notification.sessionId, notification.update.configOptions);
+                else
+                    try {
+                        this.receiveConfiguration(notification.update.configOptions);
+                    }
+                    catch (error) {
+                        this.detail({ kind: 'session', severity: 'action-required', code: 'MODEL_CONFIGURATION_INVALID', summary: '远端模型配置无效，本轮不可发送', method: 'session/update', payload: { reason: error instanceof ModelConfigurationError ? error.message : '配置无法解析' } });
+                    }
+            }
             if (meta && Object.keys(meta).length)
                 this.detail({ kind: 'extension', severity: 'info', code: 'ACP_NOTIFICATION_META', summary: '远端通知扩展', method: 'session/update', payload: notification._meta });
             if (this.busy) {
@@ -57,12 +163,14 @@ export class AcpSession {
                 this.detail({ kind: notification.update.sessionUpdate === 'available_commands_update' ? 'commands' : 'session', severity: 'info', code: 'ACP_IDLE_UPDATE', summary: '远端会话建立、恢复或空闲时的轨迹', method: 'session/update', payload: notification });
         })
             .onRequest(acp.methods.client.session.requestPermission, async ({ params: request, signal: rpcSignal, requestId }) => {
+            const hooks = this.hooks, detail = (value) => this.detail(value, hooks), need = (value) => this.need(value, hooks);
             if (request.sessionId !== this.sessionId || !this.busy || this.turnSignal?.aborted)
                 return { outcome: { outcome: 'cancelled' } };
-            this.hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
+            hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
             const toolName = request.toolCall.name ?? record(request.toolCall._meta?.claudeCode)?.toolName;
+            detail({ kind: 'tool', severity: 'info', code: 'ACP_PERMISSION_REQUEST', summary: '远端工具审批标识', method: 'session/request_permission', payload: { sessionId: request.sessionId, toolCall: { toolCallId: request.toolCall.toolCallId, ...(typeof toolName === 'string' ? { name: toolName } : {}) } } });
             if (toolName === 'AskUserQuestion') {
-                this.need({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问；已取消，未提交答案', requires: '可承载此提问的官方交互接口' });
+                need({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问；已取消，未提交答案', requires: '可承载此提问的官方交互接口' });
                 return { outcome: { outcome: 'cancelled' } };
             }
             const eligible = request.options.filter(option => {
@@ -70,11 +178,11 @@ export class AcpSession {
                 const sameKind = request.options.filter(candidate => candidate.kind === option.kind);
                 const unique = single && sameKind.length === 1 && request.options.filter(candidate => candidate.optionId === option.optionId).length === 1;
                 if (!unique)
-                    this.detail({ kind: 'tool', severity: 'info', code: 'APPROVAL_OPTION_NOT_OFFERED', summary: '此远端审批选项未映射到单次审批', method: 'session/request_permission', payload: option });
+                    detail({ kind: 'tool', severity: 'info', code: 'APPROVAL_OPTION_NOT_OFFERED', summary: '此远端审批选项未映射到单次审批', method: 'session/request_permission', payload: option });
                 return unique;
             });
             if (!eligible.length) {
-                this.need({ code: 'APPROVAL_OPTION_UNSUPPORTED', message: '远端没有可唯一映射的单次审批选项，此动作未获授权', requires: '唯一对应的允许一次或拒绝一次选项' });
+                need({ code: 'APPROVAL_OPTION_UNSUPPORTED', message: '远端没有可唯一映射的单次审批选项，此动作未获授权', requires: '唯一对应的允许一次或拒绝一次选项' });
                 return { outcome: { outcome: 'cancelled' } };
             }
             const presented = { ...request, options: eligible };
@@ -82,7 +190,7 @@ export class AcpSession {
             const id = this.sessionId;
             let outcome = 'unavailable';
             const approvalSignal = this.turnSignal ? AbortSignal.any([this.turnSignal, rpcSignal]) : rpcSignal;
-            const broker = this.hooks.broker;
+            const broker = hooks.broker;
             let generation;
             // A transport disconnect withdraws only the UI question, not the ACP RPC.
             // Late UI answers lose their lease; a fresh online attachment asks again.
@@ -96,7 +204,7 @@ export class AcpSession {
                     const abort = () => interrupted.resolve('cancelled');
                     signal.addEventListener('abort', abort, { once: true });
                     try {
-                        outcome = await Promise.race([this.hooks.approve?.(presented, signal) ?? Promise.resolve('unavailable'), interrupted.promise]);
+                        outcome = await Promise.race([hooks.approve?.(presented, signal) ?? Promise.resolve('unavailable'), interrupted.promise]);
                     }
                     finally {
                         signal.removeEventListener('abort', abort);
@@ -107,7 +215,7 @@ export class AcpSession {
                 }
             }
             catch {
-                this.need({ code: 'APPROVAL_FAILED', message: '审批渠道失败或连接已结束；此动作未获授权', requires: '可用的 DSH 审批渠道和原连接' });
+                need({ code: 'APPROVAL_FAILED', message: '审批渠道失败或连接已结束；此动作未获授权', requires: '可用的 DSH 审批渠道和原连接' });
             }
             const kind = outcome === 'allowed-once' ? 'allow_once' : outcome === 'rejected' ? 'reject_once' : undefined;
             const option = kind && eligible.find(item => item.kind === kind);
@@ -116,7 +224,7 @@ export class AcpSession {
                     broker.authorizeResponse(requestId, generation);
                 return { outcome: { outcome: 'selected', optionId: option.optionId } };
             }
-            this.need({ code: outcome === 'allowed-once' ? 'APPROVAL_OPTION_UNSUPPORTED' : 'APPROVAL_UNAVAILABLE',
+            need({ code: outcome === 'allowed-once' ? 'APPROVAL_OPTION_UNSUPPORTED' : 'APPROVAL_UNAVAILABLE',
                 message: '此动作未获授权；审批已取消、不可用或没有可映射的单次选项', requires: '本次动作的有效审批' });
             return { outcome: { outcome: 'cancelled' } };
         })
@@ -126,6 +234,20 @@ export class AcpSession {
         })
             .onNotification(acp.methods.client.elicitation.complete, () => {
             this.need({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问完成通知；未提交答案', requires: '可承载此提问的官方交互接口' });
+        })
+            .onRequest('_aw/employee-exec', (params) => params, async ({ params, signal }) => {
+            if (!this.employeeNegotiated || !this.employeeMeta || !this.hooks.employeeExecution)
+                throw new acp.RequestError(-32601, 'EMPLOYEE_EXECUTION_UNSUPPORTED');
+            try {
+                return await this.hooks.employeeExecution(params, signal);
+            }
+            catch (error) {
+                if (error instanceof NeedError) {
+                    this.need(error);
+                    throw new acp.RequestError(-32603, error.code);
+                }
+                throw error;
+            }
         })
             .onRequest('*', ({ method, params }) => {
             this.detail({ kind: 'extension', severity: 'action-required', code: 'ACP_UNKNOWN_REQUEST', summary: '未知远端交互请求未获授权', method, payload: params });
@@ -136,14 +258,14 @@ export class AcpSession {
             this.detail({ kind: 'extension', severity: 'warning', code: 'ACP_UNKNOWN_NOTIFICATION', summary: '收到未知远端扩展通知，已保留技术记录', method, payload: params });
         });
         if ('readable' in transport && 'writable' in transport)
-            this.connection = app.connect(this.observe(transport));
+            this.connection = app.connect(isolateRpcIds(this.observe(transport)));
         else {
             // Stable and unstable apps use distinct private symbols. Bridge only their
             // public stream interfaces so either SDK entry point remains supported.
             const outward = new TransformStream();
             const inward = new TransformStream();
             const peer = transport.connect({ readable: outward.readable, writable: inward.writable });
-            this.connection = app.connect(this.observe({ readable: inward.readable, writable: outward.writable }));
+            this.connection = app.connect(isolateRpcIds(this.observe({ readable: inward.readable, writable: outward.writable })));
             void this.connection.closed.then(() => peer.close());
             void peer.closed.then(() => this.connection.close());
         }
@@ -155,6 +277,13 @@ export class AcpSession {
                 const raw = record(message);
                 const params = record(raw?.params);
                 const update = record(params?.update);
+                if (raw)
+                    this.hooks.broker?.processedMessage(raw);
+                if (typeof raw?.method === 'string' && Object.hasOwn(raw, 'id') && this.hooks.broker && !this.hooks.broker.promptInFlight && !(raw.method === '_aw/employee-exec' && this.hooks.employeeExecution && this.employeeMeta)) {
+                    const error = new NeedError('RECOVERY_UNSAFE_OUTPUT', '主机会话有不属于当前输入的旧审批，未自动回答', '安全结束旧会话并新建');
+                    this.hooks.broker.fail(error);
+                    throw error;
+                }
                 if (raw?.method === acp.methods.client.session.update && typeof update?.sessionUpdate === 'string' && !knownUpdates.has(update.sessionUpdate)) {
                     this.detail({ kind: 'extension', severity: 'warning', code: 'ACP_UNKNOWN_UPDATE', summary: '收到未知远端会话事件，已保留结构', method: 'session/update', payload: params });
                     return;
@@ -166,6 +295,35 @@ export class AcpSession {
     get id() { return this.sessionId; }
     get capabilities() { return this.negotiated; }
     get startMethod() { return this.method; }
+    get checkpoint() { return this.ready && !this.busy && !this.updating && !this.selecting && this.sessionId ? { sessionId: this.sessionId, capabilities: recoveryCapabilities(this.negotiated), ...(this.configuration ? { modelConfiguration: { configOptions: JSON.parse(JSON.stringify(this.configuration.snapshot.configOptions)), ...(this.resolvedEvidence ? { resolvedEvidence: { ...this.resolvedEvidence } } : {}) } } : {}) } : undefined; }
+    restore(cwd, saved, context, verifiedSameContext = false) {
+        if (context.employeeRouting)
+            throw new NeedError('EMPLOYEE_CHECKPOINT_STALE', '本机工具通道需要重新建立，旧审批没有代答。', '按原主机实例安全结束后新建本机会话');
+        if (this.startAttempted)
+            throw new NeedError('SESSION_ALREADY_STARTED', '此客户端已建立会话', '新的客户端连接');
+        this.startAttempted = true;
+        this.sessionId = saved.sessionId;
+        this.negotiated = recoveryCapabilities(saved.capabilities);
+        this.cwd = cwd;
+        this.systemPrompt = context.systemPrompt ?? '';
+        this.codexNewSessionOnly = !!context.codexNewSessionOnly;
+        // A verified same-context reattach does not create or update native context.
+        // Old journals may lack new-only metadata; never manufacture it for them.
+        if (this.codexNewSessionOnly && !verifiedSameContext)
+            this.validateNewContext(this.systemPrompt, context.systemPrompt !== undefined);
+        if (saved.modelConfiguration) {
+            this.receiveConfiguration(saved.modelConfiguration.configOptions);
+            this.resolvedEvidence = saved.modelConfiguration.resolvedEvidence;
+            for (const update of saved.configUpdates ?? []) {
+                this.resolvedEvidence = undefined;
+                this.receiveConfiguration(update);
+            }
+        }
+        this.hooks.broker?.finishRecovery();
+        this.detail({ kind: 'need', severity: 'info', code: 'ACP_CLIENT_REATTACHED', summary: '已接回原模型会话', payload: { sessionId: saved.sessionId } });
+        this.checkReporting();
+        this.ready = true;
+    }
     validatePrompt(prompt) {
         const capability = this.negotiated.promptCapabilities;
         for (const block of prompt)
@@ -175,55 +333,86 @@ export class AcpSession {
     validateContext(context) {
         if ((context.systemPrompt ?? '') === this.systemPrompt)
             return;
+        if (this.codexNewSessionOnly)
+            throw new NeedError('SYSTEM_PROMPT_NEW_SESSION_REQUIRED', 'Codex会话要求已变化，需要保留原会话并新建会话承接', '新会话及完整公开历史承接');
         if (!this.negotiated.sessionCapabilities?.systemPrompt)
             throw new NeedError('SYSTEM_PROMPT_UNSUPPORTED', '远端未声明系统与开发者上下文更新能力，不能丢弃这些要求继续', '支持 systemPrompt 的公开 ACP 能力');
         if (!this.negotiated.sessionCapabilities?.resume && !this.negotiated.loadSession)
             throw new NeedError('SYSTEM_PROMPT_UPDATE_UNSUPPORTED', '远端没有可更新原会话上下文的恢复或加载能力', '支持带 systemPrompt 的 session/resume 或 session/load');
     }
+    validateNewSessionContext(context) {
+        if (!this.codexNewSessionOnly)
+            throw new NeedError('SYSTEM_PROMPT_POLICY_UNSUPPORTED', '此会话没有使用Codex新建政策', 'Codex新建政策');
+        this.validateNewContext(context.systemPrompt ?? '', true);
+    }
     setHooks(hooks) {
-        if (this.busy || this.updating)
-            throw new NeedError('TURN_BUSY', '上一轮或上下文更新结束前不能更换会话钩子', '上一轮结束');
+        if (this.busy || this.updating || this.selecting)
+            throw new NeedError('TURN_BUSY', '上一轮或配置更新结束前不能更换会话钩子', '上一轮结束');
         this.hooks = hooks;
     }
     get closed() { return this.connection.closed; }
-    async start(cwd, resumeId, signal, context) {
+    validateNewContext(text, requirePolicy = false) {
+        if ((text || requirePolicy) && !this.negotiated.sessionCapabilities?.systemPrompt)
+            throw new NeedError('SYSTEM_PROMPT_UNSUPPORTED', '远端未声明系统与开发者上下文能力，不能丢弃这些要求继续', '支持 systemPrompt 的公开 ACP 能力');
+        if (this.codexNewSessionOnly && (text || requirePolicy)) {
+            if (!supportsCodexContextPolicy(this.negotiated))
+                throw new NeedError('SYSTEM_PROMPT_POLICY_UNSUPPORTED', '远端没有明确声明Codex上下文仅新建生效的兼容政策，本轮未发送', 'systemPrompt与精确的aiWorkbenchSystemPrompt新建政策');
+        }
+    }
+    async start(cwd, resumeId, signal, context, prompt) {
         if (this.startAttempted)
             throw new NeedError('SESSION_ALREADY_STARTED', '此连接已用于建立会话，不能转用工作区或身份', '新的独立远端连接');
         this.startAttempted = true;
+        this.employeeMeta = context?.employeeExecution;
         const abort = () => this.connection.close(new NeedError('ABORTED', '会话建立已取消', '重新连接主机'));
         signal?.throwIfAborted();
         signal?.addEventListener('abort', abort, { once: true });
         try {
-            const hello = await this.connection.agent.request(acp.methods.agent.initialize, {
-                protocolVersion: acp.PROTOCOL_VERSION, clientInfo: { name: '@ai-workbench/remote-agent', version: '0.8.1' },
-                clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false, session: { notices: {} } },
-            }, { cancellationSignal: signal });
+            const hello = await this.stage('acp-initialize', () => this.connection.agent.request(acp.methods.agent.initialize, {
+                protocolVersion: acp.PROTOCOL_VERSION, clientInfo: { name: '@ai-workbench/remote-agent', version: '0.8.10' },
+                clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false, session: { notices: {} }, ...(this.employeeMeta ? { _meta: { awEmployeeExecution: { version: 1 } } } : {}) },
+            }, { cancellationSignal: signal }));
             this.hooks.broker?.acknowledge(acp.methods.agent.initialize);
             if (hello.protocolVersion !== acp.PROTOCOL_VERSION)
                 throw new NeedError('ACP_VERSION_MISMATCH', 'ACP 协议版本不兼容', '支持 ACP v1 的远端 agent');
             this.checkReporting();
             this.negotiated = hello.agentCapabilities ?? {};
-            const systemPrompt = context?.systemPrompt;
-            if (systemPrompt && !this.negotiated.sessionCapabilities?.systemPrompt) {
-                throw new NeedError('SYSTEM_PROMPT_UNSUPPORTED', '远端未声明系统与开发者上下文能力，不能丢弃这些要求继续', '支持 systemPrompt 的公开 ACP 能力');
+            if (this.employeeMeta) {
+                const policy = record(hello._meta?.awEmployeeExecution);
+                if (!this.hooks.employeeExecution || !policy || Object.keys(policy).length !== 5 || policy.version !== 1 || policy.nativeCliVersion !== '0.160.1' || policy.native !== true || policy.perRpcGate !== true || policy.noHostFallback !== true)
+                    throw new NeedError('EMPLOYEE_EXECUTION_UNSUPPORTED', '当前主机尚不支持在你的电脑执行Codex原生工具，本轮没有执行。', 'Codex员工端原生执行适配器与明确能力声明');
+                this.employeeNegotiated = true;
+                this.detail({ kind: 'session', severity: 'info', code: 'EMPLOYEE_EXECUTION_SELECTED', summary: '文件和命令在员工电脑的选定目录执行，Git使用本机仓库；模型、登录和全局助手要求仍在主机。本机MCP、hooks、plugins、冷恢复、快捷命令和主机文件报告尚不支持。外层ACP冷恢复已拒绝；原生子代理回收/缺少存活父会话时的恢复仅做源码检查，未实测。', payload: { bindingId: this.employeeMeta.bindingId, workspaceId: this.employeeMeta.workspaceId, cwd: this.employeeMeta.cwd, nativeCliVersion: '0.160.1', noHostFallback: true, agentConfigSource: 'host CODEX_HOME', unsupportedLocalFeatures: ['mcp', 'hooks', 'plugins', 'cold-resume', 'slash-commands', 'host-file-reports'] } });
             }
-            const params = { cwd, mcpServers: [], ...(systemPrompt ? { systemPrompt: { mode: 'append', content: [{ type: 'text', text: systemPrompt }] } } : {}) };
+            const systemPrompt = context?.systemPrompt;
+            this.codexNewSessionOnly = !!context?.codexNewSessionOnly;
+            this.validateNewContext(systemPrompt ?? '', this.codexNewSessionOnly && systemPrompt !== undefined);
+            if (prompt)
+                this.validatePrompt(prompt);
+            if (context?.employeeRouting && resumeId)
+                throw new NeedError('EMPLOYEE_CHECKPOINT_STALE', '本机工具连接已变化，不能沿用旧会话。', '安全结束原主机实例并重新建立本机工具通道');
+            const routing = context?.employeeRouting;
+            const params = { cwd, mcpServers: routing ? structuredClone(routing.mcpServers) : [], ...((routing || this.employeeMeta) ? { _meta: { ...(this.employeeMeta ? { awEmployeeExecution: this.employeeMeta } : {}), ...(routing ? { claudeCode: { options: { toolAliases: structuredClone(routing.toolAliases) } } } : {}) } } : {}), ...(systemPrompt && !(resumeId && this.codexNewSessionOnly) ? { systemPrompt: { mode: 'append', content: [{ type: 'text', text: systemPrompt }] } } : {}) };
+            const configRevision = this.resetConfiguration();
             if (resumeId) {
                 this.sessionId = resumeId;
                 if (this.negotiated.sessionCapabilities?.resume) {
-                    await this.connection.agent.request(acp.methods.agent.session.resume, { ...params, sessionId: resumeId }, { cancellationSignal: signal });
+                    const result = await this.stage('acp-session-resume', () => this.connection.agent.request(acp.methods.agent.session.resume, { ...params, sessionId: resumeId }, { cancellationSignal: signal }));
+                    this.lifecycleConfiguration(result, configRevision);
                     this.method = acp.methods.agent.session.resume;
                 }
                 else {
                     if (!this.negotiated.loadSession)
                         throw new NeedError('RESUME_UNSUPPORTED', '远端未声明会话恢复或加载能力，不能恢复原会话', '支持 session/resume 或 session/load 的 agent');
-                    await this.connection.agent.request(acp.methods.agent.session.load, { ...params, sessionId: resumeId }, { cancellationSignal: signal });
+                    const result = await this.stage('acp-session-load', () => this.connection.agent.request(acp.methods.agent.session.load, { ...params, sessionId: resumeId }, { cancellationSignal: signal }));
+                    this.lifecycleConfiguration(result, configRevision);
                     this.method = acp.methods.agent.session.load;
                 }
             }
             else {
-                const result = await this.connection.agent.request(acp.methods.agent.session.new, params, { cancellationSignal: signal });
+                const result = await this.stage('acp-session-new', () => this.connection.agent.request(acp.methods.agent.session.new, params, { cancellationSignal: signal }));
                 this.sessionId = result.sessionId;
+                this.lifecycleConfiguration(result, configRevision);
                 this.method = acp.methods.agent.session.new;
             }
             this.hooks.broker?.acknowledge(this.method);
@@ -236,10 +425,59 @@ export class AcpSession {
         catch (error) {
             if (signal?.aborted)
                 throw new NeedError('ABORTED', '会话建立已取消；尚无本轮输出', '重新连接主机');
+            if (error instanceof ModelConfigurationError) {
+                this.checkReporting();
+                throw error;
+            }
+            this.checkReporting();
+            throw acpNeed(error);
+        }
+        finally {
+            signal?.removeEventListener('abort', abort);
+        }
+    }
+    /** Codex context is immutable after creation; keep the old remote session intact. */
+    async newContextSession(context, signal) {
+        this.checkReporting();
+        if (!this.ready || !this.sessionId || !this.cwd)
+            throw new NeedError('SESSION_REQUIRED', '我需要先建立远端会话', 'ACP 会话');
+        if (!this.codexNewSessionOnly)
+            throw new NeedError('SYSTEM_PROMPT_POLICY_UNSUPPORTED', '此会话没有使用Codex新建政策', 'Codex新建政策');
+        if (this.busy || this.updating || this.selecting)
+            throw new NeedError('TURN_BUSY', '上一项会话操作尚未完成', '上一项操作结束');
+        const text = context.systemPrompt ?? '';
+        this.validateNewSessionContext(context);
+        signal?.throwIfAborted();
+        const oldId = this.sessionId;
+        this.updating = true;
+        this.ready = false;
+        this.creatingReplacement = true;
+        this.pendingConfigurations.clear();
+        const abort = () => this.connection.close(new NeedError('ABORTED', '新会话建立已取消，远端状态需确认', '管理员核对远端状态'));
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+            const revision = this.resetConfiguration();
+            const result = await this.stage('acp-session-new', () => this.connection.agent.request(acp.methods.agent.session.new, { cwd: this.cwd, mcpServers: [], ...(this.employeeMeta ? { _meta: { awEmployeeExecution: this.employeeMeta } } : {}), ...(text ? { systemPrompt: { mode: 'append', content: [{ type: 'text', text }] } } : {}) }, { cancellationSignal: signal }));
+            if (!result.sessionId || result.sessionId === oldId)
+                throw new NeedError('SESSION_STATE_INVALID', '新会话没有返回独立的远端标识，原会话状态需确认', '独立的新远端会话标识');
+            this.sessionId = result.sessionId;
+            this.lifecycleConfiguration(result, revision);
+            this.hooks.broker?.acknowledge(acp.methods.agent.session.new);
+            this.checkReporting();
+            this.systemPrompt = text;
+            this.method = acp.methods.agent.session.new;
+            this.ready = true;
+            return this.sessionId;
+        }
+        catch (error) {
             this.checkReporting();
+            if (error instanceof ModelConfigurationError)
+                throw error;
             throw acpNeed(error);
         }
         finally {
+            this.creatingReplacement = false;
+            this.updating = false;
             signal?.removeEventListener('abort', abort);
         }
     }
@@ -247,8 +485,8 @@ export class AcpSession {
         this.checkReporting();
         if (!this.ready || !this.sessionId || !this.cwd)
             throw new NeedError('SESSION_REQUIRED', '我需要先建立远端会话', 'ACP 会话');
-        if (this.busy || this.updating)
-            throw new NeedError('TURN_BUSY', '此远端会话正在处理上一轮或更新上下文', '上一轮结束');
+        if (this.busy || this.updating || this.selecting)
+            throw new NeedError('TURN_BUSY', '此远端会话正在处理上一轮或更新配置', '上一轮结束');
         const text = context.systemPrompt ?? '';
         if (text === this.systemPrompt)
             return undefined;
@@ -262,7 +500,9 @@ export class AcpSession {
         try {
             const method = resume ? acp.methods.agent.session.resume : acp.methods.agent.session.load;
             const params = { sessionId: this.sessionId, cwd: this.cwd, mcpServers: [], systemPrompt: { mode: 'append', content: [{ type: 'text', text }] } };
-            await this.connection.agent.request(method, params, { cancellationSignal: signal });
+            const configRevision = this.resetConfiguration();
+            const result = await this.stage(resume ? 'acp-session-resume' : 'acp-session-load', () => this.connection.agent.request(method, params, { cancellationSignal: signal }));
+            this.lifecycleConfiguration(result, configRevision);
             this.hooks.broker?.acknowledge(method);
             this.systemPrompt = text;
             this.ready = true;
@@ -273,6 +513,10 @@ export class AcpSession {
         catch (error) {
             if (signal?.aborted)
                 throw new NeedError('ABORTED', '上下文更新已取消；原会话状态需确认', '重新连接原会话');
+            if (error instanceof ModelConfigurationError) {
+                this.checkReporting();
+                throw error;
+            }
             this.checkReporting();
             throw acpNeed(error);
         }
@@ -284,12 +528,14 @@ export class AcpSession {
     async prompt(input, signal) {
         if (!this.ready || !this.sessionId)
             throw new NeedError('SESSION_REQUIRED', '我需要先建立远端会话', 'ACP 会话');
-        if (this.busy || this.updating)
-            throw new NeedError('TURN_BUSY', '此远端会话正在处理上一轮', '上一轮结束');
+        if (this.busy || this.updating || this.selecting)
+            throw new NeedError('TURN_BUSY', '此远端会话正在处理上一轮或更新配置', '上一轮结束');
         signal?.throwIfAborted();
         const prompt = typeof input === 'string' ? [{ type: 'text', text: input }] : input;
         this.validatePrompt(prompt);
         this.checkReporting();
+        if (this.selected)
+            this.assertModelSelection(this.selected.model, this.selected.effort);
         this.busy = true;
         this.turnSignal = signal;
         this.turnToken = Symbol('turn');
@@ -303,8 +549,10 @@ export class AcpSession {
         };
         signal?.addEventListener('abort', cancel, { once: true });
         try {
-            const request = this.connection.agent.request(acp.methods.agent.session.prompt, { sessionId: this.sessionId, prompt }, { cancellationSignal: signal });
-            const result = await (signal ? Promise.race([request, interrupted]) : request);
+            const result = await this.stage('acp-prompt', () => {
+                const request = this.connection.agent.request(acp.methods.agent.session.prompt, { sessionId: this.sessionId, prompt }, { cancellationSignal: signal });
+                return signal ? Promise.race([request, interrupted]) : request;
+            });
             this.hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
             signal?.throwIfAborted();
             this.hooks.broker?.completePrompt();
@@ -330,6 +578,17 @@ export class AcpSession {
 export function acpNeed(error) {
     if (error instanceof NeedError)
         return error;
+    if (error instanceof acp.RequestError) {
+        // Host SDK1.9 uses Internal error + data.details for thrown adapter errors.
+        // Only fixed codes cross this boundary; arbitrary detail strings are never copied.
+        for (const value of [error.message, record(error.data)?.details]) {
+            if (typeof value !== 'string')
+                continue;
+            const code = value.split(':', 1)[0];
+            if (employeeAdapterCodes.has(code))
+                return new NeedError(code, employeeFailure(code), `员工电脑执行适配器明确拒绝：${code}；RPC 错误码 ${error.code}`);
+        }
+    }
     if (error instanceof acp.RequestError && error.code === -32000)
         return new NeedError('LOGIN_REQUIRED', '需要登录，请到设置 → 远程主机连接 点登录', '该员工自己的远端模型登录');
     if (error instanceof acp.RequestError)
@@ -339,3 +598,4 @@ export function acpNeed(error) {
 function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined; }
 const knownUpdates = new Set(['user_message_chunk', 'agent_message_chunk', 'agent_thought_chunk', 'tool_call', 'tool_call_update', 'plan', 'plan_update', 'plan_removed', 'available_commands_update', 'current_mode_update', 'config_option_update', 'session_info_update', 'usage_update', 'notice', 'compaction_update', 'compaction_summary_chunk', 'subagent_update', 'session_message', 'session_message_chunk']);
 function safeLabel(value) { return value.replaceAll(/[\r\n\x00-\x1f\x7f]/g, ' '); }
+const employeeAdapterCodes = new Set(["AW_EMPLOYEE_ADDITIONAL_DIRECTORIES_UNSUPPORTED", "AW_EMPLOYEE_SLASH_COMMAND_UNSUPPORTED", "AW_EMPLOYEE_HOST_FILE_REPORT_UNSUPPORTED", "AW_EMPLOYEE_CONFIG_DISCOVERY_OVERRIDE_UNSUPPORTED", "AW_EMPLOYEE_CONFIG_ADMISSION_INVALID", "AW_EMPLOYEE_CONFIG_ADMISSION_FAILED", "AW_EMPLOYEE_HOST_PROJECT_CONFIG_UNSUPPORTED", "AW_EMPLOYEE_EXECUTOR_MCP_UNSUPPORTED", "AW_EMPLOYEE_EXECUTOR_CONFIG_PROTOCOL_INVALID", "AW_EMPLOYEE_EXECUTOR_CONFIG_READ_FAILED", "AW_EMPLOYEE_AGENT_CONFIG_UNAVAILABLE", "AW_EMPLOYEE_BINDING_INVALID", "AW_EMPLOYEE_BINDING_MISMATCH", "AW_EMPLOYEE_CAPABILITY_REQUIRED", "AW_EMPLOYEE_CLOSE_FAILED", "AW_EMPLOYEE_CLOSE_RESPONSE_INVALID", "AW_EMPLOYEE_COLD_RESUME_UNSUPPORTED", "AW_EMPLOYEE_CWD_MISMATCH", "AW_EMPLOYEE_ENVIRONMENT_REGISTRATION_FAILED", "AW_EMPLOYEE_ENVIRONMENT_REQUIRED", "AW_EMPLOYEE_EXECUTION_CLOSED", "AW_EMPLOYEE_EXECUTION_ID_REQUIRED", "AW_EMPLOYEE_HOST_AUXILIARY_CONFIG_UNSUPPORTED", "AW_EMPLOYEE_HOST_AUXILIARY_UNSUPPORTED", "AW_EMPLOYEE_HOST_FALLBACK_FORBIDDEN", "AW_EMPLOYEE_MCP_UNSUPPORTED", "AW_EMPLOYEE_MESSAGE_INVALID", "AW_EMPLOYEE_MESSAGE_TOO_LARGE", "AW_EMPLOYEE_OPEN_RESPONSE_INVALID", "AW_EMPLOYEE_READ_MESSAGE_INVALID", "AW_EMPLOYEE_READ_RESPONSE_INVALID", "AW_EMPLOYEE_RELAY_ADDRESS_INVALID", "AW_EMPLOYEE_RELAY_FAILED", "AW_EMPLOYEE_REQUEST_INVALID", "AW_EMPLOYEE_SESSION_UNKNOWN", "AW_EMPLOYEE_WIRE_FAILED", "AW_EMPLOYEE_WRITE_RESPONSE_INVALID"]);

package/dist/approval-label.d.ts

@@ -0,0 +1,6 @@
+import type { RequestPermissionRequest } from '@agentclientprotocol/sdk/unstable';
+/** ACP diff.oldText=null means a new file. Write alone may overwrite a file. */
+export declare function approvalLabel(request: RequestPermissionRequest, location?: 'host' | 'local'): {
+    toolName: string;
+    reason: string;
+} | undefined;

package/dist/approval-label.js

@@ -0,0 +1,57 @@
+import { sanitizeDisplayLabel } from "./conversation-details.js";
+function display(value) {
+    const safe = sanitizeDisplayLabel(sanitizeDisplayLabel(value).replace(/[\u202a-\u202e\u2066-\u2069]/g, '')).trim();
+    // Redacted instructions/targets cannot support an informed approval.
+    return safe && !safe.includes('[已脱敏：') ? safe : undefined;
+}
+/** ACP diff.oldText=null means a new file. Write alone may overwrite a file. */
+export function approvalLabel(request, location = 'host') {
+    const tool = request.toolCall;
+    const diffs = tool.content?.filter(item => item.type === 'diff') ?? [];
+    const originalName = tool.name ?? tool._meta?.claudeCode?.toolName ?? /^(Write|Edit|MultiEdit) /.exec(tool.title ?? '')?.[1];
+    const employee = location === 'local' && originalName?.startsWith('mcp__employee__');
+    const name = employee ? originalName.slice('mcp__employee__'.length) : originalName;
+    const fileAction = diffs.length > 0 || name === 'Write' || name === 'Edit' || name === 'MultiEdit';
+    const paths = diffs.length ? diffs.map(diff => diff.path) : tool.locations?.map(location => location.path) ?? [];
+    let title = tool.title ?? '';
+    const raw = employee && tool.rawInput && typeof tool.rawInput === 'object' && !Array.isArray(tool.rawInput) ? tool.rawInput : undefined;
+    if (employee && raw) {
+        if ((fileAction || name === 'Read') && !paths.length && typeof raw.file_path === 'string')
+            paths.push(raw.file_path);
+        if ((name === 'Glob' || name === 'Grep') && !paths.length)
+            paths.push(typeof raw.path === 'string' ? raw.path : '当前文件夹');
+        title = typeof raw.description === 'string' ? raw.description : typeof raw.command === 'string' ? raw.command : '';
+        if ((name === 'Glob' || name === 'Grep') && typeof raw.pattern === 'string')
+            title = raw.pattern;
+    }
+    if (name && title.startsWith(name + ' '))
+        title = title.slice(name.length + 1);
+    else if (title === name || title === tool.toolCallId)
+        title = '';
+    if (fileAction) {
+        const action = diffs.length && diffs.every(diff => diff.oldText === null) ? '新建文件'
+            : (diffs.length && diffs.every(diff => typeof diff.oldText === 'string')) || name === 'Edit' || name === 'MultiEdit' ? '修改文件' : '写入文件';
+        // Observed Write/Edit title is a display hint, never used as a host path.
+        if (!paths.length && name && ['Write', 'Edit', 'MultiEdit'].includes(name) && title)
+            paths.push(title);
+        const unique = [...new Set(paths)];
+        const safe = unique.map(display);
+        if (!safe.length || safe.some(path => path === undefined) || new Set(safe).size !== safe.length)
+            return;
+        const names = safe.map(path => path.split(/[\\/]/).at(-1)?.trim());
+        if (names.some(name => !name))
+            return;
+        const files = safe.map((path, index) => names.filter(name => name === names[index]).length > 1 ? path : names[index]);
+        return { toolName: action, reason: action + ' ' + files.join('、') };
+    }
+    const action = (employee ? { Read: '读取文件', Glob: '查找文件', Grep: '搜索内容', Bash: '执行本机命令' }[name] : undefined) ?? { read: '读取文件', edit: '修改文件', delete: '删除文件', move: '移动文件', search: '搜索', execute: employee ? '执行本机命令' : '执行主机命令', think: '分析', fetch: '获取内容', other: '远程操作' }[tool.kind ?? ''] ?? '远程操作';
+    const safePaths = paths.map(display);
+    if (safePaths.some(path => path === undefined))
+        return;
+    const description = title ? display(title) : undefined;
+    if (title && !description)
+        return;
+    if (!safePaths.length && !description)
+        return;
+    return { toolName: action, reason: action + (safePaths.length ? ' ' + safePaths.join('、') : '') + (description ? '：' + description : '') };
+}

package/dist/broker-runtime.d.ts

@@ -0,0 +1,10 @@
+import { type SshArgv, type BrokerIo, type BrokerSettings } from './broker.ts';
+import { type ConnectApi, type ConnectTarget, type Project, type Runtime, type RuntimeRequest } from './provider.ts';
+import type { Interaction } from './interaction.ts';
+import { type RecoveryJournal } from './recovery.ts';
+/** Test ports are explicit; deployed code always supplies the official-profile journal. */
+export declare function brokerFactory(get: () => ConnectApi | undefined, _ask: Interaction | undefined, configuration: BrokerSettings | (() => BrokerSettings), provided?: {
+    argv?: SshArgv;
+    io?: (target: ConnectTarget) => BrokerIo;
+    journal?: (key: string) => RecoveryJournal;
+}): (target: ConnectTarget, project: Project, initialRequest: RuntimeRequest) => Promise<Runtime>;