@ai-workbench/remote-agent 0.8.1 → 0.8.5

package/README.md

@@ -1,14 +1,14 @@
-在 DSH「插件 → 添加插件」填 `@ai-workbench/remote-agent@0.8.1`（由编排发布后可用），或运行 `dsh plugin --profile desktop add @ai-workbench/remote-agent@0.8.1`。
+在 DSH「插件 → 添加插件」填 `@ai-workbench/remote-agent@0.8.5`（由编排发布后可用）；交付前可由官方插件管理安装固定 tgz。
 
 # 远程ACP插件
 
 一个插件提供 **Claude（远程主机）** 和 **Codex（远程主机）**，通过员工主机上的官方CLI运行。Codex保留单次模式；Claude固定会话模式。只用官方模型列表、插件管理和配置入口，不提供自制面板、问答或登录按钮。登录和原生工作区绑定唯一归连接插件L。
 
-本轮为公开npm发布准备版0.8.0，包名采用`@ai-workbench/remote-agent`以涵盖两个品牌；发布前自测从固定tgz绝对路径安装。X仅准备，不执行实际发布，编排统一发布后才可按包名安装。正式L0.7.0已交付；开发fixture逐字节保留其固定包，公开类型与SSH导出从该包消费。运行时仍要求L的`getContractInfo()`同时返回API0.7.0、implemented、native-local-v1；旧L包、draft.3或只有版本号的候选会明确报缺项。依赖范围为`~0.7.0`，L由官方插件管理单独安装，不打进X。组件验证不代表真实开通、模型或leo E通过；HanaMesh另验。
+当前为公开npm发布准备版0.8.5，包名采用`@ai-workbench/remote-agent`以涵盖两个品牌；发布前自测从固定tgz绝对路径安装。X仅准备，不执行实际发布，编排统一发布后才可按包名安装。开发fixture逐字节保留L0.7.13固定包，公开类型与SSH导出从该包消费。运行时仍要求L的`getContractInfo()`同时返回API0.7.0、implemented、native-local-v1；旧L包、draft.3或只有版本号的候选会明确报缺项。依赖范围为`~0.7.13`，L由官方插件管理单独安装，不打进X。组件验证不代表真实开通、模型或leo E通过；HanaMesh另验。
 
 ## 员工路径
 
-从官方插件管理安装，照常使用默认工作区/会话/模型入口。原生添加或选择本机工作区后，首次实际使用远程模型由L建立/绑定同名远端工作区。本地文件不自动上传，X不猜目录、不选首项。首次说明使用官方普通回复；先经官方会话提交、持久化并读回核对，才向L确认。持久记录不等于员工已看见，GUI另验；日志丢失后的未知claim由L保留，不宣称端到端恰好一次。
+从官方插件管理安装，照常使用默认工作区/会话/模型入口。L0.7.13沿唯一“远程主机连接”设置节记录文件来源；本统一版X只继续L已明确确认的legacy同名远端映射。旧映射需在L逐工作区确认，本地或新主机位置仍为pending，分别由L明确停止为WORKSPACE_EXECUTION_UNAVAILABLE/WORKSPACE_LOCATION_PROVIDER_REQUIRED，不退回同名目录或主机代跑。D20新执行位置尚未接通。本地文件不自动上传，X不猜目录、不选首项。首次说明使用官方普通回复；先经官方会话提交、持久化并读回核对，才向L确认。持久记录不等于员工已看见，GUI另验；日志丢失后的未知claim由L保留，不宣称端到端恰好一次。
 
 未登录时两个模型均回复：**需要登录，请到设置 → 远程主机连接 点登录**。无L或缺正式能力时直接说明缺项，不让员工填写主机、用户、路径或密钥。
 
@@ -56,4 +56,19 @@ Codex单次模式首版仅文本，不转接中途审批；图片或系统/开
 
 D19（0.8.1）：相邻正文增量合成连续文本块，工作区首次说明合入真实回复，按官方持久记录核对后才回报“已记入可核对回复”。这不代表界面已经显示。
 
