@ai-workbench/remote-agent 0.0.0-stage → 0.8.0

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+在 DSH「插件 → 添加插件」填 `@ai-workbench/remote-agent@0.8.0`（由编排发布后可用），或运行 `dsh plugin --profile desktop add @ai-workbench/remote-agent@0.8.0`。
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 远程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另验。
+
+## 员工路径
+
+从官方插件管理安装，照常使用默认工作区/会话/模型入口。原生添加或选择本机工作区后，首次实际使用远程模型由L建立/绑定同名远端工作区。本地文件不自动上传，X不猜目录、不选首项。首次说明使用官方普通回复；先经官方会话提交、持久化并读回核对，才向L确认。持久记录不等于员工已看见，GUI另验；日志丢失后的未知claim由L保留，不宣称端到端恰好一次。
+
+未登录时两个模型均回复：**需要登录，请到设置 → 远程主机连接 点登录**。无L或缺正式能力时直接说明缺项，不让员工填写主机、用户、路径或密钥。
+
+## 首版审批与能力边界
+
+只使用官方DSH审批：唯一的`allow_once`对应允许一次，唯一的`reject_once`对应拒绝。当前固定官方版本没有“本会话总是允许”结果；以后有公开能力才映射，不伪造。
+
+**首版不支持：`allow_always`、`reject_always`、同一种类有多个不同optionId的歧义选项。** 这些选项不出现在官方审批中；当前请求遇到时会在普通回复明确说明具体名称、标识与种类。无法映射的结果不授权，不取第一项、不静默降为允许一次、不使用userQuestions。取消或断线会撤销旧审批，迟到应答无效；只有真实本轮完成才结算其应答状态。
+
+文本、思考、工具步骤/正文/补丁、计划、通知映射为官方普通流；远端工具不变成本机工具调用。图片输入由官方附件服务读取已核验字节，经ACP传给主机，不传员工文件路径。非文本输出无法得到官方持久附件引用时，明确说明收到的内容类型与所缺能力，不假造图片引用。远端结构化提问、未映射扩展会明确提示并取消，不静默丢弃。
+
+首次系统/开发者上下文按协商的ACP系统能力传入。**首版不支持：已有Claude会话中立即生效的系统/开发者上下文变更。** 固定适配器说明恢复后的变更要到下次上下文整理才生效；X发现变更会停止本轮派发并提示新建会话，避免按旧约束执行，不自动整理、重试或新建替代会话。未声明系统能力的agent会明确报缺项。
+
+`usage_update`的used/size是上下文占用，不能当作本轮输入/输出计费量；远端真实prompt响应usage及Claude quota令牌计数是会话累计，按保存在当前实例/恢复标识中的可信基线减差后进入DSH本轮用量；重复值不重复结算。恢复缺少基线、计数缺失、回退或来源改变时明确不计入该轮，重建可信基线，不能把历史用量算成本轮。
+
+会话模式跨轮保留同一ACP客户端和主机进程；关闭实际agent/session或插件时精确清理。重开恢复优先协商resume，无能力时明确使用load，不静默新建。恢复标识绑定品牌、员工目标、DSH会话和L工作区；复制/分叉不能沿用父远端会话。客户端丢失留下的孤儿由管理员确认处理，不自动结束或重开。无TTL或隐式淘汰上限。
+
+Codex单次模式首版仅文本，不转接中途审批；图片或系统/开发者上下文需使用会话模式。文件传输、远端VFS与自动同步不在本轮。其他模型不锁定、不拦截、不记录。
+
+## 管理员配置
+
+在官方设置中使用“打开配置文件”，修改**已有同id插件条目**的config。保留官方settingsNs，不注册额外设置节；原生提供方编辑卡是否可编辑以官方实际能力为准。不要新增重复insert条目，不修改官方默认服务或布局。
+
+| 设置 | 默认 | 范围与用途 |
+|---|---|---|
+| mode | session | Codex可选session/one-shot，切换后新建会话；Claude固定session |
+| acpMaxMessageBytes | 4194304 | 正整数，会话单条消息容量，默认4MiB；超限不截断 |
+| brokerMaxFrameBytes | 2097152 | 正整数，主机回传单帧容量，默认2MiB |
+| brokerControlMaxBytes | 1048576 | 正整数，主机会话管理回复容量，默认1MiB |
+| oneShotSandbox | workspace-write | Codex单次可选read-only/workspace-write/danger-full-access |
+| oneShotApproval | never | 当前单次通道无中途交互审批；不代表自动批准 |
+
+六项沿用owner已定默认，无新增设置或策略阈值；非法值拒绝，删除覆盖遵循官方配置继承。SSH可执行程序从当前PATH发现，不写死某一系统路径。原始错误码保留在官方失败代码/技术详情，原始stderr、凭据和URL不展开。
+
+仅新增中文文案和验证；保留已有英文名称及既有locale机制。提供方名称不附状态后缀，由原注册replace更新，不自造刷新或客户端品牌分支。
+
+## 安装产物
+
+包内已含`dist`中的JavaScript、类型和客户端产物及locale/官方patch，无TypeScript源码、测试、证据或主机诊断脚本。无需postinstall、prepare或下载/编译步骤；依赖使用已固定的公开npm版本并由官方安装器正常解析，不把第三方源码/测试夹入X包。`@deepseek-ai/*`均为已测精确peer，由客户端提供；连接插件L另装。原配置id/settingsNs与两个provider id保持，旧包升级需经官方管理先卸载再装新包，不并装两份X。
+
+## 验证范围
+
+当前准备结果与限制记入源码仓`docs/evidence/2026-10-21-X-npm-prep/`（不进npm包）。先前真实emp-a协议诊断及固定三件套GUI是不同轮次，不能代替本次新包安装门。L完整绑定/登录、真实模型、物理断网、HanaMesh及leo E以实际已执行证据为准。主机命令安装来自S，X不修改S仓/安装脚本或登录状态。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: ai-workbench-codex
+      name: '@ai-workbench/remote-agent'

