Skip to content

refactor(turn-driver): slim decision_capture and subagent_execution_topology and eliminate Any - #8998

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/turn-driver-slim-20261118
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/turn-driver-slim-20261118

Conversation

@loopx-agent

@loopx-agent loopx-agent commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Rebased cleanly onto main (fac7d35a8c), eliminating all Any / cast annotations and slimming structural duplication across two loopx/control_plane/turn_driver/ modules with zero semantic changes:

  • loopx/control_plane/turn_driver/decision_capture.py (858 -> 857 lines, 0 Any, 0 dict[str, Any], 0 cast): replaced Any/cast with Mapping[str, object] / dict[str, object] (PayloadView / Payload) aliases, extracted _as_mapping, _read_physical_bytes (preserving info.st_size + 1 bounded read on exact_size=True), and _lookup_path to deduplicate regular-file validation and capture tree traversal while preserving #9022 captured_decision, #9072 docstring updates, error strings, option ordering, and bool vs int distinction.
  • loopx/control_plane/turn_driver/subagent_execution_topology.py (1039 -> 744 lines, -295 lines, 0 Any, 0 dict[str, Any]): deduplicated canonical SHA-256 hashing (_canonical_sha256), packet field extraction (_require_packet), sequence-to-string conversion (_string_list), closed enum validation, and JSON schema enum helpers while keeping exports, schema strings, and behavior unchanged.

Verification

  • Maintainability metrics on e2f89448c5: decision_capture.py lines=857 any_count=0 dict_any_count=0, subagent_execution_topology.py lines=744 any_count=0 dict_any_count=0
  • mypy --strict --follow-imports=silent loopx/control_plane/turn_driver/decision_capture.py loopx/control_plane/turn_driver/subagent_execution_topology.py: 0 issues (repo mypy 17 configured files shows only the pre-existing interaction_contract.py:1004 error reproduced identically on origin/main)
  • ruff check loopx/control_plane/turn_driver/decision_capture.py loopx/control_plane/turn_driver/subagent_execution_topology.py: passed
  • npm run typecheck:control-plane & TypeScript tests (turn_envelope.test.ts, native_child_admission.test.ts, native_child_result_inbox.test.ts): 112 passed (0 failed, 0 skipped)
  • Focused pytest suites (test_quota_decision_capture.py, test_turn_host_decision_capture.py, test_context_read_reference.py, test_context_capture_selection.py, test_codex_context_resume.py, test_agent_context.py, test_subagent_host_adapter.py, test_codex_native_child_receipts.py, test_native_child_receipts.py, test_native_child_report_inputs.py, test_codex_subagent_host_capacity.py, test_native_child_closeout_cli.py, test_native_child_replan_guard_cli.py, test_maintainability_ratchet.py, test_semantic_vocabulary_drift.py, test_content_digest_single_owner.py, test_control_plane_import_boundaries.py, test_loopx_turn_driver.py, test_loopx_turn_executor.py): 1382 passed (0 failed, 0 skipped)
  • loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main: ok: true, gate.status: "passed", merge_gate_passed: true, failures: [] (6 direct checks, 3 catalog canaries, change-quality receipt cqr_b4e7a6cbb76eb4b297ad valid)
  • loopx check --scan-path ...: ok: true, errors: 0, warnings: 0 (public boundary scan clean)
  • Base-vs-head behavioral parity probe (origin/main vs e2f89448c5): passed (e3db2f6576da755d)

@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 (self_reported)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

已针对 PR #8998 exact head 1e766278d8978be71fe3a1decf4ce8dda2cc585a 完成完整静态校验、等效行为对比与单元测试验证(审查结论:APPROVE,无 P0/P1/P2 阻塞问题;[VERDICT: APPROVE])。

动机 / Motivation

受影响调用方与运维者:所有通过 loopx/control_plane/turn_driver/ 读写 Turn 决策快照与子 Agent 执行拓扑的宿主、CLI 及运行时调用方,包括 quota_capture、quota_context_reader、quota_result_delivery、codex_execution_preparation、driver、executor、effect_program、capabilities/decision_context/、capabilities/native_chat/ 与 loopx/canary/ 可维护性棘轮。

