@ai-workbench/remote-agent 0.9.0-toolbridge.38 → 0.9.0-toolbridge.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,106 +1,11 @@
1
- # AI Workbench 远程助手 · @ai-workbench/remote-agent@0.9.0-toolbridge.38 · 插件 → 添加插件
1
+ # AI Workbench 远程助手 · @ai-workbench/remote-agent@0.9.0-toolbridge.40 · 插件 → 添加插件
2
2
 
3
- 本版配套总包 0.3.9,固定 N0.4.11 / L0.7.46,主机仍使用 aw.17 / Codex 0.162.0。修复 0.3.8 回复仅显示文件名或代码路径、无法点击打开的问题。
3
+ 本版配套紧急总包0.3.11。在同一轮本机工作区租约中,用标准OpenSSH ControlMaster分别持有员工→主机及主机→员工两层连接,MCP和Bash只开已有连接的新session,避免每个Bash重开两层握手与S配对。连接失效后不会悄悄回退新拨号,也不重放原命令。N0.4.12/L0.7.47/host0.8.14/aw.17保持;handshakeTimeoutMs默认10000不变。
4
4
 
5
- 只逐字转送当前生效的 DSH 原生 `ui:deliverable-file-references` Shared guidance;不硬编码或改写原文,不附加插件自写文字,不恢复其他已撤除的 DSH 系统规则。原文作为独立 ACP 文本上下文块,每个新 prompt 发送一次;适用于新会话及既有原生线程接回,不改变员工输入、插话回执或工具桥等待步骤。它在 ACP 中是用户级上下文,不冒称已恢复 system 角色。生效作用域与完整提示词覆盖均按 DSH 原生组装结果处理。
5
+ 专用连接归本轮租约,不归某一个MCP或Bash。单工具取消、子AI或单MCP关闭只结束自己的session;并发输出、stdin、二进制、真实退出码保持。退出255或断连仍按既有UNKNOWN处理。换工作区、换代、下一轮和取消会关闭本轮连接;控制socket仅在本轮私有目录中使用,旧租约不复用新轮资源。
6
6
 
7
- DSH 已提供的 `present` 工具恢复首轮可见:Claude 使用原生 alwaysLoad 元数据,Codex 使用既有 employee 直接工具分组;其余 DSH 扩展工具仍按需发现。工具说明、参数与结果保持 DSH 原文;执行、权限和交付卡片均由 DSH 负责,不伪造文件卡片,不把实际文件改由 DSH 工具写入。
7
+ 本版继承已完成的登录传输归类、固定诊断、文件链接、原会话恢复、插话、品牌切换、子AI和用量能力,不增加提示词、错误码、设置、业务限制或重试。只使用官方DSH公共插件机制,声明范围 `>=0.2.0-rc.2 <0.3.0-0`,原稳定latest保留0.8.31。
8
8
 
9
- 零插件自写提示词、原生技能镜像、原生子代理、B6 插话与冷恢复、U1 本轮用量、型号/推理/权限设置全部保留。技能原文、资源及项目说明仍由原生目录读取,文件和命令仍在员工所选目录执行。没有新增设置、限制或错误码。真实模型、三版 DSH 与 token 增量证据见 TESTS.md。
9
+ 员工使用总包升级:官方DSH“插件 → 添加插件”输入 `@ai-workbench/workbench-toolbridge@0.3.11`,安装后⌘Q完全退出再重开,在原会话继续。无需重建工作区或重新导入连接资料;不要重复发送结果未知的旧命令。
10
10
 