package/dist/acp.d.ts

@@ -0,0 +1,46 @@
+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';
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+export interface AcpHooks {
+    onUpdate?: (notification: acp.SessionNotification) => void;
+    onResponse?: (response: acp.PromptResponse) => void;
+    approve?: (request: acp.RequestPermissionRequest, signal?: AbortSignal) => Promise<ApprovalOutcome>;
+    onNeed?: (need: Need) => void;
+    broker?: BrokerTransport;
+}
+export interface AcpStartContext {
+    systemPrompt?: string;
+}
+export type AcpStartMethod = 'session/new' | 'session/resume' | 'session/load';
+/** ACP v1 with explicitly negotiated SDK 2.0 lifecycle/context extensions. */
+export declare class AcpSession {
+    private connection;
+    private hooks;
+    private sessionId?;
+    private turnSignal?;
+    private turnToken?;
+    private busy;
+    private startAttempted;
+    private negotiated;
+    private method?;
+    private ready;
+    private updating;
+    private cwd?;
+    private systemPrompt;
+    constructor(transport: acp.Stream | acp.AgentApp | stable.AgentApp, hooks: AcpHooks);
+    private observe;
+    get id(): string | undefined;
+    get capabilities(): Readonly<acp.AgentCapabilities>;
+    get startMethod(): AcpStartMethod | undefined;
+    validatePrompt(prompt: acp.ContentBlock[]): void;
+    validateContext(context: AcpStartContext): void;
+    setHooks(hooks: AcpHooks): void;
+    get closed(): Promise<void>;
+    start(cwd: string, resumeId?: string, signal?: AbortSignal, context?: AcpStartContext): Promise<string>;
+    updateContext(context: AcpStartContext, signal?: AbortSignal): Promise<AcpStartMethod | undefined>;
+    prompt(input: string | acp.ContentBlock[], signal?: AbortSignal): Promise<acp.StopReason>;
+    close(): void;
+}
+export declare function acpNeed(error: unknown): NeedError;

package/dist/acp.js

