Skip to content

feat(control-plane): allow the CLI Effect runtime to use stdio in restricted hosts - #9140

Merged
loopx-agent merged 1 commit into
mainfrom
codex/cli-effect-stdio-current-20261119
Nov 21, 2026
Merged

loopx-agent merged 1 commit into
mainfrom
codex/cli-effect-stdio-current-20261119

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

  • Allow the CLI Effect runtime to fall back to stdio transport in restricted hosts where local loopback sockets cannot bind, adding loopx/control_plane/effect_runtime_stdio.ts, effect_runtime_exchange.ts, loopx/control_plane/runtime/stdio_transport.py, effect_client_errors.py, and updating effect_runtime.py / effect_runtime_server.ts.
  • Update bilingual RFC (docs/architecture/rfcs/typescript-control-plane-migration-v0.{md,zh-CN.md}) and docs/product/runtimes/codex-cli/codex-cli-tui-loop.md.
  • Add integration coverage in tests/control_plane/test_effect_runtime_integration.py and tests/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 skipped
  • npx tsc -p tsconfig.control-plane.json --noEmit — passed (exit 0)
  • uv run python scripts/check_rfc_bilingual.py --base origin/main --head HEAD — passed
  • uv run loopx --runtime-root /Users/huangruiteng/.loopx check --scan-path ... — passed (0 errors, public boundary scan clean across 14 files)

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 参数化验证)。

关键代码讲解

  1. 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 回执恢复。
  2. 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。
  3. 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/回收父进程的子进程。
  4. 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)。
  5. 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):
    1. _start_stdio_runtime 在 runtime.ping 超时或异常退出时统一归类为 runtime_exited_before_ready(含启动期超时),且在节点尚未进入 stdin 读取循环前卡死的极低概率场景下 pipe.close(reap_in_background=True) 仅关闭管道与后台守护线程 wait,不额外发送信号强杀子进程;鉴于 effect_runtime_stdio.ts 启动期只做静态加载且 daemon=True 不阻塞 CLI 退出,风险低、非阻塞。
    2. _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-*.json locator、在 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 loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@loopx-agent
loopx-agent merged commit c1de735 into main Nov 21, 2026
39 of 53 checks passed
@loopx-agent
loopx-agent deleted the codex/cli-effect-stdio-current-20261119 branch November 21, 2026 13:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant