设备、节点与审批

用于设备配对和设备令牌、节点配对和调用、审批、Control UI 命令，以及自动化、技能和工具的 RPC 方法族。

设备配对和设备令牌¶

• device.pair.list 返回待批准和已批准的已配对设备。
• device.pair.setupCode 创建移动设置代码，并默认创建 PNG QR 数据 URL。它需要 operator.admin，并且有意从公开发现中省略。当前网关包含不透明的非机密 setupId、权威的 expiresAtMs、setupCode、可选的 qrDataUrl、gatewayUrl、非机密 auth 标签、urlSource，以及签发的 access 级别（full、limited 或 node）。旧版 protocol-v4 网关会省略 setupId 和 expiresAtMs，因此单独分发的客户端必须将这些生命周期字段视为可选。setupId 独立于引导凭据，并且不会嵌入到设置代码中。
• device.pair.setupStatus 核对调用者已经签发的一个设置凭据（{ setupId }）。它需要 operator.admin，从公开发现中省略，并在携带凭据的响应完成后返回 { completion }，或者在 bearer 已退役但无法确认响应投递时返回 { deliveryUncertain }。两者都使用与其对应事件相同的非机密负载。当两个字段都缺失时，网关未为该 setupId 保留任何结果。
• device.pair.approve、device.pair.reject 和 device.pair.remove 管理设备配对记录。
• device.pair.rename 分配操作员标签（{ deviceId, label }），该标签优先于客户端报告的显示名称，并在设备修复或重新批准后保留。
• device.token.rotate 在其已批准的角色和调用者作用域边界内轮换已配对设备令牌。
• device.token.revoke 在其已批准的角色和调用者作用域边界内吊销已配对设备令牌。

设置代码嵌入短期引导凭据。客户端不得在配对流程之外记录或持久化它。

配对范围的客户端只有在精确的设置交接已投递其凭据后才会收到 device.pair.setup.completed。其负载为 { setupId, deviceId, deviceName?, access, ts }；它从不包含引导凭据或令牌派生标识符。

如果响应在能够确认投递之前关闭，网关会保持 bearer 退役状态，并发出 device.pair.setup.deliveryUncertain 而不是成功。呈现客户端应向操作员提供一条路径，以检查或移除已配对设备并生成新的设置代码。

网关在消耗 bearer 时记录不确定结果，然后仅在响应投递完成后才将其提升为完成。操作员事件帧是尽力而为的，对于慢速订阅者会丢弃而不是关闭其套接字。因此，显示了设置代码的客户端必须在将代码呈现为已过期之前调用 device.pair.setupStatus。结果会在凭据自身过期后保留。

节点配对、调用和待处理工作¶

• node.pair.list、node.pair.approve、node.pair.reject 和 node.pair.remove 涵盖节点能力审批。node.pair.request 和 node.pair.verify 在 2026.7 中与独立的节点配对存储一起移除；待处理请求由 Gateway 在节点连接期间创建。
• node.list 和 node.describe 返回已知/已连接节点状态。
• node.rename 更新已配对节点标签。
• node.invoke 将命令转发到已连接节点。
• node.invoke.result 返回调用请求的结果。 节点仅在生命周期清理阻止执行、且在调用命令处理器或发出进度之前，才可返回 NODE_NOT_READY。Gateway 会在原始调用截止时间内最多重试此拒绝四次，并在每次分发时重新检查连接、配对和命令授权。一般 UNAVAILABLE 错误、断开连接、超时以及进度之后的失败不会重试。
• mcp.tools.call.v1 是无头节点主机命令，用于调用已配置的节点本地 MCP 工具。它通过 node.invoke 承载，要求节点声明该命令，并且仍受配对审批和 gateway.nodes.commands.deny 约束。
• node.event 将节点发起的事件带回网关。
• node.pluginTools.update 是替换已连接节点的 agent 可见插件/MCP 工具描述符的唯一发布路径；connect 参数不携带它们。
• node.pending.pull 和 node.pending.ack 是已连接节点队列 API。
• node.pending.enqueue 和 node.pending.drain 管理离线/断开连接节点的持久待处理工作。

审批族¶

• approval.history 返回按最新优先排序的、为 exec、plugin 和 system-agent 请求保留 30 天的终态审批（作用域 operator.approvals）。它支持游标分页以及可选的 kind 过滤器；待处理审批不是历史记录行。将每个游标视为不透明的服务器令牌，并原样返回精确值，不要填充、重写或添加字段。
• approval.get 和 approval.resolve 是与 kind 无关的持久审批方法（作用域 operator.approvals）。approval.get 返回经过净化的待处理或保留终态投影，并带有稳定的 urlPath；approval.resolve 接受规范审批 id、显式 kind 和决定，应用首个回答获胜的解析，并始终返回记录的规范结果。
• exec.approval.request、exec.approval.get、exec.approval.list 和 exec.approval.resolve 涵盖一次性 exec 审批请求以及待处理审批查找/重放。它们是同一持久审批注册表上的协议边界适配器。
• exec.approval.waitDecision 等待一个待处理 exec 审批并返回最终决定（超时则返回 null）。
• exec.approvals.get 和 exec.approvals.set 管理网关 exec 审批策略快照。
• exec.approvals.node.get 和 exec.approvals.node.set 通过节点中继命令管理节点本地 exec 审批策略。
• plugin.approval.request、plugin.approval.list、plugin.approval.waitDecision 和 plugin.approval.resolve 涵盖插件定义的审批流程。

在存储工作待处理期间，审批查询、历史记录、等待和解决保留其原始设备与账户权限。仅断开套接字不会取消已接纳的请求。 在提交准入之前撤销该权限会阻止裁决并扣留审批详情；待处理审批仍可供另一位授权审阅者使用。 已提交的裁决仍会被记录，并完成其等待中的操作。

Control UI 命令¶

• ui.command 允许 operator.write 调用者向发起请求的 Control UI 连接发送类型化的布局和导航命令，该连接必须声明 ui-commands 能力。
• 命令涵盖窗格拆分/关闭/聚焦、侧边栏可见性、终端/浏览器面板可见性和停靠，以及会话导航。
• Gateway 从经过身份验证的请求或代理轮次捕获的浏览器目标推导接收者，绝不从目标会话推导。其他连接保持其当前视图。缺失或已断开的请求者会以 UNAVAILABLE 失败；没有广播回退。
• 依赖旧版广播传递的独立调用者必须从 Control UI 连接或在那里启动的轮次发起这些操作。没有浏览器目标的独立调用不再控制已连接的仪表盘。

自动化、技能和工具¶

• 自动化：wake 安排立即或下一次心跳唤醒文本注入；cron.get、cron.list、cron.status、cron.add、cron.update、cron.remove、cron.run、cron.runs 管理计划任务。
• cron.run 将手动运行加入队列，并以 { ok: true, enqueued: true, runId } 确认。传入 waitTimeoutMs 可保持响应，直到该运行记录其结果：确认随后还会携带 run（即 cron.runs 为该 runId 返回的相同条目），或在运行已结束但其历史对调用者不可见时携带 finished: true。如果等待先结束，则两者都不设置，运行继续。对于主会话作业以及在自身会话中运行的作业，Agent-runtime 调用者会立即获得普通确认，因为这些运行仅在调用轮次之后开始。
• cron.runs 接受可选的非空 runId 过滤器，以便客户端可以跟踪一个已入队的手动运行，而不会与同一作业的其他历史条目发生竞态。
• 技能和工具：commands.list、skills.*、tools.catalog、tools.effective、tools.invoke。参见 操作员辅助方法。