@@ -0,0 +1,303 @@
+import * as acp from '@agentclientprotocol/sdk/unstable';
+import { NeedError } from "./remote.js";
+/** ACP v1 with explicitly negotiated SDK 2.0 lifecycle/context extensions. */
+export class AcpSession {
+    connection;
+    hooks;
+    sessionId;
+    turnSignal;
+    turnToken;
+    busy = false;
+    startAttempted = false;
+    negotiated = {};
+    method;
+    ready = false;
+    updating = false;
+    cwd;
+    systemPrompt = '';
+    constructor(transport, hooks) {
+        this.hooks = hooks;
+        const app = acp.client({ name: '@ai-workbench/remote-agent' })
+            .onNotification(acp.methods.client.session.update, ({ params: notification }) => {
+            if (this.busy && notification.sessionId === this.sessionId) {
+                // Session metadata is not evidence that the current prompt was accepted.
+                if (['agent_message_chunk', 'agent_thought_chunk', 'tool_call', 'tool_call_update'].includes(notification.update.sessionUpdate))
+                    this.hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
+                const meta = record(notification._meta);
+                if (meta && Object.keys(meta).length)
+                    this.hooks.onNeed?.({ code: 'ACP_EXTENSION_UNSUPPORTED', message: `首版不支持：远端通知扩展字段 ${Object.keys(meta).map(safeLabel).join('、')}；扩展值未展开`, requires: '对应的公开扩展映射' });
+                this.hooks.onUpdate?.(notification);
+            }
+        })
+            .onRequest(acp.methods.client.session.requestPermission, async ({ params: request, signal: rpcSignal, requestId }) => {
+            if (request.sessionId !== this.sessionId || !this.busy || this.turnSignal?.aborted)
+                return { outcome: { outcome: 'cancelled' } };
+            this.hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
+            const toolName = request.toolCall.name ?? record(request.toolCall._meta?.claudeCode)?.toolName;
+            if (toolName === 'AskUserQuestion') {
+                this.hooks.onNeed?.({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问；已取消，未提交答案', requires: '可承载此提问的官方交互接口' });
+                return { outcome: { outcome: 'cancelled' } };
+            }
+            const eligible = request.options.filter(option => {
+                const single = option.kind === 'allow_once' || option.kind === 'reject_once';
+                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.hooks.onNeed?.({ code: 'APPROVAL_OPTION_UNSUPPORTED', message: `首版不支持：${option.name} / ${option.optionId} / ${option.kind}`, requires: '唯一对应的允许一次或拒绝一次选项' });
+                return unique;
+            });
+            if (!eligible.length)
+                return { outcome: { outcome: 'cancelled' } };
+            const presented = { ...request, options: eligible };
+            const token = this.turnToken;
+            const id = this.sessionId;
+            let outcome = 'unavailable';
+            const approvalSignal = this.turnSignal ? AbortSignal.any([this.turnSignal, rpcSignal]) : rpcSignal;
+            const broker = this.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.
+            try {
+                while (!approvalSignal.aborted) {
+                    await broker?.waitOnline(approvalSignal);
+                    generation = broker?.generation;
+                    const lease = broker?.signal;
+                    const signal = lease ? AbortSignal.any([approvalSignal, lease]) : approvalSignal;
+                    const interrupted = Promise.withResolvers();
+                    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]);
+                    }
+                    finally {
+                        signal.removeEventListener('abort', abort);
+                    }
+                    if (broker && !approvalSignal.aborted && (generation !== broker.generation || lease?.aborted))
+                        continue;
+                    break;
+                }
+            }
+            catch {
+                this.hooks.onNeed?.({ 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);
+            if (this.busy && token === this.turnToken && id === this.sessionId && !approvalSignal.aborted && option && (!broker || (broker.online && generation === broker.generation))) {
+                if (broker)
+                    broker.authorizeResponse(requestId, generation);
+                return { outcome: { outcome: 'selected', optionId: option.optionId } };
+            }
+            this.hooks.onNeed?.({ code: outcome === 'allowed-once' ? 'APPROVAL_OPTION_UNSUPPORTED' : 'APPROVAL_UNAVAILABLE',
+                message: '此动作未获授权；审批已取消、不可用或没有可映射的单次选项', requires: '本次动作的有效审批' });
+            return { outcome: { outcome: 'cancelled' } };
+        })
+            .onRequest(acp.methods.client.elicitation.create, () => {
+            this.hooks.onNeed?.({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问或信息收集；已取消，未提交答案', requires: '可承载此提问的官方交互接口' });
+            return { action: 'cancel' };
+        })
+            .onNotification(acp.methods.client.elicitation.complete, () => {
+            this.hooks.onNeed?.({ code: 'INTERACTION_UNSUPPORTED', message: '首版不支持：远端提问完成通知；未提交答案', requires: '可承载此提问的官方交互接口' });
+        })
+            .onRequest('*', () => {
+            this.hooks.onNeed?.({ code: 'ACP_EXTENSION_UNSUPPORTED', message: '首版不支持：远端请求的扩展交互；未授权此动作', requires: '受支持的公开 ACP 交互接口' });
+            throw new acp.RequestError(-32601, '不支持此扩展交互');
+        })
+            .onNotification('*', () => {
+            this.hooks.onNeed?.({ code: 'ACP_EXTENSION_UNSUPPORTED', message: '首版不支持：收到未知的远端扩展通知', requires: '受支持的公开 ACP 通知接口' });
+        });
+        if ('readable' in transport && 'writable' in transport)
+            this.connection = app.connect(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 }));
+            void this.connection.closed.then(() => peer.close());
+            void peer.closed.then(() => this.connection.close());
+        }
+    }
+    observe(stream) {
+        // Observe already-parsed public Stream messages: no NDJSON parsing, second
+        // byte buffer, message-size policy, or transport fallback is introduced.
+        const readable = stream.readable.pipeThrough(new TransformStream({ transform: (message, controller) => {
+                const raw = record(message);
+                const params = record(raw?.params);
+                const update = record(params?.update);
+                if (raw?.method === acp.methods.client.session.update && typeof update?.sessionUpdate === 'string' && !knownUpdates.has(update.sessionUpdate)) {
+                    if (this.busy && params?.sessionId === this.sessionId)
+                        this.hooks.onNeed?.({ code: 'ACP_UPDATE_UNSUPPORTED', message: `首版不支持：远端事件 ${safeLabel(update.sessionUpdate)}；未展开未知事件内容`, requires: '对应的公开 ACP 显示映射' });
+                    return;
+                }
+                controller.enqueue(message);
+            } }));
+        return { readable, writable: stream.writable };
+    }
+    get id() { return this.sessionId; }
+    get capabilities() { return this.negotiated; }
+    get startMethod() { return this.method; }
+    validatePrompt(prompt) {
+        const capability = this.negotiated.promptCapabilities;
+        for (const block of prompt)
+            if ((block.type === 'image' && !capability?.image) || (block.type === 'audio' && !capability?.audio) || (block.type === 'resource' && !capability?.embeddedContext))
+                throw new NeedError('PROMPT_CONTENT_UNSUPPORTED', `远端未声明此输入内容能力：${block.type}；本轮未发送`, '对应内容类型的公开 ACP 输入能力');
+    }
+    validateContext(context) {
+        if ((context.systemPrompt ?? '') === this.systemPrompt)
+            return;
+        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');
+    }
+    setHooks(hooks) {
+        if (this.busy || this.updating)
+            throw new NeedError('TURN_BUSY', '上一轮或上下文更新结束前不能更换会话钩子', '上一轮结束');
+        this.hooks = hooks;
+    }
+    get closed() { return this.connection.closed; }
+    async start(cwd, resumeId, signal, context) {
+        if (this.startAttempted)
+            throw new NeedError('SESSION_ALREADY_STARTED', '此连接已用于建立会话，不能转用工作区或身份', '新的独立远端连接');
+        this.startAttempted = true;
+        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.0' },
+                clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false, session: { notices: {} } },
+            }, { 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.negotiated = hello.agentCapabilities ?? {};
+            const systemPrompt = context?.systemPrompt;
+            if (systemPrompt && !this.negotiated.sessionCapabilities?.systemPrompt) {
+                throw new NeedError('SYSTEM_PROMPT_UNSUPPORTED', '远端未声明系统与开发者上下文能力，不能丢弃这些要求继续', '支持 systemPrompt 的公开 ACP 能力');
+            }
+            const params = { cwd, mcpServers: [], ...(systemPrompt ? { systemPrompt: { mode: 'append', content: [{ type: 'text', text: systemPrompt }] } } : {}) };
+            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 });
+                    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 });
+                    this.method = acp.methods.agent.session.load;
+                }
+            }
+            else {
+                const result = await this.connection.agent.request(acp.methods.agent.session.new, params, { cancellationSignal: signal });
+                this.sessionId = result.sessionId;
+                this.method = acp.methods.agent.session.new;
+            }
+            this.hooks.broker?.acknowledge(this.method);
+            this.ready = true;
+            this.cwd = cwd;
+            this.systemPrompt = systemPrompt ?? '';
+            return this.sessionId;
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new NeedError('ABORTED', '会话建立已取消；尚无本轮输出', '重新连接主机');
+            throw acpNeed(error);
+        }
+        finally {
+            signal?.removeEventListener('abort', abort);
+        }
+    }
+    async updateContext(context, signal) {
+        if (!this.ready || !this.sessionId || !this.cwd)
+            throw new NeedError('SESSION_REQUIRED', '我需要先建立远端会话', 'ACP 会话');
+        if (this.busy || this.updating)
+            throw new NeedError('TURN_BUSY', '此远端会话正在处理上一轮或更新上下文', '上一轮结束');
+        const text = context.systemPrompt ?? '';
+        if (text === this.systemPrompt)
+            return undefined;
+        this.validateContext(context);
+        const resume = !!this.negotiated.sessionCapabilities?.resume;
+        signal?.throwIfAborted();
+        this.updating = true;
+        this.ready = false;
+        const abort = () => this.connection.close(new NeedError('ABORTED', '上下文更新已取消，原会话状态需确认', '重新连接原会话'));
+        signal?.addEventListener('abort', abort, { once: true });
+        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 });
+            this.hooks.broker?.acknowledge(method);
+            this.systemPrompt = text;
+            this.ready = true;
+            this.hooks.onNeed?.({ code: 'SYSTEM_PROMPT_UPDATE_DEFERRED', message: '系统与开发者上下文变更已通过原会话恢复接口传送。Claude 恢复会话沿用首次系统提示，新要求在下次上下文整理后生效；不能据此认定本轮已立即生效。', requires: '远端实际应用新要求；Claude 须完成下一次上下文整理' });
+            return method;
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new NeedError('ABORTED', '上下文更新已取消；原会话状态需确认', '重新连接原会话');
+            throw acpNeed(error);
+        }
+        finally {
+            this.updating = false;
+            signal?.removeEventListener('abort', abort);
+        }
+    }
+    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', '此远端会话正在处理上一轮', '上一轮结束');
+        signal?.throwIfAborted();
+        const prompt = typeof input === 'string' ? [{ type: 'text', text: input }] : input;
+        this.validatePrompt(prompt);
+        this.busy = true;
+        this.turnSignal = signal;
+        this.turnToken = Symbol('turn');
+        let rejectAbort;
+        const interrupted = new Promise((_resolve, reject) => { rejectAbort = reject; });
+        const cancel = () => {
+            rejectAbort?.(new NeedError('ABORTED', '已请求取消本轮，远端状态需确认', '确认主机取消状态'));
+            void this.connection.agent.notify(acp.methods.agent.session.cancel, { sessionId: this.sessionId }).catch(() => {
+                this.hooks.onNeed?.({ code: 'CANCEL_UNCONFIRMED', message: '连接中断，无法确认主机已取消本轮', requires: '恢复连接以确认远端状态' });
+            });
+        };
+        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);
+            this.hooks.broker?.acknowledge(acp.methods.agent.session.prompt);
+            signal?.throwIfAborted();
+            this.hooks.broker?.completePrompt();
+            this.hooks.onResponse?.(result);
+            return result.stopReason;
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new NeedError('ABORTED', '本轮已取消；已请求主机停止', '确认主机取消状态');
+            throw acpNeed(error);
+        }
+        finally {
+            signal?.removeEventListener('abort', cancel);
+            this.turnSignal = undefined;
+            this.busy = false;
+            this.turnToken = undefined;
+        }
+    }
+    close() { this.connection.close(); }
+}
+export function acpNeed(error) {
+    if (error instanceof NeedError)
+        return error;
+    if (error instanceof acp.RequestError && error.code === -32000)
+        return new NeedError('LOGIN_REQUIRED', '需要登录，请到设置 → 远程主机连接 点登录', '该员工自己的远端模型登录');
+    if (error instanceof acp.RequestError)
+        return new NeedError('ACP_FAILED', '远端 ACP 请求失败，根因未查明；未切换到新会话', `有效的远端 ACP 连接；RPC 错误码 ${error.code}`);
+    return new NeedError('ACP_FAILED', '远端 ACP 请求失败或连接中断，根因未查明；未切换到新会话', '有效的远端 ACP 连接');
+}
+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, ' '); }

