Skip to content

feat(turn): prepare a missing lease for a generic CLI first Turn - #9047

Open
cocolord wants to merge 1 commit into
mainfrom
codex/core-managed-first-turn-20261119
Open

cocolord wants to merge 1 commit into
mainfrom
codex/core-managed-first-turn-20261119

Conversation

@cocolord

Copy link
Copy Markdown
Member

Goal And Delivered Outcome

The independently installed Core previously needed a separate Todo claim for the first hard-lease Turn on generic-cli. With a declared complete v1 adapter and an independent validator, the existing turn run-once --execute now consumes the exact Host-executable claim from the typed decision, then checks that the same Todo is ready before dispatch. The Core guide and paired RFC document this path.

Related to #5072 and independent of the package and Worker-input slices in #9034, #9038, and #9045.

Author Declaration

Written by model_agent — OpenAI Codex. The existing managed preparation owner performs the ordinary claim. The caller validates the configured command arguments before creating a reservation or lease. The current generic adapter uses the same effect-bound cadence identity at preparation and dispatch, with the established transaction-key recovery path for older reservations.

Acceptance Evidence
Start the first approved generic Turn from a clean Core install File and SQLite find an eligible Todo with a missing hard lease. The old wheel refuses the same execution. The candidate creates the lease, launches one bounded host process, passes independent validation, and commits once.
Compatible request and real authorization before preparation The invalid adapter argv case is refused before a lease, subprocess, or debit. Existing same-Todo and canonical ownership checks cover the preparation.
Cadence and recovery retain the original identity A configured 1,440-minute floor resumes the same unstarted reservation when dispatch follows the claim. Replaying the recorded Turn performs zero new effects. Process-loss tests begin with a missing lease and recover the original result on both backends or refuse a renewed or released generation.
No independent decision owner The CLI reuses the same preparation, claim, cadence and readback owners. The complete v1 adapter and validator are the existing configuration inputs.

Validation

  • Tested head 7754b37b449b94f219b5bf52e7c41e187cfbefa2 on main@5110b3afd8fbc33d2da33c28815e9320636244c3. The newest main recheck merges cleanly. The rebuilt Core wheel's four runtime changes match the reviewed source across 1,907 packaged runtime files.
  • 50 non-editable Core tests pass using real CLI, TypeScript effects, File and SQLite authority, and a local synthetic adapter. 43 focused source cases pass, including the existing Codex claim, cadence recovery, conflict and concurrent guard tests.
  • A separate clean installed wheel combining the exact heads of refactor(core): keep benchmark execution out of capability discovery #9034, Install Benchmark Toolkit alongside standalone Core #9038, fix(turn): keep executor commands out of the Worker task context #9045 and this change passes 16 cases. The package omits the 44 benchmark files and exercises capability discovery, first-Turn preparation, Worker input, and recovery together.
  • The quick premerge gate passes with zero blocking failures. The maintainability advisory is reported in local validation. Ruff, configured mypy, Git diff hygiene, and both staged and committed bilingual checks pass.

Bounded refactoring reuses the effect-bound cadence selector for the two preparation paths. This fulfills one observable step of the independent Core journey. Initial host setup, complete composition qualification, and matched real-model cost and coverage remain open. Visual scope is the existing CLI flow and its usage guide.

Signed-off-by: cicolord <cicolord@outlook.com>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

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

动机 / Motivation

适用对象与触发条件: 使用 loopx-core 的自主宿主接入方或独立 CLI 调度器在首次执行 turn run-once --execute --host generic-cli 时,此前若尚未预先调用 todo claim 领取可运行任务租约,就会在准备工作阶段停住。

修改前后场景对比: 修改前(基线 5110b3a):即使调用方已显式传入 generic-cli v1 请求格式与独立校验命令(--validation-command-json),turn.py 仍仅允许 codex-cli 自动执行准备阶段的 todo claim,generic-cli 只能退回 claim_required 阻塞,必须由外部脚手架额外先跑一次 todo claim 并手工串联 cadence 冷却窗口,且容易在首次 claim 后立刻撞上 minimum_interval_wait;修改后(7754b37b44):同一 Turn 身份在校验参数通过后通过 builtin_execution_preparation_claim 复用普通 todo claim 补齐缺失租约,并在正式派发时复用同一 settlement_identity.effect_id 恢复未启动的 cadence 预留槽位,无需外部预先 claim 且保持恢复语义一致。

可观测收益: 在 SQLite 与 File 双后端的已构建安装版 loopx-core wheel 实测中,仅携带兼容 generic-cli v1 adapter 与独立校验命令的 turn run-once --execute 会自动完成前置准备、通过 resumed_unstarted_reservation 避开虚假的 1440 分钟间隔阻塞、执行任务并落盘提交,随后可用 --resume-turn-key 无副作用重放,进程被 SIGKILL 中断后仍按原始租约代次精确恢复或拒绝被续约/释放的过期租约。

