Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/architecture/rfcs/monorepo-distribution-split-v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,10 @@ Operation provider 必须说明某个 effect 能否核对、能否安全重试
外部状态未知时,后续依赖操作须等待回读或人工干预;“未观测到”不等于“未执行”。
设备幂等、物理联锁与补偿归 provider 负责,不能虚构为内核保证。

通用 CLI 的结果持久化后,原 Turn 可继续验收或结算,无需重新提供适配器命令及其请求版本。
调用方仍使用已批准的工作区,验收未完成时提供独立检查命令。已结算的 Turn 回读已保存结果。
恢复流程判定需要再次启动宿主时,调用方须提供适配器,准入才能继续。

模型取消、进程终止、设备确认停止是不同事实。模型停止不能在缺少设备证据时生成
“设备已停止”声明。需要持续监督的 provider,在 effect 尚未解决时不能卸载。
结果验收、传输交付、用户回读也必须保留现有的不同证据。
Expand Down
19 changes: 10 additions & 9 deletions loopx/cli_commands/turn_host_request.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion loopx/cli_commands/turn_registration.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
1 change: 1 addition & 0 deletions loopx/cli_commands/turn_run_once.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
44 changes: 40 additions & 4 deletions loopx/control_plane/turn_driver/executor.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 {}
Expand All @@ -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],
Expand All @@ -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,
Expand All @@ -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 {}
)
Expand Down Expand Up @@ -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},
Expand Down
8 changes: 8 additions & 0 deletions packages/loopx-core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 49 additions & 6 deletions tests/test_core_distribution.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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"]
Expand All @@ -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
Expand All @@ -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"]


Expand Down
Loading