-技术详情由 L 0.7.9 的唯一“远程主机连接”设置节展示，正文只放模型文本。命令目录保留完整描述；未知事件和工具输入输出保留字段、JSON类型及处理结果，未获准原文明确脱敏，数字用量可核对。没有 `remoteConversationDetails:1` 时明确提示“技术详情暂不可用”，本轮不发送模型请求。X 在官方当前 profile 的 `ai-workbench-remote-agent/diagnostics/` 保存私有诊断日志（目录700、文件600、落盘同步）；写入/归属/顺序/容量失败中止本轮，不自动重发、换代重投、过期或淘汰。结果未知时只读核对原事件完整回执，未找到仍保持未知。X本轮无新增设置/阈值；L的单事件容量和分页设置在L设置节可见。
+技术详情由 L 0.7.11 的唯一“远程主机连接”设置节展示，正文只放模型文本。命令目录保留完整描述；未知事件和工具输入输出保留字段、JSON类型及处理结果，未获准原文明确脱敏，数字用量可核对。没有 `remoteConversationDetails:1` 时明确提示“技术详情暂不可用”，本轮不发送模型请求。X 在官方当前 profile 的 `ai-workbench-remote-agent/diagnostics/` 保存私有诊断日志（目录700、文件600、落盘同步）；写入/归属/顺序/容量失败中止本轮，不自动重发、换代重投、过期或淘汰。结果未知时只读核对原事件完整回执，未找到仍保持未知。X本轮无新增设置/阈值；L的单事件容量和分页设置在L设置节可见。
+
+
+0.8.2 登录检查原交付需要 L `~0.7.11`（本统一版peer为`~0.7.13`），失败来源及固定分支保留到 L“登录前技术详情”（`loginDiagnostics:1`），员工正文保持原文。按 L 明确的本品牌 queued/checking/authorizing 状态订阅等待；不以全局checking猜测在途，不新增刷新、轮询、超时或重试。每轮ensureReady仍是合同规定的显式检查，L的新可信结果可以替代旧检查，较早返回不得覆盖它。
+
+L安全规范的officialReason原串完整保留；旧/不支持格式明确记OFFICIAL_REASON_UNSUPPORTED与字节数/SHA，秘密原文不保存。L0.7.11的LOGIN_INSTANCE_MISMATCH记录通过observedLoginInstanceId与原始login.instanceId保存实际观测ID，事件及connection仍绑定当前可信ID/代次；L技术详情和X私有日志均保留真实双ID，不归一、不清空快照。复合未知官方原因以固定summary完整保存OFFICIAL_REASON_UNSUPPORTED及bytes/SHA，不交原文。X私有原快照先同步落盘，再追加L；ACK未知只读核实原事件，跨代不重写/重发。此版本的工程验证不替代leo员工路径复验，真实故障根因尚未证实。
+
+0.8.3 会话恢复：正常关闭客户端保留原broker；重开仅在私有clean检查点、完整ACP消息边界、原broker UUID及官方最新持久回复一致时接续。否则记录原因、独占并确认结束旧会话后新建，正文说明一次；旧审批不代答，按官方当前步骤保留本批全部输入，不重发历史未确认输入。S0.4.10 的实际冻结controlMaxBytes用于分块，心跳/等待严格消费主机公开策略与remainingLeaseMs；没有新增X超时或重试设置。编排00:05决定：0.4.10以前的x/a仅为测试会话，X不接入、不代答也不结束它们，直接新建r会话并说明；旧进程由编排安装S0.4.10时一次性整理。重开续接只对S0.4.10新broker承诺。
+
+D22阶段耗时进入技术详情；D23文件审批用中文动作，原工具名和会话ID进入技术详情。恢复记录沿官方profile的ai-workbench-remote-agent/recovery，目录700/文件600/fsync，无过期或淘汰。产品设置仍为上列六项，无新增默认/阈值。含真实S进程的工程测试按文件串行运行，避免多个持久化/编译测试同时争用磁盘；测试观察期限和所有断言不变，工程证据不等于leo验收。
+
+D21（0.8.5）：两个品牌的官方模型菜单从 L 的 `modelCatalogTarget:1` / `getModelCatalogTarget` 取得当前可信员工目标，再只读调用 S 的 `aw-model-catalog --provider codex|claude`。目录按 host-user 作用域展示完整模型与逐模型推理等级，保留远端标识原值；失败显示“无法获取模型列表：原因”，不登录、不创建项目、不返回替代模型。L 必须宣告该正式能力，S 必须安装保护入口；这两项未就绪时不能据组件测试声称菜单可用。
+
+每轮先核对目录代次和所选模型，再经 ACP 逐项配置模型及推理等级，收到完整配置确认后才发送输入。Claude 别名必须有当前会话的具体型号证据；没有就明确拒绝。真实回复追加所选值和远端确认值，并在恢复标识与技术详情保留，确认配置不等于验证推理效果。连接/身份/目录变化清除旧确认；远端清理待定或结果未知时阻止派发，不自动清理重试或另开替代会话。Codex 单次模式当前不能确认此选择，会在发送前明确拒绝。新增设置 0；本轮工程证据、真实只读链路与产品未验项见 `docs/evidence/2026-10-22-X2-D21/`。
+
+0.8.5统一包对齐L `~0.7.13`。D8模型目录双事件长期监听保留；同epoch的recovery提示/失败消息变化不触发执行状态失效，真实实例/epoch/phase/可信目标/登录变化仍失效。完整D9两品牌正文/状态/就绪门呈现按编排00:50允许的范围记下一版，本版不宣称已消费完成；L的connectionMessages.administratorAfterMs仍只由L管理，X新增设置0。