11
- 上一轮正常结束仍异步清理,不延迟已完成回复。下一次同一可信主机、DSH会话、品牌、原生线程及连接代次打开前,只等待本插件已经发出的那一次释放操作;取消等待不取消释放,失败仍走原有归属校验,不增加模型重试或重复发送任务。
12
-
13
- ## 办公依赖与开工计时(O1,2026-11-15)
14
-
15
- 员工目录模式现在桥接 DSH `load_workspace_dependencies`,由 DSH 原生循环执行、审批并返回员工电脑的 Python/Node 绝对路径;命令仍通过员工执行器执行这些路径。主机目录模式不开放工具桥,不能使用员工运行时路径。Codex 新建线程在主机明确声明能力时,先按本轮所选模型建立原生基础说明,再保留每轮模型、推理与权限的真实设置回执;没有裁剪 DSH、安全或原生说明,恢复与真实换模型维持原语义。需主机含桥适配器 `2.2.2-aw.13`;旧主机照旧运行。
16
-
17
- 技术详情的 `STARTUP_TIMING` 只记录单调时钟与固定阶段,含目录快照、登录、端点、静态执行器元数据、broker、工具桥、ACP 初始化/建会话、模型/权限确认、实际 SDK 派发,以及支持持久消息协议时的 `prompt-delivery`(绑定和输入确认)。`startup` 到实际 SDK 写出,不能直接称为 DSH 提交到主机 task_started;跨机差额需同轮事件另算。静态执行器路径与本轮端点准备并行;每轮目录/登录/端点核验及事件撤销、主机目标绑定保持。
18
-
19
- 新增设置、限制、错误码均为 0。已有会话的历史说明不会被改写;避免初始模型切换冗余的效果从新会话开始。
20
-
21
- ## 含工具桥发布线
22
-
23
- 本包为 `0.9.0-toolbridge.37`,从 `v0.9.0-toolbridge.14` 派生,使用 `host-toolbridge` 发布渠道。员工安装由连接组件提供的「AI 写作工作台(含工具桥)」总包 `@ai-workbench/workbench-toolbridge@0.3.8`,与不含工具桥的版本二选一。
24
-
25
- 本轮增加两家运行中插话(DSH 原生 nextStep),保留官方队列和原话;明确 followup 仍排下一轮。Codex 含桥组件需 `2.2.2-aw.12`,Claude 仍为官方 `0.94.0`。插件确定消息未发出时保留排队资格;送达未确认时明确报错且不重放。已注入旧正文不能撤回,编辑版下一步骤交付。
26
-
27
- host `0.8.11` 的新 broker 支持同一客户端/SDK 在切网后按输出游标和输入 ACK 水位接回原 prompt、结果及用量,不重新发送原 prompt;旧本机执行端失效仍为 UNKNOWN,不用新进程替换或重放旧操作。客户端完全退出、崩溃后,重新打开同一 DSH 会话会自动接回已持久登记的原 prompt,显示未落盘输出并取回原结果、增量用量。原 prompt 只执行一次;旧审批仅取消,不复活未知本机执行。旧运行 broker 和 X.14 在途轮不会被安装自动补造冷恢复记录。无新增设置;512,000,000 字节默认保留,实际协议头计入同一容量。
28
-
29
- 原轮正常完成(或冷接回已交付原结果)后结束该轮主机 broker,原生线程写锁随之释放,同一 DSH 会话下一轮不再因旧轮保留 10 分钟而报“原会话仍被占用”;结果未定(插件退出、断开、失败)时仍保留原轮待接回。保留的原轮若已不在主机上(按既有回收时限结束、broker 崩溃或主机重启),下一条消息先说明那一轮结果无法接回、没有重发那一轮任务,再用原会话编号恢复原生会话(Claude session/resume、Codex session/load)带着原上下文处理新消息,不新建会话(0.9.0-toolbridge.22 起;此前同一会话每条新消息都报“主机会话控制失败(ENOENT/ECONNREFUSED)”,只能新开对话)。保留的原轮若是因主机登录失效(登出、换账号、过期或被撤销)而失败(ACP 认证失败 -32000),下一条消息先说明那一轮因登录失效没有完成、没有重发那一轮任务,结束那一轮持旧登录的主机进程,再用当前登录按原会话编号恢复(Claude session/resume、Codex session/load)处理新消息;主机仍未登录时照旧提示需要登录(0.9.0-toolbridge.23 起;此前这条消息报“原轮返回错误(-32000)”且不处理,旧进程留到回收)。旧 X.14–.16 发出的结束请求在主机上始终不生效,只有升级本包才消除;只升主机不够。
30
-
31
- 本机文件夹下的主机 Claude 可以开自己的子代理(原生 Agent 与 TaskStop),子代理还能再开子代理,插件不加层数或次数限制。子代理继承同一工具表:原生 Read/Write/Edit/Glob/Grep/Bash 仍关闭,文件和命令只走员工本机工具并按原审批;工具桥的 DSH 工具同样可用。子代理的工具事件进技术详情,结论由主 Claude 在原回复里给出;取消本轮会一并结束子代理。Claude 原生的 SendMessage/ListAgents 不开放(DSH 同名的 send_message/list_agents 见下段),因为它们能触及主机账号的其他本地和云端会话;子代理完成后结果仍自动交回主 Claude。主机文件夹本就允许,行为不变。Claude 的云端子代理(Agent 的 isolation:"remote",会在员工 Claude 账号的云端运行,碰不到员工电脑和主机)在本机文件夹和主机文件夹下都被拒绝(0.9.0-toolbridge.21 起,上游 PreToolUse 钩子:调用里写 remote,或所调子代理类型的定义文件写 `isolation: remote`,都拒;检查在主机跑一个固定脚本,只读钩子输入和子代理定义文件,不执行模型内容);本地子代理、worktree、套娃、Skill 和 DSH 子代理工具照常。Codex 自身的多代理功能本线没有关闭(层数和线程数是 Codex 上游默认值,插件不改)。
32
-
33
- 任何 agent 都可以调用其他 agent:本机文件夹下的主机 Claude/Codex 经工具桥使用 DSH 自带的子代理工具(subagent、subagent_fork、list_subagent_models、send_message、interrupt_agent、list_agents、wait_agent、spawn_teammate、team_task_*、workflow 及后台任务 job_output/job_list/job_kill),由 DSH 执行、审批、显示子代理卡片和交回结果。被调方可以是主机 Claude 新会话、主机 Codex 新会话或员工在 DSH 配好的模型;跨品牌路由需员工在 DSH 子代理设置里允许。DSH 的子会话不是工作区成员,插件沿 live 的 parentSession 找到最近一个登记在工作区里的祖先会话,按它的工作区执行(子会话 cwd 仍须等于该工作区,本机/主机文件夹同样适用);子会话有自己的主机原生会话、broker、冷接回记录,文件和命令照常走员工本机或所选主机目录。层数、并发由 DSH 自己的用户设置决定,插件不加任何层数、并发、次数或预算限制,也不改 DSH 设置。主机文件夹不开放工具桥,所以主机文件夹下的主机 Claude/Codex 只能用自己的原生子代理,作为被调方时由 DSH 子代理派出。
34
-
35
-
36
- 选择本机文件夹后,Claude 和 Codex 可以把 DSH 已启用的 MCP、web、skill、ask_user、todo/present/goal 等工具交给 DSH 原生执行和审批。DSH 内置文件/命令、终端、run_code 不经工具桥转交;DSH 子代理/agent-team/workflow/后台任务工具经工具桥交给 DSH;原有文件和命令执行方式保留。plan 不自动放行桥接权限;default 下 Claude 的桥接原生权限由插件单次应答,员工只在 DSH 审批实际工具。主机文件夹不开放工具桥。
37
-
38
- 工具表按每次主机连接生成快照,新增/移除在下一次连接生效;不承诺 Codex 当前 MCP 会话热刷新。审批期间的插话等当前主机 prompt 结束后再发,停泊中切换助手会停止原轮次并明确提示。工具主动结束DSH轮次时,已提交结果仍交回原agent;确认原生工具收到后结束原prompt,下一条沿原线程继续,不在已关闭步骤追加模型回复。取消和主机结束等待后的结果不重放;工具已执行的副作用不能因取消而撤销,请按说明核对。图片结果由官方附件组件读取后交回。
39
-
40
- Codex 使用独立受保护命令 `/usr/local/aw-host/bin/codex-acp-toolbridge`(本版 aw.17,组件自带固定 Node24.13.1),不会替换原 codex-acp/aw.6;Claude命令不变。指定桥接 server 的等待为 owner 确认的 **1800 秒**、审批交 DSH;不改其他server的调用时限,不新增插件设置项。含桥的本机Codex会话按原生规则等各扩展现有启动时限结算后再捕获工具;启动失败会明确说明,文件和命令仍按原方式执行,本轮不自动重试。N0.4.9、L0.7.37沿既有公开合同;真实界面/员工验收由编排安排。完整合同和本轮启动修复证据见 `docs/contracts/codex-toolbridge.md`、`docs/evidence/2026-10-27-toolbridge-startup/REPORT.md`。
41
-
42
- 通过官方 DSH 插件入口使用 Claude(远程主机)与 Codex(远程主机)。登录和工作区来源由“远程主机连接”组件提供;员工在原生工作区和模型菜单中选择文件夹与型号。
43
-
44
- 文件和命令在所选的本机或主机目录执行,订阅凭据留在主机。插件不改写 DSH 的默认模型,不为员工创建同名主机目录,已有主机会话只提取一次原有主机来源并保存。
45
-
46
- 需要远程主机连接组件 0.7.37 或更新的 0.7.x、联网助手 0.4.9,以及支持公开会话归属接口的主机组件 S0.4.26。主机来源保存于官方 storage.domain 的会话元数据表,每轮仅由连接组件检查一次主机目录,不检查本机占位目录。
47
-
48
- Claude 员工MCP的stdio通道保持在当前原生客户端上。底层员工SSH/Unix流断开时,在途工具只返回结果未知,不重放;连接恢复后下一次新工具调用串行重新连接并初始化。同一DSH会话无需新建;若连接/绑定已撤销或DSH桥工具在途结束本轮,网络恢复后在原会话发新消息,沿原生编号续接。只使用原已核验的设备/账户/绑定,不跨代偷接。
49
-
50
- DSH技能工具仅使用DSH公布的目录,主机原生技能按各自原生指令加载;本机文件夹下主机 Claude 的主会话和子代理都能用原生 Skill 加载主机账户的用户级技能(0.9.0-toolbridge.20 起),技能里的 `!` 内联命令需要原生 Bash,原生 Bash 仍关闭,所以不会在主机执行,该技能加载失败并明确报错;桥接工具描述仅使用 DSH 原文;同步后的原生技能入口提供资源路径。
51
-
52
- Claude 本机 Bash 会单独消费员工桥代理的控制诊断,不把它交给模型当作命令输出;真实传输中断仍提示结果未知。命令自身的标准输出、标准错误与退出码照常返回。非UTF-8流不拒绝,按原始字节base64返回并增加对应stdoutEncoding/stderrEncoding标记;有效UTF-8格式不变。没有新增原始字节上限,编码后的消息沿既有512MB容量核验。
53
-
54
- 模型列表读取会随连接状态或连接代际变化取消,连接恢复时通过官方机制刷新。目录失败原因写入当前 profile 的 `ai-workbench-remote-agent/logs/model-catalog.jsonl`(脱敏);未增加单次读取时限或重试。
55
-
56
- ## 会话行为
57
-
58
- 新的用户轮启动一个新助手进程,按原生会话编号恢复上下文;退出前尚未结算的原轮则附着原进程,仅取回该轮输出、结果和用量,不重发原输入。主机会话始终使用创建时保存的主机和目录;工作区之后的选择只影响新会话。
59
-
60
- 同一 DSH 会话切换 Claude/Codex 时,切回会接本品牌最近的远端会话,并补充它尚未见过的可见对话;首次使用某品牌则带入全部可见历史。工具内部状态、推理和技术详情不转交。历史超出既有 `acpMaxMessageBytes` 容量时,只带能容纳的最近完整轮,并在技术详情说明省略数量;当前输入保持完整,超限仍明确失败。没有新增设置、重试或时限。
61
-
62
- 断线会结束本轮;已派发的操作可能已部分执行,请先检查文件。恢复连接后可在原会话继续。旧进程清理和技术详情记录尽力而为,不阻止发起下一轮。续接明确遇到原线程被占用时,使用 S0.4.26 的会话归属和原子结束接口:只有唯一匹配的旧进程确实已断开、主机明确确认退出后,才接回同一线程一次;不会新建替代线程、重发用户输入或抢占活跃会话。旧版无归属进程不能安全清理,需等待主机按现有策略回收;失败或释放结果未知则说明本轮输入未发送。原生本机会话恢复的兼容性及实际设备结果见本轮交付证据,未验证项不作为已通过。
63
-
64
- DSH 启动和打开模型菜单时读取一次主机型号列表。发送时不再查询目录或预核所选型号;所选型号不可用时,请在模型菜单重新选择。
65
-
66
- ## 执行位置与权限
67
-
68
- - 员工选本机文件夹,就在员工电脑上执行;通道失败不会改在主机运行。
69
- - 订阅凭据留在主机,不放进命令参数、日志或技术详情。
70
- - 跟随 DSH 当前权限:完全权限不问、工作区内修改先问、仅可查看只读。需要审批时使用官方卡片。
71
- - 一条会话对应一个文件来源;主机来源不会随工作区后续选择改变,本机来源继续沿用原生绑定。
72
-
73
- Codex 员工端只使用随包提供的原生组件,通道等待本次组件的启动标记后才完成开通,不逐通道执行摘要或版本校验。当前员工端支持范围以发布验证记录为准,不让员工手填执行器路径。
74
-
75
- 本机附加扩展本次不启用,不修改本机配置。能安全显示的扩展名称会用普通提示说明;协议细节只进技术详情,不能安全显示的名称不打印原文。
76
-
77
- ## 管理员参数
78
-
79
- 参数经官方 Config schema 编辑,显式值优先。只有会话运行方式,没有运行模式选项或单次执行路径。
80
-
81
- | 参数 | 默认值 | 作用 |
82
- | --- | ---: | --- |
83
- | acpMaxMessageBytes | 512000000 | 会话消息容量;默认512 MB(十进制),自有Codex适配器接收参数另留协议外壳余量;不代表模型上下文或上游Claude适配器承诺 |
84
- | brokerMaxFrameBytes | 2097152 | 主机回传单段容量 |
85
- | brokerControlMaxBytes | 1048576 | 主机会话管理回复容量 |
86
- | employeeShellKillGraceMs | 1000 | 本机命令连接取消后的清理宽限毫秒 |
87
-
88
- 容量超限明确失败,不截断成有效消息。参数范围、生效时机和调整后果由官方 schema 与参数页显示;以上四条执行不变量不可关闭。
89
-
90
- ## 技术详情与交付
91
-
92
- 技术详情只写官方 profile 下本地私有日志,并由既有技术详情界面展开显示。写入失败不覆盖原始错误、不等待远端投递回执。连接与独立工具操作分别保留首次关闭原因,普通工具退出不再占用连接首因;首先观察到的原因不自动等同跨层根因。
93
-
94
- 工程验证和独立审查见 `docs/evidence/2026-10-25-X-host-source-v2/`;AUTH profile 夹具补齐与最终 main 全套复验见其中的 `auth-profile-return.md`。固定包摘要及真实设备验收状态以项目 X 回执为准。插件不修改 DSH 核心,不添加启动器或自定义 profile。
95
-
96
- 远程助手参数页只显示官方 ConfigForms 当前值,不提供保存、放弃或恢复继承值;修改请使用 DSH 官方 Config“打开配置文件”入口。
97
-
98
- 模型目录在官方启动读取时获取,并在连接变为 connected 时经官方注册刷新;官方菜单打开或重试读取缓存是 DSH 官方限制,本插件不改官方菜单或核心。真正不支持的推理档位由 DSH 预检,其英文提示保留为观察项。
99
-
100
- U1(本版保留):Codex 和 Claude 的 ACP 用量按本次 prompt 逐轮全额结算一次,不减历史基线。冷接回只减同一 prompt 已在 DSH 落盘的部分;可靠终态先持久化,原 broker 回收后仍可补记未落盘用量。订阅额度卡读取官方额度窗口,不由 token 数推算百分比。旧 I3 系统规则传递机制已删除。
101
-
102
- T3(0.9.0-toolbridge.33):在已连接、当前员工目录已接纳的 Codex 路径,同轮登录核验与端点准备重叠;两项均成功并再次核对目标、连接代次与物理目录后才开工,每轮核验与正常完成后结束 broker 的做法保留。当前输入已完整列出同一技能目录时,skill 工具省去重复名字数组;目录不完整或只有历史目录时保留原快照。未改变首轮工具可见性,没有新增设置、限制或错误码。本机受控时延与工具字节测量不代表远机实测速率或实际 API token 节省;DSH 原生本轮因缺独立登录未测。
103
-
104
- B6(0.9.0-toolbridge.30,本版继承):Codex 员工执行环境接纳原生 turn/steer,含桥主机组件需 aw.16;冷恢复承接 DSH 准备阶段已固定的当前模型与推理档,不再在后置请求钩子用失败轮配置改档;历史专用元数据保留原轮模型和 native 关联。原失败冷轮可落定并按原 native 会话继续,原输入不重放。U1 的本次 prompt 用量修复来自 X.28,本版继续保留。
105
-
106
- 本版同时继承 B6 X.32 对插话与冷恢复链十类无效状态的清理;当前步骤选择、旧 JSON 字段的读取、原轮可靠结果、取消与防重放行为保持。
11
+ 详细性能分布、实测边界和源码固定记录见本轮发布说明与交件回执。测试只使用自建本机进程、临时文件与受控链路,不将合成夹具称为tank真实任务或员工GUI验收。
@@ -1,7 +1,8 @@
1
1
  /** L 0.7.10 officialReason v1 consumer validation; preserve canonical bytes only. */