修改前(71b66f2980):decision_capture.py 为 858 行含 61 处 Any/cast 且在多处重复正则表达式/路径遍历与物理文件校验;subagent_execution_topology.py 为 1039 行含 59 处 Any 且在 packet 提取、规范 JSON SHA-256 哈希、封闭枚举校验及 JSON Schema 枚举构造中存在大量重复逻辑。修改后(1e766278d8):两文件全面切换为 Payload = dict[str, object] 与 PayloadView = Mapping[str, object] 静态窄化并抽取共享私有辅助函数(_as_mapping、_read_physical_bytes、_lookup_path、_canonical_sha256、_require_packet、_require_enum、_string_enum),decision_capture.py 收敛至 856 行(0 Any / 0 dict[str, Any]),subagent_execution_topology.py 瘦身至 744 行(-295 行,0 Any / 0 dict[str, Any]),合计净减 297 行且完整保留对外导出符号、常量文本、错误字符串与运行时行为。

可观测结果:exact head 1e766278d8 上:module_metrics 验证 decision_capture.py (lines=856, any_count=0, dict_any_count=0) 与 subagent_execution_topology.py (lines=744, any_count=0, dict_any_count=0);uv run --extra test mypy --strict --follow-imports=silent 与全仓 17 文件 uv run --extra test mypy 均返回 Success: no issues found;uv run --extra test ruff check 返回 All checks passed!;11 组定向 pytest(test_quota_decision_capture.py、test_turn_host_decision_capture.py、test_context_read_reference.py、test_context_capture_selection.py、test_loopx_turn_driver.py、test_loopx_turn_executor.py、test_codex_native_child_receipts.py、test_native_child_receipts.py、test_native_child_report_inputs.py、test_maintainability_ratchet.py、test_semantic_vocabulary_drift.py)全部通过:895 passed in 144.06s(0 failed, 0 skipped);uv run --extra test loopx canary premerge --tier quick --from-git-diff --git-diff-base 71b66f2980e199a5a26568bf7d11ceb7a343751e 返回 ok=true, gate.status="passed"(direct=6/6, selected=3/3, failures=0, manual_holds=0);loopx check --scan-path ... 返回 ok=true(errors=0, warnings=0)。

非目标边界:本 PR 不修改 loopx/canary/module_metric_baseline.json(保留现有 858 / 1039 基线上限供独立收口 PR 处理),不改变任何 CLI 参数顺序、错误提示原文、CONTEXT_CAPTURE_* 引导常量及导出的函数/类型签名,亦不顺带修复非本 PR 引入的主干既有用例失败(如已在未改动主干复现的 first_party_host_admission、command_template、handoff_decision 与 test_public_facade_compatibility_entries_have_contract_evidence)。

改动思路 / Approach

所有静态类型收敛与结构去重严格约束在 loopx/control_plane/turn_driver/ 原有两个模块内部完成,未跨模块改写上游 quota/ 契约或 canary/module_metric_baseline.json,无并行所有者或重复状态。

当前 PR 边界:仅包含 loopx/control_plane/turn_driver/decision_capture.py(+277/-279)与 loopx/control_plane/turn_driver/subagent_execution_topology.py(+201/-496)两处纯类型收敛与结构瘦身(总计 +478/-775)。

  • 零 Any 与物理读取/路径查找收敛(decision_capture.py):使用 Payload = dict[str, object] 与 PayloadView = Mapping[str, object] 替代 61 处 Any 与 cast;抽取 _as_mapping、_read_physical_bytes(支持 stat_size_error 与 exact_size 精确保持原有报错文本与大小校验)和 _lookup_path(严格区分 type(key) is str 与 type(key) is int),同时完整保留 context_capture_read_command 参数顺序与全部 CONTEXT_CAPTURE_* 引导文案。
  • 拓扑校验与 Schema 辅助去重(subagent_execution_topology.py):消除全部 59 处 Any,整合 _canonical_sha256、_require_packet、_require_enum 及 string_enum 构造器,净删 295 行冗余代码(1039 -> 744),AST 校验公开符号集零缺失。

具体改动 / Changes

本次 diff 严格限定在 2 个生产文件(+478 / -775):

  1. loopx/control_plane/turn_driver/decision_capture.py(+277 / -279,858 -> 856 行,61 -> 0 Any,0 dict[str, Any])。
  2. loopx/control_plane/turn_driver/subagent_execution_topology.py(+201 / -496,1039 -> 744 行,59 -> 0 Any,0 dict[str, Any])。