明确非目标与边界: 不放宽未提供独立校验命令或未使用 loopx_turn_host_request_v1 的 bare generic-cli 调用门槛,不引入新状态枚举、不弱化 hard_lease/cadence 约束,也不改动任何前端或 Lark 控制面界面。

改动思路 / Approach

如果不做这次改动,独立 CLI/Core 调用方在冷启动运行 turn run-once --execute --host generic-cli 时仍不得不维护双步启动脚本(先 todo claim 再 turn run-once),或因准备阶段与真正执行阶段使用不同的 cadence request_id 而被 minimum_interval_wait 误拦。与之相比,本 PR 没有为 generic-cli 新建平行的状态机或放开无校验器的裸命令自动领任务,而是沿着已验证的 codex-cli 准备机制做了最小扩面。

turn run-once --execute
  |-- host == generic-cli & 缺 validation-command-json / 非 v1 schema
  |     --> 保持原路径:不构造 execution_preparer,未领租约仍停在 claim_required
  '-- host == codex-cli OR (generic-cli + loopx_turn_host_request_v1 + validation-command-json)
        --> admit_preparation(): prepare_turn_host_arguments() + normalize_host_argv()
              |-- 非法空命令 "[]" --> 直接抛出 ValueError(0 cadence 预留 / 0 claim)
              '-- 合法命令 --> managed_cadence_start(request_id=identity.effect_id)
                              --> todo claim 写入租约 --> 重读就绪 decision
                              --> turn_run_once.py 以同 effect_id 恢复未启动槽位 (resumed_unstarted_reservation)

(Illustrative source-derived control-flow diagram against 7754b37b449b94f219b5bf52e7c41e187cfbefa2; tested positive/negative behaviors are backed by pytest & CLI probes below.)

架构分工与当前边界(architecture_assessment): 在现有 Turn CLI 与准备层拥有者(uses_effect_bound_start_identity、handle_turn_command 中的 builtin_execution_preparation_claim、managed_cadence_start)内通过单处路由谓词和参数校验前置完成扩面,而非为 generic-cli 复制一套独立 claim/cadence 状态机。 职责拆分保持清晰:handle_turn_command 仅承担入口门控、prepare_turn_host_arguments/normalize_host_argv 承担输入不变量前置检查、managed_cadence_start 承担频次/不重叠预约、builtin_execution_preparation_claim 承担普通认领与租约写入,各路径失败均原子中止于真实执行与扣费前。本 PR 仅将既有且可恢复的缺失租约前置准备与 effect-bound start identity 复用扩展至同时显式声明 generic-cli + loopx_turn_host_request_v1 + 非空 --validation-command-json 的单回合执行路径,同步更新安装包说明与双语 RFC 段落,保持其他主机类型与旧版请求协议路径完全不变。

具体改动 / Changes

本次精确提交 7754b37b449b94f219b5bf52e7c41e187cfbefa2(merge-base 5110b3afd8fbc33d2da33c28815e9320636244c3)共修改 8 个文件(+99 / -19):运行时代码 4 个文件(+26 / -8)、安装包文档 1 个文件(+6 / -5)、双语 RFC 2 个文件(+10 / -0)、安装版测试 1 个文件(+57 / -6)。