2
- 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'];
2
+ const markers = ['AW_REMOTE_COMMAND_KILL_FAILED', 'AUTH_STATUS_JSON_INVALID:SyntaxError', 'Permission denied', 'Host key verification failed', 'Connection refused', 'Connection closed', 'Broken pipe', 'Connection reset by peer', 'Connection timed out', 'command not found', 'No such file or directory'];
3
3
  const names = ['Error', 'TypeError', 'SyntaxError', 'RangeError', 'AbortError', 'DOMException', 'UnknownError'];
4
4
  const codes = ['ENOENT', 'EPERM', 'ESRCH', 'EACCES', 'EINVAL', 'EPIPE', 'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ABORT_ERR', 'UNKNOWN'];
5
+ const transportReasons = ['CONNECTION_REFUSED', 'CONNECTION_RESET', 'PIPE_CLOSED', 'CONNECTION_CLOSED', 'CONNECTION_TIMEOUT', 'CANCELLED', 'SSH_EXIT_NONZERO', 'SSH_STDERR_NONEMPTY', 'SSH_PROCESS_FAILED'];
5
6
  const stages = ['ssh-status', 'ssh-result', 'remote-frame', 'auth-status', 'connect-check-login', 'integration-pre-login', 'process-spawn', 'process-stdin', 'process-output', 'process-runner'];
6
7
  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'];
7
8
  const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
@@ -22,6 +23,6 @@ export function validOfficialReason(value) {
22
23
  }
23
24
  if (!object(v) || JSON.stringify(v) !== value || v.version !== 1 || !member(stages, v.stage) || !member(reasons, v.reason))
