diff --git a/docs/product/runtimes/codex-cli/codex-cli-automation-driver.md b/docs/product/runtimes/codex-cli/codex-cli-automation-driver.md index 45cd648097..1ed9c2a254 100644 --- a/docs/product/runtimes/codex-cli/codex-cli-automation-driver.md +++ b/docs/product/runtimes/codex-cli/codex-cli-automation-driver.md @@ -93,6 +93,32 @@ and `--host-adapter-command-json ...` for a compatible Trae or another CLI after its wrapper implements the typed stdin/stdout contract in the host-neutral protocol. +The built-in Codex result schema accepts `validated_completion` for a fully +delivered selected Todo. After independent validation, the adapter invokes the +existing Todo lifecycle, including its controller-declared validator, before +accountable refresh and one quota debit. It retains the original launch lease +generation in the Turn journal for completion and cached-result recovery; +lease loss or a newer same-Agent generation cannot authorize the old result. +`validated_progress` remains partial progress and never silently completes work. +For a predeclared terminal Todo, closeout after debit uses the original +completion receipt and closes the same Turn. +Goal acceptance remains a separate owner check. + +After independent validation, the adapter checks the original Goal's running +authority before settling either result. When the owner stops the Goal during +that validation, the Turn retains its validation checkpoint and leaves the +Todo and quota untouched. + +内置 Codex 的结果格式支持 `validated_completion`,用于已满足全部要求的已选 Todo。 +独立验证通过后,adapter 先调用现有 Todo 生命周期及 controller 声明的完成验证器, +再写回可核算进展并扣额一次。Turn journal 保留启动时的原租约代次,完成和缓存结果 +恢复都使用该代次;租约丢失或同 Agent 的新代次不能授权旧结果。`validated_progress` +仍表示部分进展,不会被静默升级为完成。对于预声明的终态 Todo,扣额后按原完成回执 +收尾同一轮 Turn。Goal 验收仍由原 owner 单独检查。 + +独立验证结束后,adapter 会在结算前重新检查原 Goal 的运行权限。验证期间若 owner +停止 Goal,Turn 保留验证记录,Todo 和额度不变。 + That wrapper is deliberately thin: it translates one Turn request into one bounded Agent CLI invocation, preserves only an opaque local resume handle, and returns one typed candidate result. LoopX remains responsible for the control diff --git a/loopx/cli_commands/turn_run_once.py b/loopx/cli_commands/turn_run_once.py index fa28ea033e..80e46f402f 100644 --- a/loopx/cli_commands/turn_run_once.py +++ b/loopx/cli_commands/turn_run_once.py @@ -4,6 +4,7 @@ from functools import partial import sys as _sys from collections.abc import Callable, Mapping +from contextlib import contextmanager, nullcontext from pathlib import Path from typing import TYPE_CHECKING as _TYPE_CHECKING from typing import Any @@ -476,8 +477,29 @@ def terminal_closeout( effect_ref: str, ) -> dict[str, object]: require_effect_ref(effect_ref, SettlementStepKind.TERMINAL_CLOSEOUT) + if args.host == "codex-cli": + # Builtin completion has already retired the original lease. + # Verify the exact terminal receipt; never start another completion. + observed = terminal_closeout_resolver(effect_ref) + receipt = observed.get("payload") + if observed.get("kind") == "committed" and isinstance(receipt, dict): + return receipt + return { + "ok": False, + "appended": False, + "reason": observed.get("reason") or "Builtin terminal completion receipt is missing", + } return todo_completion(result, effect_ref=effect_ref) + def codex_writeback( + result: dict[str, object], *, effect_ref: str, + ) -> dict[str, object]: + # Accountable refresh requires durable controller validation even for + # a predeclared terminal Todo. Other hosts keep their existing order. + if result.get("result_kind") == "validated_completion": + return completion_writeback(result, effect_ref=effect_ref) + return writeback(result, effect_ref=effect_ref) + def current_status() -> dict[str, object]: return collect_turn_status_payload( args, @@ -847,6 +869,19 @@ def settlement_admission(): return request_settlement_lifetime(request_locator, settlement_identity, registry_path=registry_path, runtime_root=runtime_root, workspace=project) + if args.host == "codex-cli" and goal_admission is not None: + request_lifetime = settlement_admission or nullcontext + + @contextmanager + def codex_settlement_admission(): + with request_lifetime(): + # Independent validation can outlive the running Goal. + # Check the original authority before any settlement effect. + goal_admission.require_running(operation="codex_cli_turn_settle") + yield + + settlement_admission = codex_settlement_admission + def on_managed_start_admitted() -> None: if settlement_identity.request_subject is not None: require_current_request_operation(request_locator, settlement_identity, @@ -898,7 +933,8 @@ def on_managed_start_admitted() -> None: retry_failed=bool(args.retry_failed_turn), task_validator=task_validator, settlement_admission=settlement_admission, - writeback=writeback if args.execute else None, + writeback=(codex_writeback if args.host == "codex-cli" else writeback) + if args.execute else None, completion_writeback=completion_writeback if args.execute else None, completion_intent=completion_intent if args.execute else None, terminal_closeout=terminal_closeout if args.execute else None, diff --git a/loopx/control_plane/turn_driver/codex_cli.py b/loopx/control_plane/turn_driver/codex_cli.py index dd4d453b5e..e2433070b0 100644 --- a/loopx/control_plane/turn_driver/codex_cli.py +++ b/loopx/control_plane/turn_driver/codex_cli.py @@ -58,6 +58,7 @@ CODEX_STDIO_MCP_SERVER_SCHEMA_VERSION = "codex_stdio_mcp_server_v0" CODEX_CLI_RESULT_KINDS = ( "validated_progress", + "validated_completion", "repair_required", "replan_required", "user_action_required", @@ -395,7 +396,7 @@ def _render_prompt(request: Mapping[str, Any], *, checked: Mapping[str, Any] | N ("Use task_context for the admitted work. Its interaction_contract.agent_channel carries work_context, required_reads and primary_action; the outer adapter retains the complete original source and Core effect instructions. " if complete else ("Use turn_authority as the verified authority for this Turn. " if staged else "Use the TurnEnvelope as the source of truth. ")) + "Read work_context and remaining required_reads before primary_action; do not repeat fulfilled reads; perform work only when its contract allows it. The selected Todo summary is not its full requirements, and completing that work does not prove Goal completion.", "Do not write LoopX state, spend quota, or apply scheduler changes; the adapter owns those effects.", - "Return only the schema-constrained result. For validated_progress, repair_required, or replan_required, fill every material field with public-safe evidence.", + "Return only the schema-constrained result. Use validated_completion when the selected Todo's full requirements are met; the adapter runs its declared completion validation and durably completes it before accountable writeback. Use validated_progress for partial work; progress alone never completes a Todo. Neither result proves Goal closure. For validated_progress, validated_completion, repair_required, or replan_required, fill every material field with public-safe evidence.", "For those material results, preserve the actual delivery_batch_scale and delivery_outcome selected from the signed execution_profile's work and outcome requirements. Return work_evidence and validation_evidence as separate non-empty arrays of short public-safe strings; name the artifact or observed work in the first and the independent command or readback in the second. For legacy requests without execution_profile, use null when evidence is not supplied. For stop results, set both evidence fields to null.", "For those material results, set path_delta_mode=material_replan and result_kind=replan_required only when this Turn changes a prior assumption, route, scope, acceptance rule, or stops prior work; then provide a complete bounded agent vision packet with goal_path_delta_v0 in agent_vision_json and leave vision_unchanged_reason empty.", "For routine continuation, retry, successor creation, or no-change replanning, explicitly set path_delta_mode=unchanged. Reuse the current checkpoint with vision_unchanged_reason and empty agent_vision_json, or record new progress/completion evidence in a fresh agent_vision_json packet with path_delta.outcome continue or no_change and empty vision_unchanged_reason.", diff --git a/tests/test_codex_turn_completion.py b/tests/test_codex_turn_completion.py new file mode 100644 index 0000000000..614cebc3de --- /dev/null +++ b/tests/test_codex_turn_completion.py @@ -0,0 +1,512 @@ +"""Builtin completion uses the real Todo validator and canonical lease fence.""" + +from __future__ import annotations + +import contextlib +import io +import json +import sys +from pathlib import Path +from types import SimpleNamespace + +import pytest + +from loopx.capabilities.native_chat.steward_turn import StewardTurnHost +from loopx.cli import build_parser, main +from loopx.cli_commands import turn_run_once +from loopx.cli_commands.turn import handle_turn_command +from loopx.control_plane.todos.mutation_api import add_goal_todo +from loopx.control_plane.turn_driver.codex_cli import codex_cli_result_schema +from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime +from tests.test_loopx_turn_codex_cli import _fake_codex +from tests.test_loopx_turn_driver import ( + _completion_host_and_validation_scripts, + _turn_journal, + _write_live_fixture, +) + + +def _cli(registry: Path, runtime: Path, *args: str) -> tuple[int, dict]: + output = io.StringIO() + with contextlib.redirect_stdout(output): + code = main( + [ + "--registry", + str(registry), + "--runtime-root", + str(runtime), + "--format", + "json", + *args, + ] + ) + return code, json.loads(output.getvalue()) + + +@pytest.mark.parametrize("provider", ["file", "sqlite"]) +@pytest.mark.parametrize( + "scenario", + [ + "completion", + "terminal", + "progress", + "independent_validation", + "declared_validation", + "stale_lease", + "stop_after_progress_validation", + "stop_after_completion_validation", + ], +) +def test_builtin_codex_completes_before_accountable_writeback( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + provider: str, + scenario: str, +) -> None: + isolate_sqlite_runtime(tmp_path, monkeypatch) + terminal = scenario == "terminal" + progress = scenario in {"progress", "stop_after_progress_validation"} + stopped_after_validation = scenario in { + "stop_after_progress_validation", + "stop_after_completion_validation", + } + project, runtime, registry = _write_live_fixture( + tmp_path, + provider=provider, + handoff_mode="hard_lease", + todo_metadata_extra="no_followup=true" if terminal else "", + ) + added = ( + {"todo_id": "todo_fixture0001"} + if terminal + else add_goal_todo( + registry_path=registry, + goal_id="loopx-turn-fixture", + role="agent", + text="Deliver the independently checked artifact.", + task_class="advancement_task", + action_kind="fixture", + claimed_by="codex-fixture", + agent_id="codex-fixture", + validation_command_json=None + if progress + else json.dumps( + [ + sys.executable, + "-c", + "raise SystemExit(1)" + if scenario == "declared_validation" + else "raise SystemExit(0)", + ] + ), + ) + ) + todo_id = added["todo_id"] + claim_code, claim = _cli( + registry, + runtime, + "todo", + "claim", + "--goal-id", + "loopx-turn-fixture", + "--todo-id", + todo_id, + "--agent-id", + "codex-fixture", + "--claimed-by", + "codex-fixture", + ) + assert claim_code == 0, claim + if terminal: + code, current = _cli( + registry, runtime, "todo", "list", "--goal-id", "loopx-turn-fixture" + ) + assert code == 0, current + code, declaration = _cli( + registry, + runtime, + "todo", + "update", + "--goal-id", + "loopx-turn-fixture", + "--todo-id", + todo_id, + "--agent-id", + "codex-fixture", + "--claim-operation-id", + claim["claim_operation_id"], + "--validation-command-json", + json.dumps([sys.executable, "-c", "raise SystemExit(0)"]), + "--update-operation-id", + "declare-terminal-validation", + "--update-expected-provider-revision", + current["authority_read"]["provider_revision"], + ) + assert code == 0, declaration + binary, host_log = _fake_codex(tmp_path) + codex_home = tmp_path / "codex-home" + codex_home.mkdir() + monkeypatch.setenv("CODEX_HOME", str(codex_home)) + monkeypatch.setenv("LOOPX_RELEASE_ROOT", str(Path(__file__).resolve().parents[1])) + monkeypatch.setenv("FAKE_CODEX_LOG", str(host_log)) + monkeypatch.setenv( + "FAKE_CODEX_RESULT_FIELDS", + json.dumps( + { + "result_kind": "validated_progress" if progress else "validated_completion", + } + ), + ) + if scenario == "stale_lease": + code, inspection = _cli( + registry, + runtime, + "task-lease", + "inspect", + "--goal-id", + "loopx-turn-fixture", + "--todo-id", + todo_id, + ) + assert code == 0 and inspection["active"] is True, inspection + lease = inspection["lease"] + run_codex = turn_run_once.run_codex_cli_host + + def host(request, **kwargs): + # Renew after launch capture. A newer generation of the same owner + # still cannot authorize this result. + code, renewed = _cli( + registry, + runtime, + "task-lease", + "renew", + "--goal-id", + "loopx-turn-fixture", + "--todo-id", + todo_id, + "--owner", + "codex-fixture", + "--idempotency-key", + lease["idempotency_key"], + "--expected-version", + str(lease["version"]), + ) + assert code == 0, renewed + return run_codex(request, **kwargs) + + monkeypatch.setattr(turn_run_once, "run_codex_cli_host", host) + if stopped_after_validation: + build_validator = turn_run_once.build_loopx_turn_command_validator + + def validate_then_stop(*args, **kwargs): + validate = build_validator(*args, **kwargs) + + def checked(plan, result): + observation = validate(plan, result) + assert observation["status"] == "passed", observation + lifecycle = ("goal-lifecycle", "--goal-id", "loopx-turn-fixture", "--operation", "stop") + code, preview = _cli(registry, runtime, *lifecycle) + assert code == 0 and not preview["written"], preview + code, stopped = _cli( + registry, runtime, *lifecycle, "--actor-kind", "owner", + "--expected-state-fingerprint", preview["observed_state_fingerprint"], "--execute", + ) + assert code == 0 and stopped["readback"]["verified"], stopped + assert stopped["after_state"] == "stopped", stopped + return observation + + return checked + + monkeypatch.setattr(turn_run_once, "build_loopx_turn_command_validator", validate_then_stop) + argv = [ + "turn", + "run-once", + "--goal-id", + "loopx-turn-fixture", + "--agent-id", + "codex-fixture", + "--todo-id", + todo_id, + "--host", + "codex-cli", + "--project", + str(project), + "--codex-bin", + str(binary), + "--codex-model", + "fixture-model", + "--codex-reasoning-effort", + "high", + "--codex-sandbox", + "read-only", + "--validation-command-json", + json.dumps( + [ + sys.executable, + "-c", + "raise SystemExit(1)" + if scenario == "independent_validation" + else "raise SystemExit(0)", + ] + ), + "--no-global-sync", + "--execute", + ] + code, result = _cli(registry, runtime, *argv) + journals = list((runtime / "goals" / "loopx-turn-fixture" / "turns").glob("*.json")) + assert len(journals) == 1 + journal = json.loads(journals[0].read_text()) + assert len(host_log.read_text().splitlines()) == 1 + if stopped_after_validation: + assert code == 1 and result["error_code"] == "goal_stopped", result + assert journal["completed_phases"] == ["host_execute", "typed_result", "validation"] + read_code, readback = _cli( + registry, runtime, "todo", "list", "--goal-id", "loopx-turn-fixture", "--todo-id", todo_id, + ) + assert read_code == 0 and readback["todo"]["status"] == "open", readback + return + if scenario in {"independent_validation", "declared_validation", "stale_lease"}: + assert result["status"] != "committed", result + assert "quota_spend" not in journal["completed_phases"] + assert "durable_writeback" not in journal["completed_phases"] + if scenario == "stale_lease": + recovery_args = argv[:-1] + todo_option = recovery_args.index("--todo-id") + del recovery_args[todo_option : todo_option + 2] + code, retried = _cli( + registry, + runtime, + *recovery_args, + "--resume-turn-key", + journal["turn_key"], + "--execute", + ) + assert retried.get("status") != "committed", retried + assert len(host_log.read_text().splitlines()) == 1 + return + assert code == 0 and result["status"] == "committed", result + kinds = _effect_kinds(runtime, journal) + if progress: + assert "completion" not in journal["writeback"] + assert kinds == ["refresh_state", "quota_spend"] + read_code, readback = _cli( + registry, runtime, "todo", "list", "--goal-id", "loopx-turn-fixture" + ) + assert read_code == 0, readback + assert ( + next(todo for todo in readback["todos"] if todo["todo_id"] == todo_id)[ + "status" + ] + == "open" + ) + else: + completion = { + "todo_id": todo_id, + "continuation": "no_followup" if terminal else "active_goal", + } + assert journal["writeback"]["completion"] == completion + assert kinds == ["todo_complete", "refresh_state", "quota_spend"] + if terminal: + assert journal["terminal_closeout"]["completion"] == completion + replay_args = argv[:-1] + todo_option = replay_args.index("--todo-id") + del replay_args[todo_option : todo_option + 2] + code, replay = _cli( + registry, + runtime, + *replay_args, + "--resume-turn-key", + journal["turn_key"], + "--execute", + ) + assert code == 0 and replay["replayed"] is True, replay + assert len(host_log.read_text().splitlines()) == 1 + assert not any(replay["effects"].values()) + assert _effect_kinds(runtime, journal) == kinds + + +def _effect_kinds(runtime: Path, journal: dict) -> list[str]: + identity = journal["plan"]["transaction"] + run_id = identity.get("turn_instance_id", journal["turn_key"]) + path = runtime / "goals" / "loopx-turn-fixture" / "rollout-event-log.jsonl" + rows = (json.loads(line) for line in path.read_text().splitlines()) + return [ + row["event_kind"] + for row in rows + if row.get("run_id") == run_id + and row["event_kind"] in {"refresh_state", "quota_spend", "todo_complete"} + ] + + +@pytest.mark.parametrize("provider", ["file", "sqlite"]) +@pytest.mark.parametrize( + "interruption", [None, "after_debit", "lost_completion_receipt"] +) +def test_native_terminal_closeout_keeps_the_original_lease_and_turn( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + provider: str, + interruption: str | None, +) -> None: + isolate_sqlite_runtime(tmp_path, monkeypatch) + project, runtime, registry = _write_live_fixture( + tmp_path, + provider=provider, + handoff_mode="hard_lease", + todo_metadata_extra="no_followup=true", + ) + goal_id, agent_id, todo_id = ( + "loopx-turn-fixture", + "codex-fixture", + "todo_fixture0001", + ) + code, claim = _cli( + registry, + runtime, + "todo", + "claim", + "--goal-id", + goal_id, + "--todo-id", + todo_id, + "--agent-id", + agent_id, + "--claimed-by", + agent_id, + ) + assert code == 0, claim + lease_argv = ("task-lease", "inspect", "--goal-id", goal_id, "--todo-id", todo_id) + code, inspection = _cli(registry, runtime, *lease_argv) + assert code == 0 and inspection["active"] is True, inspection + lease = inspection["lease"] + adapter = SimpleNamespace( + controller=SimpleNamespace( + registry_path=registry, coordination_runtime_root=runtime + ) + ) + host_calls, lease_reads = [], [] + + def resolve_lease(): + lease_reads.append(lease["version"]) + return StewardTurnHost._task_lease_proof( + adapter, {"actor": {"goal_id": goal_id}, "todo_id": todo_id}, lease + ) + + def host(request, launch_lifetime): + with launch_lifetime(): + host_calls.append(request["turn_key"]) + (project / "completion-artifact.txt").write_text( + "completed", encoding="utf-8" + ) + return { + "schema_version": "loopx_turn_result_v0", + "turn_key": request["turn_key"], + "result_kind": "validated_completion", + "completed_phases": ["host_execute", "typed_result"], + "classification": "fixture_completion", + "recommended_action": "Refresh the active Goal.", + "next_action": "Read the fresh decision.", + "delivery_batch_scale": "implementation", + "delivery_outcome": "outcome_progress", + "vision_unchanged_reason": "The remaining Goal is unchanged.", + "work_evidence": ["artifact:completion-artifact"], + "validation_evidence": ["check:artifact-contents"], + } + + _, validation = _completion_host_and_validation_scripts() + base = [ + "turn", + "run-once", + "--host", + "generic-cli", + "--goal-id", + goal_id, + "--agent-id", + agent_id, + "--project", + str(project), + "--no-global-sync", + "--validation-command-json", + json.dumps([sys.executable, "-c", validation]), + "--execute", + ] + + def invoke(*extra: str): + args = build_parser().parse_args([*base, *extra]) + args.host, args.session_scope = "codex-app-server", "agent" + result: dict = {} + code = handle_turn_command( + args, + registry_path=registry, + runtime_root_arg=str(runtime), + output_format=lambda *_args, **_kwargs: "json", + print_payload=lambda value, *_args: result.update(value), + native_host_runner=host, + native_completion_lease_resolver=resolve_lease, + native_session_binding_resolver=lambda _: { + "schema_version": "loopx_turn_session_binding_v0", + "goal_id": goal_id, + "agent_id": agent_id, + }, + ) + return code, result + + complete = turn_run_once.write_turn_validated_completion + if interruption is not None: + + def lose_terminal_attempt(**kwargs): + assert _effect_kinds(runtime, _turn_journal(runtime)) == [ + "refresh_state", + "quota_spend", + ] + if interruption == "lost_completion_receipt": + applied = complete(**kwargs) + assert applied["ok"] and applied["completed"], applied + raise OSError("injected terminal completion interruption") + + monkeypatch.setattr( + turn_run_once, "write_turn_validated_completion", lose_terminal_attempt + ) + code, result = invoke("--todo-id", todo_id) + journal = _turn_journal(runtime) + if interruption is not None: + assert code == 1 and journal["status"] == "in_progress", result + assert journal["completed_phases"][-1] == "quota_spend" + assert _effect_kinds(runtime, journal) == ["refresh_state", "quota_spend"] + assert _cli(registry, runtime, *lease_argv)[1]["active"] is ( + interruption == "after_debit" + ) + monkeypatch.setattr(turn_run_once, "write_turn_validated_completion", complete) + code, result = invoke( + "--resume-turn-key", journal["turn_key"], "--retry-failed-turn" + ) + assert code == 0 and result["status"] == "committed", result.get( + "error" + ) or result.get("reason") + assert _turn_journal(runtime)["terminal_closeout"]["completion"] == { + "todo_id": todo_id, + "continuation": "no_followup", + } + assert len(lease_reads) == (2 if interruption == "after_debit" else 1) + assert _cli(registry, runtime, *lease_argv)[1]["active"] is False + assert _effect_kinds(runtime, journal) == [ + "refresh_state", + "quota_spend", + "todo_complete", + ] + code, replay = invoke("--resume-turn-key", journal["turn_key"]) + assert code == 0 and replay["replayed"] is True, replay + assert not any(replay["effects"].values()) + assert host_calls == [journal["turn_key"]] + assert _effect_kinds(runtime, journal) == [ + "refresh_state", + "quota_spend", + "todo_complete", + ] + + +def test_builtin_codex_advertises_explicit_completion_without_promoting_progress() -> ( + None +): + kinds = codex_cli_result_schema()["properties"]["result_kind"]["enum"] + assert "validated_completion" in kinds and "validated_progress" in kinds diff --git a/tests/test_loopx_turn_driver.py b/tests/test_loopx_turn_driver.py index b5b0b3464d..65682ba1ff 100644 --- a/tests/test_loopx_turn_driver.py +++ b/tests/test_loopx_turn_driver.py @@ -1850,6 +1850,7 @@ def _write_live_fixture( }, "quota": {"compute": 1.0, "window_hours": 24}, "coordination": { + **({"handoff_mode": handoff_mode} if handoff_mode != "soft_claim" else {}), "agent_model": "peer_v1", "registered_agents": ["codex-fixture"], "agent_profiles": {