chore: import upstream snapshot with attribution

tools/pi_coding_tool/runner.py

@@ -0,0 +1,80 @@
+"""Lifecycle and execution orchestration for the Pi coding tool.
+
+These are the stages ``PiCodingTool.run`` drives, kept as small free functions so
+the tool class stays a thin agent-facing contract:
+
+- :func:`ensure_enabled`    — opt-in gate (``PI_CODING_ENABLED``).
+- :func:`ensure_cli_ready`  — Pi binary installed and authenticated.
+- :func:`execute`           — run the polled Pi process (``integrations/pi`` client).
+- :func:`to_output`         — shape a stable result dict (with ``error_kind``).
+- :func:`error_output`      — the same dict shape for an early/expected failure.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+from integrations.pi import (
+    PiCodingResult,
+    is_pi_coding_enabled,
+    run_pi_coding_task,
+    verify_pi_coding,
+)
+from tools.pi_coding_tool.errors import (
+    ERR_CLI_UNAVAILABLE,
+    ERR_DISABLED,
+    ERR_EXECUTION,
+    ERR_TIMEOUT,
+    PiCodingError,
+)
+from tools.pi_coding_tool.validation import ResolvedRequest
+
+#: Evidence source tag stamped on every result dict.
+SOURCE: Final = "knowledge"
+
+_DISABLED_MESSAGE = (
+    "Pi coding tool is disabled. Set PI_CODING_ENABLED=1 (and install/authenticate "
+    "the Pi CLI) to enable it."
+)
+
+
+def ensure_enabled() -> None:
+    if not is_pi_coding_enabled():
+        raise PiCodingError(ERR_DISABLED, _DISABLED_MESSAGE)
+
+
+def ensure_cli_ready() -> None:
+    available, detail = verify_pi_coding()
+    if not available:
+        raise PiCodingError(ERR_CLI_UNAVAILABLE, f"Pi CLI is not ready: {detail}")
+
+
+def execute(request: ResolvedRequest) -> PiCodingResult:
+    return run_pi_coding_task(
+        request.task,
+        workspace=request.workspace,
+        model=request.model,
+        timeout_sec=request.timeout_sec,
+    )
+
+
+def to_output(result: PiCodingResult) -> dict[str, Any]:
+    error_kind: str | None = None
+    if not result.success:
+        error_kind = ERR_TIMEOUT if result.timed_out else ERR_EXECUTION
+    return {
+        "source": SOURCE,
+        "success": result.success,
+        "error_kind": error_kind,
+        "summary": result.summary,
+        "changed_files": result.changed_files,
+        "diff": result.diff,
+        "diff_truncated": result.diff_truncated,
+        "returncode": result.returncode,
+        "timed_out": result.timed_out,
+        "error": result.error,
+    }
+
+
+def error_output(kind: str, message: str) -> dict[str, Any]:
+    return {"source": SOURCE, "success": False, "error_kind": kind, "error": message}