对照上游已接受规范 docs/architecture/rfcs/monorepo-distribution-split-v0.md 在改动前版本 5110b3afd8fbc33d2da33c28815e9320636244c3 的核对结论如下(同时 PR #9047 本身在该 RFC 的 Governed lifecycle and external effects 节末尾中英双语同步补充 1 段关于显式 generic-cli + 独立校验器补齐缺失租约的说明,未修改既有架构不变量):

  • I2(implemented):唯一内核真值与单一认领实现。handle_turn_command(loopx/cli_commands/turn.py)直接复用 builtin_execution_preparation_claim 完成普通 todo claim 与重读核对,不引入第二套租约写入者或包内分叉逻辑;由 tests/test_core_distribution.py::test_installed_core_prepares_generic_cli_first_turn 在安装版 wheel 中实测验证。
  • I4(implemented):核心命令语义自洽、无静默降级替代。未提供独立 --validation-command-json 或未选择 loopx_turn_host_request_v1 时保持原有 claim_required 显式诊断。
  • I7(implemented):缺失前置执行条件必须在派发前失败而非落入无治理执行。admit_preparation 在 cadence.admit 与 todo claim 之前先执行 prepare_turn_host_arguments 与 normalize_host_argv,非法空命令 [] 直接拒止且零副作用。
  • I8(implemented):重放与恢复严格核对持久化身份与租约代次。turn_run_once.py 通过 uses_effect_bound_start_identity 与准备阶段共享同一 settlement_identity.effect_id,--resume-turn-key 无副作用重放且 SIGKILL 恢复对 renew/release 拒绝继续提交;由安装版 SQLite/File 双后端实测覆盖。

关键代码讲解

  1. uses_effect_bound_start_identity(turn_cadence.py):将此前分散在 turn.py 和 turn_run_once.py 两处的 args.host == "codex-cli" 判断收敛为共享辅助函数。当 host == "codex-cli" 或 host == "generic-cli" 且 adapter_request_schema == COMPLETE_TURN_HOST_REQUEST_SCHEMA(即 loopx_turn_host_request_v1)时返回 True,保证准备阶段预留槽位与执行阶段消耗槽位使用同一判定规则。
  2. handle_turn_command 中的 admit_preparation(turn.py):仅在 execution_preparer is None、args.turn_command == "run-once"、args.execute 为真、非 generic-cli 或已显式提供 args.validation_command_json,且 uses_effect_bound_start_identity(...) 为真时构造准备器。在 admit_preparation 内部,故意先把 prepare_turn_host_arguments(..., validator_builder=build_loopx_turn_command_validator) 与 normalize_host_argv(raw_argv) 放在 managed_cadence_start(...).admit({"attempt": 1}) 之前,避免先占位记账后校验失败导致污染 cadence 窗口或错误触发 todo claim。
  3. execute_turn_run_once(turn_run_once.py):在真正进入回合执行前的 managed_cadence_start(...) 调用中,以 uses_effect_bound_start_identity(...) 决定是否传入 settlement_identity.effect_id;从而与 admit_preparation 中的预约 ID 对齐,让同一 Turn 命中 admitAutomationStart 的 resumed_unstarted_reservation 而不受 min_interval_minutes 误伤。

对主干的风险 / Risks

  • 阻断级缺陷: 无(No blocking finding)。
  • 最坏回归场景与边界约束验证: 最危险的失效模式是“校验前移遗漏导致非法命令先占用了 cadence 槽位或误领 Todo 租约”,以及“未带校验器的 generic-cli 被意外自动认领”。经实际检查:admit_preparation 对无效 --validation-command-json [] 和 --host-command-json [] 均在 prepare_turn_host_arguments/normalize_host_argv 中即刻抛出 ValueError(已通过真实 loopx.cli.build_parser 探针直接验证);test_installed_core_prepares_generic_cli_first_turn 也证明 --host-adapter-command-json [] 返回退出码 1 且 active is False、_spends == 0;未传 --validation-command-json 或非 v1 schema 的 generic-cli 不进入准备分支,与基线 5110b3afd8 行为完全隔离。
  • 范围适配、兼容与隔离评估: 新增函数均有现役生产调用方(turn.py 与 turn_run_once.py);未引入新的共享枚举或需注册的语义常量(沿用既有 COMPLETE_TURN_HOST_REQUEST_SCHEMA 与 resumed_unstarted_reservation);无范围膨胀或对无关主机的默认行为漂移,因此属于必要、克制且易回滚的改动。
  • 本地验证与残余风险: 本地已于工作树运行完整安装版 loopx_core-2.4.0 wheel 测试(50 passed in 146.63s)、turn 准备与执行器四套核心 pytest(401 passed in 506.00s),以及 ruff / mypy / check_rfc_bilingual.py / typecheck:control-plane / loopx check / canary premerge --tier quick(merge_gate_passed: true,仅预先存在与本 PR 无关的两处可维护性棘轮告警 advisory_failure_count: 1)。残余观测缺口:真实 CLI 探针测到 --validation-command-json [] 在解析后即抛 ValueError,未额外构建独立冷启动 subprocess 来重复覆盖该特定 [] 参数,且未咨询远端 CI(按策略 wait_for_ci=false)。

我的整体评价 / Verdict

交付与影响判定(outcome_impact): long_horizon 与 user_experience 均判定为 improved —— 冷启动兼容 generic-cli + 独立校验器的单回合自主执行不再因缺少前置 todo claim 或制备/派发 cadence ID 割裂而卡住,同时严守了无校验器或非 v1 适配器的既有保护边界。关于可视化界面评审(visual_review):inspected paths: loopx/cli_commands/turn.py, loopx/cli_commands/turn_cadence.py, loopx/cli_commands/turn_run_once.py, packages/loopx-core/README.md — CLI 与 runtime/docs 变更,未涉及渲染界面。;unverified_scope: none。

语义、兼容性与代码体量结论: observable_semantics 判定为 intentional_change_validated(对兼容 generic-cli + v1 + 独立校验器放开前置认领准备,非兼容路径及 codex-cli 全量等价保留);repository_reuse 为 reused(未复制第二份认领或 cadence 逻辑);code_volume 为 necessary(兼容性保留现有 codex-cli、bare generic-cli 与 legacy_request_id 路径);change_proportionality 为 proportionate(核心源码净增仅 +18 行且换得跨 SQLite/File 的已安装核心端到端可用性);default_off_isolation 为 isolated;authority_semantics 为 aligned;semantic_alignment 为 aligned(沿用既有 COMPLETE_TURN_HOST_REQUEST_SCHEMA 与既有控制面词表,无新词表登记或 RFC 补充缺口,双语 RFCDiff 检查已通过)。

综上,在精确提交 7754b37b449b94f219b5bf52e7c41e187cfbefa2 上所有核心不变量与本地安装版验证已直接跑通,无阻断发现,建议批准合入。

English Verdict: APPROVE

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.

2 participants