chore: import upstream snapshot with attribution

integrations/coding_agent/__init__.py

@@ -0,0 +1,28 @@
+"""Agent-neutral coding-agent seam.
+
+Callers depend on this interface — a :class:`CodingResult`, a
+:func:`run_coding_task` entry point, and :func:`verify_coding_agent` readiness —
+rather than on a specific agent. Pi is the only wired backend today; others plug in
+behind the same interface (see :mod:`integrations.coding_agent.runner`).
+"""
+
+from __future__ import annotations
+
+from integrations.coding_agent.config import (
+    coding_agent_provider,
+    coding_model,
+    coding_timeout_seconds,
+    coding_workspace,
+)
+from integrations.coding_agent.models import CodingResult
+from integrations.coding_agent.runner import run_coding_task, verify_coding_agent
+
+__all__ = [
+    "CodingResult",
+    "coding_agent_provider",
+    "coding_model",
+    "coding_timeout_seconds",
+    "coding_workspace",
+    "run_coding_task",
+    "verify_coding_agent",
+]

integrations/coding_agent/config.py

@@ -0,0 +1,53 @@
+"""Agent-neutral configuration for the coding-agent seam.
+
+Neutral ``CODING_*`` settings with backward-compatible ``PI_CODING_*`` fallbacks,
+so the coding backend can be selected/tuned without the tool layer hard-coding a
+specific agent.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from integrations.llm_cli.timeout_utils import resolve_timeout_from_env
+
+_DEFAULT_PROVIDER = "pi"
+_DEFAULT_TIMEOUT_SEC = 600.0
+_MIN_TIMEOUT_SEC = 60.0
+_MAX_TIMEOUT_SEC = 1800.0
+
+
+def coding_agent_provider(env: Mapping[str, str] | None = None) -> str:
+    """Which coding-agent backend to use (``CODING_AGENT``; defaults to ``pi``)."""
+    source = env if env is not None else os.environ
+    return (source.get("CODING_AGENT") or _DEFAULT_PROVIDER).strip().lower() or _DEFAULT_PROVIDER
+
+
+def coding_model(env: Mapping[str, str] | None = None) -> str | None:
+    """Model override for the coding agent (``CODING_MODEL``, else ``PI_CODING_MODEL``)."""
+    source = env if env is not None else os.environ
+    return (source.get("CODING_MODEL") or source.get("PI_CODING_MODEL") or "").strip() or None
+
+
+def coding_workspace(env: Mapping[str, str] | None = None) -> str:
+    """Workspace the agent edits (``CODING_WORKSPACE``, else ``PI_CODING_WORKSPACE``, else cwd)."""
+    source = env if env is not None else os.environ
+    return (
+        source.get("CODING_WORKSPACE") or source.get("PI_CODING_WORKSPACE") or ""
+    ).strip() or os.getcwd()
+
+
+def coding_timeout_seconds() -> float:
+    """Per-run timeout (``CODING_TIMEOUT_SECONDS``, else ``PI_CODING_TIMEOUT_SECONDS``)."""
+    env_key = (
+        "CODING_TIMEOUT_SECONDS"
+        if os.environ.get("CODING_TIMEOUT_SECONDS")
+        else "PI_CODING_TIMEOUT_SECONDS"
+    )
+    return resolve_timeout_from_env(
+        env_key=env_key,
+        default=_DEFAULT_TIMEOUT_SEC,
+        minimum=_MIN_TIMEOUT_SEC,
+        maximum=_MAX_TIMEOUT_SEC,
+    )

integrations/coding_agent/models.py

@@ -0,0 +1,23 @@
+"""Agent-neutral result of a coding-agent run over a workspace."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class CodingResult:
+    """Outcome of running a coding agent against a workspace.
+
+    Backend-agnostic: whatever agent produced it (Pi today; others later), callers
+    read the same shape — a summary, the files it changed, and the git diff.
+    """
+
+    success: bool
+    summary: str
+    changed_files: list[str] = field(default_factory=list)
+    diff: str = ""
+    diff_truncated: bool = False
+    returncode: int = 0
+    timed_out: bool = False
+    error: str | None = None

integrations/coding_agent/pi_backend.py

@@ -0,0 +1,29 @@
+"""Pi coding-agent backend — the one place the seam is coupled to Pi.
+
+Adapts ``integrations/pi`` to the neutral :class:`CodingResult`. Adding another
+backend (codex/claude_code/…) later means adding a sibling module and registering
+it in :mod:`integrations.coding_agent.runner`, with no change to callers.
+"""
+
+from __future__ import annotations
+
+from integrations.coding_agent.models import CodingResult
+from integrations.pi import run_pi_coding_task, verify_pi_coding
+
+
+def run(task: str, *, workspace: str, model: str | None, timeout_sec: float) -> CodingResult:
+    result = run_pi_coding_task(task, workspace=workspace, model=model, timeout_sec=timeout_sec)
+    return CodingResult(
+        success=result.success,
+        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 verify() -> tuple[bool, str]:
+    return verify_pi_coding()

integrations/coding_agent/runner.py

@@ -0,0 +1,54 @@
+"""Provider-agnostic entry point for running a coding agent over a workspace.
+
+Resolves the configured backend (``CODING_AGENT``, default ``pi``) and dispatches
+to it. Today only ``pi`` is wired; new backends register in ``_BACKENDS`` and every
+caller keeps using :func:`run_coding_task` / :func:`verify_coding_agent` unchanged.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from integrations.coding_agent.config import coding_agent_provider
+from integrations.coding_agent.models import CodingResult
+from integrations.coding_agent.pi_backend import run as _pi_run
+from integrations.coding_agent.pi_backend import verify as _pi_verify
+
+_RunFn = Callable[..., CodingResult]
+_VerifyFn = Callable[[], tuple[bool, str]]
+
+# provider name -> (run, verify)
+_BACKENDS: dict[str, tuple[_RunFn, _VerifyFn]] = {
+    "pi": (_pi_run, _pi_verify),
+}
+
+
+def _resolve(provider: str | None) -> tuple[str, tuple[_RunFn, _VerifyFn] | None]:
+    name = (provider or coding_agent_provider()).strip().lower()
+    return name, _BACKENDS.get(name)
+
+
+def verify_coding_agent(provider: str | None = None) -> tuple[bool, str]:
+    """Whether the configured coding agent is installed/ready (never raises)."""
+    name, backend = _resolve(provider)
+    if backend is None:
+        supported = ", ".join(sorted(_BACKENDS))
+        return False, f"Unsupported coding agent '{name}'. Set CODING_AGENT to one of: {supported}."
+    _run, verify = backend
+    return verify()
+
+
+def run_coding_task(
+    task: str,
+    *,
+    workspace: str,
+    model: str | None,
+    timeout_sec: float,
+    provider: str | None = None,
+) -> CodingResult:
+    """Run the configured coding agent on *task* in *workspace*."""
+    name, backend = _resolve(provider)
+    if backend is None:
+        return CodingResult(success=False, summary="", error=f"Unsupported coding agent '{name}'.")
+    run, _verify = backend
+    return run(task, workspace=workspace, model=model, timeout_sec=timeout_sec)