package/dist/acp.d.ts

@@ -2,9 +2,13 @@ import * as stable from '@agentclientprotocol/sdk';
 import * as acp from '@agentclientprotocol/sdk/unstable';
 import { NeedError, type Need } from './remote.ts';
 import type { BrokerTransport } from './broker.ts';
+import { StageTiming } from './stage-timing.ts';
+import { type AcpRecovery } from './recovery.ts';
 import { type SanitizedObservation } from './conversation-details.ts';
+import { type ModelConfigurationSnapshot } from './model-configuration.ts';
 export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
 export interface AcpHooks {
+    timing?: StageTiming;
     onUpdate?: (notification: acp.SessionNotification) => void;
     onResponse?: (response: acp.PromptResponse) => void;
     approve?: (request: acp.RequestPermissionRequest, signal?: AbortSignal) => Promise<ApprovalOutcome>;
@@ -31,8 +35,27 @@ export declare class AcpSession {
     private updating;
     private cwd?;
     private systemPrompt;
+    private configuration?;
+    private configRevision;
+    private selected?;
+    private selecting;
+    private resolvedEvidence?;
+    private pendingConfigurations;
+    get modelConfiguration(): ModelConfigurationSnapshot | undefined;
+    get resolvedModelEvidence(): Readonly<{
+        modelValue: string;
+        resolvedModel: string;
+    }> | undefined;
+    get models(): readonly import("./model-configuration.ts").ModelCatalogValue[];
+    private receiveConfiguration;
+    private resetConfiguration;
+    private lifecycleConfiguration;
+    selectModel(model: string, effort?: string, signal?: AbortSignal): Promise<ModelConfigurationSnapshot>;
+    assertModelSelection(model: string, effort?: string): void;
     private reports;
     private reportingFailure;
+    private readonly timing;
+    private stage;
     get diagnostics(): readonly Readonly<SanitizedObservation>[];
     private detail;
     private need;
@@ -42,6 +65,8 @@ export declare class AcpSession {
     get id(): string | undefined;
     get capabilities(): Readonly<acp.AgentCapabilities>;
     get startMethod(): AcpStartMethod | undefined;
+    get checkpoint(): AcpRecovery | undefined;
+    restore(cwd: string, saved: AcpRecovery, context: AcpStartContext): void;
     validatePrompt(prompt: acp.ContentBlock[]): void;
     validateContext(context: AcpStartContext): void;
     setHooks(hooks: AcpHooks): void;

package/dist/acp.js

@@ -1,6 +1,10 @@
 import * as acp from '@agentclientprotocol/sdk/unstable';
 import { NeedError } from "./remote.js";
+import { StageTiming } from "./stage-timing.js";
+import { isolateRpcIds } from "./rpc-namespace.js";
+import { recoveryCapabilities } 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,8 +20,86 @@ export class AcpSession {
     updating = false;
     cwd;
     systemPrompt = '';
+    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) {
         const safe = sanitizeObservation(observation);
@@ -38,6 +120,7 @@ export class AcpSession {
         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.sessionId && notification.sessionId !== this.sessionId) {
@@ -45,6 +128,18 @@ export class AcpSession {
                 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) {
@@ -61,6 +156,7 @@ export class AcpSession {
                 return { outcome: { outcome: 'cancelled' } };
             this.hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
             const toolName = request.toolCall.name ?? record(request.toolCall._meta?.claudeCode)?.toolName;
+            this.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: '可承载此提问的官方交互接口' });
                 return { outcome: { outcome: 'cancelled' } };
@@ -136,14 +232,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 +251,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) {
+                    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 +269,27 @@ 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) {
+        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.ready = true;
+        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 } });
+    }
     validatePrompt(prompt) {
         const capability = this.negotiated.promptCapabilities;
         for (const block of prompt)
@@ -181,8 +305,8 @@ export class AcpSession {
             throw new NeedError('SYSTEM_PROMPT_UPDATE_UNSUPPORTED', '远端没有可更新原会话上下文的恢复或加载能力', '支持带 systemPrompt 的 session/resume 或 session/load');
     }
     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; }
@@ -194,10 +318,10 @@ export class AcpSession {
         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' },
+            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.5' },
                 clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false, session: { notices: {} } },
-            }, { cancellationSignal: signal });
+            }, { 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');
@@ -208,22 +332,26 @@ export class AcpSession {
                 throw new NeedError('SYSTEM_PROMPT_UNSUPPORTED', '远端未声明系统与开发者上下文能力，不能丢弃这些要求继续', '支持 systemPrompt 的公开 ACP 能力');
             }
             const params = { cwd, mcpServers: [], ...(systemPrompt ? { 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,6 +364,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);
         }
@@ -247,8 +379,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 +394,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 +407,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 +422,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 +443,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();

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): {
+    toolName: string;
+    reason: string;
+} | undefined;

package/dist/approval-label.js

@@ -0,0 +1,45 @@
+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) {
+    const tool = request.toolCall;
+    const diffs = tool.content?.filter(item => item.type === 'diff') ?? [];
+    const name = tool.name ?? /^(Write|Edit|MultiEdit) /.exec(tool.title ?? '')?.[1];
+    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 ?? '';
+    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 = { read: '读取文件', edit: '修改文件', delete: '删除文件', move: '移动文件', search: '搜索', execute: '执行主机命令', 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/auth-reason.d.ts

@@ -0,0 +1 @@
+export declare function validOfficialReason(value: unknown): value is string;

package/dist/auth-reason.js

@@ -0,0 +1,27 @@
+/** L 0.7.10 officialReason v1 consumer validation; preserve canonical bytes only. */
+const markers = ['AW_REMOTE_COMMAND_KILL_FAILED', 'AUTH_STATUS_JSON_INVALID:SyntaxError', 'Permission denied', 'Host key verification failed', 'Connection refused', 'Connection closed', 'command not found', 'No such file or directory'];
+const names = ['Error', 'TypeError', 'SyntaxError', 'RangeError', 'AbortError', 'DOMException', 'UnknownError'];
+const codes = ['ENOENT', 'EPERM', 'ESRCH', 'EACCES', 'EINVAL', 'EPIPE', 'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ABORT_ERR', 'UNKNOWN'];
+const stages = ['ssh-status', 'ssh-result', 'remote-frame', 'auth-status', 'connect-check-login', 'integration-pre-login', 'process-spawn', 'process-stdin', 'process-output', 'process-runner'];
+const reasons = ['CANCELLED', 'SSH_EXIT_NONZERO', 'SSH_STDERR_NONEMPTY', 'FRAME_TRUNCATED', 'FRAME_JSON_INVALID', 'FRAME_OBJECT_INVALID', 'FRAME_VERSION_INVALID', 'FRAME_NONCE_INVALID', 'FRAME_AFTER_END', 'FRAME_KEYS_INVALID', 'FRAME_START_MISSING', 'FRAME_BASE64_INVALID', 'REMOTE_COMMAND_SIGNAL', 'FRAME_END_EXIT_INVALID', 'FRAME_SEQUENCE_OR_VALUE_INVALID', 'FRAME_END_MISSING', 'STATUS_ARGUMENT_INVALID', 'STATUS_EXECUTION_FAILED', 'STATUS_JSON_INVALID', 'STATUS_OBJECT_INVALID', 'STATUS_KEYS_INVALID', 'STATUS_VERSION_INVALID', 'STATUS_PROVIDER_INVALID', 'STATUS_EXIT_MISMATCH', 'STATUS_LOGGED_IN_INVALID', 'STATUS_STDERR_NONEMPTY', 'STATUS_EXIT_INVALID', 'STATUS_EXCEPTION', 'STATUS_SUPERSEDED', 'SSH_PORT_MISSING', 'STDIN_FAILED', 'SPAWN_FAILED', 'OUTPUT_LIMIT_EXCEEDED', 'PROCESS_SIGNAL'];
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const integer = (v) => Number.isSafeInteger(v) && Number(v) >= 0;
+const member = (list, v) => typeof v === 'string' && list.includes(v);
+function summary(v) {
+    return object(v) && Object.keys(v).every(k => ['bytes', 'sha256', 'markers', 'cleanupErrors'].includes(k)) && integer(v.bytes) && typeof v.sha256 === 'string' && /^[a-f0-9]{64}$/.test(v.sha256) && Array.isArray(v.markers) && v.markers.every(m => member(markers, m)) && (v.cleanupErrors === undefined || Array.isArray(v.cleanupErrors) && v.cleanupErrors.every(e => object(e) && Object.keys(e).sort().join(',') === 'errorCode,errorName' && member(['Error', 'TypeError', 'RangeError', 'UnknownError'], e.errorName) && member(['EPERM', 'EACCES', 'EINVAL', 'UNKNOWN'], e.errorCode)));
+}
+export function validOfficialReason(value) {
+    if (typeof value !== 'string')
+        return false;
+    let v;
+    try {
+        v = JSON.parse(value);
+    }
+    catch {
+        return false;
+    }
+    if (!object(v) || JSON.stringify(v) !== value || v.version !== 1 || !member(stages, v.stage) || !member(reasons, v.reason))
+        return false;
+    const fields = { version: x => x === 1, stage: x => member(stages, x), reason: x => member(reasons, x), errorName: x => member(names, x), errorCode: x => member(codes, x), exitCode: x => x === null || typeof x === 'number' && Number.isFinite(x) && Number.isInteger(x), signal: x => member(['SIGTERM', 'SIGKILL', 'SIGABRT', 'SIGHUP', 'SIGINT', 'SIGSEGV', 'OTHER'], x), index: integer, unexpectedCount: integer, maxOutputBytes: x => integer(x) && Number(x) > 0, observedBytes: integer, stderr: summary, output: summary, missing: x => Array.isArray(x) && x.every(k => member(['nonce', 'protocolVersion', 'type', 'data', 'exitCode', 'signal', 'loggedIn', 'provider'], k)), loggedInType: x => member(['null', 'undefined', 'object', 'boolean', 'number', 'string', 'function', 'symbol', 'bigint'], x), exitCodeType: x => member(['undefined', 'object', 'boolean', 'number', 'string', 'function', 'symbol', 'bigint'], x) };
+    return Object.entries(v).every(([key, item]) => Object.hasOwn(fields, key) && fields[key](item));
+}

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>;