From 7754b37b449b94f219b5bf52e7c41e187cfbefa2 Mon Sep 17 00:00:00 2001 From: cicolord Date: Thu, 19 Nov 2026 01:48:17 +0800 Subject: [PATCH] feat(turn): prepare a missing lease for a generic CLI first Turn Signed-off-by: cicolord --- .../rfcs/monorepo-distribution-split-v0.md | 6 ++ .../monorepo-distribution-split-v0.zh-CN.md | 4 ++ loopx/cli_commands/turn.py | 16 +++-- loopx/cli_commands/turn_cadence.py | 10 ++- loopx/cli_commands/turn_run_once.py | 6 +- .../codex_execution_preparation.py | 2 +- packages/loopx-core/README.md | 11 ++-- tests/test_core_distribution.py | 63 +++++++++++++++++-- 8 files changed, 99 insertions(+), 19 deletions(-) diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 6e5521ac0a..3f8262f32f 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -428,6 +428,12 @@ and persist evidence, settle once, then deliver/read back through the owning channel. Each step uses its existing legal transitions and replay rules; this description adds no competing status enum or transaction coordinator. +An explicit `turn run-once --execute` with a compatible generic CLI adapter +and an independent validator can prepare an eligible Todo's missing lease. +The Host reuses the ordinary claim and reads back that same Todo before +dispatch. The claim and launch share one Turn identity. Recovery uses the +lease generation captured by the original attempt. + An executor crash, a lost effect acknowledgement and a lost result-delivery acknowledgement are different recovery cases. An operation provider must expose whether an effect can be reconciled and retried safely. Unknown external state diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md index 2303929af4..61f5a703b1 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -296,6 +296,10 @@ authority receipt 持久化、弱化 fsync/事务保证,或缓存过期权限/ 再经所属 channel 交付/回读。各步骤使用既有合法迁移与重放规则;这段描述不新增竞争的 status enum 或事务协调者。 +显式执行 `turn run-once --execute` 时,兼容的通用 CLI 宿主配合独立校验器,可为准入 +Todo 补齐缺失的租约。宿主复用普通领取操作,核对同一 Todo 已就绪后再派发。领取与 +派发共用同一 Turn 身份。恢复使用原尝试捕获的租约代次。 + Executor 崩溃、effect ACK 丢失、结果交付 ACK 丢失是不同恢复情形。 Operation provider 必须说明某个 effect 能否核对、能否安全重试。 外部状态未知时,后续依赖操作须等待回读或人工干预;“未观测到”不等于“未执行”。 diff --git a/loopx/cli_commands/turn.py b/loopx/cli_commands/turn.py index 8f5f220dfa..06ed815709 100644 --- a/loopx/cli_commands/turn.py +++ b/loopx/cli_commands/turn.py @@ -94,31 +94,39 @@ def project_preparation_effects(value: dict[str, Any]) -> None: registry_path=registry_path, runtime_root_override=runtime_root_arg, ) + from .turn_cadence import managed_cadence_start, uses_effect_bound_start_identity + preparation_admission: dict[str, Any] | None = None execution_preparer = native_execution_preparer preparation_error = "native task preparation did not make the same Todo ready" if ( execution_preparer is None and args.turn_command == "run-once" - and args.host == "codex-cli" and bool(getattr(args, "execute", False)) + and (args.host != "generic-cli" or getattr(args, "validation_command_json", None)) + and uses_effect_bound_start_identity( + args.host, getattr(args, "host_adapter_request_schema", None), + ) ): from ..control_plane.turn_driver.codex_execution_preparation import ( builtin_execution_preparation_claim, ) from .turn_host_request import prepare_turn_host_arguments - from ..control_plane.turn_driver import build_loopx_turn_command_validator - from .turn_cadence import managed_cadence_start + from ..control_plane.turn_driver.command_validation import ( + build_loopx_turn_command_validator, normalize_host_argv, + ) project_cwd = Path(args.project).expanduser().resolve() def admit_preparation(identity): nonlocal preparation_admission - prepare_turn_host_arguments( + _, raw_argv, _ = prepare_turn_host_arguments( args, native_host_runner=None, native_session_binding_resolver=None, native_task_validator=None, validator_builder=build_loopx_turn_command_validator, ) + if raw_argv is not None: + normalize_host_argv(raw_argv) args.turn_instance_id = identity.turn_instance_id cadence = managed_cadence_start( runtime_root=runtime_root, goal_id=args.goal_id, agent_id=args.agent_id, diff --git a/loopx/cli_commands/turn_cadence.py b/loopx/cli_commands/turn_cadence.py index d5e3befd8d..f0440a9ec2 100644 --- a/loopx/cli_commands/turn_cadence.py +++ b/loopx/cli_commands/turn_cadence.py @@ -6,6 +6,7 @@ from typing import Any, NamedTuple from ..control_plane.effect_runtime import effect_runtime_result +from ..control_plane.quota.turn_envelope import COMPLETE_TURN_HOST_REQUEST_SCHEMA class ManagedCadenceStart(NamedTuple): @@ -21,6 +22,13 @@ class ManagedCadenceStart(NamedTuple): confirm: Callable[[], None] +def uses_effect_bound_start_identity(host: str, adapter_request_schema: str | None) -> bool: + """These Host routes can reserve the same start before a Turn plan exists.""" + return host == "codex-cli" or ( + host == "generic-cli" and adapter_request_schema == COMPLETE_TURN_HOST_REQUEST_SCHEMA + ) + + def managed_cadence_start( *, runtime_root: Path, @@ -59,7 +67,7 @@ def reserve(start_id: str) -> dict[str, Any]: and start_request_id != legacy_request_id and admission.get("admitted") is not True and admission.get("reason") == "minimum_interval_wait"): - # Historical Codex journals reserved by transaction key. Retry only + # Historical journals reserved by transaction key. Retry only # this exact identity, after a no-write wait, so their unstarted # reservations remain recoverable; never bypass a started request. admission = reserve(legacy_request_id) diff --git a/loopx/cli_commands/turn_run_once.py b/loopx/cli_commands/turn_run_once.py index bd75698823..d0e2f0183f 100644 --- a/loopx/cli_commands/turn_run_once.py +++ b/loopx/cli_commands/turn_run_once.py @@ -42,7 +42,7 @@ from ..quota import spend_quota_slot from ..state_refresh import refresh_state_run from ..control_plane.todos.path_resolution import resolve_todo_state_path -from .turn_cadence import managed_cadence_start +from .turn_cadence import managed_cadence_start, uses_effect_bound_start_identity from .turn_host_request import build_codex_cli_host_runner, prepare_turn_host_request from .turn_decision import collect_turn_status_payload, current_turn_host_launch_decision from .turn_rendering import build_turn_error_payload @@ -771,7 +771,9 @@ def on_managed_start_admitted() -> None: automation_id=args.automation_id, manual_reason=args.manual_interval_bypass_reason, on_admitted=on_managed_start_admitted, - request_id=settlement_identity.effect_id if args.host == "codex-cli" else None, + request_id=settlement_identity.effect_id if uses_effect_bound_start_identity( + args.host, getattr(args, "host_adapter_request_schema", None), + ) else None, ) execution_started = bool(args.execute) diff --git a/loopx/control_plane/turn_driver/codex_execution_preparation.py b/loopx/control_plane/turn_driver/codex_execution_preparation.py index 8648adaefb..d07d9cc4f9 100644 --- a/loopx/control_plane/turn_driver/codex_execution_preparation.py +++ b/loopx/control_plane/turn_driver/codex_execution_preparation.py @@ -1,4 +1,4 @@ -"""Codex lifecycle-hook executor for the typed execution-preparation action. +"""Managed Host lease preparation and the Codex lifecycle-hook adapter. The TypeScript control plane remains the decision owner. This adapter accepts only its exact ordinary claim, executes it through the public CLI, and proves diff --git a/packages/loopx-core/README.md b/packages/loopx-core/README.md index ae5ef9df5d..240e97724b 100644 --- a/packages/loopx-core/README.md +++ b/packages/loopx-core/README.md @@ -38,11 +38,12 @@ caller's selected executable. Deep diagnosis still requires recorded module and console entrypoints; redirected or missing records fail. The host supplies the model, tools and scheduler; the wheel does not provide them or activate an optional capability from goal wording. `connect` and `configure-goal` remain -available for explicit setup. Create and claim work through the existing `todo` -commands. An ordinary managed claim -prepares the default SQLite lease without asking the task model to manage lease -flags. Completion carries the original captured lease generation; recovery -refuses a renewed, released or replaced generation rather than adopting it. +available for explicit setup. Create work through `todo add`. With an explicitly +selected `generic-cli` v1 adapter and an independent validator, `turn run-once +--execute` prepares a missing lease for the eligible Todo before dispatch. +Completion and recovery use the original captured lease generation. Recovery +refuses a renewed, released or replaced lease. The ordinary `todo claim` +command is available for explicit preparation. The installed-only qualification in [`tests/test_core_distribution.py`](../../tests/test_core_distribution.py) exercises setup, independent result validation, process loss, replay and refusal. diff --git a/tests/test_core_distribution.py b/tests/test_core_distribution.py index f39fae8197..b6e4810e3b 100644 --- a/tests/test_core_distribution.py +++ b/tests/test_core_distribution.py @@ -402,6 +402,10 @@ def test_installed_core_module_doctor_requires_recorded_entrypoints(core_python, @pytest.fixture(params=["sqlite", "file"]) def task(tmp_path, monkeypatch, core_python, request): + return _prepare_task(tmp_path, monkeypatch, core_python, provider=request.param, claim=True) + + +def _prepare_task(tmp_path, monkeypatch, core_python, *, provider, claim): from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime isolate_sqlite_runtime(tmp_path, monkeypatch) @@ -410,7 +414,7 @@ def task(tmp_path, monkeypatch, core_python, request): registry = project / ".loopx/registry.json" prefix = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json"] - if request.param == "file": + if provider == "file": # Configure the existing installed owner before creating synthetic # state; never migrate or edit a live Goal for qualification. setup = '''import json,sys @@ -437,7 +441,7 @@ def command(*arguments): created = command("connect", "--project", str(project), "--goal-id", GOAL, "--objective", "Produce and independently check squared integers zero through seven.", "--write-scope", "docs/**", "--no-global-sync") - assert created["storage_selection"]["provider"] == request.param + assert created["storage_selection"]["provider"] == provider assert created["storage_selection"]["handoff_mode"] == "hard_lease" command("configure-goal", "--goal-id", GOAL, "--registered-agent", AGENT, "--quota-compute", "1", "--execute") @@ -445,8 +449,9 @@ def command(*arguments): "--text", "Produce and independently validate squares.json.", "--priority", "P1", "--task-class", "advancement_task", "--action-kind", "validate", "--operation-id", "core-create-task") - command("todo", "claim", "--goal-id", GOAL, "--todo-id", added["todo_id"], - "--agent-id", AGENT, "--claimed-by", AGENT, "--claim-operation-id", "core-new-task") + if claim: + command("todo", "claim", "--goal-id", GOAL, "--todo-id", added["todo_id"], + "--agent-id", AGENT, "--claimed-by", AGENT, "--claim-operation-id", "core-new-task") workspace = project / "docs/isolated-work" workspace.mkdir(parents=True) arguments = ["--registry", str(registry), "--runtime-root", str(runtime), @@ -567,6 +572,47 @@ def _assert_committed(core_python, workspace, runtime, result): return result["resume_turn_key"] +@pytest.mark.parametrize("provider", ["sqlite", "file"]) +def test_installed_core_prepares_generic_cli_first_turn(core_python, tmp_path, monkeypatch, provider): + workspace, runtime, registry, arguments = _prepare_task( + tmp_path, monkeypatch, core_python, provider=provider, claim=False, + ) + configure_cadence = '''import sys +from loopx.control_plane.effect_runtime import effect_runtime_result + +runtime, goal, agent = sys.argv[1:] +result = effect_runtime_result("quota.automation_cadence.manage", { + "runtime_root": runtime, "goal_id": goal, "agent_id": agent, + "operation": "configure", "min_interval_minutes": 1440, + "expected_revision": 0, "owner_reference": "fixture-owner", "execute": True, +}) +assert result["ok"] and result["min_interval_minutes"] == 1440 +''' + configured = subprocess.run([core_python, "-I", "-c", configure_cadence, str(runtime), GOAL, AGENT], + cwd=workspace, env=_environment(core_python), capture_output=True, text=True, timeout=30) + assert configured.returncode == 0, configured.stderr + + prefix = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json"] + before = json.loads(_run(core_python, [*prefix, "quota", "should-run", "--goal-id", GOAL, + "--agent-id", AGENT, "--context-delivery", "off"], workspace).stdout) + preparation = before["execution_preparation"] + assert preparation["state"] == "claim_required" and preparation["reason_code"] == "task_lease_missing" + lease_args = [*prefix, "task-lease", "inspect", "--goal-id", GOAL, "--todo-id", preparation["todo_id"]] + + refused = json.loads(_run(core_python, [*arguments, "--host-adapter-command-json", "[]"], + workspace, expected=1).stdout) + assert not any(value is True for value in refused["effects"].values()) + assert json.loads(_run(core_python, lease_args, workspace).stdout)["active"] is False + assert not (workspace / "host-invocations").exists() and _spends(runtime) == 0 + + result = json.loads(_run(core_python, arguments, workspace).stdout) + key = _assert_committed(core_python, workspace, runtime, result) + assert result["admission"]["reason"] == "resumed_unstarted_reservation" + replay = json.loads(_run(core_python, [*arguments, "--resume-turn-key", key], workspace).stdout) + assert replay["replayed"] is True and all(value is False for value in replay["effects"].values()) + _assert_committed(core_python, workspace, runtime, replay) + + @pytest.mark.parametrize("checkpoint", [None, "continue", "no_change"]) def test_installed_core_executes_checks_and_replays_once(core_python, task, checkpoint): workspace, runtime, registry, arguments = task @@ -612,9 +658,14 @@ def test_installed_core_executes_checks_and_replays_once(core_python, task, chec @pytest.mark.skipif(os.name == "nt", reason="this qualification injects a POSIX SIGKILL") +@pytest.mark.parametrize("provider", ["sqlite", "file"]) @pytest.mark.parametrize("lease_change", [None, "renew", "release"]) -def test_installed_core_recovers_confirmed_result_after_process_loss(core_python, task, lease_change): - workspace, runtime, registry, arguments = task +def test_installed_core_recovers_confirmed_result_after_process_loss( + core_python, tmp_path, monkeypatch, provider, lease_change, +): + workspace, runtime, registry, arguments = _prepare_task( + tmp_path, monkeypatch, core_python, provider=provider, claim=False, + ) pause = workspace / "pause-validator" pause.touch() process = subprocess.Popen(_command(core_python, arguments), cwd=workspace,