diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 6e5521ac0a..88e26b9e0d 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -435,6 +435,13 @@ holds further dependent effects for readback or intervention; “not observed” does not mean “not executed.” Device idempotency, physical interlocks and compensation remain provider responsibilities, not invented kernel guarantees. +After a generic CLI result is durably recorded, the original Turn can resume +validation or settlement without the adapter command or its request schema. +The caller retains the approved workspace and supplies the independent checker +if validation is pending. An already settled Turn reads back its saved result. +If the recovery owner requires a Host attempt, the caller must supply the +adapter before admission can advance. + Model cancellation, process termination and confirmed device stop are separate facts. A stopped model must not produce a “device stopped” claim without device evidence. Providers needing persistent supervision cannot be unloaded while 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..e198b8066c 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -301,6 +301,10 @@ Operation provider 必须说明某个 effect 能否核对、能否安全重试 外部状态未知时,后续依赖操作须等待回读或人工干预;“未观测到”不等于“未执行”。 设备幂等、物理联锁与补偿归 provider 负责,不能虚构为内核保证。 +通用 CLI 的结果持久化后,原 Turn 可继续验收或结算,无需重新提供适配器命令及其请求版本。 +调用方仍使用已批准的工作区,验收未完成时提供独立检查命令。已结算的 Turn 回读已保存结果。 +恢复流程判定需要再次启动宿主时,调用方须提供适配器,准入才能继续。 + 模型取消、进程终止、设备确认停止是不同事实。模型停止不能在缺少设备证据时生成 “设备已停止”声明。需要持续监督的 provider,在 effect 尚未解决时不能卸载。 结果验收、传输交付、用户回读也必须保留现有的不同证据。 diff --git a/loopx/cli_commands/turn_host_request.py b/loopx/cli_commands/turn_host_request.py index 34852557a3..5c2fe92241 100644 --- a/loopx/cli_commands/turn_host_request.py +++ b/loopx/cli_commands/turn_host_request.py @@ -31,25 +31,26 @@ def prepare_turn_host_arguments( native_host_runner is not None or native_session_binding_resolver is not None ): raise ValueError("a native Chat connection cannot replace a selected CLI host") + raw_argv = None if args.host == "generic-cli": - if not args.host_command_json: + if args.host_command_json: + raw_argv = json.loads(args.host_command_json) + if not isinstance(raw_argv, list) or not all( + isinstance(item, str) for item in raw_argv + ): + raise ValueError( + "--host-adapter-command-json must be a JSON string array" + ) + elif args.host_command_json is not None or not getattr(args, "resume_turn_key", None): raise ValueError( "generic-cli requires --host-adapter-command-json " "(alias --host-command-json)" ) - raw_argv = json.loads(args.host_command_json) - if not isinstance(raw_argv, list) or not all( - isinstance(item, str) for item in raw_argv - ): - raise ValueError( - "--host-adapter-command-json must be a JSON string array" - ) else: if args.host_command_json: raise ValueError(f"{args.host} does not accept --host-command-json") if getattr(args, "host_adapter_request_schema", None): raise ValueError("--host-adapter-request-schema is only for generic-cli") - raw_argv = None if native_task_validator is not None and args.host != "codex-app-server": raise ValueError("a native task validator cannot replace a selected CLI validator") task_validator = native_task_validator diff --git a/loopx/cli_commands/turn_registration.py b/loopx/cli_commands/turn_registration.py index 551afde034..51cf7d55a3 100644 --- a/loopx/cli_commands/turn_registration.py +++ b/loopx/cli_commands/turn_registration.py @@ -189,7 +189,8 @@ def register_turn_commands( help=( "JSON argv array for a typed generic host adapter. The adapter reads " "the Turn request from stdin and emits one result JSON object; shell " - "parsing is never used." + "parsing is never used. Omit this on journal recovery that needs no " + "new host invocation." ), ) run_once.add_argument( diff --git a/loopx/cli_commands/turn_run_once.py b/loopx/cli_commands/turn_run_once.py index bd75698823..44b4c96cba 100644 --- a/loopx/cli_commands/turn_run_once.py +++ b/loopx/cli_commands/turn_run_once.py @@ -789,6 +789,7 @@ def on_managed_start_admitted() -> None: timeout_seconds=args.timeout_seconds, execute=bool(args.execute), retry_failed=bool(args.retry_failed_turn), + resume_existing_turn=args.host == "generic-cli" and bool(getattr(args, "resume_turn_key", None)), task_validator=task_validator, settlement_admission=settlement_admission, writeback=(codex_writeback if args.host == "codex-cli" else writeback) diff --git a/loopx/control_plane/turn_driver/executor.py b/loopx/control_plane/turn_driver/executor.py index 7782e575fc..b7b4ce0806 100644 --- a/loopx/control_plane/turn_driver/executor.py +++ b/loopx/control_plane/turn_driver/executor.py @@ -1526,12 +1526,14 @@ def persist_tail_checkpoint(*, release: bool) -> None: def _prepare_host_invocation( plan: Mapping[str, Any], *, host_argv: Sequence[str] | None, - host_runner: HostRunner | None, + host_runner: HostRunner | None, resume_existing_turn: bool, ) -> tuple[list[str] | None, dict[str, str | int]]: """Normalize the existing external or built-in transport before admission.""" if host_runner is not None and host_argv is not None: raise ValueError("run-once accepts either host_argv or host_runner, not both") if host_runner is None: + if host_argv is None and resume_existing_turn: + return None, {} argv = normalize_host_argv(host_argv or []) return argv, {"executable": Path(argv[0]).name, "argv_count": len(argv)} planned_host = plan.get("host") if isinstance(plan.get("host"), dict) else {} @@ -1558,6 +1560,34 @@ def _host_attempt_requirements( return needs_host, retry_validation, None +def _turn_transport_refusal( + *, + argv: Sequence[str] | None, + host_runner: HostRunner | None, + needs_host: bool, + request_schema: str, + adapter_schema: str | None, + journal: Mapping[str, object] | None, + recovery: Mapping[str, object] | None, + task_validator: TaskValidator | None, +) -> str | None: + """Check the selected transport against the locked journal before effects.""" + if argv is not None: + return host_request_schema_mismatch(request_schema, adapter_schema) if needs_host else None + if host_runner is not None: + return None + if needs_host or recovery is None or recovery["reinvoke_host"]: + return "This Turn needs a host invocation. Supply --host-adapter-command-json." + if recovery["resume_from"] == "validation" and task_validator is None: + stored_result = journal.get("host_result") if journal is not None else None + if ( + not isinstance(stored_result, Mapping) + or str(stored_result.get("result_kind")) not in STOP_HOST_RESULT_KINDS + ): + return "The saved result still needs independent validation. Supply --validation-command-json." + return None + + @single_executor_per_turn_lane(execution_payload) def run_loopx_turn_once( plan: Mapping[str, Any], @@ -1572,6 +1602,7 @@ def run_loopx_turn_once( timeout_seconds: float | None, execute: bool, retry_failed: bool = False, + resume_existing_turn: bool = False, decision_capture_payload: Mapping[str, Any] | None = None, require_decision_capture: bool = False, task_validator: TaskValidator | None = None, @@ -1591,7 +1622,10 @@ def run_loopx_turn_once( goal_admission: FirstPartyHostGoalAdmission | None = None, host_launch_guard: Callable[[], AbstractContextManager[None]] | None = None, ) -> dict[str, Any]: - argv, host_projection = _prepare_host_invocation(plan, host_argv=host_argv, host_runner=host_runner) + argv, host_projection = _prepare_host_invocation( + plan, host_argv=host_argv, host_runner=host_runner, + resume_existing_turn=resume_existing_turn, + ) transaction_plan = ( plan.get("transaction") if isinstance(plan.get("transaction"), dict) else {} ) @@ -1728,8 +1762,10 @@ def persist_source_journal(source_admission: Mapping[str, Any]) -> None: if needs_host and goal_admission is not None: goal_admission.require_current() - if needs_host and argv is not None and (reason := host_request_schema_mismatch( - request["schema_version"], host_adapter_request_schema, + if (reason := _turn_transport_refusal( + argv=argv, host_runner=host_runner, needs_host=needs_host, + request_schema=request["schema_version"], adapter_schema=host_adapter_request_schema, + journal=journal, recovery=recovery_decision, task_validator=task_validator, )) is not None: return execution_payload( plan, {"status": "unavailable", "host": host_projection, "reason": reason}, diff --git a/packages/loopx-core/README.md b/packages/loopx-core/README.md index ae5ef9df5d..80fcf1d79a 100644 --- a/packages/loopx-core/README.md +++ b/packages/loopx-core/README.md @@ -21,6 +21,14 @@ tasks requires a qualified Node runtime (22.22.3+ and the existing SQLite reliability checks), an explicitly selected host and its own prerequisites. Use the existing `turn run-once --host generic-cli` entry, a separate validation command, `turn inspect-journal` and `--resume-turn-key` for execution and recovery. + +When recovering a generic CLI Turn with a saved result, use the original +`--resume-turn-key`, Goal, Agent, and approved project path. Omit +`--host-adapter-command-json` and `--host-adapter-request-schema`. If the result +still needs validation, supply its independent `--validation-command-json`. +An already settled result can be read back without either command. The recovery +decision asks for the adapter if the original Turn needs another Host attempt. + Start with one natural-language goal in your existing model host: ```sh diff --git a/tests/test_core_distribution.py b/tests/test_core_distribution.py index f39fae8197..938c2f4101 100644 --- a/tests/test_core_distribution.py +++ b/tests/test_core_distribution.py @@ -128,6 +128,16 @@ def _run(python, arguments, cwd, *, environment=None, expected=0): return result +def _resume_without_adapter(arguments, turn_key, *, needs_validator): + omit = {"--host-adapter-command-json", "--host-adapter-request-schema"} + if not needs_validator: + omit.add("--validation-command-json") + return [ + argument for index, argument in enumerate(arguments) + if argument not in omit and (index == 0 or arguments[index - 1] not in omit) + ] + ["--resume-turn-key", turn_key] + + def test_installed_core_identity_help_and_unavailable_workspace(core_python, tmp_path): script = '''import importlib.util as u,json,loopx from pathlib import Path @@ -595,7 +605,8 @@ def test_installed_core_executes_checks_and_replays_once(core_python, task, chec assert history["ok"] is True result = json.loads(_run(core_python, arguments, workspace).stdout) key = _assert_committed(core_python, workspace, runtime, result) - replay = json.loads(_run(core_python, [*arguments, "--resume-turn-key", key], workspace).stdout) + resume = _resume_without_adapter(arguments, key, needs_validator=False) + replay = json.loads(_run(core_python, resume, workspace).stdout) _assert_committed(core_python, workspace, runtime, replay) assert replay["effects"]["host_invoked"] is False assert replay["effects"]["state_written"] is False @@ -617,6 +628,9 @@ def test_installed_core_recovers_confirmed_result_after_process_loss(core_python workspace, runtime, registry, arguments = task pause = workspace / "pause-validator" pause.touch() + adapter = workspace / "original-adapter.py" + adapter.write_text(HOST_SOURCE) + arguments[arguments.index("--host-adapter-command-json") + 1] = json.dumps([core_python, "-I", str(adapter)]) process = subprocess.Popen(_command(core_python, arguments), cwd=workspace, env=_environment(core_python), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) @@ -645,8 +659,10 @@ def test_installed_core_recovers_confirmed_result_after_process_loss(core_python process.wait(timeout=10) pause.unlink(missing_ok=True) process.communicate(timeout=10) + adapter.unlink() assert not journal.get("quota_spend") assert _spends(runtime) == 0 + resume = _resume_without_adapter(arguments, journal["turn_key"], needs_validator=True) if lease_change: todo_id = journal["plan"]["work_contract"]["selected_todo"]["todo_id"] prefix = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json"] @@ -655,8 +671,7 @@ def test_installed_core_recovers_confirmed_result_after_process_loss(core_python _run(core_python, [*prefix, "task-lease", lease_change, "--goal-id", GOAL, "--todo-id", todo_id, "--owner", AGENT, "--idempotency-key", lease["idempotency_key"], "--expected-version", str(lease["version"])], workspace) - rejected = json.loads(_run(core_python, [*arguments, "--resume-turn-key", journal["turn_key"]], - workspace, expected=1).stdout) + rejected = json.loads(_run(core_python, resume, workspace, expected=1).stdout) assert rejected["status"] == "failed" assert rejected["effects"]["host_invoked"] is False assert rejected["effects"]["state_written"] is False @@ -667,11 +682,39 @@ def test_installed_core_recovers_confirmed_result_after_process_loss(core_python assert readback["todo"]["status"] == "open" assert (workspace / "host-invocations").read_text().splitlines() == ["called"] return - result = json.loads(_run(core_python, [*arguments, "--resume-turn-key", journal["turn_key"]], workspace).stdout) + journal_path = runtime / "goals" / GOAL / "turns" / f"{journal['turn_key'].removeprefix('sha256:')}.json" + before = journal_path.read_bytes() + replay = _resume_without_adapter(arguments, journal["turn_key"], needs_validator=False) + missing_validator = json.loads(_run(core_python, replay, workspace, expected=1).stdout) + assert missing_validator["status"] == "unavailable" + assert "--validation-command-json" in missing_validator["reason"] + assert all(value is False for value in missing_validator["effects"].values()) + assert journal_path.read_bytes() == before + result = json.loads(_run(core_python, resume, workspace).stdout) _assert_committed(core_python, workspace, runtime, result) assert result["effects"]["host_invoked"] is False - replay = json.loads(_run(core_python, [*arguments, "--resume-turn-key", journal["turn_key"]], workspace).stdout) - assert replay["effects"]["quota_spent"] is False + settled = json.loads(_run(core_python, replay, workspace).stdout) + assert settled["replayed"] is True and all(value is False for value in settled["effects"].values()) + assert (workspace / "host-invocations").read_text().splitlines() == ["called"] + + +def test_installed_core_resume_without_adapter_refuses_new_host_attempt(core_python, task): + workspace, runtime, _, arguments = task + host_script = workspace / "invalid-adapter.py" + host_script.write_text(HOST_SOURCE.replace("'result_kind':'validated_completion'", "'result_kind':'invalid'")) + arguments[arguments.index("--host-adapter-command-json") + 1] = json.dumps([core_python, "-I", str(host_script)]) + launch = json.loads(_run(core_python, arguments, workspace, expected=1).stdout) + assert launch["validation_stage"] == "host_result_contract" and launch["effects"]["host_invoked"] is True + key = launch["resume_turn_key"] + journal = runtime / "goals" / GOAL / "turns" / f"{key.removeprefix('sha256:')}.json" + before = journal.read_bytes() + recovery = _resume_without_adapter(arguments, key, needs_validator=True) + refused = json.loads(_run(core_python, [*recovery, "--retry-failed-turn"], workspace, expected=1).stdout) + assert refused["status"] == "unavailable" + assert "--host-adapter-command-json" in refused["reason"] + assert all(value is False for value in refused["effects"].values()) + assert journal.read_bytes() == before + assert _spends(runtime) == 0 assert (workspace / "host-invocations").read_text().splitlines() == ["called"]