Skip to content

refactor(native-chat): slim external_conversations below 2k lines and retire ceiling - #8911

Merged
loopx-agent merged 2 commits into
mainfrom
codex/external-conv-slim-20261117
Nov 19, 2026
Merged

loopx-agent merged 2 commits into
mainfrom
codex/external-conv-slim-20261117

Conversation

@loopx-agent

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

Copy link
Copy Markdown
Collaborator

Summary

  • Goal / Gap: Retire the 2,111-line temporary baseline exception for loopx/capabilities/native_chat/external_conversations.py (>2,000-line hotspot) while reducing module size below the 2,000-line ceiling, preserving all post-41ea75e898 main fixes (#8929, #9041, #9072, #9081, #9083, #8939), and fixing the [P2] retained-result raw_response payload regression flagged in review 5935013057.
  • Changes:
    • Extract ExternalStewardCommissionMixin (plus _AUDIENCE_KEYS, _commission_goal_identity, and _steward_proposal_context) into loopx/capabilities/native_chat/steward_commands.py (130 -> 394 lines), fixing code: int | None typing in native_command, preserving external_conversations monkeypatch seams (datetime, _read_json, _atomic_write_json, exclusive_file_lock) via module-level lookup, and preserving FileChatDiscovery._recovery_rows() (#9041) and steward_pr_merge / ProtectedActionGate (#9081) inside commission_evidence, todo_confirmation_reply, and _run_steward_action.
    • Have ChatExternalConversations inherit ExternalStewardCommissionMixin and slim loopx/capabilities/native_chat/external_conversations.py (2,111 -> 1,834 lines) by deduplicating repeated review/session helpers (_load_checked_review_state, _started_native_inputs, _source_requests, _codex_quota_route_capacity, _latest_selection_target, _request_paths), lifting from ...control_plane import effect_runtime to module level, reusing _REQUEST_JOURNAL_STEM in admit_history_answer, and compacting _automation_cadence_observation.
    • Fix [P2] in _original_native_result: pass include_raw_response=True only when include_raw_response is explicitly requested (removing or use_retained) so ordinary retained recovery does not bloat collaboration.conversation.request beyond the 8 MiB Effect RPC limit, while explicit include_raw_response=True paths (recover_failed_request / _checked_metadata_review) keep raw_response.
    • Add test_original_queue_recovers_long_retained_answer_without_raw_response_bloat verifying full recovery of a 1,140,069-byte retained answer via LarkPrivateConversations.reconcile() without raw_response bloat or turn/delivery replay, alongside explicit include_raw_response=True metadata review coverage.
    • Remove "loopx/capabilities/native_chat/external_conversations.py": {"lines": 2111} from loopx/canary/module_metric_baseline.json.
  • Owning Boundary & Rollback: Python Native Chat adapter/orchestration layer only; no TypeScript control-plane contract or wire behavior change; reversible via branch reset/revert.

Verification

Exact rebased HEAD ec1666d120e1b393f6f1c1cf2ca315dbfd3202f1 (based on origin/main 6e1a0bd9e722ee2d287371c5586559d1b466a1b8):

  • ruff check loopx/capabilities/native_chat/external_conversations.py loopx/capabilities/native_chat/steward_commands.py tests/test_lark_private_conversations.py -> All checks passed!
  • mypy --strict --follow-imports=silent loopx/capabilities/native_chat/steward_commands.py -> Success: no issues found in 1 source file
  • mypy (repo default 17 files) -> 1 pre-existing error at loopx/control_plane/work_items/interaction_contract.py:1004 (identical on origin/main 6e1a0bd9e7)
  • pytest -n 4 on 21 targeted native_chat/steward/architecture suites -> 995 passed in 191.58s (0 failed, 0 skipped)
  • pytest -n 4 tests/test_lark_private_conversations.py -q -> 575 passed in 222.76s (0 failed, 0 skipped)
  • Small + 1,140,069-byte retained-payload counterfactual test -> 1 passed in 20.51s (small plain=689 < raw=872; forcing or use_retained reproduced EffectRuntimeRejected: TypeScript Effect runtime request is oversized, fixed path recovered with delivery_verified=True and no raw_response)
  • npm run typecheck:control-plane + 5 Steward/conversation TS control-plane suites -> 89 passed, 0 failed
  • scripts/check_rfc_bilingual.py --base origin/main --head HEAD -> passed
  • git diff --check origin/main...HEAD -> clean
  • examples/control_plane/control-plane-maintainability-ratchet-smoke.py -> ok (unreviewed: 0, stale_exceptions: 0, magnitude_regressions: 0)
  • examples/semantic-vocabulary-drift-smoke.py -> ok
  • loopx check --scan-path ... (all 4 changed files) -> errors: 0, warnings: 0
  • Goal-bound change-quality verify -> receipt_id: cqr_568ec24e9df806bdf261, receipt_valid: true, decision: pass
  • Goal-bound canary premerge --tier quick --from-git-diff --git-diff-base origin/main -> status: passed, merge_gate_passed: true, 3/3 catalog canaries passed, 0 failures

@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.1-sol · OpenAI · runtime_reported · reasoning_effort=max

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

REQUEST_CHANGES。 68903f5acd4d4a842e26f0796e6d5933decb1a7b 有一处已独立复现的 P2 恢复回归;完整审阅仍认可有界抽取的维护目的。

动机 / Motivation

维护 Native Chat 外部请求适配器的开发者,以及需要补回已完成原答复的管家用户,依赖拆分后保持恢复行为。
原适配器超过临时规模预算,命令职责和恢复规则混在同一模块;候选抽取命令并合并重复读取,但同时把普通保留结果恢复改成携带 raw_response。
常规回归通过且模块上限例外删除;独立同条件恢复却发现约1.14 MB原答复在基线成功、候选触发8 MiB桥接请求大小拒绝。
本 PR 是 Python 适配器维护,不授权新的业务、模型、安装或平台操作;本轮没有认证真实 Antigravity、飞书或长期速度收益。

改动思路 / Approach

委托命令留在现有 native-chat provider adapter、决策仍调用原 TypeScript owner,抽取范围可接受;普通结果恢复必须继续遵守原始响应显式请求开关。
保留可审的委托命令抽取和读取去重,只修复新增 raw_response 复制;无须扩大 RPC 上限或重做控制面。
命令 IO 仍属 Python native-chat adapter,Goal/Todo 创建、确认及停止的决定继续由既有 typed owner 和 ChatActionService 处理。把四个命令方法放入已存在的 steward_commands,并共用原状态读取,有局部内聚价值;模块低于两千行本身不证明用户收益,必须保持真实恢复语义。

具体改动 / Changes

本轮完整比较 d210e4cc1d002f92498b2811c565b9430e79f4c1 到本头三文件 +385/-408,净减23行;不是只检查搬移。external_conversations 从2111至1842行,steward_commands 从130至379行,并删除对应临时 baseline 例外。调用方搜索同时覆盖原 private transport、所有 moved methods、结果恢复与未改的 TypeScript owner。

依据 docs/development/testing-and-quality.md#refactor-real-path-gate--重构真实路径门,版本 d210e4cc1d002f92498b2811c565b9430e79f4c1 的 Refactor Real-Path Gate:合法输入的真实入口兼容和持久读回目前 not_met,如下 P2;不能用重构标题或绿测试替代。

关键代码讲解

  • ExternalStewardCommissionMixin 承接委托证据、Todo预览回复、原命令执行和采用,原类通过继承复用。锁、时钟和 journal 的既有测试接缝仍引用原模块;没有额外服务或调度器。
  • _load_checked_review_state 汇合原 metadata、answer 和 result 复核中的 Session/Turn、绑定、队列、Stop及steering检查;不同调用方保留所需参数,未用描述性正文猜状态。
  • _original_native_result 合并保留/实时观测调用时,改变了 include_raw_response=False 的语义。保留结果只决定读哪个原生结果,不应自动要求复制原始响应。

对主干的风险 / Risks

[P2] 普通保留结果恢复额外复制 raw_response,缩小可恢复答复范围

第720行 把 include_raw_response or use_retained 作为返回原始响应的条件。原普通 _recover_native_result 没有请求 raw_response;基线只携带解析后的答复,候选却连完整原始 envelope 一起发送到 collaboration.conversation.request,随后还进入恢复 journal。该方法仍使用现有8 MiB请求界,不能无损承受这份额外复制。

独立沿现有原请求恢复 fixture 的实际 Core/SQLite、Effect桥和合成 native/provider 执行。正文为 1,140,069字节、其余来源与授权相同:base完整恢复、delivery_verified=true,重复 reconcile 不再发送;本头在恢复决策前抛 EffectRuntimeRejected: TypeScript Effect runtime request is oversized。在同一头只以内存反事实去掉 or use_retained,相同原入口又通过,原 Turn、events和保留结果字节不变,无业务/模型重放。小答复也观测到基线无 raw_response、候选新增该字段。

最小修复是继续独立尊重显式 include_raw_response 开关;metadata review 已有显式 True 的调用保留。增加同一普通恢复入口的长正文正例、完整读回及不重复投递检查即可,不需要放宽 RPC 预算。原答复仍在保留文件,问题是新增恢复拒绝,而非已经证实的数据删除。

  • PASS 当前六组源码回归278项;原维护规模检查通过。移入的命令、普通结果、确认、拒绝与回放由相关用例覆盖,provider及初始模型为合成边界。
  • PASS 补齐当前工作区根 TypeScript 开发依赖后,quick premerge 6直接+3选中通过。首次缺依赖失败保留;基线独立语义检查通过,不能把环境缺包写成产品回归。
  • FAIL 上述同条件长答复恢复。最初100000倍正文两边都超界,不作为此回归证据;30000倍的原单消息数量断言不适用分段投递,最终以完整正文、真实投递回执、字节不变及重放不重发判定。脚本初版缩进匹配失败也保留。未查询 CI。

语义与 CI 对齐

没有增加共享语义枚举,原TypeScript决定 owner保持;但“普通恢复不要求raw”的既有输入/输出边界实际改变,故当前语义不等价。通过规模或语义扫描不能覆盖这个运行时反例,修复后须重跑它及显式metadata路径。

我的整体评价 / Verdict

抽取范围可保留,当前长程连续性和结果可达性有回归,不能批准。要求修复具体字段复制及其公开恢复入口测试,不要求扩张整个父路线图。其他 helper 的全部平台组合未逐一配对,278项绿测也不冒称线上资格;这个已证实反例本身足以阻断当前头。
已核三文件完整差异及原 Lark 发送、App 读回消费者:没有改变渲染模板、布局或可见文案,不需要新的截图。
真实平台未执行;本次回归是输出产生前的恢复拒绝,模拟 provider 不证明线上平台结果。

English verdict: REQUEST_CHANGES at 68903f5. The retained-result refactor forces raw_response into ordinary recovery and reproduces an 8 MiB transport refusal for a 1,140,069-byte answer that recovers at the baseline. Respect the explicit raw-response flag and verify the same real recovery, readback and replay path.

@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/external-conv-slim-20261117 branch from 68903f5 to c7e92b5 Compare November 18, 2026 19:01
@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 | model: Gemini | provider: Google | declaration_source: self_reported (host execution observation unavailable)

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

动机 / Motivation

受影响调用方为外部私聊与 Steward 命令协调链路:包含飞书私聊协调器(LarkPrivateConversations)、对外对话核心(ChatExternalConversations)以及工作区管理状态投影(loopx/chat/coordination.py),触发场景为模块消债重构期间的长回复 retained result 恢复及 /commission、/confirm、/cancel、/stop-commission、/resume-commission、待办预览确认等日常私聊指令调度。重构前,loopx/capabilities/native_chat/external_conversations.py 超过 2,000 行热点上限并依赖 module_metric_baseline.json 中 2,111 行的临时基线豁免;且本 PR 初版拆分曾在 _original_native_result 误将 include_raw_response 放宽为 include_raw_response or use_retained,导致 1.14 MB 级长回复通过 retained_result 恢复时把庞大的 raw_response 塞进 TypeScript Effect 请求信封,触发 8 MiB 上限拒绝(EffectRuntimeRejected)并卡死恢复队列。当前精确提交已完成外部 Steward 委托混入类提取、重复局部逻辑合并与基线豁免退休,同时恢复 include_raw_response 的严格按需透传,使长回复可不重跑业务 Turn 完整分片送达。

从工程维护与线上稳定性角度看,长期保留超过 2,000 行的热点豁免会让外部对话编排、原生恢复与 Steward 委托操作持续耦合在同一文件中;如果不拆出可独立演进的命令职责边界,后续任何私聊动作修改都会持续叠加认知负担与冲突面。更重要的是,评审期间发现的 [P2] 缺陷表明“看似只是控制行数”的重构一旦误改边界布尔条件(include_raw_response or use_retained),会直接在真实长回复恢复场景中引发 TypeScript Effect 桥接层 8 MiB 请求体超限故障。因此,把模块瘦身、豁免退休与该 [P2] 修复及端到端回归测试作为一个自洽切片一起落地,既消除了长期热点债务,也守住了长程回复恢复的可用性。

在可验证成果方面,external_conversations.py 降至 1,836 行且彻底移除 module_metric_baseline.json 中的 2,111 行豁免条目;1,140,069 字节长回复在原生线程清理后可通过 LarkPrivateConversations.reconcile() 完整分片回填送达且不携带冗余 raw_response;需要原始响应文本的元数据核验路径(recover_failed_request 与 _checked_metadata_review)显式传入 include_raw_response=True 后仍可读取完整 raw_response。同时,本 PR 不改变 TypeScript 控制面决策协议、不修改外部请求日志 JSON 格式或幂等锁边界,也不重做无关模块的圈复杂度消债或修改测试/核心以外的发布界面。

改动思路 / Approach

本 PR 通过“职责剥离 + 内部去重 + 参数语义还原”三步完成目标:

  1. Steward 委托职责剥离:将原驻留在 ChatExternalConversations 内的 commission_evidence、todo_confirmation_reply、_run_steward_action、_adopt_commission 以及 _commission_goal_identity 抽离为 ExternalStewardCommissionMixin,归位到专门承载 Steward 命令的 steward_commands.py,再由 ChatExternalConversations(ExternalStewardCommissionMixin) 通过单继承 MRO 保持全部公开方法签名和调用路径不变;同时用 _ext._read_json、_ext._atomic_write_json、_ext.exclusive_file_lock、_ext.datetime 保持测试对 external_conversations 模块属性的 monkeypatch 接缝兼容。
  2. 内部重复逻辑收敛与命名对齐:在 external_conversations.py 中提取 _started_native_inputs、_source_requests、_codex_quota_route_capacity、_latest_selection_target、_request_paths 与统一的锁内校验助手 _load_checked_review_state,并在模块顶部引入 effect_runtime 替代多处分散的函数内懒导入,配合统一复用的 _REQUEST_JOURNAL_STEM 正则,使文件净降至 1,836 行并安全删除 module_metric_baseline.json 中的 2,111 行豁免配置。
  3. [P2] retained result 体积膨胀修复:在 _original_native_result 中删除错误的 or use_retained,仅当调用方显式要求 include_raw_response=True 时才向 AntigravityAdapter.completed_result_observation 请求保留 raw_response。
恢复调用路径 include_raw_response 修复前(初版 #8911) 修复后(c7e92b5dcd)
普通长回复 retained_result 恢复(_recover_native_result) False 误传 True,raw_response 随 native_observation 传入 8 MiB Effect 桥接层并超限失败 省略 raw_response,仅返回精简 response 文本与元数据并完整送达
元数据格式核验(recover_failed_request / _checked_metadata_review) True 传入 True,读取完整 raw_response 保持传入 True,继续读取完整 raw_response

保持双层清晰归属:所有回复恢复策略、元数据核验条件与 Steward 委托准入继续由 TypeScript 控制面 Effect runtime(conversation_binding.ts)唯一裁决;Python 侧仅将 Steward 委托队列执行(ExternalStewardCommissionMixin)拆分入 steward_commands.py、在 ChatExternalConversations 内部抽取高复用的局部状态读取与锁内校验辅助函数,并通过显式参数 include_raw_response 控制 AntigravityAdapter.completed_result_observation 是否携带原始响应。当前 PR 边界严格限定在 Python Native Chat 适配层(external_conversations.py、steward_commands.py)、module_metric_baseline.json 豁免项清理与针对性回归测试,未扩大到控制面语义重写或跨模块接口迁移。

具体改动 / Changes

本次 PR 无独立新增产品 RFC 或外部协议规范;验收严格依据仓库控制面可维护性棘轮(单文件 2,000 行上限与豁免清理约束)以及既有 Python/TypeScript 外部对话恢复与 Steward 委托契约执行。变动覆盖 4 个文件(共 +524 / -408 行):

关键代码讲解

  1. _original_native_result(external_conversations.py#L699-L722):合并了原有双分支 completed_result_observation(...) 调用并判定 use_retained 条件(Turn 已完成、存在唯一输入锚点且本地 store.native_result 与 upstream_turn_id 匹配)。关键修复位于第 720 行:移除 or use_retained,改为仅在 include_raw_response 为真时传入 include_raw_response=True。这样在 _recover_native_result(第 731 行)等普通恢复入口不会再把百万字节级原始 steps/raw_response 序列化后送进 TypeScript Effect 运行时;而在 recover_failed_request(第 477 行、第 580 行)和 _checked_metadata_review(第 986 行)显式传入 include_raw_response=True 时仍照常保留完整原始载荷。
  2. _load_checked_review_state(external_conversations.py#L931-L961):将原本散落在 _checked_metadata_review、_checked_answer_review 和 _checked_completed_result_review 中的前置校验(row["turn_id"] 集合检验、client_turn_id 对应、原始 turn/binding_snapshot 一致性、会话关闭/活动 Turn、队列为空要求、来源停止标记与 turn.steered 事件排查)收口为一处参数化检查,保留 historical 与非 historical 的差异边界及各自的宿主门禁报错文案。
  3. ExternalStewardCommissionMixin 及 _run_steward_action / todo_confirmation_reply(steward_commands.py#L143-L370):完整承接原 external_conversations.py 中的 commission_evidence、todo_confirmation_reply、_run_steward_action 与 _adopt_commission 实现,并抽取纯辅助函数 _commission_goal_identity 和 _steward_proposal_context。在涉及 exclusive_file_lock、_read_json、_atomic_write_json 及 datetime 的位置显式通过 external_conversations 模块命名空间读取,保证既有 tests/test_native_steward_private.py 与 tests/test_chat_external_todo_confirmation.py 的隔离测试替身继续精准命中;同时在 native_command 中补充 code: int | None 标注以符合 mypy --follow-imports=silent 检查。
  4. _recover_native_result 与 reconcile 端到端回归测试(tests/test_lark_private_conversations.py#L2270-L2405):新增 test_original_queue_recovers_long_retained_answer_without_raw_response_bloat。该测试先注入 1,140,069 字节(含 30,000 行中文与 emoji)的响应在损坏摘要投递路径下触发真实 native-results/<turn_id>.json 落盘,再将远端 Antigravity 实时帧清空为 CLEARED;验证修复后经公共恢复入口 LarkPrivateConversations.reconcile() 可将 1.14 MB 原回答完整分片投递至私聊并建立幂等交付回执、且 native_observation 不含 raw_response、零业务 Turn 重放与零多余语言服务器调用;同时在后半段使用显式元数据核验场景确认 include_raw_response=True 仍从 retained_result 读回完整 raw_response。
  5. 基线配置与其余内部合并辅助(module_metric_baseline.json 与 _started_native_inputs 等 5 个内部辅助):删除 external_conversations.py 的 2,111 行豁免记录,将 ChatExternalConversations 与文件扫描路径统一到 _REQUEST_JOURNAL_STEM 与 _request_paths,无新增状态字段或默认开关偏移。

对主干的风险 / Risks

结合逐行审查、局部反例复现与多套件回归运行,当前精确提交不存在未解决的阻断性缺陷(no blocking finding),原针对前序提交提出的内联 [P2] 问题(comment 4596933341 / 线程 PRRT_kwDOStEbEs64VMFn)已在 c7e92b5dcdf045395df4f1a2fdf71a8f9626c416 修复并补齐回归测试验证。需要如实记录以下剩余风险与基线归因情况:

  1. 隐式模块命名空间兼容接缝与类型债:steward_commands.py 中的 ExternalStewardCommissionMixin 通过导入 external_conversations as _ext 并访问 _ext._read_json / _ext._atomic_write_json / _ext.exclusive_file_lock / _ext.datetime 来维系旧测试 monkeypatch 兼容(仅限同包协作迁移期,属于可接受的低成本兼容策略,且 steward_commands.py 自身已通过 mypy --follow-imports=silent 零报错)。而 external_conversations.py 原文件仍不在 pyproject.toml [tool.mypy] 严格文件列表中,全量 mypy --follow-imports=silent 检查其存留类型注解尚有 36 条历史告警(本 PR 未新增类型退化)。
  2. 共享验证中观察到的与本 PR 无关的主干既有失败:
    • tests/test_native_steward_turn_host.py::test_managed_work_never_commits_without_current_independent_postcondition[stopped_after_model] 在本分支(1,042 通过 / 1 失败)与纯净 origin/main(41ea75e898,2 通过 / 1 失败)以完全一致的断言(AssertionError: assert ('committed' == 'failed'))失败;该用例直接走 CodexAppServerAdapter.start_turn,不经过 external_conversations.py 或 steward_commands.py。
    • tests/test_chat_external_todo_confirmation.py::test_other_app_cannot_confirm_a_known_todo_preview 在主干与本分支均因提交 03e0b9a992 向 start_turn 传入 reply_image_turn_id 而旧测试桩仍使用 lambda *_args: response 签名触发 TypeError;同文件其余 9 个用例全部通过。
    • examples/control_plane/control-plane-maintainability-ratchet-smoke.py 对全仓报告 2 项主干已存在的 unreviewed_findings(loopx/control_plane/heartbeat/builder.py:build_heartbeat_prompt 与 loopx/control_plane/work_items/interaction_contract.py:_admitted_interaction_next_cli_actions),canary premerge 已自动判定为 advisory_inherited_failure(本 PR 修改文件 0 违例、module_metric_budget=0、merge_gate_passed: true)。
    • examples/loopx-steward-managed-chat-smoke.py 因本地未安装可选 deepseek-harness-sdk 而跳过(skip)。

本 PR 未新增或修改状态枚举值或控制面词表(semantic-vocabulary-drift-smoke.py 检查通过),不引入权限扩大或新调度入口;所有失败恢复仍由原有文件锁与 TS Effect 状态机兜底。

我的整体评价 / Verdict

  • 长程与用户体验评估:long_horizon 评估为 improved(在完整保留基线文件锁、不重放业务 Turn 与不扩散权限边界的同时,消除长回复 retained recovery 超 8 MiB 卡死的阻断风险,并将外部对话主文件降至 1,836 行);user_experience 评估为 improved(visual_review 为 not_applicable,仅调整 Python 原生对话适配器与回归测试,未涉及前端界面、响应式或可见 UI 变更,unverified_scope 为 none)。
  • 语义对齐、兼容与体积判断:observable_semantics 与主干 41ea75e898 保持 equivalent(还原 _original_native_result 的 include_raw_response 精确透传语义);semantic_alignment 为 not_applicable(无新增/扩展/创建词表,仅复用既有模块内部私有辅助函数且经 semantic-vocabulary-drift-smoke.py 验证);code_volume 为 necessary,compatibility_assessment 为 retain(共存部署边界下保留 ChatExternalConversations 方法名及 _ext monkeypatch 接缝);default_off_isolation 与 authority_semantics 均检查通过。
  • 本地验证实证汇总(精确提交 c7e92b5dcdf045395df4f1a2fdf71a8f9626c416,未等待远程 CI):
    • tests/test_lark_private_conversations.py:PASS(572 passed in 629.18s,含新增 1,140,069 字节长回复回归用例;修前同用例实测复现 EffectRuntimeRejected: TypeScript Effect runtime request is oversized)。
    • 架构、恢复与协作相关套件:PASS(tests/architecture/test_content_digest_single_owner.py、tests/architecture/test_top_level_module_budget.py、tests/test_collaboration_mcp.py 等 11 个文件合计 408 passed in 179.03s;test_chat_conversation_bindings.py 117 passed;test_original_conversation_peer.py 40 passed;test_chat_manager_model_adoption.py 38 passed;test_lark_private_agents.py 17 passed)。
    • Steward 17 个套件:1042 passed / 1 pre-existing origin/main failure(唯一失败 stopped_after_model 已在纯净 origin/main 独立复现)。
    • TypeScript 控制面测试与类型检查:PASS(conversation_binding.test.ts + steward_managed_mode.test.ts + steward_reports.test.ts 共 83 passed, 0 failed;npm run typecheck:control-plane 通过)。
    • 静态检查、公私边界与 Pre-merge 门禁:PASS(ruff check 通过;mypy 17 个严格文件及 mypy --follow-imports=silent steward_commands.py 零错误;隔离 HOME 下 loopx check --scan-path 4 文件 errors: 0;scripts/check_rfc_bilingual.py、examples/semantic-vocabulary-drift-smoke.py 及 loopx canary premerge --tier quick 均通过且 merge_gate_passed: true,仅伴随主干既有的 1 条非本 PR 维护性警告;3 项主要 smoke 脚本通过,1 项因缺可选依赖 deepseek-harness-sdk 跳过)。

全部修改目标已实现,已核验文件边界清晰且 [P2] 缺陷在精确提交 c7e92b5dcdf045395df4f1a2fdf71a8f9626c416 得到有效验证;最主要的未测边界仅限真实外部 Lark/Antigravity 网络进程集成及前述主干既有用例的独立修复。

English verdict: APPROVE

@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
…nds and retire external_conversations ceiling

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
…overy

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
@loopx-agent
loopx-agent force-pushed the codex/external-conv-slim-20261117 branch from c7e92b5 to ec1666d Compare November 19, 2026 17:25
@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 | model: Gemini | provider: Google | declaration_source: self_reported (host execution observation unavailable)

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

动机 / Motivation

维护 Native Chat 外部对话适配器的开发者,以及在原生会话窗口被清理或截断后需要无重放补回长答复的 Steward 与私聊用户,均依赖 external_conversations.py 的可读性与长程结果恢复稳定性。此前 external_conversations.py 膨胀至 2,111 行并长期占用 module_metric_baseline.json 临时豁免,把 Steward 委托命令和外部恢复耦合在一起;初版重构还曾在 _original_native_result 误用 include_raw_response or use_retained,导致 1,140,069 字节长答复恢复时被 8 MiB TypeScript Effect 桥接层拒绝。重基于最新 origin/main(6e1a0bd9e7)后,文件降至 1,834 行、基线豁免退休,且普通 retained 恢复不再附带冗余 raw_response。external_conversations.py 净降至 1,834 行(<2,000)并从 module_metric_baseline.json 移除豁免条目,1,140,069 字节 retained 答复经 LarkPrivateConversations.reconcile() 完整分片送达且不携带 raw_response,显式 include_raw_response=True 的元数据复核仍保留完整 raw_response。本 PR 不改变 TypeScript 控制面协议、不扩大 Effect RPC 字节上限,也不涉及无关模块的圈复杂度消债或真实线上网络进程集成。

改动思路 / Approach

将 Steward 委托命令收口至同一模块族的 steward_commands.py(ExternalStewardCommissionMixin),在 external_conversations.py 内去重局部辅助逻辑并还原 include_raw_response 精确条件,既保持 TypeScript 控制面为唯一决策所有者,又以最小可逆切片消除超过两千行的维护债务。本次改动严格限定于 Python Native Chat 适配器(external_conversations.py、steward_commands.py)、module_metric_baseline.json 基线清理与针对性回归测试,不改动 TypeScript 控制面状态机或外部请求日志持久化格式。具体实现上,ChatExternalConversations 通过单继承复用了 ExternalStewardCommissionMixin,并保留既有测试对 external_conversations 模块级符号(_read_json、_atomic_write_json、exclusive_file_lock、datetime)的 monkeypatch 接缝;同时在 _original_native_result 中去除 or use_retained,恢复仅在显式请求 include_raw_response=True 时才附加原始响应,避免普通恢复把百万字节级原始响应写入 native_result_recovery 并塞入 Effect 运行时信封。

恢复调用入口 include_raw_response 参数 初版 #8911 行为 重基精确头 ec1666d120 行为
普通 retained 结果恢复(_recover_native_result) False 误因 or use_retained 附带完整 raw_response,1.14 MB 回复触发 8 MiB Effect RPC 拒绝 不附带 raw_response,仅返回精简 response 与元数据并完整分片送达
元数据格式复核(recover_failed_request / _checked_metadata_review) True 附带完整 raw_response 继续按显式 True 保留并返回完整 raw_response

具体改动 / Changes

本次 PR 面向代码可维护性棘轮(单文件 <2,000 行上限)与现有外部对话恢复/Steward 命令契约,无独立新增外部 RFC 规范(spec_basis: no_spec)。四个变动文件在精确提交 ec1666d120e1b393f6f1c1cf2ca315dbfd3202f1 下均处于已验证边界内(+542 / -419 行):external_conversations.py 由 2,111 行降至 1,834 行,steward_commands.py 由 130 行增至 394 行,module_metric_baseline.json 删除 external_conversations.py 的 2,111 行豁免条目,tests/test_lark_private_conversations.py 新增 139 行回归测试。

关键代码讲解

  1. _original_native_result:复用 _started_native_inputs 与 _original_native_session 校验唯一原生输入锚点,并将 live/retained 两条分支收口到单次 AntigravityAdapter.completed_result_observation(...) 调用;第 720 行恢复为仅当 include_raw_response 为真时传入 include_raw_response=True,从而避免 _recover_native_result 把百万字节级原始响应写入 native_result_recovery 并塞入 Effect 运行时信封,而 _checked_metadata_review 显式传入 include_raw_response=True 时仍照常读回完整 raw_response。
  2. _load_checked_review_state:统一 _checked_metadata_review、_checked_answer_review 和 _checked_completed_result_review 共享的锁前与门禁校验(row["turn_id"]、客户端 turn 映射、原始 turn/binding_snapshot 一致性、非关闭状态与活动 Turn 校验、可选队列清空及停止/steering 检查),通过 historical、allowed_row_turns、require_project_context 与 require_empty_queue 保留三条路径各自的精准门禁报错语义。
  3. ExternalStewardCommissionMixin:承接 commission_evidence、todo_confirmation_reply、_run_steward_action 与 _adopt_commission,并通过共享 _AUDIENCE_KEYS 与 _steward_proposal_context 消除观众字段与 15 分钟有效期计算的重复构造。重基后完整保留了主干 #9041 的 self._recovery_rows() 目录扫描优化以及 #9081 的 steward_pr_merge(merge_protected_action、preview_reply_block、run_steward_pr_merge_command 与 ProtectedActionGate)受保护合并预览和确认链路,且向 run_steward_pr_merge_command 透传 write_json=_ext._atomic_write_json 维持原有写入测试接缝。
  4. _recovery_rows 与 source_controls:统一复用 _request_paths() 遍历标准 24 位十六进制请求文件,保留 #9041 引入的 FileChatDiscovery 增量投影读取(recovery_journal_fields 与 source_control_fields),同时供 commission_evidence、recover 与 source_controls 共享。
  5. test_original_queue_recovers_long_retained_answer_without_raw_response_bloat:构造 1,140,069 字节(含 30,000 行中文与 emoji)原回答并在触发 native-results 落盘后将远端帧设为 CLEARED,验证公共入口 LarkPrivateConversations.reconcile() 能够分片送达完整正文、建立幂等交付回执且不出现 raw_response 字段与业务 Turn 重放,并在同一夹具中验证显式 include_raw_response=True 的元数据核验仍可正常读回 raw_response。

对主干的风险 / Risks

结合逐行比对、反例实测与本地验证矩阵,当前精确提交 ec1666d120e1b393f6f1c1cf2ca315dbfd3202f1 无阻断性回归或合并风险(no blocking finding)。原评审 5935013057 指出的 [P2] 缺陷已在本头真实消除:在独立复现中,小包 retained 样本在不请求 raw_response 时响应字节更小(689 vs 872 字节);对 1,140,069 字节样本在内存中临时强制 include_raw_response=True(模拟 or use_retained)会由 reconcile_request 触发 EffectRuntimeRejected: TypeScript Effect runtime request is oversized 且 delivery_verified 保持 False,去除后同一公开恢复路径即刻恢复为 delivery_verified=True 且无 raw_response 膨胀。

需要说明的非阻断性残留与基线说明如下:

  1. 模块命名空间测试接缝与局部类型现状:ExternalStewardCommissionMixin 通过导入 external_conversations as _ext 读取 _read_json、_atomic_write_json、exclusive_file_lock 与 datetime 以兼容现有测试替身;steward_commands.py 本身已通过 mypy --strict --follow-imports=silent 零报错。external_conversations.py 目前未纳入 pyproject.toml [tool.mypy] 严格文件列表,其历史严格检查错误主要来自既有 Any 和 _load_checked_review_state 返回 original: dict[str, Any] | None 的联合类型推断,未影响运行语义或严格配置检查;仓级默认 mypy 仅在无关文件 loopx/control_plane/work_items/interaction_contract.py:1004 报 1 项与 origin/main (6e1a0bd9e7) 完全一致的既有错误。
  2. 公私边界、语义词表与权限隔离:本次仅在 Python 适配器内部拆分和合并方法,未新增或修改任何状态枚举、控制面词表(semantic-vocabulary-drift-smoke.py 通过)、授权边界或默认开关;4 个修改文件经 loopx check --scan-path 扫描 0 错误 0 警告。

我的整体评价 / Verdict

  • 长程与用户体验评估:long_horizon 为 improved(消除了百万字节级长回复在 retained recovery 链路触发 8 MiB RPC 拒绝的断点,保留幂等文件锁与零业务 Turn 重放保证,并解除 external_conversations.py 长期超行债务);user_experience 为 preserved(visual_review 为 not_applicable:仅涉及 Python 适配器重构、回归测试与基线配置,不改动前端页面、布局或用户交互文案。 未覆盖视觉范围为 none)。
  • 语义对齐、兼容与体积判断:observable_semantics 与 origin/main(6e1a0bd9e7)保持 equivalent(_original_native_result 还原 include_raw_response 显式透传语义,steward_pr_merge 与 _recovery_rows 行为完整延续);semantic_alignment 为 not_applicable(未新增、扩展或自创词表,经 semantic-vocabulary-drift-smoke.py 验证通过);code_volume 为 necessary,compatibility_assessment 为 retain(保留 ChatExternalConversations 全部公开与测试接缝,迁移期风险低),default_off_isolation 与 authority_semantics 均保持不变。
  • 精确头 ec1666d120e1b393f6f1c1cf2ca315dbfd3202f1 本地验证结果(未等待远程 CI):
    • PASS:21 个相关 Python 测试套件(覆盖 native_chat、steward_pr_merge、file_discovery、目录扫描性能、OpenViking 记忆隔离、可维护性棘轮与架构约束)合计 995 passed in 191.58s。
    • PASS:完整 tests/test_lark_private_conversations.py 套件 575 passed in 222.76s(含长回复 retained recovery 与元数据 review 回归测试)。
    • PASS:小包与 1,140,069-byte retained 恢复反事实复现(1 passed in 20.51s:强制 or use_retained 精确触发 oversized 拒绝,当前精确头完整恢复)。
    • PASS:TypeScript 控制面 npm run typecheck:control-plane 及 5 组相关测试(89 passed, 0 failed)。
    • PASS:ruff check 全部修改文件通过;mypy --strict --follow-imports=silent loopx/capabilities/native_chat/steward_commands.py 零报错;scripts/check_rfc_bilingual.py、git diff --check、loopx check --scan-path(0 错误)、control-plane-maintainability-ratchet-smoke.py、semantic-vocabulary-drift-smoke.py、catalog-planner-smoke.py 全部通过。
    • PASS:Goal 绑定 change-quality verify(receipt_id: cqr_568ec24e9df806bdf261,receipt_valid: true)与 canary premerge --tier quick(merge_gate_passed: true,3/3 通过)。
    • UNVERIFIED(非阻断范围边界):真实线上飞书/Antigravity 外部网络进程未运行(本轮由合成语言服务器与真实 Core/SQLite/TS Effect 运行时验证)。

English verdict: APPROVE at ec1666d. Rebase onto origin/main (6e1a0bd) cleanly slims external_conversations.py to 1,834 lines, retires its baseline ceiling, preserves #9041/#9081/#9083 fixes, and verifies the 1.14 MB retained raw_response fix via real Effect runtime counterfactuals, 1,571 passing tests across Python and TypeScript suites, CQR, and canary premerge.

@loopx-agent
loopx-agent merged commit 109ed4b into main Nov 19, 2026
29 of 58 checks passed
@loopx-agent
loopx-agent deleted the codex/external-conv-slim-20261117 branch November 19, 2026 17:30
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