fix(onboarding): qualify custom agent skill delivery (#2527)

Preserve strict Codex skill diagnostics while making custom-agent skill delivery host-owned, required for workflow readiness, and readback-verifiable.

Author: huangruiteng

examples/control_plane/agent-onboard-host-loop-activation-smoke.py

@@ -29,13 +29,18 @@
 )
 
 
-def run_cli(*args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+def run_cli(
+    *args: str,
+    check: bool = True,
+    env: dict[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
     return subprocess.run(
         [sys.executable, "-m", "loopx.cli", "--format", "json", *args],
         cwd=REPO_ROOT,
         check=check,
         text=True,
         capture_output=True,
+        env=env,
     )
 
 
@@ -301,6 +306,71 @@ def main() -> int:
             "loopx_goal_activate"
         )
 
+        other_agent_onboarding = build_agent_onboarding_packet(
+            project=project,
+            agent_type="other-agent",
+            goal_id="multi-agent-goal",
+            agent_id="codex-product-capability",
+            cli_bin=cli_bin,
+        )
+        other_commands = other_agent_onboarding["commands"]
+        assert "install_command_facade" not in other_commands
+        assert "doctor --agent-type other-agent" in other_commands["doctor_or_install"]
+        delivery = other_agent_onboarding["skill_delivery"]
+        assert delivery["mode"] == "host_managed", delivery
+        assert delivery["owner"] == "custom_agent_host", delivery
+        assert delivery["status"] == "pending_host_readback", delivery
+        assert delivery["codex_skills_root_required"] is False, delivery
+        assert delivery["required_for_cli_health"] is False, delivery
+        assert delivery["required_for_loopx_workflow"] is True, delivery
+        assert set(delivery["required_skill_ids"]) == {
+            "loopx-project",
+            "loopx-pr-review",
+            "loopx-doc-registry",
+            "loopx-self-repair",
+        }, delivery
+        assert delivery["delivery_options"] == [
+            "host_skill_manifest",
+            "prompt_injection",
+        ], delivery
+        assert delivery["source_directories"] == [
+            f"skills/{skill_id}" for skill_id in delivery["required_skill_ids"]
+        ], delivery
+        assert delivery["host_readback_required"] is True, delivery
+        assert set(delivery["readback_fields"]) == {
+            "integration_mode",
+            "loaded_skill_ids",
+            "source_revision",
+        }, delivery
+        assert any(
+            "loaded-skill readback" in item
+            for item in other_agent_onboarding["slash_command_contract"][
+                "setup_complete_requires"
+            ]
+        ), other_agent_onboarding
+
+        doctor_home = root / "doctor-home"
+        doctor_home.mkdir()
+        doctor_env = {
+            **os.environ,
+            "HOME": str(doctor_home),
+            "PATH": f"{REPO_ROOT / 'scripts'}{os.pathsep}{os.environ.get('PATH', '')}",
+        }
+        other_agent_doctor = json.loads(
+            run_cli(
+                "doctor",
+                "--agent-type",
+                "other-agent",
+                env=doctor_env,
+            ).stdout
+        )
+        assert other_agent_doctor["install_freshness"]["requires_upgrade"] is False
+        assert other_agent_doctor["skill_delivery"]["mode"] == "host_managed"
+        for check in other_agent_doctor["checks"]:
+            if str(check.get("id", "")).startswith("installed_"):
+                assert check["ok"] is True, check
+                assert check["applicable"] is False, check
+
     return 0
 
 

loopx/agent_onboarding.py

@@ -20,6 +20,13 @@
 
 
 SCHEMA_VERSION = "loopx_agent_onboarding_v0"
+HOST_SKILL_DELIVERY_SCHEMA_VERSION = "loopx_host_skill_delivery_v0"
+REQUIRED_HOST_SKILL_IDS = [
+    "loopx-project",
+    "loopx-pr-review",
+    "loopx-doc-registry",
+    "loopx-self-repair",
+]
 
 
 def _surface_install_command(agent_type: str, cli_bin: str) -> str | None:
@@ -35,6 +42,52 @@ def _surface_install_command(agent_type: str, cli_bin: str) -> str | None:
     return None
 
 
+def _skill_delivery_contract(agent_type: str) -> dict[str, Any]:
+    if agent_type != "other-agent":
+        return {
+            "schema_version": HOST_SKILL_DELIVERY_SCHEMA_VERSION,
+            "mode": "surface_managed",
+            "owner": "loopx_surface_installer",
+            "codex_skills_root_required": agent_type.startswith("codex-"),
+            "host_readback_required": False,
+        }
+    return {
+        "schema_version": HOST_SKILL_DELIVERY_SCHEMA_VERSION,
+        "mode": "host_managed",
+        "owner": "custom_agent_host",
+        "status": "pending_host_readback",
+        "codex_skills_root_required": False,
+        "required_for_cli_health": False,
+        "required_for_loopx_workflow": True,
+        "required_skill_ids": REQUIRED_HOST_SKILL_IDS,
+        "delivery_options": [
+            "host_skill_manifest",
+            "prompt_injection",
+        ],
+        "source_repository": "https://github.com/huangruiteng/loopx",
+        "source_directories": [
+            f"skills/{skill_id}" for skill_id in REQUIRED_HOST_SKILL_IDS
+        ],
+        "source_contract": (
+            "Use the same LoopX release or repository revision as the CLI when "
+            "materializing skills or injecting equivalent SKILL.md instructions "
+            "through the custom host."
+        ),
+        "host_readback_required": True,
+        "readback_fields": [
+            "integration_mode",
+            "loaded_skill_ids",
+            "source_revision",
+        ],
+        "success_criteria": [
+            "the host reports which integration mode it selected",
+            "the host reports every required LoopX skill id as loaded",
+            "the host reports the source revision or digest used for delivery",
+            "no Codex-specific skill directory is assumed",
+        ],
+    }
+
+
 def _bootstrap_pack_command(
     *,
     project: str,
@@ -86,7 +139,11 @@ def _start_instruction(agent_type: str) -> str:
         return "Run `/loopx <task>`; after todo writeback, call `loopx_goal_activate` with the generated heartbeat task body."
     if agent_type == "manual":
         return "Use the CLI packet and wire an external scheduler, or run quota/status/todo commands manually."
-    return "Use the host's explicit LoopX command facade such as `@loopx <task>` or `$loopx <task>`, then wire its scheduler through this packet."
+    return (
+        "Deliver the required LoopX skills through the custom host and verify its "
+        "loaded-skill readback; then use the host's explicit LoopX command facade "
+        "and wire its scheduler through this packet."
+    )
 
 
 def build_agent_onboarding_packet(
@@ -132,7 +189,10 @@ def build_agent_onboarding_packet(
         available_capabilities=normalized_available_capabilities,
     )
     commands: dict[str, Any] = {
-        "doctor_or_install": render_codex_cli_no_clone_preflight(cli_bin=cli_bin),
+        "doctor_or_install": render_codex_cli_no_clone_preflight(
+            cli_bin=cli_bin,
+            doctor_agent_type=canonical_agent_type,
+        ),
         "bootstrap_command_pack": bootstrap_pack_command,
         "quota_guard": (
             render_quota_guard_command(
@@ -184,6 +244,7 @@ def build_agent_onboarding_packet(
         "task_text": task_text,
         "project_connection": inspection,
         "host_loop_activation": host_loop_activation,
+        "skill_delivery": _skill_delivery_contract(canonical_agent_type),
         "recommended_start": (
             "Select one registered agent lane from identity_selection_gate, then rerun onboarding."
             if not activation_allowed
@@ -207,6 +268,13 @@ def build_agent_onboarding_packet(
             "setup_complete_requires": [
                 "project-local LoopX state exists or was intentionally previewed",
                 "ordered todos are written when task text was supplied",
+                *(
+                    [
+                        "custom host loaded-skill readback satisfies skill_delivery.success_criteria"
+                    ]
+                    if canonical_agent_type == "other-agent"
+                    else []
+                ),
                 "host_loop_activation success criteria are satisfied or a concrete gate is reported",
             ],
         },
@@ -230,6 +298,11 @@ def render_agent_onboarding_markdown(payload: dict[str, Any]) -> str:
     )
     identity_gate = payload.get("identity_selection_gate")
     identity_gate = identity_gate if isinstance(identity_gate, dict) else {}
+    skill_delivery = (
+        payload.get("skill_delivery")
+        if isinstance(payload.get("skill_delivery"), dict)
+        else {}
+    )
     lines = [
         "# LoopX Agent Onboarding",
         "",
@@ -247,6 +320,24 @@ def render_agent_onboarding_markdown(payload: dict[str, Any]) -> str:
     ]
     if commands.get("install_command_facade"):
         lines.extend(["", "```bash", str(commands.get("install_command_facade")), "```"])
+    if skill_delivery.get("mode") == "host_managed":
+        lines.extend(
+            [
+                "",
+                "## Host-Managed Skill Delivery",
+                "",
+                f"- owner: `{skill_delivery.get('owner')}`",
+                f"- required_for_cli_health: `{skill_delivery.get('required_for_cli_health')}`",
+                f"- required_for_loopx_workflow: `{skill_delivery.get('required_for_loopx_workflow')}`",
+                f"- delivery_options: `{','.join(skill_delivery.get('delivery_options') or [])}`",
+                f"- required_skill_ids: `{','.join(skill_delivery.get('required_skill_ids') or [])}`",
+                f"- source_repository: `{skill_delivery.get('source_repository')}`",
+                f"- source_directories: `{','.join(skill_delivery.get('source_directories') or [])}`",
+                f"- host_readback_required: `{skill_delivery.get('host_readback_required')}`",
+                f"- readback_fields: `{','.join(skill_delivery.get('readback_fields') or [])}`",
+                f"- source_contract: {skill_delivery.get('source_contract')}",
+            ]
+        )
     lines.extend(["", "```bash", str(commands.get("bootstrap_command_pack") or ""), "```"])
     if commands.get("codex_cli_bootstrap_message"):
         lines.extend(["", "```bash", str(commands.get("codex_cli_bootstrap_message")), "```"])

loopx/cli_commands/doctor.py

@@ -4,6 +4,7 @@
 from collections.abc import Callable
 
 from ..doctor import collect_doctor, render_doctor_markdown
+from ..host_loop_activation import SUPPORTED_AGENT_TYPES
 
 
 PrintPayload = Callable[
@@ -22,10 +23,21 @@ def register_doctor_command(subparsers: argparse._SubParsersAction) -> argparse.
         action="store_true",
         help="Run slower representative release-candidate checks.",
     )
+    parser.add_argument(
+        "--agent-type",
+        choices=SUPPORTED_AGENT_TYPES,
+        help=(
+            "Evaluate host-specific integration checks. For other-agent, custom-host "
+            "skill delivery replaces the Codex skill-directory check."
+        ),
+    )
     return parser
 
 
 def handle_doctor_command(args: argparse.Namespace, print_payload: PrintPayload) -> int:
-    payload = collect_doctor(deep=bool(args.deep))
+    payload = collect_doctor(
+        deep=bool(args.deep),
+        agent_type=args.agent_type,
+    )
     print_payload(payload, args.format, render_doctor_markdown)
     return 0 if payload.get("ok") else 1