From 3f607bbd1a4758c921998a6ca675bc1ab0a223cb Mon Sep 17 00:00:00 2001 From: cicolord Date: Thu, 19 Nov 2026 03:14:49 +0800 Subject: [PATCH 1/7] Start a checked local task directly from a goal Signed-off-by: cicolord --- .../rfcs/monorepo-distribution-split-v0.md | 9 + .../monorepo-distribution-split-v0.zh-CN.md | 6 + loopx/bootstrap.py | 12 ++ loopx/cli_commands/start_goal.py | 39 +++- loopx/cli_commands/start_goal_managed.py | 171 ++++++++++++++++++ loopx/cli_runtime.py | 1 + packages/loopx-core/README.md | 14 ++ tests/test_core_distribution.py | 62 +++++++ 8 files changed, 310 insertions(+), 4 deletions(-) create mode 100644 loopx/cli_commands/start_goal_managed.py diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 6e5521ac0a..73bcea5d1e 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -329,6 +329,15 @@ process-group behavior and Windows best-effort tree cleanup retain their existing qualification boundary. It is process supervision, not a sandbox; operator-selected tools retain only their already authorized effects. +A configured local caller can use `start-goal --execute` to submit one goal +sentence and run the first checked task in a fresh project. The approved +adapter and independent validator are caller inputs. The entry uses the existing +Goal, Todo, lease and Turn owners and defaults to project-local runtime state. +After registration is published, identical requests recover the original task +and Turn. A recoverable journal continues at its recorded phase and a settled +journal returns the recorded result. The ordinary guided entry continues to +handle interactive hosts and connected projects. + ### Responsibility and installation acceptance Directory regrouping and distribution splitting have separate acceptance. 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..489c91be6c 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -228,6 +228,12 @@ stdio relay 在父进程 EOF、SIGTERM 或 SIGINT 时取消所持进程组,并 监督器完成回收再退出。POSIX 进程组行为与 Windows 尽力而为的进程树回收仍沿用 原资格边界。这是进程监督,不是沙箱;操作者选择的工具只保有原先获准的效果。 +已配置的本地调用方可以通过 `start-goal --execute` 在新项目中提交一句目标并运行首个受验收任务。 +获批的适配器和独立检查器由调用方提供。入口复用既有 Goal、Todo、租约和 Turn 的 owner, +运行状态默认保存在项目内。注册发布后,相同请求续接原任务和 Turn。可恢复的日志从已记录阶段 +继续,已结算的日志回读原结果。 +交互式宿主和已连接项目继续使用现有的引导入口。 + ### 职责与安装验收 目录重组与发行物拆分分别验收。每次移动说明规则的唯一 owner、变更 caller、 diff --git a/loopx/bootstrap.py b/loopx/bootstrap.py index aac03ac5dd..d1400e66fc 100644 --- a/loopx/bootstrap.py +++ b/loopx/bootstrap.py @@ -326,6 +326,7 @@ def bootstrap_project( sync_global: bool, allow_global_route_replacement: bool = False, creation_operation_id: str | None = None, + initial_agent_id: str | None = None, ) -> dict[str, Any]: project = project.expanduser().resolve() goal_id = validate_goal_id_path_segment(goal_id or default_goal_id(project)) @@ -391,6 +392,13 @@ def bootstrap_project( if storage_target is not None: goal_entry.setdefault("coordination", {})["storage_target"] = storage_target canonical_creation = (storage_target or {}).get("schema_version") == "loopx_new_goal_storage_target_v1" + if initial_agent_id is not None: + from .control_plane.todos.contract import normalize_todo_claimed_by + + agent_id = normalize_todo_claimed_by(initial_agent_id) + if not canonical_creation or creation_operation_id is None or agent_id != initial_agent_id: + raise ValueError("First task creation requires a new canonical Goal and an exact Agent identity") + goal_entry["coordination"].update(agent_model="peer_v1", registered_agents=[agent_id]) # Imported/promoted Goals have no canonical *creation* receipt. Resolve # their current authority through the existing typed reader, never by # manufacturing a creation target or reviving their old Markdown source. @@ -553,6 +561,8 @@ def bootstrap_project( ) as registry_transaction, nullcontext(): current_registry = registry_transaction.payload_copy() current_goal = find_registry_goal(current_registry, goal_id) + if initial_agent_id is not None and current_registry.get("goals"): + raise GoalCreationConflictError("First task creation requires a fresh local project registry") if canonical_existing and current_goal != previous_goal: raise ValueError("Canonical Goal registration changed; retry bootstrap") if creation_operation_id is not None and current_goal is not None: @@ -567,6 +577,8 @@ def bootstrap_project( goal_entry["coordination"]["storage_target"] = frozen frozen_target = goal_entry.get("coordination", {}).get("storage_target") or {} canonical_creation = frozen_target.get("schema_version") == "loopx_new_goal_storage_target_v1" + if initial_agent_id is not None and not canonical_creation: + raise ValueError("First task creation could not establish its original canonical storage target") if canonical_creation and force and (current_goal is not None or state_file.exists()): raise ValueError("Canonical creation cannot rebuild existing state; restore or migrate through its owning operation") diff --git a/loopx/cli_commands/start_goal.py b/loopx/cli_commands/start_goal.py index 50982b6b18..9fd5a0a648 100644 --- a/loopx/cli_commands/start_goal.py +++ b/loopx/cli_commands/start_goal.py @@ -181,12 +181,26 @@ def add_capability_route_argument(parser: argparse.ArgumentParser) -> None: def register_start_goal_command(subparsers: argparse._SubParsersAction) -> None: start_goal_parser = subparsers.add_parser( "start-goal", - help="Preview a guided /loopx start transaction without mutating state.", + help="Preview a guided goal or execute its first checked task with a configured local adapter.", ) - start_goal_parser.add_argument( + start_mode = start_goal_parser.add_mutually_exclusive_group() + start_mode.add_argument( "--guided", action="store_true", - help="Required for now: render the guided dry-run transaction packet.", + help="Render the guided read-only transaction packet.", + ) + start_mode.add_argument( + "--execute", + action="store_true", + help="Start one checked task in a fresh local project using the supplied adapter and validator.", + ) + start_goal_parser.add_argument( + "--host-adapter-command-json", + help="Approved JSON argv for a v1 generic CLI adapter when executing the first task.", + ) + start_goal_parser.add_argument( + "--validation-command-json", + help="Approved JSON argv for a separate independent check when executing the first task.", ) start_goal_parser.add_argument("--project", default=".", help="Project directory to inspect.") start_goal_parser.add_argument("--goal-id", help="Goal id. Defaults to -goal.") @@ -362,12 +376,29 @@ def handle_start_goal_command( print_payload: PrintPayload, *, runtime_root_arg: str | None = None, + explicit_registry: Path | None = None, ) -> int: + if getattr(args, "execute", False): + from .start_goal_managed import execute_managed_start, render_managed_start_markdown + + try: + payload = execute_managed_start(args, runtime_root_arg=runtime_root_arg, + explicit_registry=explicit_registry) + except (OSError, RuntimeError, ValueError) as exc: + payload = {"ok": False, "error": str(exc)} + print_payload(payload, args.format, _render_start_goal_markdown) + return 1 + print_payload(payload, args.format, render_managed_start_markdown) + return 0 if payload["ok"] else 1 + if getattr(args, "host_adapter_command_json", None) is not None or getattr(args, "validation_command_json", None) is not None: + print_payload({"ok": False, "error": "Adapter and validator commands require start-goal --execute."}, + args.format, _render_start_goal_markdown) + return 2 if not bool(getattr(args, "guided", False)): payload = { "ok": False, "schema_version": "loopx_start_goal_guided_v0", - "error": "`loopx start-goal` currently requires --guided", + "error": "`loopx start-goal` requires --guided or --execute", "suggested_command": "loopx start-goal --guided --goal-text ''", } print_payload(payload, args.format, _render_start_goal_markdown) diff --git a/loopx/cli_commands/start_goal_managed.py b/loopx/cli_commands/start_goal_managed.py new file mode 100644 index 0000000000..ad56d4d0c1 --- /dev/null +++ b/loopx/cli_commands/start_goal_managed.py @@ -0,0 +1,171 @@ +"""Compose one checked first task through the existing local execution owners.""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path +from typing import Any + +from ..bootstrap import DEFAULT_DOMAIN, bootstrap_project, read_json_if_exists +from ..cli_runtime import add_subcommand_format +from ..control_plane.coordination.new_goal_storage_transport import initialize_goal_storage_target +from ..control_plane.goals.source_session_registry_state import canonical_digest +from ..control_plane.projects.identity import GoalCreationConflictError, default_goal_id, derive_goal_display_name +from ..control_plane.quota.turn_envelope import COMPLETE_TURN_HOST_REQUEST_SCHEMA +from ..control_plane.todos.mutation_api import add_goal_todo, update_goal_todo +from ..control_plane.turn_driver.command_validation import build_loopx_turn_command_validator, normalize_host_argv +from ..control_plane.turn_driver.journal_store import find_loopx_turn_key_by_instance +from ..kunluncode_goal_mode.guards import native_controller_cli_write_block +from ..paths import resolve_runtime_root +from ..registry import find_registry_goal +from .turn import handle_turn_command +from .turn_host_request import prepare_turn_host_arguments +from .turn_registration import register_turn_commands +from .turn_rendering import render_loopx_turn_execution_markdown + + +def _first_turn_args( + args: argparse.Namespace, project: Path, goal_id: str, agent_id: str, +) -> argparse.Namespace: + if ( + args.host_surface not in {None, "shell"} or args.thread_id or args.new_peer + or args.available_capabilities or args.capability_route or args.fine_grained + or args.include_command_pack_detail or args.slash_command_arguments is not None + ): + raise ValueError("start-goal --execute takes a local --goal-text and a configured adapter and validator") + if not args.host_adapter_command_json or not args.validation_command_json: + raise ValueError("start-goal --execute requires --host-adapter-command-json and --validation-command-json") + parser = argparse.ArgumentParser(prog="loopx", add_help=False) + register_turn_commands(parser.add_subparsers(dest="command"), add_subcommand_format) + return parser.parse_args([ + "turn", "run-once", "--goal-id", goal_id, "--agent-id", agent_id, + "--project", str(project), "--host", "generic-cli", + "--host-adapter-request-schema", COMPLETE_TURN_HOST_REQUEST_SCHEMA, + "--host-adapter-command-json", args.host_adapter_command_json, + "--validation-command-json", args.validation_command_json, "--no-global-sync", "--execute", + ]) + + +def _register_first_goal( + *, + registry_path: Path, + runtime_root: Path, + project: Path, + goal_id: str, + agent_id: str, + objective: str, + display_name: str | None, + operation_id: str, +) -> None: + if not registry_path.exists(): + try: + receipt = bootstrap_project( + project=project, registry_path=registry_path, runtime_root=runtime_root, + goal_id=goal_id, objective=objective, display_name=display_name, + domain=DEFAULT_DOMAIN, role="controller", parent_goal_id=None, + state_file=None, goal_doc=None, adapter_kind="generic_project_goal_v0", + adapter_status="connected", next_probe=None, spawn_allowed=False, max_children=0, + allowed_domains=[], write_scope=[], force=False, dry_run=False, sync_global=False, + creation_operation_id=operation_id, initial_agent_id=agent_id, + ) + if not receipt.get("ok"): + raise RuntimeError(str(receipt.get("error") or "The Goal could not be registered")) + return + except GoalCreationConflictError: + # A concurrent publication may have completed the same operation. + pass + registry = read_json_if_exists(registry_path) + goal = find_registry_goal(registry, goal_id) + if goal is None or goal.get("creation_operation_id") != operation_id or goal.get("repo") != str(project): + raise ValueError("This project is already connected. Use its original start request or inspect the existing goal.") + initialize_goal_storage_target(runtime_root, goal, registry_path=registry_path) + + +def execute_managed_start( + args: argparse.Namespace, *, runtime_root_arg: str | None, explicit_registry: Path | None, +) -> dict[str, Any]: + project = Path(args.project).expanduser().resolve() + objective = (args.goal_text or "").strip() + if not project.is_dir() or not objective: + raise ValueError("A project directory and non-empty goal text are required") + registry_path = project / ".loopx/registry.json" + if not registry_path.resolve().is_relative_to(project) or ( + explicit_registry is not None and explicit_registry.resolve() != registry_path.resolve() + ): + raise ValueError("start-goal --execute uses the selected project's local registry") + goal_id = args.goal_id or default_goal_id(project) + agent_id = args.agent_id or "local-worker" + turn_args = _first_turn_args(args, project, goal_id, agent_id) + blocked = native_controller_cli_write_block(turn_args) + if blocked is not None: + return blocked + _, host_argv, _ = prepare_turn_host_arguments( + turn_args, native_host_runner=None, native_session_binding_resolver=None, + native_task_validator=None, validator_builder=build_loopx_turn_command_validator, + ) + assert host_argv is not None + registry = read_json_if_exists(registry_path) + runtime_root = resolve_runtime_root( + registry or {"common_runtime_root": str(project / ".loopx/runtime")}, + runtime_root_arg, registry_path=registry_path, + ).resolve() + display_name = args.display_name or derive_goal_display_name(objective) + digest = canonical_digest({ + "project": str(project), "runtime_root": str(runtime_root), + "goal_id": goal_id, "agent_id": agent_id, "goal": objective, "title": display_name, + "adapter": normalize_host_argv(host_argv), "validator": json.loads(args.validation_command_json), + }) + operation_id = "start-" + digest.removeprefix("sha256:")[:32] + _register_first_goal( + registry_path=registry_path, runtime_root=runtime_root, project=project, + goal_id=goal_id, agent_id=agent_id, objective=objective, + display_name=display_name, operation_id=operation_id, + ) + todo = add_goal_todo( + registry_path=registry_path, runtime_root_arg=str(runtime_root), + goal_id=goal_id, role="agent", text=objective, priority="P1", + claimed_by=agent_id, task_class="advancement_task", action_kind="advance", + operation_id=f"{operation_id}:first-task", + ) + if not todo.get("ok") or not todo.get("todo_id"): + raise RuntimeError("The goal was registered. Retry the same start request to recover its first task.") + todo_id = str(todo["todo_id"]) + resume = find_loopx_turn_key_by_instance( + runtime_root, goal_id=goal_id, agent_id=agent_id, turn_instance_id=operation_id, + ) + if resume: + turn_args.resume_turn_key = resume + else: + claimed = update_goal_todo( + registry_path=registry_path, runtime_root_arg=str(runtime_root), + goal_id=goal_id, todo_id=todo_id, claimed_by=agent_id, agent_id=agent_id, + claim_only=True, manage_execution=True, claim_operation_id=f"{operation_id}:first-claim", + ) + if not claimed.get("ok"): + raise RuntimeError(str(claimed.get("error") or "The first task could not be claimed")) + turn_args.todo_id = todo_id + turn_args.turn_instance_id = operation_id + result: dict[str, Any] = {} + handle_turn_command( + turn_args, registry_path=registry_path, runtime_root_arg=str(runtime_root), + output_format=lambda _args: "json", print_payload=lambda payload, *_: result.update(payload), + ) + return {**result, "goal_id": goal_id, "agent_id": agent_id, "todo_id": todo_id, + "turn_instance_id": operation_id} + + +def render_managed_start_markdown(payload: dict[str, object]) -> str: + kind = payload.get("result_kind") + if payload.get("status") != "committed" or kind not in ("validated_completion", "validated_progress"): + return render_loopx_turn_execution_markdown(payload) + line = ( + "Task completed and checked." + if kind == "validated_completion" + else "Checked progress saved." + ) + evidence = payload.get("host_evidence") + refs = evidence.get("work_evidence") if isinstance(evidence, dict) else None + if not isinstance(refs, list): + return line + return "\n".join([line, "", *(f"- {ref}" for ref in refs if isinstance(ref, str))]) diff --git a/loopx/cli_runtime.py b/loopx/cli_runtime.py index bc674449aa..f47cdabb96 100644 --- a/loopx/cli_runtime.py +++ b/loopx/cli_runtime.py @@ -567,6 +567,7 @@ def _dispatch_common_command( return handle_start_goal_command( args, print_payload, runtime_root_arg=args.runtime_root, + explicit_registry=registry_path if registry_was_configured else None, ) if args.command == "bootstrap-command-pack": from .cli_commands.starter_bootstrap import handle_loopx_bootstrap_command_pack_command diff --git a/packages/loopx-core/README.md b/packages/loopx-core/README.md index ae5ef9df5d..21a786b704 100644 --- a/packages/loopx-core/README.md +++ b/packages/loopx-core/README.md @@ -16,6 +16,20 @@ uv pip install --python /tmp/loopx-core-env/bin/python /tmp/loopx-core-dist/loop /tmp/loopx-core-env/bin/loopx doctor --installation-only --deep --format json ``` +For a fresh local project with an approved v1 CLI adapter and independent +checker, start the first task from the goal text in one invocation. + +```sh +loopx start-goal --execute --project . --goal-text "Create and check an inventory report." \ + --host-adapter-command-json "$adapter_argv" --validation-command-json "$validator_argv" +``` + +The configured caller supplies the two JSON argv arrays. Core registers the +local Goal and worker, creates one task, then runs the existing checked Turn. +Repeat the original invocation to continue its saved attempt or read back its +result. The `--guided` route remains available for an existing project or an +interactive host. + Python 3.11+ is required. Import and help do not need Node. Executing governed tasks requires a qualified Node runtime (22.22.3+ and the existing SQLite reliability checks), an explicitly selected host and its own prerequisites. diff --git a/tests/test_core_distribution.py b/tests/test_core_distribution.py index f39fae8197..c82803e61f 100644 --- a/tests/test_core_distribution.py +++ b/tests/test_core_distribution.py @@ -732,3 +732,65 @@ def test_installed_core_codex_prepares_only_an_admitted_valid_request(core_pytho workspace, environment=environment).stdout) assert replay["replayed"] is True and all(value is False for value in replay["effects"].values()) assert len(log.read_text().splitlines()) == 1 and _spends(runtime) == 1 + + +def test_installed_core_starts_one_checked_task_from_goal_text(core_python, tmp_path, monkeypatch): + from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime + + isolate_sqlite_runtime(tmp_path, monkeypatch) + project = tmp_path / "first-work" + project.mkdir() + objective = "生成并独立检查从零到七的平方值。" + adapter = HOST_SOURCE.replace("request=json.load(sys.stdin)\n", + f"request=json.load(sys.stdin)\nassert {objective!r} in json.dumps(request,ensure_ascii=False)\n") + arguments = ["--format", "json", "start-goal", "--project", str(project), + "--goal-text", objective, "--execute", "--host-adapter-command-json", + json.dumps([core_python, "-I", "-c", adapter]), "--validation-command-json", + json.dumps([core_python, "-I", "-c", VALIDATOR_SOURCE])] + first = json.loads(_run(core_python, arguments, tmp_path).stdout) + assert first["status"] == "committed" and first["validation"]["status"] == "passed" + assert first["goal_id"] == "first-work-goal" and first["agent_id"] == "local-worker" + assert first["effects"]["host_invoked"] and first["effects"]["quota_spent"] + runtime = project / ".loopx/runtime" + registry = project / ".loopx/registry.json" + readback = json.loads(_run(core_python, ["--registry", str(registry), "--format", "json", + "todo", "list", "--goal-id", first["goal_id"], "--todo-id", first["todo_id"]], project).stdout) + assert readback["todo"]["status"] == "done" + assert json.loads((project / "squares.json").read_text()) == [0, 1, 4, 9, 16, 25, 36, 49] + repeated = json.loads(_run(core_python, arguments, tmp_path).stdout) + assert repeated["replayed"] and repeated["resume_turn_key"] == first["resume_turn_key"] + assert repeated["todo_id"] == first["todo_id"] + assert all(value is False for value in repeated["effects"].values()) + rendered = _run(core_python, ["--format", "markdown", *arguments[2:]], tmp_path).stdout + assert "Task completed and checked." in rendered and "artifact:squares.json" in rendered + assert "quota_spent" not in rendered and "turn_instance_id" not in rendered + changed = list(arguments) + changed[changed.index("--goal-text") + 1] = "Start an unrelated task." + registry_before = registry.read_bytes() + denied = json.loads(_run(core_python, changed, tmp_path, expected=1).stdout) + assert "already connected" in denied["error"] + assert registry.read_bytes() == registry_before + assert (project / "host-invocations").read_text().splitlines() == ["called"] + spends = runtime / "goals" / first["goal_id"] / "runs/index.jsonl" + assert spends.read_text().count("quota_slot_spent") == 1 + + +@pytest.mark.parametrize("invalid", ["missing-validator", "invalid-adapter", "owned-goal"]) +def test_installed_core_start_goal_preflights_before_creation(core_python, tmp_path, invalid): + arguments = ["--format", "json", "start-goal", "--project", str(tmp_path), + "--goal-text", "Produce a checked report.", "--execute"] + environment = None + if invalid == "owned-goal": + arguments += ["--goal-id", "native-owned-goal", "--host-adapter-command-json", json.dumps([core_python]), + "--validation-command-json", json.dumps([core_python])] + environment = {"LOOPX_KUNLUNCODE_OUTER_CONTROLLER": "1", "LOOPX_KUNLUNCODE_OUTER_GOAL_ID": "native-owned-goal"} + elif invalid == "missing-validator": + arguments += ["--host-adapter-command-json", json.dumps([core_python])] + else: + arguments += ["--host-adapter-command-json", "[]", + "--validation-command-json", json.dumps([core_python])] + refused = json.loads(_run(core_python, arguments, tmp_path, expected=1, environment=environment).stdout) + assert refused["ok"] is False + if invalid == "owned-goal": + assert refused["error_code"] == "kunluncode_outer_controller_write_owned" + assert not (tmp_path / ".loopx").exists() From 7499fcab02c8c68df56499a819ac11744efea185 Mon Sep 17 00:00:00 2001 From: cicolord Date: Thu, 19 Nov 2026 03:33:16 +0800 Subject: [PATCH 2/7] Recover first goal creation before its initial state exists Signed-off-by: cicolord --- .../rfcs/monorepo-distribution-split-v0.md | 9 +- .../monorepo-distribution-split-v0.zh-CN.md | 5 +- loopx/bootstrap.py | 63 ++++++++++++- loopx/cli_commands/start_goal_managed.py | 5 +- .../new_goal_storage_transport.py | 9 +- packages/loopx-core/README.md | 7 +- tests/test_core_distribution.py | 88 +++++++++++++++++++ 7 files changed, 169 insertions(+), 17 deletions(-) diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 73bcea5d1e..3fdd5d0f3b 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -333,10 +333,11 @@ A configured local caller can use `start-goal --execute` to submit one goal sentence and run the first checked task in a fresh project. The approved adapter and independent validator are caller inputs. The entry uses the existing Goal, Todo, lease and Turn owners and defaults to project-local runtime state. -After registration is published, identical requests recover the original task -and Turn. A recoverable journal continues at its recorded phase and a settled -journal returns the recorded result. The ordinary guided entry continues to -handle interactive hosts and connected projects. +Registration records the original operation and storage target before the +initial source is written. The identical request can supply a missing initial +source when the authority owner still needs it, and can recover the original +task and Turn. Settled work returns the recorded result. The ordinary guided +entry continues to handle interactive hosts and connected projects. ### Responsibility and installation acceptance 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 489c91be6c..419cccaac8 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -230,8 +230,9 @@ stdio relay 在父进程 EOF、SIGTERM 或 SIGINT 时取消所持进程组,并 已配置的本地调用方可以通过 `start-goal --execute` 在新项目中提交一句目标并运行首个受验收任务。 获批的适配器和独立检查器由调用方提供。入口复用既有 Goal、Todo、租约和 Turn 的 owner, -运行状态默认保存在项目内。注册发布后,相同请求续接原任务和 Turn。可恢复的日志从已记录阶段 -继续,已结算的日志回读原结果。 +运行状态默认保存在项目内。注册先记录原始操作和存储目标,再写入初始状态。 +中断后,原请求可以在权威 owner 仍需要初始状态时补写缺失的文件,并续接原任务和 Turn。 +已结算的工作回读原结果。 交互式宿主和已连接项目继续使用现有的引导入口。 ### 职责与安装验收 diff --git a/loopx/bootstrap.py b/loopx/bootstrap.py index d1400e66fc..fe8e736317 100644 --- a/loopx/bootstrap.py +++ b/loopx/bootstrap.py @@ -27,7 +27,7 @@ from typing import Any from .control_plane.runtime.time import now_local_iso -from .control_plane.runtime.document_io import atomic_write_state_text +from .control_plane.runtime.document_io import atomic_write_state_text, fsync_state_directory from .control_plane.todos.active_state_editing import ( TODO_SECTION_HEADINGS, insertion_anchor, @@ -42,6 +42,7 @@ compact_execution_profile, execution_profile_summary, ) +from .file_lock import exclusive_cross_runtime_file_lock from .global_registry import sync_project_registry_to_global from .install_contract import ( archive_fallback_install_command, @@ -196,6 +197,54 @@ def relative_state_file(project: Path, state_file: Path) -> str: return rel_or_abs(state_file, project) +def initialize_first_goal_storage( + runtime_root: Path, goal: dict[str, Any], *, registry_path: Path, objective: str, + goal_doc: Path | None = None, +) -> dict[str, Any]: + """Prepare the registered initial source only when the authority owner needs it.""" + project = Path(goal["repo"]) + goal_id = str(goal["id"]) + state_file = resolve_state_file(project, goal.get("state_file")) + if state_file is None or not state_file.resolve().is_relative_to(project): + raise ValueError("The first goal requires a state file inside its project") + + def prepare_source() -> None: + from .control_plane.goals.activation import goal_is_stopped + + with ( + project_registry_transaction(registry_path, operation="bootstrap_registry") as transaction, + exclusive_cross_runtime_file_lock(state_file, operation="bootstrap_state"), + ): + registry = transaction.payload_copy() + if find_registry_goal(registry, goal_id) != goal or resolve_runtime_root( + registry, None, registry_path=registry_path, + ).resolve() != runtime_root: + raise GoalCreationConflictError("The first goal registration changed; retry the original start request") + if state_file.exists(): + return + if goal_is_stopped(goal): + raise ValueError("The goal is stopped. Resume it before retrying the original start request.") + require_single_goal_state_route(project, goal_id, state_file) + require_legacy_state_replacement_allowed(runtime_root=runtime_root, goal_id=goal_id, goal=goal) + require_registry_source_write_allowed( + registry_path=registry_path, runtime_root=runtime_root, goal_id=goal_id, state_file=state_file, + ) + fsync_state_directory(registry_path) + atomic_write_state_text(state_file, render_state_markdown( + project=project, goal_id=goal_id, adapter_kind=goal["adapter"]["kind"], + objective=objective, updated_at=now_iso(), goal_doc=goal_doc, + execution_profile=goal.get("execution_profile"), + handoff_mode=goal["coordination"]["storage_target"]["handoff_mode"], + ), create_only=True) + + result = initialize_goal_storage_target( + runtime_root, goal, registry_path=registry_path, prepare_source=prepare_source, + ) + if result is None or result.get("authority_initialized") is not True: + raise RuntimeError("The first goal authority could not be initialized") + return result + + def build_goal_entry( *, project: Path, @@ -398,6 +447,8 @@ def bootstrap_project( agent_id = normalize_todo_claimed_by(initial_agent_id) if not canonical_creation or creation_operation_id is None or agent_id != initial_agent_id: raise ValueError("First task creation requires a new canonical Goal and an exact Agent identity") + if not state_file.resolve().is_relative_to(project): + raise ValueError("The first goal requires a state file inside its project") goal_entry["coordination"].update(agent_model="peer_v1", registered_agents=[agent_id]) # Imported/promoted Goals have no canonical *creation* receipt. Resolve # their current authority through the existing typed reader, never by @@ -603,7 +654,7 @@ def bootstrap_project( if action.get("path") == str(state_file): action["action"] = state_action planned = original - if state_action in {"created", "replaced"}: + if state_action in {"created", "replaced"} and initial_agent_id is None: declared_handoff_mode = goal_handoff_mode(original) if original and force else frozen_target.get("handoff_mode", HANDOFF_MODE_LEGACY) planned = render_state_markdown( project=project, @@ -632,7 +683,13 @@ def bootstrap_project( # Registry intent survives an interrupted initialization. Reconnect retries # it outside the legacy/registry locks; changing machine defaults cannot # retarget that Goal. The TS owner refuses replacing an existing provider. - if not canonical_existing: + if initial_agent_id is not None: + # Publish the existing creation intent first. The same operation + # can supply its missing initial source after a process exit. + storage_selection = initialize_first_goal_storage( + runtime_root, goal_entry, registry_path=registry_path, objective=objective, goal_doc=goal_doc, + ) + elif not canonical_existing: storage_selection = initialize_goal_storage_target(runtime_root, find_registry_goal(registry, goal_id) or {}, registry_path=registry_path) if sync_global: global_sync = sync_project_registry_to_global( diff --git a/loopx/cli_commands/start_goal_managed.py b/loopx/cli_commands/start_goal_managed.py index ad56d4d0c1..70a5584193 100644 --- a/loopx/cli_commands/start_goal_managed.py +++ b/loopx/cli_commands/start_goal_managed.py @@ -7,9 +7,8 @@ from pathlib import Path from typing import Any -from ..bootstrap import DEFAULT_DOMAIN, bootstrap_project, read_json_if_exists +from ..bootstrap import DEFAULT_DOMAIN, bootstrap_project, initialize_first_goal_storage, read_json_if_exists from ..cli_runtime import add_subcommand_format -from ..control_plane.coordination.new_goal_storage_transport import initialize_goal_storage_target from ..control_plane.goals.source_session_registry_state import canonical_digest from ..control_plane.projects.identity import GoalCreationConflictError, default_goal_id, derive_goal_display_name from ..control_plane.quota.turn_envelope import COMPLETE_TURN_HOST_REQUEST_SCHEMA @@ -79,7 +78,7 @@ def _register_first_goal( goal = find_registry_goal(registry, goal_id) if goal is None or goal.get("creation_operation_id") != operation_id or goal.get("repo") != str(project): raise ValueError("This project is already connected. Use its original start request or inspect the existing goal.") - initialize_goal_storage_target(runtime_root, goal, registry_path=registry_path) + initialize_first_goal_storage(runtime_root, goal, registry_path=registry_path, objective=objective) def execute_managed_start( diff --git a/loopx/control_plane/coordination/new_goal_storage_transport.py b/loopx/control_plane/coordination/new_goal_storage_transport.py index 07aa162560..401362260b 100644 --- a/loopx/control_plane/coordination/new_goal_storage_transport.py +++ b/loopx/control_plane/coordination/new_goal_storage_transport.py @@ -5,7 +5,7 @@ """ from __future__ import annotations -from collections.abc import Mapping +from collections.abc import Callable, Mapping from pathlib import Path from typing import Any @@ -22,7 +22,10 @@ def resolve_canonical_creation_target(provider: str) -> dict[str, Any]: return result -def initialize_goal_storage_target(runtime_root: Path, goal: Mapping[str, Any], *, registry_path: Path | None = None) -> dict[str, Any] | None: +def initialize_goal_storage_target( + runtime_root: Path, goal: Mapping[str, Any], *, registry_path: Path | None = None, + prepare_source: Callable[[], None] | None = None, +) -> dict[str, Any] | None: target = (goal.get("coordination") or {}).get("storage_target") if target is None: return None @@ -56,6 +59,8 @@ def initialize_goal_storage_target(runtime_root: Path, goal: Mapping[str, Any], # owner can request a complete source capture for unfinished creation. if result.get("source_capture_required") is not True: return result + if prepare_source is not None: + prepare_source() from .authority_source_capture import build_runtime_shadow_source_snapshot projection, snapshot = build_runtime_shadow_source_snapshot(goal=goal, runtime_root=runtime_root, state_path=state_path, registry_path=registry_path) diff --git a/packages/loopx-core/README.md b/packages/loopx-core/README.md index 21a786b704..05b85b19f3 100644 --- a/packages/loopx-core/README.md +++ b/packages/loopx-core/README.md @@ -26,9 +26,10 @@ loopx start-goal --execute --project . --goal-text "Create and check an inventor The configured caller supplies the two JSON argv arrays. Core registers the local Goal and worker, creates one task, then runs the existing checked Turn. -Repeat the original invocation to continue its saved attempt or read back its -result. The `--guided` route remains available for an existing project or an -interactive host. +Repeat the original invocation after an interruption, including during +registration. It continues the saved attempt or returns the checked result. +The `--guided` route remains available for an existing project or an interactive +host. Python 3.11+ is required. Import and help do not need Node. Executing governed tasks requires a qualified Node runtime (22.22.3+ and the existing SQLite diff --git a/tests/test_core_distribution.py b/tests/test_core_distribution.py index c82803e61f..ec501ce7ba 100644 --- a/tests/test_core_distribution.py +++ b/tests/test_core_distribution.py @@ -794,3 +794,91 @@ def test_installed_core_start_goal_preflights_before_creation(core_python, tmp_p if invalid == "owned-goal": assert refused["error_code"] == "kunluncode_outer_controller_write_owned" assert not (tmp_path / ".loopx").exists() + + +def _configure_first_goal_storage(core_python, project, runtime, provider): + setup = '''import sys +from pathlib import Path +from loopx.capabilities.machine_configuration.builtins import build_builtin_machine_configuration_registry +from loopx.capabilities.machine_configuration.contract import MACHINE_CONFIGURATION_SCHEMA +from loopx.capabilities.machine_configuration.store import configure_machine_configuration +configuration={'schema_version':MACHINE_CONFIGURATION_SCHEMA,'namespaces':{'goal_storage':{ +'schema_version':'loopx_goal_storage_defaults_v1','new_goal_provider':sys.argv[2], +'canonical_creation':True,'new_goal_handoff_mode':'hard_lease'}}} +arguments={'runtime_root':Path(sys.argv[1]),'configuration':configuration, +'registry':build_builtin_machine_configuration_registry()} +preview=configure_machine_configuration(**arguments) +result=configure_machine_configuration(**arguments,execute=True,expected_plan_revision=preview['plan_revision']) +assert result['readback_verified'] +''' + configured = subprocess.run([core_python, "-I", "-c", setup, str(runtime), provider], cwd=project, + env=_environment(core_python), capture_output=True, text=True, timeout=45) + assert configured.returncode == 0, configured.stderr + + +@pytest.mark.skipif(os.name != "posix", reason="requires POSIX SIGKILL") +@pytest.mark.parametrize("provider", ["sqlite", "file"]) +@pytest.mark.parametrize("phase", ["registration", "initial-source"]) +def test_installed_core_recovers_first_goal_publication(core_python, tmp_path, monkeypatch, provider, phase): + from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime + + isolate_sqlite_runtime(tmp_path, monkeypatch) + project = tmp_path / "first-work" + project.mkdir() + runtime = project / ".loopx/runtime" + registry = project / ".loopx/registry.json" + state = project / ".loopx/goals/first-work-goal/ACTIVE_GOAL_STATE.md" + if provider == "file": + _configure_first_goal_storage(core_python, project, runtime, provider) + arguments = ["--format", "json", "start-goal", "--project", str(project), + "--goal-text", "Produce and independently check the first report.", "--execute", + "--host-adapter-command-json", json.dumps([core_python, "-I", "-c", HOST_SOURCE]), + "--validation-command-json", json.dumps([core_python, "-I", "-c", VALIDATOR_SOURCE])] + hook = """import os,signal +def kill_after(effect): + def run(*args, **kwargs): + effect(*args, **kwargs) + os.kill(os.getpid(), signal.SIGKILL) + return run +""" + if phase == "registration": + hook += """from loopx.control_plane.projects.registry_codec import ProjectRegistryTransaction +ProjectRegistryTransaction.commit=kill_after(ProjectRegistryTransaction.commit) +""" + else: + hook += """from loopx import bootstrap +bootstrap.atomic_write_state_text=kill_after(bootstrap.atomic_write_state_text) +""" + command = _command(core_python, arguments) + command[3] = hook + command[3] + interrupted = subprocess.run(command, cwd=project, env=_environment(core_python), + capture_output=True, text=True, timeout=90) + assert interrupted.returncode == -signal.SIGKILL, (interrupted.stdout, interrupted.stderr) + before = registry.read_bytes() + (goal,) = json.loads(before)["goals"] + assert goal["id"] == "first-work-goal" and goal["coordination"]["storage_target"]["provider"] == provider + assert state.exists() == (phase == "initial-source") + assert not (project / "host-invocations").exists() + + _configure_first_goal_storage(core_python, project, runtime, "file" if provider == "sqlite" else "sqlite") + changed = list(arguments) + changed[changed.index("--goal-text") + 1] = "Start an unrelated task." + denied = json.loads(_run(core_python, changed, project, expected=1).stdout) + assert "already connected" in denied["error"] and registry.read_bytes() == before + assert state.exists() == (phase == "initial-source") + assert not (project / "host-invocations").exists() + + recovered = json.loads(_run(core_python, arguments, project).stdout) + assert recovered["status"] == "committed" and recovered["validation"]["status"] == "passed" + assert recovered["turn_instance_id"] == goal["creation_operation_id"] + assert state.is_file() and registry.read_bytes() == before + readback = json.loads(_run(core_python, ["--registry", str(registry), "--format", "json", + "todo", "list", "--goal-id", goal["id"], "--todo-id", recovered["todo_id"]], project).stdout) + assert readback["todo"]["status"] == "done" + assert readback["authority_read"]["source_authority"] == f"{provider}_v0" + assert json.loads((project / "squares.json").read_text()) == [0, 1, 4, 9, 16, 25, 36, 49] + replay = json.loads(_run(core_python, arguments, project).stdout) + assert replay["todo_id"] == recovered["todo_id"] and replay["resume_turn_key"] == recovered["resume_turn_key"] + assert replay["replayed"] and not any(replay["effects"].values()) + assert (project / "host-invocations").read_text().splitlines() == ["called"] + assert (runtime / "goals/first-work-goal/runs/index.jsonl").read_text().count("quota_slot_spent") == 1 From 341063ea507f0e18395253397daaffd8a54ef888 Mon Sep 17 00:00:00 2001 From: cicolord Date: Thu, 19 Nov 2026 07:57:54 +0800 Subject: [PATCH 3/7] Check first-task executables before registering a goal Signed-off-by: cicolord --- .../rfcs/monorepo-distribution-split-v0.md | 9 ++- .../monorepo-distribution-split-v0.zh-CN.md | 8 ++- loopx/cli_commands/start_goal_managed.py | 22 +++++++- packages/loopx-core/README.md | 3 + tests/test_core_distribution.py | 55 +++++++++++++++++++ 5 files changed, 91 insertions(+), 6 deletions(-) diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 3fdd5d0f3b..1fab325228 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -331,12 +331,17 @@ operator-selected tools retain only their already authorized effects. A configured local caller can use `start-goal --execute` to submit one goal sentence and run the first checked task in a fresh project. The approved -adapter and independent validator are caller inputs. The entry uses the existing +adapter and independent validator are caller inputs. The first registration +checks the program paths using the task working directory on POSIX and +checks explicitly absolute paths on Windows. An unavailable program is +reported before creating local Goal state or dispatching work, so the caller +can correct the launch configuration and retry. The entry uses the existing Goal, Todo, lease and Turn owners and defaults to project-local runtime state. Registration records the original operation and storage target before the initial source is written. The identical request can supply a missing initial source when the authority owner still needs it, and can recover the original -task and Turn. Settled work returns the recorded result. The ordinary guided +task and Turn. Settled work returns the recorded result even if the original +executables have been removed. The ordinary guided entry continues to handle interactive hosts and connected projects. ### Responsibility and installation acceptance 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 419cccaac8..f25416fdda 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -229,10 +229,12 @@ stdio relay 在父进程 EOF、SIGTERM 或 SIGINT 时取消所持进程组,并 原资格边界。这是进程监督,不是沙箱;操作者选择的工具只保有原先获准的效果。 已配置的本地调用方可以通过 `start-goal --execute` 在新项目中提交一句目标并运行首个受验收任务。 -获批的适配器和独立检查器由调用方提供。入口复用既有 Goal、Todo、租约和 Turn 的 owner, -运行状态默认保存在项目内。注册先记录原始操作和存储目标,再写入初始状态。 +获批的适配器和独立检查器由调用方提供。首次注册时,POSIX 按任务工作目录检查程序路径, +Windows 检查显式的绝对路径。程序不可用时,在创建本地 Goal 状态或派发任务前提示调用方修正 +启动配置并重试。入口复用既有 Goal、Todo、租约和 Turn 的 owner,运行状态默认保存在项目内。 +注册先记录原始操作和存储目标,再写入初始状态。 中断后,原请求可以在权威 owner 仍需要初始状态时补写缺失的文件,并续接原任务和 Turn。 -已结算的工作回读原结果。 +已结算的工作沿原记录回读,即使原程序已移除。 交互式宿主和已连接项目继续使用现有的引导入口。 ### 职责与安装验收 diff --git a/loopx/cli_commands/start_goal_managed.py b/loopx/cli_commands/start_goal_managed.py index 70a5584193..983ddf2bc5 100644 --- a/loopx/cli_commands/start_goal_managed.py +++ b/loopx/cli_commands/start_goal_managed.py @@ -4,7 +4,9 @@ import argparse import json +import os from pathlib import Path +import shutil from typing import Any from ..bootstrap import DEFAULT_DOMAIN, bootstrap_project, initialize_first_goal_storage, read_json_if_exists @@ -46,6 +48,17 @@ def _first_turn_args( ]) +def _first_task_executable_available(program: str, project: Path) -> bool: + if os.name == "nt": + # CreateProcess owns search for relative names and can use system + # locations outside PATH. Check explicit absolute paths here. + return not Path(program).is_absolute() or shutil.which(program) is not None + if os.path.dirname(program): + return shutil.which(os.path.join(project, program)) is not None + project_path = os.pathsep.join(os.path.join(project, entry) for entry in os.get_exec_path()) + return shutil.which(program, path=project_path) is not None + + def _register_first_goal( *, registry_path: Path, @@ -104,7 +117,14 @@ def execute_managed_start( native_task_validator=None, validator_builder=build_loopx_turn_command_validator, ) assert host_argv is not None + host_argv = normalize_host_argv(host_argv) + validator_argv = json.loads(args.validation_command_json) registry = read_json_if_exists(registry_path) + if not registry: + if not _first_task_executable_available(host_argv[0], project): + raise ValueError("The task runner executable is unavailable. Check --host-adapter-command-json and retry.") + if not _first_task_executable_available(validator_argv[0], project): + raise ValueError("The independent checker executable is unavailable. Check --validation-command-json and retry.") runtime_root = resolve_runtime_root( registry or {"common_runtime_root": str(project / ".loopx/runtime")}, runtime_root_arg, registry_path=registry_path, @@ -113,7 +133,7 @@ def execute_managed_start( digest = canonical_digest({ "project": str(project), "runtime_root": str(runtime_root), "goal_id": goal_id, "agent_id": agent_id, "goal": objective, "title": display_name, - "adapter": normalize_host_argv(host_argv), "validator": json.loads(args.validation_command_json), + "adapter": host_argv, "validator": validator_argv, }) operation_id = "start-" + digest.removeprefix("sha256:")[:32] _register_first_goal( diff --git a/packages/loopx-core/README.md b/packages/loopx-core/README.md index 05b85b19f3..cde2a76b3e 100644 --- a/packages/loopx-core/README.md +++ b/packages/loopx-core/README.md @@ -26,6 +26,9 @@ loopx start-goal --execute --project . --goal-text "Create and check an inventor The configured caller supplies the two JSON argv arrays. Core registers the local Goal and worker, creates one task, then runs the existing checked Turn. +Core checks executable availability before the first registration on POSIX +and checks absolute executable paths on Windows. Correct an unavailable +program in the launch configuration and repeat the same goal. Repeat the original invocation after an interruption, including during registration. It continues the saved attempt or returns the checked result. The `--guided` route remains available for an existing project or an interactive diff --git a/tests/test_core_distribution.py b/tests/test_core_distribution.py index ec501ce7ba..78b6bd58bb 100644 --- a/tests/test_core_distribution.py +++ b/tests/test_core_distribution.py @@ -796,6 +796,61 @@ def test_installed_core_start_goal_preflights_before_creation(core_python, tmp_p assert not (tmp_path / ".loopx").exists() +@pytest.mark.parametrize("unavailable_option", ["--host-adapter-command-json", "--validation-command-json"]) +def test_installed_core_first_task_can_retry_after_correcting_an_unavailable_program( + core_python, tmp_path, monkeypatch, unavailable_option, +): + from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime + + isolate_sqlite_runtime(tmp_path, monkeypatch) + arguments = ["--format", "json", "start-goal", "--project", str(tmp_path), + "--goal-text", "Produce and independently check the squares from zero to seven.", "--execute", + "--host-adapter-command-json", json.dumps([core_python, "-I", "-c", HOST_SOURCE]), + "--validation-command-json", json.dumps([core_python, "-I", "-c", VALIDATOR_SOURCE])] + unavailable = list(arguments) + unavailable[unavailable.index(unavailable_option) + 1] = json.dumps([str(tmp_path / "missing.exe")]) + + refused = json.loads(_run(core_python, unavailable, tmp_path, expected=1).stdout) + assert not (tmp_path / ".loopx").exists() + assert not (tmp_path / "host-invocations").exists() + assert unavailable_option in refused["error"] and "unavailable" in refused["error"] + + result = json.loads(_run(core_python, arguments, tmp_path).stdout) + assert result["status"] == "committed" and result["validation"]["status"] == "passed" + assert json.loads((tmp_path / "squares.json").read_text()) == [0, 1, 4, 9, 16, 25, 36, 49] + assert (tmp_path / "host-invocations").read_text().splitlines() == ["called"] + + +@pytest.mark.skipif(os.name != "posix", reason="uses POSIX project-relative executable resolution") +def test_installed_core_first_task_uses_project_tools_and_replays_after_they_are_removed( + core_python, tmp_path, monkeypatch, +): + from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime + + isolate_sqlite_runtime(tmp_path, monkeypatch) + project = tmp_path / "project" + scripts = project / "tools" + scripts.mkdir(parents=True) + runner, check = scripts / "fixture-task-runner", scripts / "fixture-task-check" + for path, source in ((runner, HOST_SOURCE), (check, VALIDATOR_SOURCE)): + path.write_text("#!/usr/bin/env python3\n" + source) + path.chmod(0o700) + environment = {"PATH": "tools" + os.pathsep + os.environ["PATH"]} + arguments = ["--format", "json", "start-goal", "--project", str(project), + "--goal-text", "Produce and independently check the squares from zero to seven.", "--execute", + "--host-adapter-command-json", json.dumps(["./tools/fixture-task-runner"]), + "--validation-command-json", json.dumps(["fixture-task-check"])] + + first = json.loads(_run(core_python, arguments, tmp_path, environment=environment).stdout) + assert first["status"] == "committed" and first["validation"]["status"] == "passed" + runner.unlink() + check.unlink() + replay = json.loads(_run(core_python, arguments, tmp_path, environment=environment).stdout) + assert replay["replayed"] and replay["resume_turn_key"] == first["resume_turn_key"] + assert not any(replay["effects"].values()) + assert (project / "host-invocations").read_text().splitlines() == ["called"] + + def _configure_first_goal_storage(core_python, project, runtime, provider): setup = '''import sys from pathlib import Path From c58bfc4c87f216e0b8a12f17fbac523125cd1d85 Mon Sep 17 00:00:00 2001 From: cicolord Date: Thu, 19 Nov 2026 09:18:01 +0800 Subject: [PATCH 4/7] Start the first checked task with the installed Codex CLI Signed-off-by: cicolord --- .../rfcs/monorepo-distribution-split-v0.md | 17 ++-- .../monorepo-distribution-split-v0.zh-CN.md | 7 +- loopx/cli_commands/start_goal.py | 18 ++-- loopx/cli_commands/start_goal_managed.py | 34 ++++--- packages/loopx-core/README.md | 24 +++-- tests/test_core_distribution.py | 90 +++++++++++++++++++ 6 files changed, 160 insertions(+), 30 deletions(-) diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 1fab325228..f06346a8b1 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -330,18 +330,23 @@ existing qualification boundary. It is process supervision, not a sandbox; operator-selected tools retain only their already authorized effects. A configured local caller can use `start-goal --execute` to submit one goal -sentence and run the first checked task in a fresh project. The approved -adapter and independent validator are caller inputs. The first registration -checks the program paths using the task working directory on POSIX and -checks explicitly absolute paths on Windows. An unavailable program is +sentence and run the first checked task in a fresh project. Selecting +`--host codex-cli` uses the installed Codex CLI and existing read-only native +profile. The generic route accepts its approved adapter. Both routes require +the caller's independent check and recover through the original executor. +Before first registration the native route looks for Codex on PATH. Adapter +and check commands resolve from the task directory on POSIX and are checked +for explicitly absolute paths on Windows. An unavailable program is reported before creating local Goal state or dispatching work, so the caller can correct the launch configuration and retry. The entry uses the existing Goal, Todo, lease and Turn owners and defaults to project-local runtime state. Registration records the original operation and storage target before the initial source is written. The identical request can supply a missing initial source when the authority owner still needs it, and can recover the original -task and Turn. Settled work returns the recorded result even if the original -executables have been removed. The ordinary guided +task and Turn. The native operation records its selected host in the request +identity. An existing generic operation retains its original identity. +Settled work returns the recorded result even if the original executables +have been removed. The ordinary guided entry continues to handle interactive hosts and connected projects. ### Responsibility and installation acceptance 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 f25416fdda..7de074af5c 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -229,11 +229,14 @@ stdio relay 在父进程 EOF、SIGTERM 或 SIGINT 时取消所持进程组,并 原资格边界。这是进程监督,不是沙箱;操作者选择的工具只保有原先获准的效果。 已配置的本地调用方可以通过 `start-goal --execute` 在新项目中提交一句目标并运行首个受验收任务。 -获批的适配器和独立检查器由调用方提供。首次注册时,POSIX 按任务工作目录检查程序路径, -Windows 检查显式的绝对路径。程序不可用时,在创建本地 Goal 状态或派发任务前提示调用方修正 +选择 `--host codex-cli` 后,入口直接使用 PATH 上已安装的 Codex CLI 和现有只读配置。 +通用入口接受调用方批准的适配器。两条路径都使用调用方提供的独立检查,并沿原执行器恢复。 +首次注册时会检查所选的 Codex 可执行文件。对于适配器和检查命令,POSIX 按任务工作目录 +解析路径,Windows 检查显式的绝对路径。程序不可用时,在创建本地 Goal 状态或派发任务前提示调用方修正 启动配置并重试。入口复用既有 Goal、Todo、租约和 Turn 的 owner,运行状态默认保存在项目内。 注册先记录原始操作和存储目标,再写入初始状态。 中断后,原请求可以在权威 owner 仍需要初始状态时补写缺失的文件,并续接原任务和 Turn。 +原生入口的操作身份记录所选宿主,已有通用入口继续沿原身份恢复。 已结算的工作沿原记录回读,即使原程序已移除。 交互式宿主和已连接项目继续使用现有的引导入口。 diff --git a/loopx/cli_commands/start_goal.py b/loopx/cli_commands/start_goal.py index 9fd5a0a648..a41fc70f50 100644 --- a/loopx/cli_commands/start_goal.py +++ b/loopx/cli_commands/start_goal.py @@ -178,10 +178,10 @@ def add_capability_route_argument(parser: argparse.ArgumentParser) -> None: ) -def register_start_goal_command(subparsers: argparse._SubParsersAction) -> None: +def register_start_goal_command(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None: start_goal_parser = subparsers.add_parser( "start-goal", - help="Preview a guided goal or execute its first checked task with a configured local adapter.", + help="Preview a guided goal or execute its first checked task locally.", ) start_mode = start_goal_parser.add_mutually_exclusive_group() start_mode.add_argument( @@ -192,7 +192,13 @@ def register_start_goal_command(subparsers: argparse._SubParsersAction) -> None: start_mode.add_argument( "--execute", action="store_true", - help="Start one checked task in a fresh local project using the supplied adapter and validator.", + help="Start one checked task in a fresh local project with an independent check.", + ) + start_goal_parser.add_argument( + "--host", + dest="execution_host", + choices=("codex-cli", "generic-cli"), + help="Executor for --execute. Select codex-cli to use the installed Codex CLI.", ) start_goal_parser.add_argument( "--host-adapter-command-json", @@ -390,8 +396,10 @@ def handle_start_goal_command( return 1 print_payload(payload, args.format, render_managed_start_markdown) return 0 if payload["ok"] else 1 - if getattr(args, "host_adapter_command_json", None) is not None or getattr(args, "validation_command_json", None) is not None: - print_payload({"ok": False, "error": "Adapter and validator commands require start-goal --execute."}, + if any(getattr(args, name, None) is not None for name in ( + "execution_host", "host_adapter_command_json", "validation_command_json", + )): + print_payload({"ok": False, "error": "Host and check options require start-goal --execute."}, args.format, _render_start_goal_markdown) return 2 if not bool(getattr(args, "guided", False)): diff --git a/loopx/cli_commands/start_goal_managed.py b/loopx/cli_commands/start_goal_managed.py index 983ddf2bc5..85e9c1b917 100644 --- a/loopx/cli_commands/start_goal_managed.py +++ b/loopx/cli_commands/start_goal_managed.py @@ -34,16 +34,25 @@ def _first_turn_args( or args.available_capabilities or args.capability_route or args.fine_grained or args.include_command_pack_detail or args.slash_command_arguments is not None ): - raise ValueError("start-goal --execute takes a local --goal-text and a configured adapter and validator") - if not args.host_adapter_command_json or not args.validation_command_json: - raise ValueError("start-goal --execute requires --host-adapter-command-json and --validation-command-json") + raise ValueError("start-goal --execute takes a local --goal-text and an independent check") + host = args.execution_host or "generic-cli" + if not args.validation_command_json: + raise ValueError("start-goal --execute requires --validation-command-json") + host_args = [] + if host == "generic-cli": + if not args.host_adapter_command_json: + raise ValueError("Select --host codex-cli or supply --host-adapter-command-json for a generic adapter.") + host_args = [ + "--host-adapter-request-schema", COMPLETE_TURN_HOST_REQUEST_SCHEMA, + "--host-adapter-command-json", args.host_adapter_command_json, + ] + elif args.host_adapter_command_json is not None: + raise ValueError("An adapter command requires --host generic-cli.") parser = argparse.ArgumentParser(prog="loopx", add_help=False) register_turn_commands(parser.add_subparsers(dest="command"), add_subcommand_format) return parser.parse_args([ "turn", "run-once", "--goal-id", goal_id, "--agent-id", agent_id, - "--project", str(project), "--host", "generic-cli", - "--host-adapter-request-schema", COMPLETE_TURN_HOST_REQUEST_SCHEMA, - "--host-adapter-command-json", args.host_adapter_command_json, + "--project", str(project), "--host", host, *host_args, "--validation-command-json", args.validation_command_json, "--no-global-sync", "--execute", ]) @@ -116,12 +125,13 @@ def execute_managed_start( turn_args, native_host_runner=None, native_session_binding_resolver=None, native_task_validator=None, validator_builder=build_loopx_turn_command_validator, ) - assert host_argv is not None - host_argv = normalize_host_argv(host_argv) + host_argv = normalize_host_argv(host_argv) if host_argv is not None else None validator_argv = json.loads(args.validation_command_json) registry = read_json_if_exists(registry_path) if not registry: - if not _first_task_executable_available(host_argv[0], project): + if host_argv is None and shutil.which(turn_args.codex_bin) is None: + raise ValueError("The Codex CLI executable is unavailable. Put codex on PATH and retry.") + if host_argv is not None and not _first_task_executable_available(host_argv[0], project): raise ValueError("The task runner executable is unavailable. Check --host-adapter-command-json and retry.") if not _first_task_executable_available(validator_argv[0], project): raise ValueError("The independent checker executable is unavailable. Check --validation-command-json and retry.") @@ -130,10 +140,14 @@ def execute_managed_start( runtime_root_arg, registry_path=registry_path, ).resolve() display_name = args.display_name or derive_goal_display_name(objective) + launch_identity = ( + {"adapter": host_argv} if host_argv is not None + else {"host": turn_args.host, "binary": turn_args.codex_bin, "sandbox": turn_args.codex_sandbox} + ) digest = canonical_digest({ "project": str(project), "runtime_root": str(runtime_root), "goal_id": goal_id, "agent_id": agent_id, "goal": objective, "title": display_name, - "adapter": host_argv, "validator": validator_argv, + **launch_identity, "validator": validator_argv, }) operation_id = "start-" + digest.removeprefix("sha256:")[:32] _register_first_goal( diff --git a/packages/loopx-core/README.md b/packages/loopx-core/README.md index cde2a76b3e..4a3ad49d47 100644 --- a/packages/loopx-core/README.md +++ b/packages/loopx-core/README.md @@ -16,19 +16,29 @@ uv pip install --python /tmp/loopx-core-env/bin/python /tmp/loopx-core-dist/loop /tmp/loopx-core-env/bin/loopx doctor --installation-only --deep --format json ``` -For a fresh local project with an approved v1 CLI adapter and independent -checker, start the first task from the goal text in one invocation. +For a fresh project with Codex CLI on PATH and an approved independent check, +start a read-only task from the goal text. The existing Codex installation +supplies the model and login. + +```sh +loopx start-goal --execute --host codex-cli --project . \ + --goal-text "Read the inventory and check the total." \ + --validation-command-json '["./check-inventory"]' +``` + +Use an existing project check that independently verifies the result. A +configured generic CLI caller can still supply its approved v1 adapter. ```sh loopx start-goal --execute --project . --goal-text "Create and check an inventory report." \ --host-adapter-command-json "$adapter_argv" --validation-command-json "$validator_argv" ``` -The configured caller supplies the two JSON argv arrays. Core registers the -local Goal and worker, creates one task, then runs the existing checked Turn. -Core checks executable availability before the first registration on POSIX -and checks absolute executable paths on Windows. Correct an unavailable -program in the launch configuration and repeat the same goal. +Core registers the local Goal and worker, creates one task, then runs the +existing checked Turn. It checks for the selected Codex binary and checks the +configured command paths before the first registration on POSIX. For generic +adapter and check commands on Windows it checks absolute paths. Correct an +unavailable program in the launch configuration and repeat the same goal. Repeat the original invocation after an interruption, including during registration. It continues the saved attempt or returns the checked result. The `--guided` route remains available for an existing project or an interactive diff --git a/tests/test_core_distribution.py b/tests/test_core_distribution.py index 78b6bd58bb..66ec8a928e 100644 --- a/tests/test_core_distribution.py +++ b/tests/test_core_distribution.py @@ -775,6 +775,96 @@ def test_installed_core_starts_one_checked_task_from_goal_text(core_python, tmp_ assert spends.read_text().count("quota_slot_spent") == 1 +@pytest.mark.parametrize("provider", ["file", "sqlite"]) +def test_installed_core_starts_and_replays_a_checked_codex_goal(core_python, tmp_path, monkeypatch, provider): + from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime + from tests.control_plane.host_process_fixture import write_python_host_fixture + from tests.test_loopx_turn_codex_cli import _fake_codex + + isolate_sqlite_runtime(tmp_path, monkeypatch) + project, runtime = tmp_path / "inventory", tmp_path / "runtime" + project.mkdir() + (project / "inventory.json").write_text("[2, 6, 11]", encoding="utf-8") + _configure_first_goal_storage(core_python, project, runtime, provider) + objective = "Read the inventory and independently check the total." + check = """import json,pathlib,sys +record = json.load(sys.stdin) +expected = sum(json.loads(pathlib.Path('inventory.json').read_text())) +assert record['summary'] == f'Inventory total: {expected}' +assert record['result_kind'] == 'validated_completion' +""" + command = ["--runtime-root", str(runtime), "--format", "json", "start-goal", "--execute", + "--host", "codex-cli", "--project", str(project), "--goal-text", objective, + "--validation-command-json", json.dumps([core_python, "-I", "-c", check])] + binaries = tmp_path / "bin" + binaries.mkdir() + home = tmp_path / "codex-home" + home.mkdir() + node = shutil.which("node") + assert node is not None + fake, log = _fake_codex(tmp_path) + environment = { + "PATH": os.pathsep.join([str(binaries), str(Path(core_python).parent), str(Path(node).parent), os.defpath]), + "CODEX_HOME": str(home), + "FAKE_CODEX_LOG": str(log), + } + missing = json.loads(_run(core_python, command, tmp_path, environment=environment, expected=1).stdout) + assert "Codex CLI executable is unavailable" in missing["error"] + assert not (project / ".loopx").exists() and not log.exists() + + source = fake if os.name != "nt" else fake.with_suffix(".py") + executable = write_python_host_fixture(binaries / "codex", source.read_text(encoding="utf-8").replace( + "result.update(json.loads(os.environ.get(\"FAKE_CODEX_RESULT_FIELDS\", \"{}\")))", + f"assert {objective!r} in prompt\n" + "assert args[args.index('--sandbox') + 1] == 'read-only'\n" + "total = sum(json.loads(pathlib.Path('inventory.json').read_text()))\n" + "result.update(result_kind='validated_completion', summary=f'Inventory total: {total}', " + "work_evidence=['artifact:inventory.json'], validation_evidence=['check:inventory-total'])", + )) + # Stop after the native result is durable and before the independent check. + interrupted = os.name == "posix" + if interrupted: + command_with_fault = _command(core_python, command) + command_with_fault[3] = """import os, signal +from loopx.control_plane.turn_driver import command_validation +def interrupt_validator(*args, **kwargs): + return lambda *_: os.kill(os.getpid(), signal.SIGKILL) +command_validation.build_loopx_turn_command_validator = interrupt_validator +""" + command_with_fault[3] + stopped = subprocess.run(command_with_fault, cwd=tmp_path, env=_environment(core_python, environment), + capture_output=True, text=True, timeout=90) + assert stopped.returncode == -signal.SIGKILL, (stopped.stdout, stopped.stderr) + (journal,) = [path for path in (runtime / "goals/inventory-goal/turns").glob("*.json") + if not path.name.endswith(".lock.holder.json")] + recorded = json.loads(journal.read_text()) + assert recorded["host_result"]["summary"] == "Inventory total: 19" + assert "typed_result" in recorded["completed_phases"] + executable.unlink() + + first = json.loads(_run(core_python, command, tmp_path, environment=environment).stdout) + assert first["status"] == "committed" and first["validation"]["status"] == "passed" + assert first["result_kind"] == "validated_completion" + assert first["effects"]["host_invoked"] is (not interrupted) + assert first["effects"]["quota_spent"] + registry = project / ".loopx/registry.json" + registry_bytes = registry.read_bytes() + receipt = json.loads(_run(core_python, ["--registry", str(registry), "--runtime-root", str(runtime), + "--format", "json", "todo", "list", "--goal-id", first["goal_id"], "--todo-id", first["todo_id"]], + project, environment=environment).stdout) + assert receipt["todo"]["status"] == "done" + executable.unlink(missing_ok=True) + replay = json.loads(_run(core_python, command, tmp_path, environment=environment).stdout) + assert replay["replayed"] and replay["resume_turn_key"] == first["resume_turn_key"] + assert replay["todo_id"] == first["todo_id"] and not any(replay["effects"].values()) + different = list(command) + different[different.index("--host") + 1] = "generic-cli" + different += ["--host-adapter-command-json", json.dumps([core_python])] + denied = json.loads(_run(core_python, different, tmp_path, environment=environment, expected=1).stdout) + assert "already connected" in denied["error"] and registry.read_bytes() == registry_bytes + assert len(log.read_text().splitlines()) == 1 + assert (runtime / "goals" / first["goal_id"] / "runs/index.jsonl").read_text().count("quota_slot_spent") == 1 + + @pytest.mark.parametrize("invalid", ["missing-validator", "invalid-adapter", "owned-goal"]) def test_installed_core_start_goal_preflights_before_creation(core_python, tmp_path, invalid): arguments = ["--format", "json", "start-goal", "--project", str(tmp_path), From a5851639460ffef47ec2a79624ac00a484e08230 Mon Sep 17 00:00:00 2001 From: cicolord Date: Thu, 19 Nov 2026 09:45:48 +0800 Subject: [PATCH 5/7] Keep the first Codex task's writes in its selected directory Signed-off-by: cicolord --- .../rfcs/monorepo-distribution-split-v0.md | 13 ++-- .../monorepo-distribution-split-v0.zh-CN.md | 6 +- loopx/cli_commands/start_goal.py | 6 +- loopx/cli_commands/start_goal_managed.py | 42 +++++++++---- loopx/cli_commands/turn_host_request.py | 2 + loopx/control_plane/turn_driver/codex_cli.py | 55 +++++++++++++++-- packages/loopx-core/README.md | 16 ++++- tests/test_core_distribution.py | 60 ++++++++++++++++--- 8 files changed, 168 insertions(+), 32 deletions(-) diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index f06346a8b1..40113f791b 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -331,8 +331,12 @@ operator-selected tools retain only their already authorized effects. A configured local caller can use `start-goal --execute` to submit one goal sentence and run the first checked task in a fresh project. Selecting -`--host codex-cli` uses the installed Codex CLI and existing read-only native -profile. The generic route accepts its approved adapter. Both routes require +`--host codex-cli` uses the installed Codex CLI with read-only tools by default. +An explicit `--write-dir` binds one project directory to the Goal and Task write +scope. The native adapter confines file writes to that directory through an +invocation-local Codex permission profile. The checker and its verification +rules stay outside the writable directory. The generic route accepts its +approved adapter. Both routes require the caller's independent check and recover through the original executor. Before first registration the native route looks for Codex on PATH. Adapter and check commands resolve from the task directory on POSIX and are checked @@ -343,8 +347,9 @@ Goal, Todo, lease and Turn owners and defaults to project-local runtime state. Registration records the original operation and storage target before the initial source is written. The identical request can supply a missing initial source when the authority owner still needs it, and can recover the original -task and Turn. The native operation records its selected host in the request -identity. An existing generic operation retains its original identity. +task and Turn. The native operation records its selected host and any approved +directory in the request identity. An existing generic operation retains its +original identity. Settled work returns the recorded result even if the original executables have been removed. The ordinary guided entry continues to handle interactive hosts and connected projects. 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 7de074af5c..ec6ef6edcb 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -229,14 +229,16 @@ stdio relay 在父进程 EOF、SIGTERM 或 SIGINT 时取消所持进程组,并 原资格边界。这是进程监督,不是沙箱;操作者选择的工具只保有原先获准的效果。 已配置的本地调用方可以通过 `start-goal --execute` 在新项目中提交一句目标并运行首个受验收任务。 -选择 `--host codex-cli` 后,入口直接使用 PATH 上已安装的 Codex CLI 和现有只读配置。 +选择 `--host codex-cli` 后,入口直接使用 PATH 上已安装的 Codex CLI,默认工具只读。 +显式传入 `--write-dir` 时,将项目内的一个目录绑定为 Goal 和 Task 的写范围。原生适配器使用 +仅对本次运行生效的 Codex 权限配置,把文件写入限制在该目录。检查器及验证规则放在目录外。 通用入口接受调用方批准的适配器。两条路径都使用调用方提供的独立检查,并沿原执行器恢复。 首次注册时会检查所选的 Codex 可执行文件。对于适配器和检查命令,POSIX 按任务工作目录 解析路径,Windows 检查显式的绝对路径。程序不可用时,在创建本地 Goal 状态或派发任务前提示调用方修正 启动配置并重试。入口复用既有 Goal、Todo、租约和 Turn 的 owner,运行状态默认保存在项目内。 注册先记录原始操作和存储目标,再写入初始状态。 中断后,原请求可以在权威 owner 仍需要初始状态时补写缺失的文件,并续接原任务和 Turn。 -原生入口的操作身份记录所选宿主,已有通用入口继续沿原身份恢复。 +原生入口的操作身份记录所选宿主及批准的目录,已有通用入口继续沿原身份恢复。 已结算的工作沿原记录回读,即使原程序已移除。 交互式宿主和已连接项目继续使用现有的引导入口。 diff --git a/loopx/cli_commands/start_goal.py b/loopx/cli_commands/start_goal.py index a41fc70f50..48d4370359 100644 --- a/loopx/cli_commands/start_goal.py +++ b/loopx/cli_commands/start_goal.py @@ -200,6 +200,10 @@ def register_start_goal_command(subparsers: argparse._SubParsersAction[argparse. choices=("codex-cli", "generic-cli"), help="Executor for --execute. Select codex-cli to use the installed Codex CLI.", ) + start_goal_parser.add_argument( + "--write-dir", + help="Project-relative directory the first Codex task may write. The check runs independently.", + ) start_goal_parser.add_argument( "--host-adapter-command-json", help="Approved JSON argv for a v1 generic CLI adapter when executing the first task.", @@ -397,7 +401,7 @@ def handle_start_goal_command( print_payload(payload, args.format, render_managed_start_markdown) return 0 if payload["ok"] else 1 if any(getattr(args, name, None) is not None for name in ( - "execution_host", "host_adapter_command_json", "validation_command_json", + "execution_host", "host_adapter_command_json", "validation_command_json", "write_dir", )): print_payload({"ok": False, "error": "Host and check options require start-goal --execute."}, args.format, _render_start_goal_markdown) diff --git a/loopx/cli_commands/start_goal_managed.py b/loopx/cli_commands/start_goal_managed.py index 85e9c1b917..0a7df9f1b7 100644 --- a/loopx/cli_commands/start_goal_managed.py +++ b/loopx/cli_commands/start_goal_managed.py @@ -38,6 +38,8 @@ def _first_turn_args( host = args.execution_host or "generic-cli" if not args.validation_command_json: raise ValueError("start-goal --execute requires --validation-command-json") + if args.write_dir is not None and host != "codex-cli": + raise ValueError("--write-dir requires --host codex-cli.") host_args = [] if host == "generic-cli": if not args.host_adapter_command_json: @@ -57,15 +59,19 @@ def _first_turn_args( ]) -def _first_task_executable_available(program: str, project: Path) -> bool: +def _first_task_executable(program: str, project: Path) -> str | None: if os.name == "nt": - # CreateProcess owns search for relative names and can use system - # locations outside PATH. Check explicit absolute paths here. - return not Path(program).is_absolute() or shutil.which(program) is not None + return shutil.which(program) if os.path.dirname(program): - return shutil.which(os.path.join(project, program)) is not None + return shutil.which(os.path.join(project, program)) project_path = os.pathsep.join(os.path.join(project, entry) for entry in os.get_exec_path()) - return shutil.which(program, path=project_path) is not None + return shutil.which(program, path=project_path) + + +def _first_task_executable_available(program: str, project: Path) -> bool: + # CreateProcess owns its broader search for relative names. + return (os.name == "nt" and not Path(program).is_absolute() + or _first_task_executable(program, project) is not None) def _register_first_goal( @@ -78,6 +84,7 @@ def _register_first_goal( objective: str, display_name: str | None, operation_id: str, + write_scope: list[str], ) -> None: if not registry_path.exists(): try: @@ -87,7 +94,7 @@ def _register_first_goal( domain=DEFAULT_DOMAIN, role="controller", parent_goal_id=None, state_file=None, goal_doc=None, adapter_kind="generic_project_goal_v0", adapter_status="connected", next_probe=None, spawn_allowed=False, max_children=0, - allowed_domains=[], write_scope=[], force=False, dry_run=False, sync_global=False, + allowed_domains=[], write_scope=write_scope, force=False, dry_run=False, sync_global=False, creation_operation_id=operation_id, initial_agent_id=agent_id, ) if not receipt.get("ok"): @@ -140,10 +147,25 @@ def execute_managed_start( runtime_root_arg, registry_path=registry_path, ).resolve() display_name = args.display_name or derive_goal_display_name(objective) - launch_identity = ( + launch_identity: dict[str, object] = ( {"adapter": host_argv} if host_argv is not None else {"host": turn_args.host, "binary": turn_args.codex_bin, "sandbox": turn_args.codex_sandbox} ) + write_scope: list[str] = [] + if args.write_dir is not None: + from ..control_plane.turn_driver.codex_cli import codex_project_write_scope + + raw = Path(args.write_dir) + if raw.is_absolute(): + raise ValueError("--write-dir requires a project-relative directory.") + directory, scope = codex_project_write_scope(project, raw, runtime_root) + checker = _first_task_executable(validator_argv[0], project) + if checker is not None and (project / checker).resolve().is_relative_to(directory): + raise ValueError("Keep the independent checker outside --write-dir.") + turn_args.codex_write_dir = directory + turn_args.codex_sandbox = "workspace-write" + write_scope = [scope] + launch_identity["write_dir"] = str(directory) digest = canonical_digest({ "project": str(project), "runtime_root": str(runtime_root), "goal_id": goal_id, "agent_id": agent_id, "goal": objective, "title": display_name, @@ -153,13 +175,13 @@ def execute_managed_start( _register_first_goal( registry_path=registry_path, runtime_root=runtime_root, project=project, goal_id=goal_id, agent_id=agent_id, objective=objective, - display_name=display_name, operation_id=operation_id, + display_name=display_name, operation_id=operation_id, write_scope=write_scope, ) todo = add_goal_todo( registry_path=registry_path, runtime_root_arg=str(runtime_root), goal_id=goal_id, role="agent", text=objective, priority="P1", claimed_by=agent_id, task_class="advancement_task", action_kind="advance", - operation_id=f"{operation_id}:first-task", + operation_id=f"{operation_id}:first-task", required_write_scopes=write_scope or None, ) if not todo.get("ok") or not todo.get("todo_id"): raise RuntimeError("The goal was registered. Retry the same start request to recover its first task.") diff --git a/loopx/cli_commands/turn_host_request.py b/loopx/cli_commands/turn_host_request.py index 34852557a3..b74dd6d603 100644 --- a/loopx/cli_commands/turn_host_request.py +++ b/loopx/cli_commands/turn_host_request.py @@ -139,6 +139,8 @@ def run_built_in_host( operation_request_sha256=getattr(args, "operation_request_sha256", None), **options, ) + if (directory := getattr(args, "codex_write_dir", None)) is not None: + options["write_directory"] = directory return run_codex_cli_host(request, registry_path=registry_path, **options) return run_built_in_host diff --git a/loopx/control_plane/turn_driver/codex_cli.py b/loopx/control_plane/turn_driver/codex_cli.py index ff093b0d5d..02dafafc19 100644 --- a/loopx/control_plane/turn_driver/codex_cli.py +++ b/loopx/control_plane/turn_driver/codex_cli.py @@ -786,6 +786,25 @@ def failure_kind(self, *, complete: bool = True) -> str: return _FAILURE_KINDS.get(self.category(complete=complete), "unknown") +def codex_project_write_scope(project: Path, directory: Path, runtime_root: Path) -> tuple[Path, str]: + """Resolve one writable directory without including the controller stores.""" + from ..todos.contract import normalize_required_write_scopes + + project = project.resolve() + directory = (project / directory).resolve() + if directory == project or not directory.is_relative_to(project) or (directory.exists() and not directory.is_dir()): + raise ValueError("--write-dir must name a directory inside the project.") + for protected in ((project / ".loopx").resolve(), runtime_root.resolve()): + if directory.is_relative_to(protected) or protected.is_relative_to(directory): + raise ValueError("--write-dir must stay separate from the goal and runtime state.") + if any(marker in str(directory) for marker in "*?[]"): + raise ValueError("--write-dir must use a literal path supported by the Codex permission profile.") + scope = f"{directory.relative_to(project).as_posix()}/**" + if normalize_required_write_scopes([scope]) != [scope]: + raise ValueError("--write-dir must use a directory name supported by the task write scope.") + return directory, scope + + def _codex_command( *, codex_bin: str, @@ -798,7 +817,23 @@ def _codex_command( session_id: str | None, mcp_server: Mapping[str, Any] | None, mcp_turn_environment: Mapping[str, str], + write_directory: Path | None = None, ) -> list[str]: + if write_directory is not None: + # Entry names can merge with ambient config. Use this invocation's own + # profile and bind sessions to the stable directory separately. + profile = f"loopx_{os.urandom(16).hex()}" + rule = f'{{{json.dumps(str(write_directory), ensure_ascii=False)}="write"}}' + sandbox_arguments = [ + "--strict-config", "--ignore-rules", + "-c", f'permissions.{profile}={{extends=":read-only",filesystem={rule},network={{enabled=false}}}}', + "-c", f'default_permissions="{profile}"', + "-c", 'approval_policy="never"', + ] + elif session_id: + sandbox_arguments = ["-c", f'sandbox_mode="{sandbox}"'] + else: + sandbox_arguments = ["--sandbox", sandbox] if session_id: command = [ codex_bin, @@ -807,8 +842,7 @@ def _codex_command( "-C", str(project), "resume", - "-c", - f'sandbox_mode="{sandbox}"', + *sandbox_arguments, "--json", ] else: @@ -816,8 +850,7 @@ def _codex_command( codex_bin, "exec", "--skip-git-repo-check", - "--sandbox", - sandbox, + *sandbox_arguments, "-C", str(project), "--json", @@ -882,6 +915,7 @@ def run_codex_cli_host( timeout_seconds: float | None = None, goal_admission: FirstPartyHostGoalAdmission | None = None, registry_path: Path | None = None, + write_directory: Path | None = None, ) -> dict[str, Any]: assert_turn_host_request_version(request) if sandbox not in CODEX_CLI_SANDBOXES: @@ -892,6 +926,14 @@ def run_codex_cli_host( resolved = shutil.which(codex_bin) if os.path.sep not in codex_bin else codex_bin if not resolved or not Path(resolved).exists(): raise ValueError("Codex CLI executable is unavailable") + session_sandbox = sandbox + if write_directory is not None: + write_directory, scope = codex_project_write_scope(project, write_directory, runtime_root) + work = _mapping(request.get("work_contract")) + if (_mapping(work.get("goal_boundary")).get("write_scope") != [scope] + or _mapping(work.get("selected_todo")).get("required_write_scopes") != [scope]): + raise ValueError("Codex write directory must match the admitted task and goal scope.") + session_sandbox = f"directory:{write_directory}" lineage = _lineage(request) admission = goal_admission if admission is None and registry_path is not None: @@ -919,11 +961,11 @@ def run_codex_cli_host( profile_digest = (codex_session_profile_digest( project=project, codex_bin=str(resolved), home=Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser(), - model=model, reasoning_effort=reasoning_effort, sandbox=sandbox, mcp_server=mcp_server, + model=model, reasoning_effort=reasoning_effort, sandbox=session_sandbox, mcp_server=mcp_server, ) if session_scope == "agent" else None) if binding and profile_digest: approved_write_resume = ( - sandbox == "workspace-write" + write_directory is None and sandbox == "workspace-write" and binding.get("session_profile_digest") == codex_session_profile_digest( project=project, codex_bin=str(resolved), home=Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser(), @@ -1011,6 +1053,7 @@ def commit() -> None: reasoning_effort=reasoning_effort, session_id=session_id, mcp_server=mcp_server, + write_directory=write_directory, mcp_turn_environment=collaboration_mcp_turn_environment( mcp_server, turn_key=request["turn_key"], lineage=lineage, project=project, ), diff --git a/packages/loopx-core/README.md b/packages/loopx-core/README.md index 4a3ad49d47..2fa84be756 100644 --- a/packages/loopx-core/README.md +++ b/packages/loopx-core/README.md @@ -27,7 +27,21 @@ loopx start-goal --execute --host codex-cli --project . \ ``` Use an existing project check that independently verifies the result. A -configured generic CLI caller can still supply its approved v1 adapter. +Codex CLI installation with permission-profile support can also write a first +artifact in a selected directory. + +```sh +loopx start-goal --execute --host codex-cli --project . --write-dir reports \ + --goal-text "Write a checked inventory total to reports/total.txt." \ + --validation-command-json '["./check-inventory-report"]' +``` + +Keep the checker and its verification rules outside the writable directory. +The Codex filesystem sandbox allows writes in that directory. Core keeps the +registration, task state and settlement outside the write grant. Repeat the +same directory and check when recovering the original task. + +A configured generic CLI caller can still supply its approved v1 adapter. ```sh loopx start-goal --execute --project . --goal-text "Create and check an inventory report." \ diff --git a/tests/test_core_distribution.py b/tests/test_core_distribution.py index 66ec8a928e..373cd05920 100644 --- a/tests/test_core_distribution.py +++ b/tests/test_core_distribution.py @@ -776,7 +776,8 @@ def test_installed_core_starts_one_checked_task_from_goal_text(core_python, tmp_ @pytest.mark.parametrize("provider", ["file", "sqlite"]) -def test_installed_core_starts_and_replays_a_checked_codex_goal(core_python, tmp_path, monkeypatch, provider): +@pytest.mark.parametrize("write", [False, True], ids=["read-only", "write-report"]) +def test_installed_core_starts_and_replays_a_checked_codex_goal(core_python, tmp_path, monkeypatch, provider, write): from tests.control_plane.canonical_authority_fixture import isolate_sqlite_runtime from tests.control_plane.host_process_fixture import write_python_host_fixture from tests.test_loopx_turn_codex_cli import _fake_codex @@ -793,9 +794,13 @@ def test_installed_core_starts_and_replays_a_checked_codex_goal(core_python, tmp assert record['summary'] == f'Inventory total: {expected}' assert record['result_kind'] == 'validated_completion' """ + if write: + check += "assert pathlib.Path('reports/total.txt').read_text() == str(expected)\n" command = ["--runtime-root", str(runtime), "--format", "json", "start-goal", "--execute", "--host", "codex-cli", "--project", str(project), "--goal-text", objective, "--validation-command-json", json.dumps([core_python, "-I", "-c", check])] + if write: + command += ["--write-dir", "reports"] binaries = tmp_path / "bin" binaries.mkdir() home = tmp_path / "codex-home" @@ -813,14 +818,50 @@ def test_installed_core_starts_and_replays_a_checked_codex_goal(core_python, tmp assert not (project / ".loopx").exists() and not log.exists() source = fake if os.name != "nt" else fake.with_suffix(".py") + behavior = [f"assert {objective!r} in prompt", + "total = sum(json.loads(pathlib.Path('inventory.json').read_text()))"] + if write: + behavior.extend([ + "import tomllib", + "settings = tomllib.loads('\\n'.join(args[i+1] for i,a in enumerate(args) if a == '-c'))", + "profile = settings['permissions'][settings['default_permissions']]", + "assert profile['extends'] == ':read-only' and settings['approval_policy'] == 'never'", + "assert profile['filesystem'] == {str(pathlib.Path('reports').resolve()): 'write'}", + "assert '--sandbox' not in args and '--strict-config' in args and '--ignore-rules' in args", + "task = json.loads(prompt.split('Turn request:\\n', 1)[1])['task_context']", + "assert task['goal_boundary']['write_scope'] == ['reports/**']", + "pathlib.Path('reports').mkdir()", + "pathlib.Path('reports/total.txt').write_text(str(total))", + ]) + else: + behavior.append("assert args[args.index('--sandbox') + 1] == 'read-only'") + behavior.append( + "result.update(result_kind='validated_completion', summary=f'Inventory total: {total}', " + "work_evidence=['artifact:inventory.json'], validation_evidence=['check:inventory-total'])" + ) executable = write_python_host_fixture(binaries / "codex", source.read_text(encoding="utf-8").replace( "result.update(json.loads(os.environ.get(\"FAKE_CODEX_RESULT_FIELDS\", \"{}\")))", - f"assert {objective!r} in prompt\n" - "assert args[args.index('--sandbox') + 1] == 'read-only'\n" - "total = sum(json.loads(pathlib.Path('inventory.json').read_text()))\n" - "result.update(result_kind='validated_completion', summary=f'Inventory total: {total}', " - "work_evidence=['artifact:inventory.json'], validation_evidence=['check:inventory-total'])", + "\n".join(behavior), )) + if write: + for scope in (".loopx/runtime", ".", "../outside", "two words"): + denied = json.loads(_run(core_python, [*command[:-1], scope], tmp_path, + environment=environment, expected=1).stdout) + assert "--write-dir must" in denied["error"] + scoped_runtime = list(command) + scoped_runtime[1] = str(project / "reports/runtime") + denied = json.loads(_run(core_python, scoped_runtime, tmp_path, environment=environment, expected=1).stdout) + assert "separate from the goal and runtime state" in denied["error"] + (project / "reports").mkdir() + mutable = write_python_host_fixture(project / "reports/checker", "raise SystemExit(0)\n") + scoped_checker = list(command) + scoped_checker[scoped_checker.index("--validation-command-json") + 1] = json.dumps([str(mutable)]) + denied = json.loads(_run(core_python, scoped_checker, tmp_path, environment=environment, expected=1).stdout) + assert "Keep the independent checker outside" in denied["error"] + mutable.unlink() + mutable.with_suffix(".py").unlink(missing_ok=True) + (project / "reports").rmdir() + assert not (project / ".loopx").exists() and not log.exists() # Stop after the native result is durable and before the independent check. interrupted = os.name == "posix" if interrupted: @@ -857,8 +898,11 @@ def interrupt_validator(*args, **kwargs): assert replay["replayed"] and replay["resume_turn_key"] == first["resume_turn_key"] assert replay["todo_id"] == first["todo_id"] and not any(replay["effects"].values()) different = list(command) - different[different.index("--host") + 1] = "generic-cli" - different += ["--host-adapter-command-json", json.dumps([core_python])] + if write: + different[-1] = "different-report" + else: + different[different.index("--host") + 1] = "generic-cli" + different += ["--host-adapter-command-json", json.dumps([core_python])] denied = json.loads(_run(core_python, different, tmp_path, environment=environment, expected=1).stdout) assert "already connected" in denied["error"] and registry.read_bytes() == registry_bytes assert len(log.read_text().splitlines()) == 1 From d4eccdbd590f9c620840db3bd9ae4ef9d378c752 Mon Sep 17 00:00:00 2001 From: cicolord Date: Thu, 19 Nov 2026 09:53:20 +0800 Subject: [PATCH 6/7] Check the selected write directory in the shared Turn reader Signed-off-by: cicolord --- loopx/control_plane/quota/turn_envelope.py | 4 +++ loopx/control_plane/quota/turn_envelope.ts | 7 +++++ loopx/control_plane/turn_driver/codex_cli.py | 33 ++++++++++++-------- tests/control_plane_ts/turn_envelope.test.ts | 18 +++++++++++ 4 files changed, 49 insertions(+), 13 deletions(-) diff --git a/loopx/control_plane/quota/turn_envelope.py b/loopx/control_plane/quota/turn_envelope.py index 7807ffa16e..f65fed8b97 100644 --- a/loopx/control_plane/quota/turn_envelope.py +++ b/loopx/control_plane/quota/turn_envelope.py @@ -186,10 +186,13 @@ def complete_turn_host_source( include_session_lineage: bool = False, include_model_context: bool = False, recorded_capability_result: bool = False, + required_write_scope: str | None = None, ) -> dict[str, Any] | None: if "schema_version" in request: assert_turn_host_request_version(request) if "work_contract" not in request: + if required_write_scope is not None: + raise ValueError("A Codex write directory requires the complete admitted work source.") return None wire = {} if request.get("schema_version") == COMPLETE_TURN_HOST_REQUEST_SCHEMA: @@ -200,6 +203,7 @@ def complete_turn_host_source( # An explicit historical adapter still requires full validation. wire["envelope"] = _wire_mapping(request.get("turn_envelope")) checked = _turn_envelope_result(operation, payload=request["work_contract"], **wire, + **({"required_write_scope": required_write_scope} if required_write_scope is not None else {}), **({"recorded_capability_result": True} if recorded_capability_result else {}), **({"include_model_context": True} if include_model_context else {}), **({"include_session_lineage": True} if include_session_lineage else {})) diff --git a/loopx/control_plane/quota/turn_envelope.ts b/loopx/control_plane/quota/turn_envelope.ts index ea50115021..616accecf8 100644 --- a/loopx/control_plane/quota/turn_envelope.ts +++ b/loopx/control_plane/quota/turn_envelope.ts @@ -2651,6 +2651,13 @@ export function evaluateTurnEnvelope(value: unknown): JsonObject { // need the historical executor projection to prove agreement with them. const legacy = Object.hasOwn(request, "complete_host_request") ? null : completeHostSource(request); const decision = legacy?.decision ?? completeHostDecision(request); + if (Object.hasOwn(request, "required_write_scope")) { + const scope = [requireNonEmptyString(request.required_write_scope, "required Host write scope")]; + if (!isDeepStrictEqual(object(decision.goal_boundary).write_scope, scope) || + !isDeepStrictEqual(object(decision.selected_todo).required_write_scopes, scope)) { + throw new EffectRuntimeRequestError("Codex write directory must match the admitted task and goal scope."); + } + } const {primaryAction, replanPacket} = legacy ? {primaryAction: object(legacy.projection.action).primary_action ?? null, replanPacket: legacy.projection.replan_action_packet ?? null} diff --git a/loopx/control_plane/turn_driver/codex_cli.py b/loopx/control_plane/turn_driver/codex_cli.py index 02dafafc19..4c1021651a 100644 --- a/loopx/control_plane/turn_driver/codex_cli.py +++ b/loopx/control_plane/turn_driver/codex_cli.py @@ -358,6 +358,7 @@ def _prompt(request: Mapping[str, Any]) -> str: def _checked_prompt_context( request: Mapping[str, Any], *, include_session_lineage: bool = False, + required_write_scope: str | None = None, ) -> dict[str, Any] | None: from ..quota.turn_envelope import assert_turn_envelope_consumer_version @@ -369,7 +370,7 @@ def _checked_prompt_context( try: checked = complete_turn_host_source(request, operation="host_dispatch_context", include_session_lineage=include_session_lineage, - include_model_context=True) + include_model_context=True, required_write_scope=required_write_scope) except RuntimeError: # Preserve the historical diagnostic precedence for doubly malformed # input without imposing a second bridge call on valid requests. @@ -379,7 +380,9 @@ def _checked_prompt_context( return checked -def prepare_codex_cli_input(request: Mapping[str, Any]) -> tuple[str, dict[str, Any]]: +def prepare_codex_cli_input( + request: Mapping[str, Any], *, required_write_scope: str | None = None, +) -> tuple[str, dict[str, Any]]: """Prepare one launch's prompt and schema from one complete-source check. This value never crosses an attempt/result boundary or enters a cache. @@ -387,7 +390,7 @@ def prepare_codex_cli_input(request: Mapping[str, Any]) -> tuple[str, dict[str, their existing prompt/schema readers. Launch and result authority stay with the original Host and outer executor. """ - checked = _checked_prompt_context(request) + checked = _checked_prompt_context(request, required_write_scope=required_write_scope) if checked is None: return _prompt(request), codex_cli_result_schema(request) return _render_prompt(request, checked=checked), _result_schema(request, checked=checked) @@ -805,6 +808,15 @@ def codex_project_write_scope(project: Path, directory: Path, runtime_root: Path return directory, scope +def _codex_write_launch_options( + project: Path, runtime_root: Path, directory: Path | None, sandbox: str, +) -> tuple[Path | None, str, dict[str, str]]: + if directory is None: + return None, sandbox, {} + directory, scope = codex_project_write_scope(project, directory, runtime_root) + return directory, f"directory:{directory}", {"required_write_scope": scope} + + def _codex_command( *, codex_bin: str, @@ -926,14 +938,9 @@ def run_codex_cli_host( resolved = shutil.which(codex_bin) if os.path.sep not in codex_bin else codex_bin if not resolved or not Path(resolved).exists(): raise ValueError("Codex CLI executable is unavailable") - session_sandbox = sandbox - if write_directory is not None: - write_directory, scope = codex_project_write_scope(project, write_directory, runtime_root) - work = _mapping(request.get("work_contract")) - if (_mapping(work.get("goal_boundary")).get("write_scope") != [scope] - or _mapping(work.get("selected_todo")).get("required_write_scopes") != [scope]): - raise ValueError("Codex write directory must match the admitted task and goal scope.") - session_sandbox = f"directory:{write_directory}" + write_directory, session_sandbox, write_context = _codex_write_launch_options( + project, runtime_root, write_directory, sandbox, + ) lineage = _lineage(request) admission = goal_admission if admission is None and registry_path is not None: @@ -965,7 +972,7 @@ def run_codex_cli_host( ) if session_scope == "agent" else None) if binding and profile_digest: approved_write_resume = ( - write_directory is None and sandbox == "workspace-write" + session_sandbox == "workspace-write" and binding.get("session_profile_digest") == codex_session_profile_digest( project=project, codex_bin=str(resolved), home=Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser(), @@ -1034,7 +1041,7 @@ def commit() -> None: temporary = Path(directory) schema_path = temporary / "result-schema.json" output_path = temporary / "last-message.json" - input_text, result_schema = prepare_codex_cli_input(request) + input_text, result_schema = prepare_codex_cli_input(request, **write_context) schema_path.write_text( json.dumps( result_schema, diff --git a/tests/control_plane_ts/turn_envelope.test.ts b/tests/control_plane_ts/turn_envelope.test.ts index b60c8be8bd..2f5e04709b 100644 --- a/tests/control_plane_ts/turn_envelope.test.ts +++ b/tests/control_plane_ts/turn_envelope.test.ts @@ -212,6 +212,24 @@ test("operation preflight optionally shares the existing normalized session line assert.deepEqual(complete, before); }); +test("a native write directory agrees with both captured work scopes", () => { + const scope = "reports/**"; + const source = payload(); + (source.goal_boundary as JsonObject).write_scope = [scope]; + (source.selected_todo as JsonObject).required_write_scopes = [scope]; + const request = {operation: "host_dispatch_context", + complete_host_request: {schema_version: "loopx_turn_host_request_v1", turn_key: `sha256:${"a".repeat(64)}`}}; + const capture = () => evaluateTurnEnvelope({operation: "compose_complete", payload: source, scheduler_execution_args: ""}); + const complete = capture(); + assert.deepEqual(evaluateTurnEnvelope({...request, payload: complete, required_write_scope: scope}), + evaluateTurnEnvelope({...request, payload: complete})); + assert.throws(() => evaluateTurnEnvelope({...request, payload: complete, required_write_scope: "src/**"}), + /write directory must match the admitted task and goal scope/); + (source.selected_todo as JsonObject).required_write_scopes = []; + assert.throws(() => evaluateTurnEnvelope({...request, payload: capture(), required_write_scope: scope}), + /write directory must match the admitted task and goal scope/); +}); + test("Host task presentation is source-checked and keeps task and backlog facts", () => { const source = payload(); source.future_task_data = {instructions: "Preserve the final stop. ".repeat(200), value: -0}; From 770fe0473f955b537aac493e9cb755d5c4e2660f Mon Sep 17 00:00:00 2001 From: cicolord Date: Thu, 19 Nov 2026 10:24:44 +0800 Subject: [PATCH 7/7] Explain the missing Node prerequisite on first task start Signed-off-by: cicolord --- .../rfcs/monorepo-distribution-split-v0.md | 4 ++- .../monorepo-distribution-split-v0.zh-CN.md | 4 ++- loopx/cli_commands/start_goal.py | 33 ++++++++++++++----- packages/loopx-core/README.md | 10 ++++-- tests/test_core_distribution.py | 12 +++++++ 5 files changed, 49 insertions(+), 14 deletions(-) diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 40113f791b..c0268ef33a 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -342,7 +342,9 @@ Before first registration the native route looks for Codex on PATH. Adapter and check commands resolve from the task directory on POSIX and are checked for explicitly absolute paths on Windows. An unavailable program is reported before creating local Goal state or dispatching work, so the caller -can correct the launch configuration and retry. The entry uses the existing +can correct the launch configuration and retry. A cold launch with missing or +unsupported Node reports `node_unavailable` and directs the caller to repeat +the original command after runtime setup. The entry uses the existing Goal, Todo, lease and Turn owners and defaults to project-local runtime state. Registration records the original operation and storage target before the initial source is written. The identical request can supply a missing initial 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 ec6ef6edcb..92430865e2 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -235,7 +235,9 @@ stdio relay 在父进程 EOF、SIGTERM 或 SIGINT 时取消所持进程组,并 通用入口接受调用方批准的适配器。两条路径都使用调用方提供的独立检查,并沿原执行器恢复。 首次注册时会检查所选的 Codex 可执行文件。对于适配器和检查命令,POSIX 按任务工作目录 解析路径,Windows 检查显式的绝对路径。程序不可用时,在创建本地 Goal 状态或派发任务前提示调用方修正 -启动配置并重试。入口复用既有 Goal、Todo、租约和 Turn 的 owner,运行状态默认保存在项目内。 +启动配置并重试。冷启动遇到 Node 缺失或版本过低时返回 `node_unavailable`, +提示准备运行时后重试原命令。 +入口复用既有 Goal、Todo、租约和 Turn 的 owner,运行状态默认保存在项目内。 注册先记录原始操作和存储目标,再写入初始状态。 中断后,原请求可以在权威 owner 仍需要初始状态时补写缺失的文件,并续接原任务和 Turn。 原生入口的操作身份记录所选宿主及批准的目录,已有通用入口继续沿原身份恢复。 diff --git a/loopx/cli_commands/start_goal.py b/loopx/cli_commands/start_goal.py index 48d4370359..4736ca1a16 100644 --- a/loopx/cli_commands/start_goal.py +++ b/loopx/cli_commands/start_goal.py @@ -14,6 +14,7 @@ render_start_goal_guided_markdown, ) from ..control_plane.effect_runtime import ( + EffectRuntimeNodeProbeError, EffectRuntimeStartupError, MINIMUM_NODE_VERSION_TEXT, ) @@ -69,8 +70,13 @@ def _effect_runtime_startup_recommended_action( diagnostic_code: str, message: str, + *, + guided: bool, ) -> str: node_action = node_probe_remediation(diagnostic_code) + if not guided: + action = node_action or "Check the Node.js launcher on PATH, then run `loopx doctor --deep`." + return f"{action} Then repeat the original command." if node_action is not None: return f"{node_action} Then retry `loopx start-goal --guided`." if diagnostic_code == "invalid_idle_timeout": @@ -86,12 +92,13 @@ def _effect_runtime_startup_recommended_action( def _effect_runtime_startup_failure_payload( exc: EffectRuntimeStartupError, + *, + guided: bool = True, ) -> dict[str, object]: diagnostic_code = getattr(exc, "diagnostic_code", "runtime_startup_failed") - return { + payload: dict[str, object] = { "ok": False, - "schema_version": "loopx_start_goal_guided_v0", - "error": "LoopX TypeScript control-plane runtime is unavailable", + "error": "LoopX TypeScript control-plane runtime is unavailable" if guided else str(exc), "diagnostic_code": diagnostic_code, "runtime_requirement": { "runtime": "node", @@ -101,17 +108,22 @@ def _effect_runtime_startup_failure_payload( "recommended_action": _effect_runtime_startup_recommended_action( diagnostic_code, str(exc), + guided=guided, ), } + if guided: + payload["schema_version"] = "loopx_start_goal_guided_v0" + return payload -def _render_start_goal_markdown(payload: dict[str, object]) -> str: +def _render_start_goal_markdown(payload: dict[str, object], *, guided: bool = True) -> str: if payload.get("ok") is not False: message = payload.get("message") if isinstance(message, str): return message return render_start_goal_guided_markdown(payload) - lines = ["# Guided Start Goal", "", f"- error: `{payload.get('error')}`"] + heading = "# Guided Start Goal" if guided else "# Start Goal" + lines = [heading, "", f"- error: `{payload.get('error')}`"] for field in ( "error_code", "diagnostic_code", @@ -394,12 +406,15 @@ def handle_start_goal_command( try: payload = execute_managed_start(args, runtime_root_arg=runtime_root_arg, explicit_registry=explicit_registry) + except EffectRuntimeNodeProbeError as exc: + payload = _effect_runtime_startup_failure_payload(exc, guided=False) except (OSError, RuntimeError, ValueError) as exc: payload = {"ok": False, "error": str(exc)} - print_payload(payload, args.format, _render_start_goal_markdown) - return 1 - print_payload(payload, args.format, render_managed_start_markdown) - return 0 if payload["ok"] else 1 + else: + print_payload(payload, args.format, render_managed_start_markdown) + return 0 if payload["ok"] else 1 + print_payload(payload, args.format, lambda failure: _render_start_goal_markdown(failure, guided=False)) + return 1 if any(getattr(args, name, None) is not None for name in ( "execution_host", "host_adapter_command_json", "validation_command_json", "write_dir", )): diff --git a/packages/loopx-core/README.md b/packages/loopx-core/README.md index 2fa84be756..22abd88b24 100644 --- a/packages/loopx-core/README.md +++ b/packages/loopx-core/README.md @@ -58,9 +58,13 @@ registration. It continues the saved attempt or returns the checked result. The `--guided` route remains available for an existing project or an interactive host. -Python 3.11+ is required. Import and help do not need Node. Executing governed -tasks requires a qualified Node runtime (22.22.3+ and the existing SQLite -reliability checks), an explicitly selected host and its own prerequisites. +Python 3.11+ is required. Import and help work before Node is installed. +A fresh `status` read and governed tasks use the TypeScript runtime. On a cold +start with missing or unsupported Node, the first task reports +`node_unavailable` before creating Goal state. Install or activate Node.js +22.22.3+ on PATH, run `loopx doctor --deep`, and repeat the same start command. +Execution also requires the existing SQLite reliability checks and the selected +host's 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. Start with one natural-language goal in your existing model host: diff --git a/tests/test_core_distribution.py b/tests/test_core_distribution.py index 373cd05920..7303d16006 100644 --- a/tests/test_core_distribution.py +++ b/tests/test_core_distribution.py @@ -747,6 +747,18 @@ def test_installed_core_starts_one_checked_task_from_goal_text(core_python, tmp_ "--goal-text", objective, "--execute", "--host-adapter-command-json", json.dumps([core_python, "-I", "-c", adapter]), "--validation-command-json", json.dumps([core_python, "-I", "-c", VALIDATOR_SOURCE])] + empty_path = tmp_path / "no-node" + empty_path.mkdir() + environment = {"PATH": str(empty_path)} + refused = json.loads(_run(core_python, arguments, tmp_path, environment=environment, expected=1).stdout) + assert refused["ok"] is False and refused["diagnostic_code"] == "node_unavailable" + assert refused["runtime_requirement"]["runtime"] == "node" + assert "Node.js" in refused["recommended_action"] and "original command" in refused["recommended_action"] + markdown = _run(core_python, ["--format", "markdown", *arguments[2:]], + tmp_path, environment=environment, expected=1).stdout + assert "Install or activate Node.js" in markdown and "repeat the original command" in markdown + assert not list(project.iterdir()) + first = json.loads(_run(core_python, arguments, tmp_path).stdout) assert first["status"] == "committed" and first["validation"]["status"] == "passed" assert first["goal_id"] == "first-work-goal" and first["agent_id"] == "local-worker"