Repository navigation
feat(control-plane): allow the CLI Effect runtime to use stdio in restricted hosts - #9140
Conversation
Signed-off-by: LoopX Agent <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Gemini · Google DeepMind · self_reported
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
本次复审基于 PR #9140 在 exact head c18c473cff5982035621b30327323ca451f760d5(merge-base eb552a8bb0532de117513ee5277a92e74e746309)的全部 14 个改动文件,结合本地测试、TypeScript 类型检查与真实 CLI/管道反事实实验,给出 APPROVE 结论。
动机 / Motivation
在禁止绑定或连接本地回环 TCP 端口的受限 POSIX 宿主(例如开启网络沙盒的 Codex CLI 会话)中,运行 LoopX CLI 命令、Doctor 探测或结算子进程的开发者与自动化进程会遇到该问题。改动前(基于 eb552a8),Python 客户端只能启动并连接 127.0.0.1 回环守护进程,遇到宿主拒绝本地 socket 时会以 runtime_host_permission_denied 失败并阻断全部控制面请求;改动后,显式设置 LOOPX_EFFECT_RUNTIME_TRANSPORT=stdio 且处于 POSIX 环境时,每个 CLI 进程改由标准输入输出管道托管专属 Node 子进程并由其子进程继承,同时默认 tcp 路径的行为与生命周期保持不变。已验证开启 stdio 后可在完全不触碰回环 socket 与 locator 文件的前提下完成 runtime.ping、8 MiB/64 MiB 大上下文私有快照往返、并发线程串行化、fork 后子进程隔离以及断链后通过 quota 持久回执幂等恢复,且无效传输值与非 POSIX 宿主均 fail-closed 报错。本 PR 不在宿主拒绝 TCP 时静默自动回退到 stdio,不修改默认 tcp 守护进程的单实例/空闲退出语义,也不为 Windows 提供匿名管道 stdio 传输。
改动思路 / Approach
将请求解析、认证、本地快照读写、分发和响应编码抽离为无传输层依赖的共享核心 exchangeEffectRuntimeRequest(invariant 与业务分发留在 TypeScript 内核,transport IO 下沉到 effect_runtime_server.ts 与 effect_runtime_stdio.ts,Python 侧拆出 effect_client_errors.py 与阻塞/超时受控的 stdio_transport.py),既避免了在两套服务端里复制协议逻辑,也让未开启 stdio 的默认路径无需承受多进程并发写协调语义变更。当前 PR 交付由环境变量显式选通、单进程生命周期绑定的 POSIX stdio 传输适配器及其双向文档和集成验证,不改变现有 tcp 守护进程的多客户端共享 writer 架构。
LOOPX_EFFECT_RUNTIME_TRANSPORT
├── unset / "tcp" (默认) ──> 复用/拉起 127.0.0.1 回环 daemon(locator + compile cache + idle_shutdown)
├── "stdio" (POSIX) ──> 进程私有 Node 子进程 (effect_runtime_stdio.ts) ──> 共享 exchangeEffectRuntimeRequest
└── 其他值 / 非 POSIX ──> fail-closed: invalid_runtime_transport / unsupported_runtime_transport
注:上图为基于 exact head c18c473cff5982035621b30327323ca451f760d5 源码整理的示意控制流,用于说明传输路由分流边界。
在持久化与错误语义上,stdio 模式继续沿用“派发后不可靠传输即判为 EffectRuntimeResponseAmbiguous”的不变量:一旦写入管道开始或响应在途丢失(包括超时、EOF、超大帧或递归超限),客户端直接关闭管道、置空 _stdio_runtime 并抛出模糊响应异常,强制上层先读取目标业务(如 quota.spend.commit)的持久回执再决定后续动作,不自动重试有副作用请求。
具体改动 / Changes
规范对齐(spec_basis)
依据 docs/architecture/rfcs/typescript-control-plane-migration-v0.md(baseline revision eb552a8bb0532de117513ee5277a92e74e746309)对单一 TypeScript 内核、默认回环传输与派发后模糊回执恢复的既有约束(本 PR 亦同步更新了该双语 RFC 与 docs/product/runtimes/codex-cli/codex-cli-tui-loop.md 以登记显式 POSIX stdio 形态):
RFC-2.1-single-ts-kernel-> implemented:loopx/control_plane/effect_runtime_exchange.ts(exchangeEffectRuntimeRequest)与effect_runtime_stdio.ts复用同一静态 handler 注册表与解码边界(经 Node 集成测试与tsc校验)。RFC-2.2-default-loopback-isolation-> implemented:loopx/control_plane/effect_runtime.py(_uses_stdio_runtime默认"tcp")及sqlite_runtime.ts(servingManagedRuntime)保持未启用stdio时回环行为与生命周期完全一致(经基线/当前头对比与 CLI 实测)。RFC-2.5-ambiguous-receipt-recovery-> implemented:effect_runtime.py(_request_with_info、EffectRuntimeResponseAmbiguous)在 stdio 管道超时/EOF/超限时闭环拒绝自动重试(经test_stdio_lost_spend_response_recovers_exact_receipt_without_a_second_debit与子进程强杀探针验证)。RFC-6-local-snapshot-parity-> implemented:effect_runtime_exchange.ts与effect_runtime.py对params_ref/response_sink保持相同的 8 MiB 在线与 64 MiB 私有快照边界(经test_complete_unicode_context_uses_actual_wire_bytes_and_snapshot_fallback参数化验证)。
关键代码讲解
loopx/control_plane/effect_runtime_exchange.ts(exchangeEffectRuntimeRequest、encodeResponse):从旧effect_runtime_server.ts抽离单帧 RPC 解析、token 校验、params_ref/response_sink私有文件打开与业务分发逻辑;关键不变量在于encodeResponse位于业务catch块之外,因此若已提交结果的编码或writePrivateResponse超限失败,不会将已提交操作降级成ok: false错误信封,而是返回null或抛出错误促使传输层断链,由调用方触发EffectRuntimeResponseAmbiguous回执恢复。loopx/control_plane/effect_runtime_stdio.ts(serve、reply):以for await (const chunk of process.stdin)按原始字节缓冲区拼接至0x0a(),正确处理跨块切分的 UTF-8 多字节字符与单块内粘连多帧;入站前按MAX_REQUEST_BYTES(8 MiB)拦截并回写oversizedEffectRuntimeRequest()后退出;通过process.stdout.on("error", () => undefined)确保调用方提前断开时不击穿正在收尾的 handler。loopx/control_plane/runtime/stdio_transport.py(EffectRuntimeStdio.exchange、close):对标准输入输出 pipe 设为非阻塞模式,使用selectors.DefaultSelector在同一单调时钟截止时间deadline下完成分段写与按换行定界读,严格限制MAX_RESPONSE_BYTES且在响应行尾后出现意外附加字节时抛ValueError;close()仅关闭管道让子进程自然读到 EOF 退出而不主动强杀正在收尾的写入,并在fork子进程路径下(self._owner_pid != os.getpid())只关闭继承的文件描述符而绝不错误 wait/回收父进程的子进程。loopx/control_plane/effect_runtime.py(_uses_stdio_runtime、_request_stdio_runtime、collect_effect_runtime_readiness):_uses_stdio_runtime()对"tcp"、POSIX"stdio"之外的输入或非 POSIX 下的"stdio"fail-closed 抛出EffectRuntimeStartupError(invalid_runtime_transport/unsupported_runtime_transport);_stdio_runtime_lock串行化进程内并发线程请求,os.register_at_fork在子进程清理全局缓存与锁,且collect_effect_runtime_readiness在stdio下准确报告idle_shutdown: false、transport: "stdio"、locator_state: "missing"及进程作用域的 SQLite 升级提示(配合sqlite_runtime.ts)。loopx/control_plane/runtime/effect_client_errors.py:集中托管EffectRuntimeRemoteError、EffectRuntimeStartupError等异常族与_remote_runtime_error信封解码并在effect_runtime.py重新导出,保持既有公开导入兼容。
对主干的风险 / Risks
- 默认路径隔离与向后兼容:默认环境变量未设置时走原
tcp路径,sqlite_runtime.ts与effect_runtime_server.ts保持原生命周期投影(idle_shutdown: true,无transport键)与错误信封格式;CLI 与runtime.ping对比结果同基线完全一致。 - 已知非阻塞边界与观察(No blocking finding):
_start_stdio_runtime在runtime.ping超时或异常退出时统一归类为runtime_exited_before_ready(含启动期超时),且在节点尚未进入stdin读取循环前卡死的极低概率场景下pipe.close(reap_in_background=True)仅关闭管道与后台守护线程 wait,不额外发送信号强杀子进程;鉴于effect_runtime_stdio.ts启动期只做静态加载且daemon=True不阻塞 CLI 退出,风险低、非阻塞。_restart_stdio_runtime始终等待管道 EOF 退出(复用timeout),忽略wait_for_exit=False差异;实际闲置子进程收到 EOF 在毫秒级退出,属于合理的进程内收尾行为。
- 本地验证与反事实探针汇总:
pytest(test_effect_runtime_integration.py+test_quota_spend_commit_runtime.py):126 passed, 1 skipped(PASS;仅 1 条 Linux/proc线程组退出测试因 macOS 环境跳过)。pytest(test_managed_effect_runtime_fixture.py):12 passed(PASS)。- Node TS 测试(
sqlite_runtime_admission.test.ts、effect_runtime_errors.test.ts、effect_program.test.ts、effect_runtime_compile_cache.test.ts、sqlite_capacity.test.ts):55 passed, 0 failed(PASS)。 - TypeScript 编译校验(
tsc --noEmit --strict针对全部 5 个改动 TS 文件):PASS(0 错误;注:完整tsconfig.control-plane.json在无node_modules的隔离 worktree 仅因单测content_digest_single_owner.test.ts缺少typescript依赖报错,5 个控制面产品 TS 文件本身 0 错误)。 ruff check、mypy、scripts/check_rfc_bilingual.py、loopx check --scan-path ...、loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main:全部 PASS(0 错误,14 文件边界扫描干净)。- 独立反事实探针(PASS):实测
loopx doctor --installation-only --deep在stdio下成功且不生成runtime-*.jsonlocator、在bogus/ 模拟非 POSIX 下 fail-closed 返回invalid_runtime_transport/unsupported_runtime_transport、在tcp下保持原样;实测effect_runtime_stdio.ts跨包 UTF-8 拆分与管道粘包双请求、错误 JSON/错误 token 恢复、8 MiB+ 请求截断退出;实测os.fork()父子进程各自持有独立子进程、父进程在子进程被SIGKILL后自动重建,以及sqlite_runtime.ts在stdio下不误报--restart-runtime。
我的整体评价 / Verdict
- 长程与用户体验评估(
outcome_impact):long_horizon为preserved(保留派发后EffectRuntimeResponseAmbiguous不变量与quota.spend.commit持久回执幂等恢复,避免重复扣减或状态撕裂);user_experience为improved(在禁用回环 socket 的受限终端宿主中提供可遗传、免手动守护进程管理的stdio逃生通道与准确诊断)。视觉评审(visual_review):本 PR 仅涉及 CLI 控制面传输层、错误信封与文档说明,不涉及任何前端页面或渲染视图变更,已在 loopx/control_plane/ 与 docs/ 中核实。(未验证范围:none)。 - 代码体量与可维护性(
code_volume/change_proportionality):虽新增 4 个文件并有较多重构搬迁行,但主要是将effect_runtime.py中的纯客户端错误族(201 行)与effect_runtime_server.ts中的请求分发核心(127 行)拆出共用,净增逻辑精简内聚,架构分层清晰,保留现有封装即可(retain)。 - 语义与词表对齐(
semantic_alignment):新增可观测传输状态值stdio与诊断码invalid_runtime_transport/unsupported_runtime_transport,均限定于本地 Effect 传输配置与已有runtime_lifecycle/EffectRuntimeStartupError契约扩展,未改变上游域策略语义且与双语 RFC 同步。
综上,PR #9140 在 exact head c18c473cff5982035621b30327323ca451f760d5 上设计边界克制、默认路径完全隔离、反事实与本地门禁充分通过,未发现阻塞合并的 P0/P1 缺陷。
English verdict: APPROVE — exact head c18c473; no blocking findings; verified with local pytest (126+12 passed), Node TS tests (55 passed), tsc on touched TS files, canary premerge quick tier, and live stdio/fork/framing counterfactuals.
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, xhigh)
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机 / Motivation
在 POSIX 上运行 Codex CLI 的用户,如果当前宿主禁止本机回环 socket,仍需要读取 Goal,并让结算命令按原身份写回。 在 macOS 进程级网络限制下,回环 bind 被拒绝,默认 TCP 语义探针失败。显式选 stdio 后,安装 wheel 的 CLI 读回 SQLite 合格,File 和 SQLite 的原硬租约结算可继续。 相同限制下,模拟已提交扣额的回复丢失后,读回原持久回执。重试后的账本仍只有一条扣额。 本地验证使用 macOS、隔离 File/SQLite 与精确候选 wheel,未在真实 Linux 或正式安装 Desktop 上复验。 跨平台的安装和宿主验收仍有范围边界。
改动思路 / Approach
两种传输共享认证、Effect 分派和持久回执,子进程由启动它的 CLI 生命周期管理。 保留默认 TCP。显式 stdio 只替换传输,以现有写入栅栏和同一原始结算回执处理效果。 用网络可用的标准套件覆盖默认路径,再在真正禁止网络的 macOS 进程里对照默认 TCP 和显式 stdio。最后在原 File、SQLite 状态上重跑接续、扣额和读回。
具体改动 / Changes
精确头 c18c473cff5982035621b30327323ca451f760d5 的原基线为 eb552a8bb0532de117513ee5277a92e74e746309。以当前主干 23dacd5fb449194c6a8d83e9764534cdbdd081b4 进行干净整合,14 个文件新增 956 行、删除 381 行。新增的只是传输和进程生命周期,原有校验和 typed Effect 分派成为两种路径的共用入口。
same-authority保留同一认证字段、请求长度、私有快照和 Effect 所有者。stdio 由显式环境设置启用,默认回环处理仍保留。 传输选择 共享分派receipt-first-recovery进程只持有本次管道。收到不完整回复后关闭该管道,对已提交效果按同一 ID 读回。隔离 File 测试以真实提交后的响应中断为对照,整合的两种 authority provider 均实际走完原租约结算。 过程接续 迁移契约
对主干的风险 / Risks
当前主干整合通过 126 项 Python、80 项 TypeScript,另有一个平台限定用例跳过。网络被拒绝时,独立 File/SQLite 硬租约流程 2 项、丢回包对照 1 项通过。 独立构建并安装了该精确头 wheel,直接运行其 CLI 入口 doctor --deep,在本地网络被系统拒绝时,TypeScript 探针和 SQLite 资格均通过。仍需按现有权威库和工作区权限运行,选 stdio 不改变谁可写。未查询托管检查。本地验证使用 macOS、隔离 File/SQLite 与精确候选 wheel,未在真实 Linux 或正式安装 Desktop 上复验。
我的整体评价 / Verdict
APPROVE。 显式管道模式打通受限的本地 CLI,保留默认 TCP 与原有结算身份。丢失回应后能读回单次扣额,实际限制下两个本地存储都可继续接续。跨平台资格和合并权限保持独立。
English verdict: APPROVE at c18c473cff5982035621b30327323ca451f760d5. The exact installed wheel passed the control-plane probe under real loopback denial; File and SQLite kept their original recovery and settlement path. The ambiguous delivery case retained a single debit.
Summary
loopx/control_plane/effect_runtime_stdio.ts,effect_runtime_exchange.ts,loopx/control_plane/runtime/stdio_transport.py,effect_client_errors.py, and updatingeffect_runtime.py/effect_runtime_server.ts.docs/architecture/rfcs/typescript-control-plane-migration-v0.{md,zh-CN.md}) anddocs/product/runtimes/codex-cli/codex-cli-tui-loop.md.tests/control_plane/test_effect_runtime_integration.pyandtests/control_plane/test_quota_spend_commit_runtime.py.Local Verification
uv run --extra test python -m pytest tests/control_plane/test_effect_runtime_integration.py tests/control_plane/test_quota_spend_commit_runtime.py— 126 passed, 1 skippednpx tsc -p tsconfig.control-plane.json --noEmit— passed (exit 0)uv run python scripts/check_rfc_bilingual.py --base origin/main --head HEAD— passeduv run loopx --runtime-root /Users/huangruiteng/.loopx check --scan-path ...— passed (0 errors, public boundary scan clean across 14 files)