对主干的风险 / Risks

  • 契约与兼容性:公开导出符号表、JSON schema 版本、CLI 参数拼装顺序及错误文本经静态 AST 与 895 项聚焦单测验证完全等价;canary premerge --tier quick 中 3 项目录金丝雀及 semantic-vocabulary-drift 全部通过。
  • 独立主干前置说明:此前全量检索(rg 匹配 57 个含关联导入的测试文件)曾见 77 例失败;经对照未改动主干检出复现及隔离验证,属于主干既有失败(first_party_host_admission.goal_launch_not_allowed、command_template / vision_authoring 键缺失、quota.handoff_decision 与 test_public_facade_compatibility_entries_have_contract_evidence 等),直接归属 decision_capture / subagent_execution_topology / turn_driver / native_child / ratchet 的 11 组 895 例全部一次性通过且 0 跳过。
  • 合入前提:涉及 loopx/control_plane/turn_driver/ 核心运行时路径,合入需遵循仓库维护者合并授权流程及远端 CI 完成检查。

我的整体评价 / Verdict

  • Long-horizon 影响:improved — 消除 120 处 Any/cast 并净削减 297 行重复胶水代码,使 turn_driver 两大核心模块一次性低于现有可维护性棘轮基线。
  • User-experience 影响:preserved — 纯行为等价重构,外部输出、错误文本与 CLI 命令生成保持不变。
  • visual_review:not_applicable — 纯控制面 Python 模块,无前端/UI 表面变更。

改动内聚、验证充实、零增量风险;待维护者合并授权后可走标准合入流程。

[VERDICT: APPROVE]
English verdict: APPROVE exact head 1e76627 (author-owned COMMENTED approval review); eliminates all 120 Any usages and trims 297 lines across loopx/control_plane/turn_driver/decision_capture.py (856 lines) and subagent_execution_topology.py (744 lines) with full behavioral equivalence verified by 895 passed pytest cases, mypy --strict & 17-file repo mypy (0 issues), ruff check, quick premerge canaries (0 failures), and loopx check clean (0 errors).

@mergify

mergify Bot commented Nov 18, 2026

Copy link
Copy Markdown

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @loopx-agent.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 18, 2026
@loopx-agent
loopx-agent force-pushed the codex/turn-driver-slim-20261118 branch from 1e76627 to f33f7d6 Compare November 18, 2026 19:49
@mergify mergify Bot removed the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 18, 2026

@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 (self_reported)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

已针对变基至 origin/main(41ea75e89892ed88d0ae543e97e31aad0a181c47)后的 PR #8998 exact head f33f7d6c87efa2ec76e283c7c6e0b3dc49724233 完成逐行 diff 审查、静态类型与规范检查、base/head 行为等效探针对比与本地回归验证(无远端 CI 等待)。审查结论:APPROVE,未发现阻塞性回归或语义漂移。

动机 / Motivation

受影响对象:所有通过 loopx/control_plane/turn_driver/ 读写 Turn 决策捕获快照与子 Agent 执行拓扑的宿主、CLI 及控制面调用方(包括 quota_capture、quota_context_reader、quota_native_context、codex_context、driver、executor、codex_cli 与 execution_readback)以及维护可维护性棘轮检查的开发者。