package/dist/agents.d.ts

@@ -0,0 +1,15 @@
+/** Provider identities and protected commands from L/S's public contracts. */
+export interface AgentDefinition {
+    readonly id: string;
+    readonly name: Readonly<{
+        zh: string;
+        en: string;
+    }>;
+    readonly command: string;
+    readonly loginProvider: 'claude' | 'codex';
+    readonly oneShot: boolean;
+}
+export declare const CODEX_AGENT: AgentDefinition;
+export declare const CLAUDE_AGENT: AgentDefinition;
+export declare const AGENTS: readonly AgentDefinition[];
+export declare function agentForProvider(id: string): AgentDefinition | undefined;

package/dist/agents.js

@@ -0,0 +1,4 @@
+export const CODEX_AGENT = Object.freeze({ id: 'codex-remote', name: Object.freeze({ zh: 'Codex（远程主机）', en: 'Codex (Remote Host)' }), command: '/usr/local/aw-host/bin/codex-acp', loginProvider: 'codex', oneShot: true });
+export const CLAUDE_AGENT = Object.freeze({ id: 'claude-code-workbench', name: Object.freeze({ zh: 'Claude（远程主机）', en: 'Claude (Remote Host)' }), command: '/usr/local/aw-host/bin/claude-agent-acp', loginProvider: 'claude', oneShot: false });
+export const AGENTS = Object.freeze([CODEX_AGENT, CLAUDE_AGENT]);
+export function agentForProvider(id) { return AGENTS.find(agent => agent.id === id); }