24
25
  return false;
25
- 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) };
26
+ const fields = { transportReason: x => member(transportReasons, x), 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) };
26
27
  return Object.entries(v).every(([key, item]) => Object.hasOwn(fields, key) && fields[key](item));
27
28
  }
package/dist/broker.d.ts CHANGED
@@ -106,9 +106,13 @@ export declare class BrokerTransport {
106
106
  private send;
107
107
  }
108
108
  export type SshArgv = (target: ConnectTarget) => string[];
109
+ export interface SshMultiplex {
110
+ controlPath: string;
111
+ mode: 'master' | 'reuse';
112
+ }
109
113
  export interface BrokerIo {
110
114
  run: (command: string, signal?: AbortSignal) => Promise<string>;
111
- attach: (command: string) => Promise<Attachment>;
115
+ attach: (command: string, multiplex?: SshMultiplex) => Promise<Attachment>;
112
116
  }
113
117
  export declare function controlNeed(stderr: string): NeedError;
114
118
  export declare function sshIo(target: ConnectTarget, argv: SshArgv, maxControlBytes: number): BrokerIo;
package/dist/broker.js CHANGED
@@ -601,7 +601,7 @@ export function controlNeed(stderr) {
601
601
  }
602
602
  export function sshIo(target, argv, maxControlBytes) {
603
603
  const base = argv(target);
604
- return { attach: async (command) => spawn('ssh', [...base, command], { stdio: ['pipe', 'pipe', 'pipe'] }), run: (command, signal) => new Promise((resolve, reject) => {
604
+ return { attach: async (command, multiplex) => spawn('ssh', [...(multiplex ? multiplex.mode === 'master' ? ['-M', '-S', multiplex.controlPath, '-o', 'ControlPersist=no'] : ['-S', multiplex.controlPath, '-o', 'ControlMaster=no', '-o', 'ProxyCommand=/usr/bin/false'] : []), ...base, command], { stdio: ['pipe', 'pipe', 'pipe'] }), run: (command, signal) => new Promise((resolve, reject) => {
605
605
  const child = spawn('ssh', ['-n', ...base, command], { stdio: ['ignore', 'pipe', 'pipe'] });
606
606
  let bytes = Buffer.alloc(0);
607
607
  let diagnostics = Buffer.alloc(0);
@@ -1,3 +1,4 @@
1
+ import { openEmployeeSshMaster } from './employee-ssh-master.ts';
1
2
  import { type CloseCause } from './close-diagnostics.ts';
2
3
  import { type EmployeeLease, type EmployeeLeaseOptions, type EmployeeNetworkApi, type EmployeeWorkspace } from './employee-endpoint.ts';
3
4
  import { type EmployeeMcpOptions } from './employee-mcp.ts';
@@ -21,6 +22,7 @@ interface Options {
21
22
  open: (target: ConnectTarget, project: Project, request: RuntimeRequest) => Promise<Runtime>;
22
23
  /** Explicit component-test ports only. Production supplies none. */
23
24
  ports?: {
25
+ master: typeof openEmployeeSshMaster;
24
26
  lease: (options: EmployeeLeaseOptions, signal?: AbortSignal) => Promise<EmployeeLease>;
25
27
  mcp: (options: EmployeeMcpOptions) => Promise<{
26
28
  routing: EmployeeRouting;
@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
6
6
  }
7
7
  return path;
8
8
  };
9
+ import { openEmployeeSshMaster } from "./employee-ssh-master.js";
9
10
  import { EMPLOYEE_EXECUTION_NOTICE as NOTICE } from "./employee-presentation.js";
10
11
  import { CloseDiagnostics, closeCode } from "./close-diagnostics.js";
11
12
  import { openEmployeeLease } from "./employee-endpoint.js";
@@ -58,16 +59,20 @@ export function createClaudeLocalProvider(options) {
58
59
  throw failure('DEPENDENCY_REQUIRED');
59
60
  io = sshIo(target, l.sshArgs, control);
60
61
  } return io; };
62
+ let master;
61
63
  let lease, mcp, base;
62
64
  let privateTail = Promise.resolve();
63
65
  try {
64
66
  const unscoped = (observation) => { privateTail = privateTail.then(() => options.recordUnscoped(request, observation)).catch(() => { console.warn('CLAUDE_DIAGNOSTIC_DROPPED'); }); };
65
67
  const network = options.getNetwork();
66
68
  lease = await (options.ports?.lease ?? openEmployeeLease)({ closeDiagnostics, getConnect: () => options.getConnect(), getNetwork: options.getNetwork, readWorkspace: () => options.readWorkspace(request.sessionId), host: target, sessionId: request.sessionId, control: async (_target, command, signal) => (await transport()).run(command, signal), detail: unscoped }, request.signal);
67
- const shell = (options.ports?.shell ?? createEmployeeShell)({ closeDiagnostics, target: lease.target, sshArgs: lease.sshArgs, maxBytes: maximum, killGraceMs: grace, attach: async (spec) => (await transport()).attach([spec.command, ...spec.args].map(shellQuote).join(' ')) });
69
+ master = await (options.ports?.master ?? openEmployeeSshMaster)({ sshArgs: lease.sshArgs, maxBytes: maximum, killGraceMs: grace, signal: AbortSignal.any([lease.signal, ...request.signal ? [request.signal] : []]), closeDiagnostics, attach: async (spec, multiplex) => (await transport()).attach([spec.command, ...spec.args].map(shellQuote).join(' '), multiplex) });
70
+ const sshControlRoot = master?.root;
71
+ const shell = (options.ports?.shell ?? createEmployeeShell)({ sshControlRoot, closeDiagnostics, target: lease.target, sshArgs: lease.sshArgs, maxBytes: maximum, killGraceMs: grace, attach: async (spec) => (await transport()).attach([spec.command, ...spec.args].map(shellQuote).join(' '), master ? { controlPath: master.outerControlPath, mode: 'reuse' } : undefined) });
68
72
  request.toolBridge?.enable(event => details.record(event));
69
- mcp = await (options.ports?.mcp ?? openEmployeeMcp)({ bridge: request.toolBridge, closeDiagnostics, lease, maxBytes: maximum, killGraceMs: grace, runShell: shell, activeSignal: () => entry?.active?.signal, captureDetail: () => { const sink = entry?.active?.details; if (!sink)
73
+ mcp = await (options.ports?.mcp ?? openEmployeeMcp)({ bridge: request.toolBridge, sshControlRoot, closeDiagnostics, lease, maxBytes: maximum, killGraceMs: grace, runShell: shell, activeSignal: () => entry?.active?.signal, captureDetail: () => { const sink = entry?.active?.details; if (!sink)
70
74
  throw failure('EMPLOYEE_NO_ACTIVE_TURN'); return observation => sink.record(observation); }, detail: unscoped });
75
+ master.signal.throwIfAborted();
71
76
  entry = { runtime: undefined, scope, lease, details, request };
72
77
  const row = entry;
73
78
  base = await options.open(target, { name: workspace.workspaceId, path: target.session.root }, openRequest());
@@ -79,7 +84,7 @@ export function createClaudeLocalProvider(options) {
79
84
  const modelLifetime = new AbortController();
80
85
  const transientLease = () => underlying.broker?.supportsRecovery && lease.signal.aborted && ['CONNECTION_LOST', 'EMPLOYEE_ENDPOINT_UNAVAILABLE'].includes(closeCode(lease.signal.reason));
81
86
  const closeLocal = (cause) => localClosing ??= Promise.resolve().then(async () => {
82
- for (const operation of [() => endpoint.close(cause), () => row.lease.close(cause)])
87
+ for (const operation of [() => endpoint.close(cause), () => master?.close(), () => row.lease.close(cause)])
83
88
  try {
84
89
  await operation();
85
90
  }
@@ -109,26 +114,29 @@ export function createClaudeLocalProvider(options) {
109
114
  throw failure('TURN_BUSY'); row.active = { signal, details: row.details }; }, endTurn: () => { row.active = undefined; } }, dispose: cause => close(false, cause), detach: cause => close(true, cause) };
110
115
  entries.set(request.sessionId, row);
111
116
  const endpointAborted = () => {
112
- const cause = { layer: 'endpoint', initiator: 'claude.lease-abort', reason: closeCode(lease?.signal.reason, 'EMPLOYEE_CONTEXT_CHANGED'), action: 'abort' };
117
+ const reason = lease?.signal.reason ?? master?.signal.reason ?? mcp?.signal?.reason;
118
+ const cause = { layer: 'endpoint', initiator: 'claude.lease-abort', reason: closeCode(reason, 'EMPLOYEE_CONTEXT_CHANGED'), action: 'abort' };
113
119
  if (transientLease()) {
114
120
  void closeLocal(cause);
115
121
  return;
116
122
  }
117
- modelLifetime.abort(lease?.signal.reason ?? mcp?.signal?.reason);
123
+ modelLifetime.abort(reason);
118
124
  void close(false, cause).catch(() => console.warn('CLAUDE_CLEANUP_FAILED'));
119
125
  };
126
+ master?.signal.addEventListener('abort', endpointAborted, { once: true });
120
127
  lease.signal.addEventListener('abort', endpointAborted, { once: true });
121
128
  mcp.signal?.addEventListener('abort', endpointAborted, { once: true });
122
- if (lease.signal.aborted) {
123
- await close(false, { layer: 'endpoint', initiator: 'claude.open-aborted', reason: closeCode(lease.signal.reason, 'EMPLOYEE_CONTEXT_CHANGED'), action: 'abort' });
124
- throw failure('EMPLOYEE_CONTEXT_CHANGED');
129
+ if (lease.signal.aborted || master.signal.aborted || mcp.signal?.aborted) {
130
+ const reason = lease.signal.reason ?? master.signal.reason ?? mcp.signal?.reason;
131
+ await close(false, { layer: 'endpoint', initiator: 'claude.open-aborted', reason: closeCode(reason, 'EMPLOYEE_CONTEXT_CHANGED'), action: 'abort' });
132
+ throw reason ?? failure('EMPLOYEE_CONTEXT_CHANGED');
125
133
  }
126
134
  return row.runtime;
127
135
  }
128
136
  catch (error) {
129
137
  closeDiagnostics.record({ layer: 'runtime', initiator: 'claude.open-failure', reason: closeCode(error, 'EMPLOYEE_OPEN_FAILED'), action: 'failure' });
130
138
  const cause = { layer: 'runtime', initiator: 'claude.open-cleanup', reason: 'EMPLOYEE_OPEN_FAILED', action: 'close' };
131
- for (const clean of [() => mcp?.close(cause), () => lease?.close(cause), () => base?.dispose?.(cause)]) {
139
+ for (const clean of [() => mcp?.close(cause), () => master?.close(), () => lease?.close(cause), () => base?.dispose?.(cause)]) {
132
140
  try {
133
141
  await clean();
134
142
  }
@@ -13,6 +13,7 @@ export interface CloseCause {
13
13
  exitCode?: number | null;
14
14
  signal?: string | null;
15
15
  remoteReason?: string;
16
+ stage?: string;
16
17
  changedFields?: readonly string[];
17
18
  changes?: readonly CloseChange[];
18
19
  }
@@ -18,7 +18,7 @@ export class CloseDiagnostics {
18
18
  recordUsing(sink, cause) {
19
19
  if (this.state.first)
20
20
  return;
21
- const payload = Object.freeze({ layer: cause.layer, initiator: cause.initiator, reason: cause.reason, ...cause.remoteReason ? { remoteReason: cause.remoteReason } : {}, ...cause.exitCode !== undefined ? { exitCode: cause.exitCode } : {}, ...cause.signal !== undefined ? { signal: cause.signal } : {}, stage: this.stage, clock: 'client-monotonic', elapsedMs: performance.now() - this.started });
21
+ const payload = Object.freeze({ layer: cause.layer, initiator: cause.initiator, reason: cause.reason, ...cause.remoteReason ? { remoteReason: cause.remoteReason } : {}, ...cause.exitCode !== undefined ? { exitCode: cause.exitCode } : {}, ...cause.signal !== undefined ? { signal: cause.signal } : {}, stage: cause.stage ?? this.stage, clock: 'client-monotonic', elapsedMs: performance.now() - this.started });
22
22
  this.state.first = payload;
23
23
  try {
24
24
  sink({ kind: 'session', severity: 'warning', code: 'REMOTE_CLOSE_REASON', summary: '首次观察到的关闭原因', payload });
@@ -29,6 +29,7 @@ export declare class EmployeeSocketTransport implements Transport {
29
29
  close(cause?: CloseCause): Promise<void>;
30
30
  }
31
31
  export interface EmployeeMcpOptions {
32
+ sshControlRoot?: string;
32
33
  bridge?: ToolBridge;
33
34
  closeDiagnostics?: CloseDiagnostics;
34
35
  lease: EmployeeLease;
@@ -185,7 +185,7 @@ export async function openEmployeeMcp(options) {
185
185
  options.lease.signal.addEventListener('abort', aborted, { once: true });
186
186
  if (options.lease.signal.aborted)
187
187
  throw options.lease.signal.reason;
188
- return { routing: employeeRouting(options.lease.target, socketPath, options.maxBytes), signal: options.lease.signal, close };
188
+ return { routing: employeeRouting(options.lease.target, socketPath, options.maxBytes, options.sshControlRoot), signal: options.lease.signal, close };
189
189
  }
190
190
  catch (error) {
191
191
  await close({ layer: 'relay', initiator: 'mcp.open-failure', reason: closeCode(error, 'MCP_OPEN_FAILED'), action: 'failure' });
@@ -15,4 +15,4 @@ export interface EmployeeRouting {
15
15
  }[];
16
16
  toolAliases: Record<string, string>;
17
17
  }
18
- export declare function employeeRouting(target: EmployeeEndpointTarget, socketPath: string, maxBytes: number): EmployeeRouting;
18
+ export declare function employeeRouting(target: EmployeeEndpointTarget, socketPath: string, maxBytes: number, sshControlRoot?: string): EmployeeRouting;
@@ -1,8 +1,8 @@
1
1
  /** Runs on the host. Only target discovery and SSH stdio forwarding; never user tools. */
2
2
  export const EMPLOYEE_TARGET_PYTHON = String.raw `
3
- import os,sys,json,subprocess,selectors,shlex,re
3
+ import os,sys,json,subprocess,selectors,shlex,re,tempfile,stat
4
4
  def fail(code):
5
- sys.stderr.write(json.dumps({"code":code})+"\n");sys.exit(254)
5
+ sys.stderr.write(json.dumps({"code":code,"stage":"relay.target"})+"\n");sys.exit(254)
6
6
  try:
7
7
  x=json.loads(sys.argv[1]);e=x["endpoint"];b=x["bridge"];maximum=x["maxBytes"]
8
8
  if not isinstance(maximum,int) or isinstance(maximum,bool) or maximum<1:fail("EMPLOYEE_RELAY_SETTINGS_INVALID")
@@ -38,11 +38,16 @@ export const EMPLOYEE_RELAY_PYTHON = EMPLOYEE_TARGET_PYTHON + String.raw `
38
38
  if not isinstance(socket,str) or not socket.startswith("/") or "\x00" in socket:fail("EMPLOYEE_RELAY_SOCKET_INVALID")
39
39
  command=shlex.join(["/usr/bin/nc","-U",socket])
40
40
  import asyncio,signal
41
+ control=x.get("sshControlRoot")
42
+ if control is not None:
43
+ if not isinstance(control,str) or not re.fullmatch(r"/private/tmp/aw-x-master-[a-f0-9]{32}",control):fail("EMPLOYEE_RELAY_SOCKET_INVALID")
44
+ info=os.lstat(control)
45
+ if not stat.S_ISDIR(info.st_mode) or stat.S_IMODE(info.st_mode)!=0o700 or info.st_uid!=os.getuid():fail("EMPLOYEE_RELAY_SOCKET_INVALID")
41
46
  class Disconnected(Exception):pass
42
47
  class Relay:
43
48
  def __init__(self,output):
44
49
  self.output=output;self.process=None;self.ready=False;self.initialize=None;self.initialized=None;self.serial=0
45
- self.pending={};self.front_ids={};self.server_ids={};self.readers=set();self.tasks={}
50
+ self.pending={};self.front_ids={};self.server_ids={};self.readers=set();self.tasks={};self.diagnostics={};self.stages={}
46
51
  self.connect_lock=asyncio.Lock();self.write_lock=asyncio.Lock();self.output_lock=asyncio.Lock()
47
52
  def identity(self):
48
53
  self.serial+=1
@@ -58,6 +63,17 @@ export const EMPLOYEE_RELAY_PYTHON = EMPLOYEE_TARGET_PYTHON + String.raw `
58
63
  async with self.write_lock:
59
64
  if process is not self.process:raise Disconnected()
60
65
  process.stdin.write(self.encode(message));await process.stdin.drain()
66
+ def diagnostic(self,process):
67
+ diagnostic=self.diagnostics.pop(process,None)
68
+ if diagnostic is None:return None
69
+ try:
70
+ diagnostic.seek(0);raw=diagnostic.read(maximum+1)
71
+ match=re.fullmatch(rb"BRIDGE_ERROR ([A-Z][A-Z0-9_]{0,63})\n",raw)
72
+ known=set("USAGE ROOT_FORBIDDEN EMPLOYEE_REQUIRED INVALID_HOME DEVELOPMENT_FORBIDDEN SETTINGS_REQUIRED UNTRUSTED_SETTINGS WRITABLE_SETTINGS SETTINGS_INVALID UNSAFE_STATE SOCKET_PATH_TOO_LONG KEY_GENERATION_FAILED IDENTITY_INCOMPLETE STATE_CORRUPT GENERATION_EXHAUSTED DEVICE_BUSY DEVICE_ACCOUNT_MISMATCH DEVICE_KEY_MISMATCH ENDPOINT_NOT_READY ENDPOINT_OFFLINE INSTANCE_MISMATCH STREAM_NOT_PENDING STREAM_ALREADY_BOUND BRIDGE_BUSY BAD_FRAME CONTROL_TOO_LARGE CONTROL_BACKPRESSURE HANDSHAKE_OBSERVATION_EXPIRED REGISTER_LEASE_EXPIRED TRANSPORT_CLOSED BRIDGE_OS_ERROR BRIDGE_INTERNAL_ERROR".split())
73
+ code=match.group(1).decode("ascii") if match else None
74
+ return code if code in known else None
75
+ except OSError:return None
76
+ finally:diagnostic.close()
61
77
  async def disconnect(self,process,report=True):
62
78
  if self.process is process:
63
79
  if self.ready and report:sys.stderr.write("CLAUDE_EMPLOYEE_MCP_UNKNOWN\n");sys.stderr.flush()
@@ -72,6 +88,8 @@ export const EMPLOYEE_RELAY_PYTHON = EMPLOYEE_TARGET_PYTHON + String.raw `
72
88
  try:process.kill()
73
89
  except ProcessLookupError:pass
74
90
  await process.wait()
91
+ code=self.diagnostic(process);stage=self.stages.pop(process,"relay.ssh-start")
92
+ if report:sys.stderr.write(json.dumps({"code":code or "EMPLOYEE_TRANSPORT_UNKNOWN","stage":stage})+"\n");sys.stderr.flush()
75
93
  async def read(self,process):
76
94
  try:
77
95
  while True:
@@ -108,15 +126,30 @@ export const EMPLOYEE_RELAY_PYTHON = EMPLOYEE_TARGET_PYTHON + String.raw `
108
126
  async with self.connect_lock:
109
127
  if self.process is not None and self.ready:return self.process
110
128
  if self.initialize is None:raise Disconnected()
111
- process=await asyncio.create_subprocess_exec("/usr/bin/ssh","-T",*args,command,stdin=asyncio.subprocess.PIPE,stdout=asyncio.subprocess.PIPE,limit=maximum+1)
129
+ ssh_args=list(args);diagnostic=None
130
+ proxy=[i for i,arg in enumerate(ssh_args) if arg.startswith("ProxyCommand=")]
131
+ if len(proxy)==1:
132
+ try:
133
+ diagnostic=tempfile.NamedTemporaryFile(prefix="aw-x-relay-")
134
+ ssh_args[proxy[0]]+=" 2>"+shlex.quote(diagnostic.name.replace("%","%%"))
135
+ except OSError:
136
+ if diagnostic is not None:diagnostic.close()
137
+ diagnostic=None
138
+ # MCP本轮持有标准OpenSSH master;子MCP与Bash只在同一租约内复用。
139
+ multiplex=["-S",control+"/ssh","-o","ControlMaster=no","-o","ProxyCommand=/usr/bin/false"] if control is not None else []
140
+ try:process=await asyncio.create_subprocess_exec("/usr/bin/ssh","-T",*multiplex,*ssh_args,command,stdin=asyncio.subprocess.PIPE,stdout=asyncio.subprocess.PIPE,limit=maximum+1)
141
+ except BaseException:
142
+ if diagnostic is not None:diagnostic.close()
143
+ raise
112
144
  self.process=process;self.ready=False
145
+ self.stages[process]="relay.mcp-initialize";self.diagnostics[process]=diagnostic
113
146
  reader=asyncio.create_task(self.read(process));self.readers.add(reader);reader.add_done_callback(self.readers.discard)
114
147
  try:
115
148
  reply=await self.request(process,{"jsonrpc":"2.0","method":"initialize","params":self.initialize})
116
149
  if "error" in reply:raise Disconnected()
117
150
  await self.write(process,{"jsonrpc":"2.0","method":"notifications/initialized"})
118
151
  if process is not self.process:raise Disconnected()
119
- self.initialized=reply["result"];self.ready=True
152
+ self.initialized=reply["result"];self.ready=True;self.stages[process]="relay.mcp-active"
120
153
  return process
121
154
  except asyncio.CancelledError:
122
155
  await self.disconnect(process);raise
@@ -186,11 +219,11 @@ export const EMPLOYEE_RELAY_PYTHON = EMPLOYEE_TARGET_PYTHON + String.raw `
186
219
  try:asyncio.run(relay())
187
220
  except asyncio.CancelledError:pass
188
221
  ` + EMPLOYEE_PYTHON_ERRORS;
189
- export function employeeRouting(target, socketPath, maxBytes) {
222
+ export function employeeRouting(target, socketPath, maxBytes, sshControlRoot) {
190
223
  const names = ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash'];
191
224
  return {
192
225
  // ACP0.94.0 uses absence of "type" to recognize stdio. Do not add type:"stdio".
193
- mcpServers: [{ name: 'employee', command: '/usr/bin/python3', args: ['-c', EMPLOYEE_RELAY_PYTHON, JSON.stringify({ endpoint: target.endpoint, bridge: target.bridge, socketPath, maxBytes })], env: [] }],
226
+ mcpServers: [{ name: 'employee', command: '/usr/bin/python3', args: ['-c', EMPLOYEE_RELAY_PYTHON, JSON.stringify({ endpoint: target.endpoint, bridge: target.bridge, socketPath, maxBytes, ...(sshControlRoot ? { sshControlRoot } : {}) })], env: [] }],
194
227
  toolAliases: Object.fromEntries(names.map(name => [name, 'mcp__employee__' + name])),
195
228
  };
196
229
  }
@@ -17,6 +17,7 @@ export type EmployeeShell = (request: {
17
17
  }) => Promise<EmployeeShellResult>;
18
18
  interface Options {
19
19
  closeDiagnostics?: CloseDiagnostics;
20
+ sshControlRoot?: string;
20
21
  target: EmployeeEndpointTarget;
21
22
  sshArgs: readonly string[];
22
23
  maxBytes: number;
@@ -2,13 +2,20 @@ import { randomUUID } from 'node:crypto';
2
2
  import { EMPLOYEE_PYTHON_ERRORS } from "./employee-relay.js";
3
3
  import { NeedError } from "./remote.js";
4
4
  const SHELL_PYTHON = String.raw `
5
- import sys,json,subprocess,shlex,tempfile,signal,re
5
+ import sys,json,subprocess,shlex,tempfile,signal,re,os,stat
6
6
  def fail(code):
7
7
  sys.stderr.write(json.dumps({"code":code})+"\n");sys.exit(254)
8
8
  try:
9
9
  x=json.loads(sys.argv[1]);e=x["endpoint"];args=list(x["sshArgs"]);cwd=x["cwd"]
10
10
  proxy=[i for i,arg in enumerate(args) if arg.startswith("ProxyCommand=")]
11
11
  if len(proxy)!=1:fail("EMPLOYEE_BRIDGE_PROTOCOL_INVALID")
12
+ control=x.get("sshControlRoot");multiplex=[]
13
+ if control is not None:
14
+ if not isinstance(control,str) or not re.fullmatch(r"/private/tmp/aw-x-master-[a-f0-9]{32}",control):fail("EMPLOYEE_TRANSPORT_UNKNOWN")
15
+ info=os.lstat(control)
16
+ if not stat.S_ISDIR(info.st_mode) or stat.S_IMODE(info.st_mode)!=0o700 or info.st_uid!=os.getuid():fail("EMPLOYEE_TRANSPORT_UNKNOWN")
17
+ # OpenSSH默认会在mux不存在时退回普通连接;固定false出口明确禁止这条回退。
18
+ multiplex=["-S",control+"/ssh","-o","ControlMaster=no","-o","ProxyCommand=/usr/bin/false"]
12
19
  # User source is stdin, never argv. The sentinel preserves trailing newlines.
13
20
  wrapper="cd -- "+shlex.quote(cwd)+" || exit 254; "+"printf '%s\\n' "+shlex.quote('AW_EMPLOYEE_SHELL_STARTED '+x['executionId'])+" >&2; "+'aw_x_source=$(/bin/cat; printf x); aw_x_source='+chr(36)+'{aw_x_source%?}; eval "'+chr(36)+'aw_x_source"'
14
21
  command=shlex.join([e["endpointShell"],"-c",wrapper])
@@ -21,7 +28,7 @@ try:
21
28
  with tempfile.NamedTemporaryFile(prefix="aw-x-bridge-") as diagnostic:
22
29
  # S already escaped its own percent tokens. Only escape the added path.
23
30
  i=proxy[0];args[i]+=" 2>"+shlex.quote(diagnostic.name.replace("%","%%"))
24
- p=subprocess.Popen(["/usr/bin/ssh","-T"]+args+[command],stdin=sys.stdin,stdout=sys.stdout,stderr=sys.stderr)
31
+ p=subprocess.Popen(["/usr/bin/ssh","-T"]+multiplex+args+[command],stdin=sys.stdin,stdout=sys.stdout,stderr=sys.stderr)
25
32
  code=p.wait()
26
33
  diagnostic.seek(0)
27
34
  # S's raw CLI emits at most one fixed error line, never arbitrary diagnostics.
@@ -46,7 +53,7 @@ export function createEmployeeShell(options) {
46
53
  signal.throwIfAborted();
47
54
  const diagnostics = options.closeDiagnostics?.child(undefined, true);
48
55
  const executionId = randomUUID(), target = options.target;
49
- const child = await options.attach({ command: '/usr/bin/python3', args: ['-c', SHELL_PYTHON, JSON.stringify({ endpoint: target.endpoint, sshArgs: options.sshArgs, cwd: target.local.directory.path, executionId, maxBytes: options.maxBytes })] });
56
+ const child = await options.attach({ command: '/usr/bin/python3', args: ['-c', SHELL_PYTHON, JSON.stringify({ endpoint: target.endpoint, sshArgs: options.sshArgs, cwd: target.local.directory.path, executionId, maxBytes: options.maxBytes, ...(options.sshControlRoot ? { sshControlRoot: options.sshControlRoot } : {}) })] });
50
57
  return new Promise((yes, no) => {
51
58
  let settled = false, bytes = 0, stdout = [], stderr = [], reason, grace, timer;
52
59
  const finish = (error, code, exitSignal) => {
@@ -94,12 +101,12 @@ export function createEmployeeShell(options) {
94
101
  source = parsed.code;
95
102
  }
96
103
  catch { /* Never expose arbitrary transport diagnostics. */ }
97
- diagnostics?.record({ layer: 'relay', initiator: 'shell.process-close', reason: bridgeCode ?? source ?? 'EMPLOYEE_EXIT_UNKNOWN', action: 'failure', exitCode: code ?? null, signal: exitSignal ?? null });
104
+ diagnostics?.record({ layer: 'relay', initiator: 'shell.process-close', reason: bridgeCode ?? source ?? 'EMPLOYEE_EXIT_UNKNOWN', action: 'failure', exitCode: code ?? null, signal: exitSignal ?? null, stage: 'shell.ssh-start' });
98
105
  no(unknown(bridgeCode ?? source ?? 'EMPLOYEE_EXIT_UNKNOWN'));
99
106
  return;
100
107
  }
101
108
  if (code === null || code === undefined || code === 255 || end < 0) {
102
- diagnostics?.record({ layer: 'relay', initiator: 'shell.process-close', reason: bridgeCode ?? 'EMPLOYEE_EXIT_UNKNOWN', action: 'failure', exitCode: code ?? null, signal: exitSignal ?? null });
109
+ diagnostics?.record({ layer: 'relay', initiator: 'shell.process-close', reason: bridgeCode ?? 'EMPLOYEE_EXIT_UNKNOWN', action: 'failure', exitCode: code ?? null, signal: exitSignal ?? null, stage: 'shell.command-result' });
103
110
  no(unknown(bridgeCode ?? 'EMPLOYEE_EXIT_UNKNOWN'));
104
111
  return;
105
112
  }
@@ -0,0 +1,22 @@
1
+ import type { Attachment, SshMultiplex } from './broker.ts';
2
+ import type { CloseDiagnostics } from './close-diagnostics.ts';
3
+ export declare const EMPLOYEE_MASTER_PYTHON: string;
4
+ interface Options {
5
+ sshArgs: readonly string[];
6
+ maxBytes: number;
7
+ killGraceMs: number;
8
+ signal?: AbortSignal;
9
+ closeDiagnostics?: CloseDiagnostics;
10
+ attach: (spec: {
11
+ command: '/usr/bin/python3';
12
+ args: string[];
13
+ }, multiplex: SshMultiplex) => Promise<Attachment>;
14
+ }
15
+ export interface EmployeeSshMaster {
16
+ root: string;
17
+ outerControlPath: string;
18
+ signal: AbortSignal;
19
+ close(): Promise<void>;
20
+ }
21
+ export declare function openEmployeeSshMaster(options: Options): Promise<EmployeeSshMaster>;
22
+ export {};
@@ -0,0 +1,117 @@
1
+ import { mkdtemp, lstat, rm } from 'node:fs/promises';
2
+ import { randomUUID } from 'node:crypto';
3
+ import { join } from 'node:path';
4
+ import { NeedError } from "./remote.js";
5
+ // SSH本身提供复用与ready事件;stdin只持有本轮资源生命周期,不承载员工输入。
6
+ export const EMPLOYEE_MASTER_PYTHON = String.raw `
7
+ import sys,os,json,re,stat,subprocess,selectors,signal
8
+ x=json.loads(sys.argv[1]);root=x["root"];marker=x["marker"];process=None;owned=False
9
+ if not re.fullmatch(r"/private/tmp/aw-x-master-[a-f0-9]{32}",root) or not re.fullmatch(r"AW_EMPLOYEE_MASTER_READY_[a-f0-9]{32}",marker):sys.exit(254)
10
+ def stop(signum,frame):raise SystemExit(255)
11
+ for sig in [signal.SIGTERM,signal.SIGHUP,signal.SIGINT]:signal.signal(sig,stop)
12
+ try:
13
+ os.mkdir(root,0o700);owned=True
14
+ # LocalCommand在已认证且mux listener创建后执行,单次核验socket,不轮询或重拨。
15
+ ready="if test -S "+root+"/ssh; then echo "+marker+"; else echo AW_EMPLOYEE_MASTER_NOT_READY; fi"
16
+ args=["/usr/bin/ssh","-N","-M","-S",root+"/ssh","-o","ControlPersist=no","-o","PermitLocalCommand=yes","-o","LocalCommand="+ready]+x["sshArgs"]
17
+ process=subprocess.Popen(args,stdin=subprocess.DEVNULL,stdout=sys.stdout,stderr=sys.stderr)
18
+ watcher=selectors.DefaultSelector();watcher.register(sys.stdin,selectors.EVENT_READ)
19
+ # 子ssh退出发SIGCHLD唤醒select;不添加连接时限、轮询或重试。
20
+ signal.signal(signal.SIGCHLD,lambda signum,frame:None)
21
+ read_fd,write_fd=os.pipe();os.set_blocking(read_fd,False);os.set_blocking(write_fd,False);signal.set_wakeup_fd(write_fd);watcher.register(read_fd,selectors.EVENT_READ)
22
+ while process.poll() is None:
23
+ for key,_ in watcher.select():
24
+ if key.fileobj is sys.stdin:
25
+ if not os.read(sys.stdin.fileno(),1):raise SystemExit(0)
26
+ else:
27
+ try:os.read(read_fd,4096)
28
+ except BlockingIOError:pass
29
+ code=process.wait();sys.exit(code if code>=0 else 255)
30
+ finally:
31
+ if process is not None and process.poll() is None:
32
+ process.terminate();process.wait()
33
+ if owned:
34
+ socket=root+"/ssh"
35
+ try:
36
+ info=os.lstat(socket)
37
+ if stat.S_ISSOCK(info.st_mode) and info.st_uid==os.getuid():os.unlink(socket)
38
+ except FileNotFoundError:pass
39
+ try:os.rmdir(root)
40
+ except FileNotFoundError:pass
41
+ `;
42
+ const failure = () => new NeedError('EMPLOYEE_TRANSPORT_UNKNOWN', '员工执行连接已中断,原命令没有重放;恢复后可在原会话继续。', '本轮已建立的员工SSH连接');
43
+ export async function openEmployeeSshMaster(options) {
44
+ options.signal?.throwIfAborted();
45
+ const local = await mkdtemp('/private/tmp/aw-x-host-'), info = await lstat(local);
46
+ if (info.uid !== process.getuid?.() || (info.mode & 0o077) !== 0) {
47
+ await rm(local, { recursive: true, force: true });
48
+ throw failure();
49
+ }
50
+ const root = '/private/tmp/aw-x-master-' + randomUUID().replaceAll('-', ''), outerControlPath = join(local, 'ssh'), marker = 'AW_EMPLOYEE_MASTER_READY_' + randomUUID().replaceAll('-', ''), lifetime = new AbortController();
51
+ let child, closing, closed = false, exitCode = null, exitSignal = null;
52
+ const ready = Promise.withResolvers();
53
+ void ready.promise.catch(() => { });
54
+ const ended = Promise.withResolvers();
55
+ const aborted = () => { ready.reject(options.signal?.reason ?? failure()); void close().catch(() => { }); };
56
+ const close = () => closing ??= Promise.resolve().then(async () => {
57
+ options.signal?.removeEventListener('abort', aborted);
58
+ if (!lifetime.signal.aborted)
59
+ lifetime.abort(failure());
60
+ if (child && !closed) {
61
+ child.stdin.end();
62
+ const timer = setTimeout(() => { if (!closed)
63
+ child?.kill('SIGTERM'); }, options.killGraceMs);
64
+ timer.unref();
65
+ try {
66
+ await ended.promise;
67
+ }
68
+ finally {
69
+ clearTimeout(timer);
70
+ }
71
+ }
72
+ await rm(local, { recursive: true, force: true });
73
+ if (child && (exitCode !== 0 || exitSignal !== null))
74
+ throw failure();
75
+ });
76
+ try {
77
+ child = await options.attach({ command: '/usr/bin/python3', args: ['-c', EMPLOYEE_MASTER_PYTHON, JSON.stringify({ root, marker, sshArgs: options.sshArgs })] }, { controlPath: outerControlPath, mode: 'master' });
78
+ let pending = '', bytes = 0;
79
+ child.stdout.on('data', (data) => { bytes += data.length; if (bytes > options.maxBytes) {
80
+ ready.reject(failure());
81
+ void close().catch(() => { });
82
+ return;
83
+ } pending += data.toString('utf8'); let end; while ((end = pending.indexOf('\n')) >= 0) {
84
+ const line = pending.slice(0, end).replace(/\r$/, '');
85
+ pending = pending.slice(end + 1);
86
+ if (line === marker && !options.signal?.aborted)
87
+ ready.resolve();
88
+ else if (line === 'AW_EMPLOYEE_MASTER_NOT_READY')
89
+ ready.reject(failure());
90
+ } });
91
+ child.stderr.on('data', () => { });
92
+ child.stdin.on('error', () => { ready.reject(failure()); void close().catch(() => { }); });
93
+ child.once('error', () => { ready.reject(failure()); });
94
+ child.once('close', (code, signal) => { closed = true; exitCode = code; exitSignal = signal ?? null; ready.reject(failure()); ended.resolve(); if (!lifetime.signal.aborted)
95
+ lifetime.abort(failure()); options.closeDiagnostics?.record({ layer: 'relay', initiator: 'employee-master.close', reason: 'CONNECTION_LOST', stage: 'employee-master', action: 'exit', exitCode: code, signal: signal ?? null }); });
96
+ if (child.exitCode !== null || child.signalCode !== null) {
97
+ closed = true;
98
+ exitCode = child.exitCode;
99
+ exitSignal = child.signalCode;
100
+ ended.resolve();
101
+ ready.reject(failure());
102
+ }
103
+ options.signal?.addEventListener('abort', aborted, { once: true });
104
+ if (options.signal?.aborted)
105
+ aborted();
106
+ await ready.promise;
107
+ options.signal?.throwIfAborted();
108
+ return { root, outerControlPath, signal: lifetime.signal, close };
109
+ }
110
+ catch (error) {
111
+ try {
112
+ await close();
113
+ }
114
+ catch { }
115
+ throw error;
116
+ }
117
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ai-workbench/remote-agent",
3
- "version": "0.9.0-toolbridge.38",
3
+ "version": "0.9.0-toolbridge.40",
4
4
  "type": "module",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",