改前与改后场景:此前在 origin/main(41ea75e898)中,decision_capture.py 存在 61 处 Any/cast 且在物理文件私有校验与 JSON 路径查找上存在多处重复逻辑,subagent_execution_topology.py 达 1039 行并包含 59 处 Any 与重复的规范哈希、packet 必填检查及枚举 Schema 构造;若继续在无严格类型窄化与高冗余状态下叠加需求(如 C1 replan digest 绑定 #9022),极易产生类型逃逸、重复分支漏改与代码体积膨胀。变基到 origin/main 并合并 #9022 的 captured_decision 接口后,decision_capture.py 收敛为 857 行、0 个 Any,subagent_execution_topology.py 精简为 744 行(净减 295 行)、0 个 Any,两者合计消除全部 120 处 Any 并净减 296 行冗余代码。

可观测收益:两个模块在保持全部公开符号、错误文案、JSON schema 字段、bool 与 int 索引区分及 #9022 新增的 captured_decision 透传契约完全一致的前提下,通过 mypy --strict --follow-imports=silent、仓库 mypy(17 个文件)、ruff check 与 1036 项关联 pytest 聚焦用例验证。

非目标与边界:本 PR 不修改任何运行时协议、schema 版本、控制面决策逻辑、TypeScript 宿主契约、测试夹具或基线账本;也不解决 origin/main 在未改动模块(heartbeat/builder.py、work_items/interaction_contract.py 及 TurnEnvelope v0/v1 既有测试漂移)上的历史遗留失败。

改动思路 / Approach

本次重构围绕“零 Any 静态收紧 + 局部重复消除 + 语义零漂移”展开,并在变基解决 decision_capture.py 冲突时完整保留了主干 #9022 引入的 captured_decision 签名与透传结构:

  • 架构归属与当前边界:本次改动仅在既有拥有者 decision_capture.py(私有捕获 IO 与选择视图渲染)和 subagent_execution_topology.py(子 Agent 执行拓扑与回执对账)内部进行静态类型收紧与局部私有辅助函数去重,不引入新模块、新状态或跨边界决策迁移,与仓库既定控制面分层完全契合,应保留现有边界。当前 PR 边界严格限定于 loopx/control_plane/turn_driver/decision_capture.py 与 loopx/control_plane/turn_driver/subagent_execution_topology.py 两个模块内部的 Payload/PayloadView 类型替换及私有辅助函数整合,保留全部公开函数签名与外部调用行为不变。
  • 类型收敛策略:在两个模块顶部统一引入 Payload = dict[str, object] 与 PayloadView = Mapping[str, object],用 isinstance(..., Mapping)、Sequence、Iterable 与 type(k) in (str, int) 显式窄化替代 Any 与 cast,让 mypy --strict 能够覆盖到每个字典与序列访问分支。
  • 结构去重策略:
    • 在 decision_capture.py 中抽取 _as_mapping、_read_physical_bytes(支持 stat_size_error 与 exact_size 参数以精确保持既有错误文案顺序)与 _lookup_path(严格区分 type(key) is str 与 type(key) is int,避免 Python 中 bool 被当作 int 索引列表)。
    • 在 subagent_execution_topology.py 中抽取 _canonical_sha256、_require_packet、_string_list 与 string_enum,合并重复的参数检查、规范 JSON 哈希与 JSON Schema 枚举构造。
对比维度 基线 origin/main (41ea75e898) 变基后 exact head (f33f7d6c87) 变化说明
decision_capture.py 858 行 / 61 Any / 0 dict[str, Any] 857 行 / 0 Any / 0 dict[str, Any] -1 行,消除全部 Any/cast 并保留 #9022 captured_decision
subagent_execution_topology.py 1039 行 / 59 Any / 0 dict[str, Any] 744 行 / 0 Any / 0 dict[str, Any] -295 行,消除全部 Any
公开导出符号集 全部已有公开符号 仅新增类型别名 Payload、PayloadView AST 校验零缺失公开定义

具体改动 / Changes

本次 diff 严格限定在 2 个生产文件,未改动测试、文档或配置文件(无独立书面 RFC/Issue 规范,行为依据现有模块契约与回归测试)。

  1. loopx/control_plane/turn_driver/decision_capture.py:引入 Payload/PayloadView 替代全部 61 处 Any 与 cast,合并物理文件正则校验与路径查找,同时在变基解决 capture_progressive_context 冲突后完整保留 #9022 的 captured_decision: Mapping[str, str] | None = None 参数与向 prepare_progressive_context 传入 captured_decision 映射的逻辑。
  2. loopx/control_plane/turn_driver/subagent_execution_topology.py:消除全部 59 处 Any,精简函数签名换行并合并重复构造逻辑,净缩减 295 行。

关键代码讲解

  • _read_physical_bytes(loopx/control_plane/turn_driver/decision_capture.py:34):统一承接 _validate_handoff_capture_root、read_context_read_reference 与 read_context_capture_file 的物理路径解析、非符号链接校验、open_regular_capture、fstat 大小/属主权限检查与有界读取;通过可选 stat_size_error 与 exact_size 精确保持原有报错文本与字节长度约束,失败直接抛出 ValueError。
  • capture_progressive_context(loopx/control_plane/turn_driver/decision_capture.py:544):变基冲突解决点。接受 payload: PayloadView 与 captured_decision: Mapping[str, str] | None = None,先发布完整投影 source,再通过 optional: Payload 透传 selection_command_args_template、dict(captured_decision) 与 replan_reader_argv 调用 TS prepare_progressive_context;未触发缩减时直接返回 (payload, source),否则保存 required-context.json。
  • context_selection_view(loopx/control_plane/turn_driver/decision_capture.py:811):基于 Payload 与 PayloadView 窄化 rendered_plan["selections"]、调用 _context_selection_bytes 与 _lookup_path 渲染选定字段并校验 SHA-256 摘要,遇到摘要漂移时抛出 ContextSelectionDigestChanged;对 bool 作为列表下标的非法输入仍保持 ValueError/KeyError 拒绝。
  • normalize_subagent_host_execution_receipts(loopx/control_plane/turn_driver/subagent_execution_topology.py:457):循环校验 child_execution_receipts 必填字段、schema_version、三个封闭枚举(execution_kind、context_mode、status)、raw_transcript_copied is False 与 opaque ref/安全边界;统一用 raw_keys = {str(key) for key in raw} 避免混合键排序异常并消除 Any。
  • reconcile_subagent_execution(loopx/control_plane/turn_driver/subagent_execution_topology.py:618):基于 _mapping 与 _string_list 安全解包 topology.lanes 与 pre_spawn_rejections,按 lane 对齐/缺失/重复/越界状态归类为 reconciled、incomplete、guarded 或 drifted,保持只读观察语义不改变任何控制面结算状态。

对主干的风险 / Risks

  • 契约与类型兼容性:两模块公开函数签名(含 #9022 captured_decision)及返回值结构保持兼容,参数注解由 dict[str, Any]/Mapping[str, Any] 收紧为 Payload/PayloadView(即 dict[str, object]/Mapping[str, object])。需注意极少数外部静态类型调用方若将 dict[str, str] 传入期望 Payload(dict[str, object] 不变型)的位置可能触发类型检查提示;实测仓库全量 mypy(17 个核心文件)与两模块 mypy --strict --follow-imports=silent 均 0 报错,capture_progressive_context 对 captured_decision 亦采用协变的 Mapping[str, str] | None。
  • 运行时与边界行为:project_captured_context 中新增 if any(val is not None and not isinstance(val, Mapping) for val in raw_opts.values()): return payload 与原有 prepare_context_delivery 对非映射入参抛出 TypeError 后被外层 except 捕获返回 payload 的效果等价;base(41ea75e898)与 head(f33f7d6c87)等效探针在同一输入与负向用例下的指纹完全一致(dfd4d34c60a01dae...)。
  • 既有主干基线失败归因(非本 PR 回归):在 origin/main(41ea75e898)及本分支 exact head 上执行相同测试命令均出现完全一致的既有失败,均不涉及 PR #8998 改动路径:
    1. tests/canary/test_maintainability_ratchet.py::test_current_repository_debt_is_reviewed_without_line_count_pins(及 canary premerge 中的 advisory_inherited_failure)仅报告未改动文件 loopx/control_plane/heartbeat/builder.py 与 loopx/control_plane/work_items/interaction_contract.py 的超标函数,PR #8998 改动文件 findings 为 0。
    2. test_replan_stages_read_original_authority_capture_without_registry(KeyError: 'review')、test_captured_replan_preserves_scoped_memory_without_trusting_reader_location(assert {} == ...)、test_authored_requirements_survive_capture_projection_and_host(unsupported TurnEnvelope schema_version)以及 test_turn_host_context_delivery.py(assert 'loopx_turn_envelope_v1' == 'loopx_turn_envelope_v0')在未改动 origin/main(41ea75e898)下以完全相同错误签名失败。
  • 验证覆盖:ruff check PASS;仓库 mypy(17 文件)与两模块 mypy --strict --follow-imports=silent PASS;npm run typecheck:control-plane PASS;scripts/check_rfc_bilingual.py PASS;loopx check --scan-path ... 0 错误;loopx canary premerge --tier quick ok: true, merge_gate_passed: true;聚焦 pytest 共 1036 passed, 46 skipped(另有 36 passed 于补充 CLI 集,1 passed 于 test_module_metric_ratchet_detects_new_oversized_module)。

我的整体评价 / Verdict

  • Long-horizon 影响(improved):在完整保留主干 #9022 replan 摘要绑定修复的前提下,彻底清零 turn_driver 两大核心模块的全部 120 处 Any/cast 并净删 296 行冗余胶水代码,降低后续长程演进中的隐式类型逃逸与分叉维护风险。
  • User-experience 影响(preserved):纯内部控制面静态类型收敛与结构去重,外部 CLI 入口、报错文案、JSON 投影结构与既有用户旅程保持不变。
  • Visual review(not_applicable):本次改动仅涉及 loopx/control_plane/turn_driver/ 下的 Python 控制面模块,不涉及任何渲染界面或前端展示变更(unverified_scope: 无前端 UI 变更,不适用视觉走查)。
  • 语义与词表对齐:不涉及新增或修改共享状态枚举、协议字段或词表(not_applicable),AST 检查确认公开符号集无遗漏且可维护性指标大幅改善。
  • 总体结论:改动内聚、行为等效与静态检查证据完备,变基后已恢复 MERGEABLE 状态;本 PR 为 loopx-agent 自有 PR,遵循作者自有 PR 规范以 COMMENT 发布通过结论,待维护者合入。

English Verdict: APPROVE exact head f33f7d6; cleanly rebased onto origin/main (41ea75e) preserving #9022 captured_decision binding, eliminates all 120 Any usages and reduces 296 lines across decision_capture.py (857 lines) and subagent_execution_topology.py (744 lines) with PASS validation on ruff, mypy --strict, typecheck:control-plane, loopx check, quick premerge canary (merge_gate_passed=true), base/head behavioral parity probe, and 1073 passing focused pytest cases (pre-existing origin/main failures identically reproduced on unmodified base).

@mergify

mergify Bot commented Nov 19, 2026

Copy link
Copy Markdown

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @loopx-agent.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 19, 2026
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
@loopx-agent
loopx-agent force-pushed the codex/turn-driver-slim-20261118 branch from f33f7d6 to e2f8944 Compare November 19, 2026 16:39
@mergify mergify Bot removed the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 19, 2026

@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 (self_reported)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

已针对重新变基至最新 origin/main(fac7d35a8c967fe67da0a1fd4a13366cef1b32a4)后的 PR #8998 exact head e2f89448c52e00a0131e8cbc100a0e22d1520f85 完成逐行 diff 审查、静态类型与规范检查、base/head 行为等效对比与本地完整回归验证(遵循 Goal wait_for_ci=false 策略,未等待或查询远端 CI)。审查结论:APPROVE,无未解决 P0/P1/P2 阻塞问题。

动机 / Motivation

所有通过 loopx/control_plane/turn_driver/ 读写决策捕获、上下文选择视图和子 Agent 执行拓扑的宿主、CLI 与控制面调用方(含 quota_capture、quota_context_reader、codex_context、codex_context_history、executor 与 manager_context),以及维护模块可维护性指标棘轮的开发者。

改前(基线 fac7d35a8c):decision_capture.py 为 858 行含 61 处 Any,subagent_execution_topology.py 为 1039 行含 59 处 Any,且在多处手写重复的文件读取和枚举构造;改后(e2f89448c5):两文件统一采用 Payload/PayloadView 类型窄化与局部私有辅助函数(含按 info.st_size + 1 精确界定读取的 _read_physical_bytes),decision_capture.py 收敛至 857 行、subagent_execution_topology.py 瘦身至 744 行,合计净减 296 行且两模块 Any/cast 计数均降至 0。

若继续保留 120 处 Any/cast 与重复的物理文件检查、路径查找、哈希和 packet 校验分支,后续叠加新契约时容易在某一副本遗漏边界检查(例如 bool 误作 int 索引或 symlink/权限校验不一致),导致静态类型检查失真与维护体积持续膨胀。

在 exact head e2f89448c5 上,module_metrics 确认 decision_capture.py 为 857 行/0 Any、subagent_execution_topology.py 为 744 行/0 Any;mypy --strict --follow-imports=silent 与 ruff check 均为 0 问题;19 组定向 pytest(1382 passed, 0 skipped)、112 项 TS 控制面测试、quick premerge canary(cqr_b4e7a6cbb76eb4b297ad)及基线/头节点行为等效探针(e3db2f6576da755d)全部通过。

本 PR 不修改任何控制面语义、CLI 参数顺序、错误提示原文、JSON Schema 版本或 module_metric_baseline.json 上限;不顺带迁移下游尚未类型化的调用方模块,也不处理未改动文件 interaction_contract.py 的既有 mypy 报错或主干既有历史漂移用例。

改动思路 / Approach

本次重构围绕“零 Any 静态收敛 + 局部重复辅助去重 + 运行时语义与内存边界零漂移”展开,变基过程完整保留了主干 #9022(captured_decision)及 #9072(docstring 精简)改动,并修复了上一版变基前 _read_physical_bytes 误按 max_bytes + 1 读取小文件引发的 tracemalloc 8 MiB 预分配回归:

  • 架构归属与当前边界:所有类型收敛与私有辅助抽取均严格保留在既有决策/IO 所有者 decision_capture.py 与 subagent_execution_topology.py 内部,不新增跨层状态或第二套所有者,净删 296 行且通过完整本地回归与行为等效验证。严格限定于 loopx/control_plane/turn_driver/decision_capture.py 与 loopx/control_plane/turn_driver/subagent_execution_topology.py 两文件内的静态类型收紧与局部辅助函数去重,不修改 baseline json、不跨模块重构调用方且不改写协议契约。
  • 既有惯例复用:参照 management_projection.py 与 monitor_poll.py 的既有约定引入 Payload = dict[str, object] 与 PayloadView = Mapping[str, object],结合 isinstance(..., Mapping)、Sequence、Iterable 与 type(k) is str / int 消除全部 Any 与 cast。
  • 私有辅助函数合并:在 decision_capture.py 内提取 _as_mapping、_read_physical_bytes 与 _lookup_path;在 subagent_execution_topology.py 内提取 _canonical_sha256、_require_packet、_string_list 与 string_enum,保留原有 open_regular_capture 与 validate_public_safe_value 所有者。
对比维度 基线 origin/main (fac7d35a8c) 本头 exact head (e2f89448c5) 变化说明
decision_capture.py 858 行 / 61 Any / 0 dict[str, Any] 857 行 / 0 Any / 0 dict[str, Any] -1 行,消除全部 Any/cast 并保留 #9022 与 #9072
subagent_execution_topology.py 1039 行 / 59 Any / 0 dict[str, Any] 744 行 / 0 Any / 0 dict[str, Any] -295 行,消除全部 Any
公开导出符号集 全部已有公开符号 仅新增类型别名 Payload、PayloadView AST 校验零缺失,签名行为保持等价

具体改动 / Changes

本次 diff 严格限定在 2 个生产文件(+479 / -775,纯内部控制面类型收敛与去重重构,无独立书面 RFC,依据现有模块契约与回归测试校验):

  1. loopx/control_plane/turn_driver/decision_capture.py(+278 / -279):全面以 Payload / PayloadView 替换 61 处 Any 指标与 cast,统一物理文件校验与路径遍历,并在变基解决 write_context_read_reference docstring 冲突时完整保留 #9072 文本。
  2. loopx/control_plane/turn_driver/subagent_execution_topology.py(+201 / -496):消除全部 59 处 Any,合并规范哈希、必填 packet 校验、字符串列表提取与 Schema 枚举构造。

关键代码讲解

  • _read_physical_bytes(loopx/control_plane/turn_driver/decision_capture.py:34):统一承接 _validate_handoff_capture_root、read_context_read_reference 与 read_context_capture_file 的物理路径解析、非符号链接守卫、open_regular_capture、fstat 大小/属主权限校验与有界读取;关键修复点为 raw = stream.read(info.st_size + 1 if exact_size else max_bytes + 1),避免 exact_size=True 场景为小文件预分配 8 MiB BufferedReader 缓冲导致回放内存超标。
  • _lookup_path(loopx/control_plane/turn_driver/decision_capture.py:57):供 context_index_fields 与 _context_selection_bytes 复用,严格以 type(key) is str 和 type(key) is int 区分字典键与列表下标,防止 Python 中 bool 被误认为 int 索引列表。
  • _canonical_sha256(loopx/control_plane/turn_driver/subagent_execution_topology.py:152):合并原 _digest 与 _sha256_ref 的重复规范 JSON SHA-256 编码逻辑,保持 ensure_ascii=True, sort_keys=True 与紧凑 JSON 分隔符和各调用方摘要格式完全一致。
  • normalize_subagent_host_execution_receipts(loopx/control_plane/turn_driver/subagent_execution_topology.py:457):收紧入参为 object,使用 {str(key) for key in raw} 安全提取键名以防混合类型键排序报错,并循环校验 execution_kind、context_mode 与 status 封闭枚举,同时保持 raw_transcript_copied is False 与错误文本不变。

对主干的风险 / Risks

  • 契约与静态类型边界:两模块全部公开函数签名与返回值结构保持兼容;参数/返回值注解从 dict[str, Any] 收紧为 dict[str, object] / Mapping[str, object] 后,尚未迁移的下游文件(如 quota_capture.py、codex_context.py、executor.py、manager_context.py)若单独执行 mypy --follow-imports=silent 会触发 dict 不变型提示,但不影响任何运行时行为,且两目标模块 mypy --strict --follow-imports=silent 为 0 错误。
  • 物理读内存边界修复验证:在变基自检中主动捕获了先前版本 _read_physical_bytes 按 max_bytes + 1 读取导致 test_codex_context_resume.py::test_unrelated_history_size_does_not_change_replay_or_decode_cost 峰值内存达到 8.40 MB 的隐蔽回归;修复为按 info.st_size + 1(当 exact_size=True 时)读取后,该测试全部 146 项用例(含 tracemalloc < 1 MiB 断言)一次性通过。
  • 既有主干报错归因(非本 PR 引入):仓库默认 mypy(17 个配置核心文件)在未改动文件 loopx/control_plane/work_items/interaction_contract.py:1004 报 1 处 arg-type 错误,已在未改动 origin/main(fac7d35a8c)以相同命令与完全一致报错签名复现。
  • 本地完整验证结果(wait_for_ci=false,未查询远端 CI):ruff check PASS;mypy --strict --follow-imports=silent(两改动文件)PASS;scripts/check_rfc_bilingual.py PASS;git diff --check PASS;loopx check --scan-path 0 错误 0 警告;npm run typecheck:control-plane 与 112 项 TS 测试 PASS;19 组定向 pytest 共 1382 passed, 0 failed, 0 skipped;loopx canary premerge --tier quick --goal-id personal-loopx-maintenance ok=true, gate.status=passed, merge_gate_passed=true(cqr_b4e7a6cbb76eb4b297ad 有效);base/head 等效探针 PASS(e3db2f6576da755d)。

我的整体评价 / Verdict

  • Long-horizon 影响(improved):在两核心 turn_driver 模块彻底消除全部 120 处 Any 指标并净删 296 行冗余代码,同时修复 exact_size=True 路径的 8 MiB 预分配缺陷,提升后续长程演进的静态安全与可维护性。
  • User-experience 影响(preserved):纯内部控制面类型收敛与去重,外部 CLI 命令、错误文本与 JSON 投影输出零漂移。
  • Visual review(not_applicable):本次改动仅限于 Python 控制面内部模块 loopx/control_plane/turn_driver/decision_capture.py 与 subagent_execution_topology.py,未修改任何前端页面、渲染模板或交互界面(unverified_scope: none (no rendered UI surface modified))。
  • 架构与语义对齐:repository_reuse=reused,observable_semantics=equivalent,change_proportionality=proportionate(architecture_assessment=retain),default_off_isolation=not_applicable,authority_semantics=not_applicable,semantic_alignment=not_applicable(无新增或修改共享词表)。
  • 总体结论:已在最新 origin/main(fac7d35a8c)完成干净变基(MERGEABLE),验证与变基修复完备;本 PR 为 loopx-agent 自有 PR,遵循作者自有 PR 规范以 COMMENT 方式发布批准审查结论,PR 保持 OPEN 状态待维护者合入。

English Verdict: APPROVE exact head e2f8944; cleanly rebased onto origin/main (fac7d35) preserving #9022 and #9072, fixed the _read_physical_bytes exact_size read-limit memory regression, eliminated all Any/cast usages and trimmed 296 net lines across decision_capture.py (857 lines) and subagent_execution_topology.py (744 lines) with PASS validation on ruff, mypy --strict, TS control-plane typecheck and 112 tests, 1382 passed focused pytest cases, base/head behavioral parity probe (e3db2f6576da755d), loopx check clean, and quick premerge canary (cqr_b4e7a6cbb76eb4b297ad, wait_for_ci=false).

This branch has not been deployed

No deployments
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