package/dist/broker.d.ts

@@ -0,0 +1,67 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { NeedError, type Need } from './remote.ts';
+import type { Interaction } from './interaction.ts';
+import { type ConnectApi, type ConnectTarget, type Project, type Runtime, type RuntimeRequest } from './provider.ts';
+export type Attachment = ChildProcessWithoutNullStreams;
+export interface BrokerOptions {
+    maxFrameBytes: number;
+    attach: (after: number) => Promise<Attachment>;
+    onNeed?: (need: Need) => void;
+    onDisconnect?: () => Promise<void>;
+}
+/** One byte stream / SDK app, multiple SSH attachments. Input is never replayed. */
+export declare class BrokerTransport {
+    readonly readable: ReadableStream<Uint8Array>;
+    readonly writable: WritableStream<Uint8Array>;
+    private options;
+    private output;
+    private attachment?;
+    private cursor;
+    private epoch;
+    private attached;
+    private ended;
+    private joining?;
+    private lease;
+    private listeners;
+    private permits;
+    private approvalSent;
+    private unconfirmed;
+    private failure?;
+    constructor(options: BrokerOptions);
+    get online(): boolean;
+    get generation(): number;
+    get signal(): AbortSignal;
+    get lastSequence(): number;
+    get error(): NeedError | undefined;
+    authorizeResponse(id: string | number | null, generation: number): void;
+    /** Called only by the ACP protocol layer after a matching result or current-turn output. */
+    acknowledge(method: string): void;
+    /** A matching terminal prompt response settles all approval replies in that turn. */
+    completePrompt(): void;
+    onChange(fn: () => void): () => void;
+    private changed;
+    private notice;
+    fail(error: NeedError): void;
+    close(): void;
+    waitOnline(signal?: AbortSignal): Promise<void>;
+    connect(): Promise<void>;
+    private attach;
+    private write;
+}
+export type SshArgv = (target: ConnectTarget) => string[];
+export interface BrokerIo {
+    run: (command: string, signal?: AbortSignal) => Promise<string>;
+    attach: (command: string) => Promise<Attachment>;
+}
+export declare function controlNeed(stderr: string): NeedError;
+export declare function sshIo(target: ConnectTarget, argv: SshArgv, maxControlBytes: number): BrokerIo;
+export declare function brokerCommand(t: ConnectTarget, args: string[]): string;
+export declare function brokerId(sessionId: string, agentId?: string): string;
+export interface BrokerSettings {
+    brokerMaxFrameBytes?: number;
+    brokerControlMaxBytes?: number;
+}
+export declare function brokerFactory(get: () => ConnectApi | undefined, _ask: Interaction | undefined, configuration: BrokerSettings | (() => BrokerSettings), provided?: {
+    argv?: SshArgv;
+    io?: (target: ConnectTarget) => BrokerIo;
+}): (target: ConnectTarget, project: Project, request: RuntimeRequest) => Promise<Runtime>;