pantheon-opencode 1.5.0-beta.1 → 1.5.0-beta.11

package/src/mcp/code_mode_server.py

@@ -16,6 +16,8 @@ Or via MCP client (stdio transport):
 from __future__ import annotations
 
 import asyncio
+import hashlib
+import json
 import logging
 import os
 import shutil
@@ -38,21 +40,47 @@ SCRIPT_TIMEOUT: int = 30
 # executor for longer than 5 minutes.
 MAX_SCRIPT_TIMEOUT: int = 300
 
+# ── Common status contract ────────────────────────────────────────────────────
+# Mirrors the nine-code `NativeTaskStatus` contract introduced in B3-05. Every
+# code-mode result is labelled with one of these statuses so callers can apply
+# the same retry/skip/escalate strategy across the whole platform.
+CONTRACT_STATUSES: frozenset[str] = frozenset(
+    {
+        "OK",
+        "UNSUPPORTED",
+        "UNAVAILABLE",
+        "INVALID_INPUT",
+        "INVALID_STATE",
+        "CONFLICT",
+        "CORRUPT_DATA",
+        "TIMEOUT",
+        "ESCALATE",
+    }
+)
+
+# Explicit installation mode: a script only runs when it is listed in this
+# manifest with a matching SHA-256. No manifest → nothing executes.
+MANIFEST_FILENAME: str = "manifest.json"
+MANIFEST_VERSION: int = 1
+_SHA256_HEX_LEN: int = 64
+
 # ── Env Allowlist ──────────────────────────────────────────────────────────────
 # Only these variables are passed to script subprocesses.  Everything else
 # (secrets, cloud credentials, etc.) is stripped to limit blast radius.
-_CODE_MODE_ENV_ALLOWLIST: frozenset[str] = frozenset({
-    "PATH",
-    "HOME",
-    "LANG",
-    "PANTHEON_HOME",
-    "PANTHEON_PROJECT",
-    "OPENAI_API_KEY",
-    "OPENAI_BASE_URL",
-    "EVAL_JUDGE_MODEL",
-    "SHELL",
-    "USER",
-})
+_CODE_MODE_ENV_ALLOWLIST: frozenset[str] = frozenset(
+    {
+        "PATH",
+        "HOME",
+        "LANG",
+        "PANTHEON_HOME",
+        "PANTHEON_PROJECT",
+        "OPENAI_API_KEY",
+        "OPENAI_BASE_URL",
+        "EVAL_JUDGE_MODEL",
+        "SHELL",
+        "USER",
+    }
+)
 
 # Optional extra vars that callers may opt-in to pass through.  Populate
 # this set at startup if needed (e.g. ``CODE_MODE_EXTRA_ENV.add("MY_VAR")``).
@@ -127,13 +155,54 @@ def _detect_prlimit() -> str | None:
         return None
     return shutil.which("prlimit")
 
+
 # ── Scripts Directory Resolution ─────────────────────────────────────────────
-# Priority:
-# 1. /.opencode/.pantheon/code-mode/  (project install)
-# 2. /.pantheon/code-mode/            (legacy fallback)
-# 3. /.pantheon/code-mode/               (global fallback)
-# 4. .pantheon/code-mode/ shipped inside the installed package (tarball
-#    fallback — package.json `files` includes .pantheon/code-mode/**)
+# Project directories are selected before global directories.  Once a usable
+# project directory is selected, manifest errors are deliberately fail-closed;
+# execution must never silently cross the project/global trust boundary.
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    """Return whether a resolved *path* is contained by a resolved *root*."""
+    try:
+        return os.path.commonpath((str(root), str(path))) == str(root)
+    except (OSError, ValueError):
+        return False
+
+
+def _has_usable_scripts(scripts_dir: Path) -> bool:
+    """Return whether *scripts_dir* contains an executable code-mode target.
+
+    A directory is only a valid resolver candidate when it contains a regular
+    ``.py`` or ``.sh`` file that can pass the same direct-child and path
+    containment rules used by script execution.  This prevents an empty
+    project overlay (or a directory containing only metadata) from masking a
+    lower-priority installation.
+    """
+    try:
+        if scripts_dir.is_symlink():
+            return False
+        resolved_dir = scripts_dir.resolve(strict=True)
+        if not resolved_dir.is_dir():
+            return False
+        for script_path in scripts_dir.iterdir():
+            if script_path.name.startswith("."):
+                continue
+            if script_path.suffix.lower() not in ALLOWED_EXTENSIONS:
+                continue
+            try:
+                resolved_script = script_path.resolve(strict=True)
+            except (OSError, RuntimeError):
+                continue
+            if (
+                resolved_script.is_file()
+                and resolved_script.parent == resolved_dir
+                and _is_within(resolved_script, resolved_dir)
+            ):
+                return True
+    except (OSError, RuntimeError):
+        return False
+    return False
 
 
 def _packaged_scripts_dir() -> Path | None:
@@ -144,39 +213,51 @@ def _packaged_scripts_dir() -> Path | None:
     Returns None when no packaged copy exists.
     """
     try:
-        here = Path(__file__).resolve()
-    except Exception:
+        here = Path(__file__).resolve(strict=True)
+    except (OSError, RuntimeError):
         return None
     for parent in [here.parent, *here.parents]:
         try:
             candidate = parent / ".pantheon" / "code-mode"
         except Exception:
             continue
-        try:
-            if candidate.is_dir():
-                return candidate
-        except OSError:
-            continue
+        if _has_usable_scripts(candidate):
+            return candidate
     return None
 
 
+def _resolve_scripts_dir(candidates: list[Path], *, allow_packaged: bool = True) -> Path | None:
+    """Select the first usable candidate, optionally trying the package copy."""
+    for candidate in candidates:
+        if _has_usable_scripts(candidate):
+            return candidate
+    return _packaged_scripts_dir() if allow_packaged else None
+
+
+def _resolve_code_mode_dir() -> Path:
+    """Resolve code-mode scripts project-first, with a global-only fallback.
+
+    A project directory is a trust boundary: if one is selected, callers use
+    its manifest even when that manifest is missing or corrupt.  Global users
+    retain the packaged/global fallback when no usable project directory is
+    available.
+    """
+    project = pantheon_project()
+    if project is not None:
+        project_candidates = [
+            project / ".opencode" / ".pantheon" / "code-mode",
+            project / ".pantheon" / "code-mode",
+        ]
+        selected = _resolve_scripts_dir(project_candidates, allow_packaged=False)
+        if selected is not None:
+            return selected
+
+    global_dir = pantheon_home() / ".pantheon" / "code-mode"
+    return _resolve_scripts_dir([global_dir]) or global_dir
+
+
 _PANTHEON_HOME: Path = pantheon_home()
-_SCRIPTS_DIR_CANDIDATES: list[Path] = []
-_proj = pantheon_project()
-if _proj is not None:
-    _SCRIPTS_DIR_CANDIDATES.append(_proj / ".opencode" / ".pantheon" / "code-mode")
-    _SCRIPTS_DIR_CANDIDATES.append(_proj / ".pantheon" / "code-mode")
-_SCRIPTS_DIR_CANDIDATES.append(_PANTHEON_HOME / ".pantheon" / "code-mode")
-
-SCRIPTS_DIR: Path = _PANTHEON_HOME / ".pantheon" / "code-mode"  # default
-for _candidate in _SCRIPTS_DIR_CANDIDATES:
-    if _candidate.is_dir():
-        SCRIPTS_DIR = _candidate
-        break
-else:
-    _packaged = _packaged_scripts_dir()
-    if _packaged is not None:
-        SCRIPTS_DIR = _packaged
+SCRIPTS_DIR: Path = _resolve_code_mode_dir()
 
 # ── FastMCP App ───────────────────────────────────────────────────────────────
 mcp = FastMCP(
@@ -188,12 +269,19 @@ mcp = FastMCP(
 # ── Helpers ───────────────────────────────────────────────────────────────────
 
 
-def _validate_script_name(script_name: str) -> Path:
+def _validate_script_name(script_name: str, scripts_dir: Path | None = None) -> Path:
     """Validate a script name and return its resolved path.
 
-    Raises ValueError if the name is invalid, traverses paths, or
-    has a disallowed extension.
+    Args:
+        script_name: Bare file name of a script in the code-mode directory.
+        scripts_dir: Directory to resolve against. Defaults to ``SCRIPTS_DIR``.
+
+    Raises:
+        ValueError: If the name is invalid, traverses paths, or has a
+            disallowed extension.
     """
+    scripts_dir = scripts_dir or SCRIPTS_DIR
+
     if not script_name:
         raise ValueError("Script name cannot be empty")
 
@@ -208,15 +296,238 @@ def _validate_script_name(script_name: str) -> Path:
         allowed = ", ".join(sorted(ALLOWED_EXTENSIONS))
         raise ValueError(f"Extension '{ext}' not allowed. Allowed: {allowed}")
 
-    script_path = (SCRIPTS_DIR / name).resolve()
-    if not str(script_path).startswith(str(SCRIPTS_DIR.resolve())):
+    if scripts_dir.is_symlink():
+        raise ValueError(f"Invalid script name: '{script_name}'")
+
+    try:
+        scripts_root = scripts_dir.resolve(strict=True)
+        script_path = (scripts_dir / name).resolve(strict=True)
+    except (FileNotFoundError, OSError, RuntimeError):
+        raise ValueError(f"Script '{script_name}' not found") from None
+
+    if (
+        not _is_within(script_path, scripts_root)
+        or script_path.parent != scripts_root
+        or not script_path.is_file()
+    ):
         raise ValueError(f"Invalid script name: '{script_name}'")
-    if not script_path.exists():
-        raise ValueError(f"Script '{script_name}' not found")
 
     return script_path
 
 
+# ── Installation Mode: Manifest + SHA-256 ─────────────────────────────────────
+# The manifest is the explicit opt-in. A script is executable only when its
+# bare name is present in `manifest.json` AND the SHA-256 of the on-disk file
+# matches the recorded digest. Any deviation fails closed with a contract
+# status instead of executing.
+
+
+class ManifestError(Exception):
+    """Raised when the code-mode manifest cannot authorise execution."""
+
+    def __init__(self, status: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+def _manifest_path(scripts_dir: Path | None = None) -> Path:
+    """Return the manifest path for *scripts_dir* (defaults to SCRIPTS_DIR)."""
+    return (scripts_dir or SCRIPTS_DIR) / MANIFEST_FILENAME
+
+
+def _sha256_file(path: Path) -> str:
+    """Return the hex SHA-256 digest of *path* (streamed, binary-safe)."""
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _load_manifest(scripts_dir: Path | None = None) -> dict[str, str]:
+    """Load and validate the manifest, returning ``{script_name: sha256}``.
+
+    Raises:
+        ManifestError: With ``INVALID_STATE`` when the manifest is absent (no
+            explicit opt-in), or ``CORRUPT_DATA`` when it is unreadable or
+            malformed.
+    """
+    manifest_file = _manifest_path(scripts_dir)
+    if not manifest_file.is_file():
+        raise ManifestError(
+            "INVALID_STATE",
+            f"Code-mode manifest not found at {manifest_file}. No script executes "
+            "without explicit opt-in — run approve_code_script first.",
+        )
+
+    try:
+        raw = manifest_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ManifestError(
+            "CORRUPT_DATA", f"Code-mode manifest unreadable: {exc}"
+        ) from None
+
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        raise ManifestError(
+            "CORRUPT_DATA",
+            f"Code-mode manifest is malformed JSON: {manifest_file}",
+        ) from None
+
+    if not isinstance(data, dict):
+        raise ManifestError(
+            "CORRUPT_DATA", "Code-mode manifest must be a JSON object."
+        )
+
+    if data.get("version") != 1:
+        raise ManifestError(
+            "CORRUPT_DATA", "Code-mode manifest malformed: version must be 1."
+        )
+
+    scripts = data.get("scripts")
+    if not isinstance(scripts, dict):
+        raise ManifestError(
+            "CORRUPT_DATA",
+            "Code-mode manifest is malformed: missing 'scripts' object.",
+        )
+
+    approved: dict[str, str] = {}
+    for name, digest in scripts.items():
+        if (
+            not isinstance(name, str)
+            or not isinstance(digest, str)
+            or len(digest) != _SHA256_HEX_LEN
+            or any(char not in "0123456789abcdefABCDEF" for char in digest)
+        ):
+            raise ManifestError(
+                "CORRUPT_DATA",
+                f"Code-mode manifest entry for '{name}' is malformed "
+                "(expected a 64-character SHA-256 hex digest).",
+            )
+        approved[name] = digest.lower()
+    return approved
+
+
+def _verify_approved(script_path: Path, scripts_dir: Path | None = None) -> None:
+    """Authorise *script_path* against the manifest.
+
+    Raises:
+        ManifestError: ``CONFLICT`` when the script is not listed and
+            ``CORRUPT_DATA`` when its hash does not match the recorded digest.
+    """
+    approved = _load_manifest(scripts_dir)
+    name = script_path.name
+    if name not in approved:
+        raise ManifestError(
+            "CONFLICT",
+            f"Script '{name}' is not approved in the code-mode manifest. "
+            "Run approve_code_script to opt in.",
+        )
+    actual = _sha256_file(script_path)
+    if actual != approved[name]:
+        raise ManifestError(
+            "CORRUPT_DATA",
+            f"Script '{name}' hash mismatch (expected {approved[name]}, got "
+            f"{actual}). Re-approve the script after verifying the change.",
+        )
+
+
+def _approve_script(
+    script_name: str, scripts_dir: Path | None = None
+) -> tuple[str, str]:
+    """Add or refresh *script_name* in the manifest with its SHA-256.
+
+    Returns:
+        A ``(status, message)`` tuple; the status is a contract code and is
+        ``OK`` on success.
+    """
+    target_dir = scripts_dir or SCRIPTS_DIR
+    try:
+        script_path = _validate_script_name(script_name, target_dir)
+    except ValueError as exc:
+        return "INVALID_INPUT", str(exc)
+
+    try:
+        approved = _load_manifest(target_dir)
+    except ManifestError as exc:
+        if exc.status == "INVALID_STATE":
+            approved = {}
+        else:
+            return exc.status, exc.message
+
+    approved[script_path.name] = _sha256_file(script_path)
+    payload = {
+        "version": MANIFEST_VERSION,
+        "scripts": dict(sorted(approved.items())),
+    }
+    try:
+        _manifest_path(target_dir).write_text(
+            json.dumps(payload, indent=2) + "\n", encoding="utf-8"
+        )
+    except OSError as exc:
+        return "UNAVAILABLE", f"Failed to write code-mode manifest: {exc}"
+
+    digest = approved[script_path.name]
+    return "OK", f"Approved '{script_path.name}' with SHA-256 {digest}"
+
+
+def _generate_manifest(scripts_dir: Path | None = None) -> int:
+    """Write a manifest covering every valid script in *scripts_dir*.
+
+    Used by the installer to (re)seed the explicit opt-in for bundled scripts.
+
+    Returns:
+        The number of scripts recorded.
+    """
+    target_dir = scripts_dir or SCRIPTS_DIR
+    try:
+        resolved_dir = target_dir.resolve(strict=True)
+    except (OSError, RuntimeError):
+        return 0
+
+    approved: dict[str, str] = {}
+    if resolved_dir.is_dir() and not resolved_dir.is_symlink():
+        for candidate in sorted(resolved_dir.iterdir()):
+            if candidate.name.startswith("."):
+                continue
+            if candidate.suffix.lower() not in ALLOWED_EXTENSIONS:
+                continue
+            try:
+                resolved = candidate.resolve(strict=True)
+            except (OSError, RuntimeError):
+                continue
+            if (
+                resolved.is_file()
+                and resolved.parent == resolved_dir
+                and _is_within(resolved, resolved_dir)
+            ):
+                approved[candidate.name] = _sha256_file(resolved)
+
+    payload = {
+        "version": MANIFEST_VERSION,
+        "scripts": dict(sorted(approved.items())),
+    }
+    try:
+        _manifest_path(target_dir).write_text(
+            json.dumps(payload, indent=2) + "\n", encoding="utf-8"
+        )
+    except OSError:
+        return 0
+    return len(approved)
+
+
+def _contract_result(
+    status: str, message: str, json_output: bool
+) -> str | dict[str, Any]:
+    """Build a contract-labelled error result (text or structured JSON)."""
+    if json_output:
+        return {"status": status, "error": message}
+    return f"[{status}] {message}"
+
+
+
 def _format_output(
     stdout: str,
     stderr: str,
@@ -286,7 +597,9 @@ def _parse_frontmatter(script_path: Path) -> dict[str, Any]:
             break
         if not stripped.startswith("#"):
             return {}  # non-comment line inside the block → not frontmatter
-        body_lines.append(stripped[1:].lstrip() if stripped.startswith("# ") else stripped[1:])
+        body_lines.append(
+            stripped[1:].lstrip() if stripped.startswith("# ") else stripped[1:]
+        )
     else:
         return {}  # no closing delimiter
 
@@ -338,10 +651,12 @@ def _build_result(
     metadata: dict[str, Any],
     json_output: bool,
     timeout_s: int,
+    status: str = "OK",
 ) -> str | dict[str, Any]:
     """Build the tool result in plain-text or structured JSON form."""
     if json_output:
         return {
+            "status": status,
             "stdout": stdout,
             "stderr": stderr,
             "exit_code": exit_code,
@@ -378,7 +693,9 @@ async def list_code_mode_scripts() -> str:
 
 @mcp.resource(
     "pantheon://code-mode/scripts/{script_name}",
-    description="Content of a code-mode script by name, with parsed frontmatter metadata",
+    description=(
+        "Content of a code-mode script by name, with parsed frontmatter metadata"
+    ),
 )
 async def get_code_mode_script(script_name: str) -> str:
     """Return the source content of a code-mode script plus its metadata."""
@@ -425,12 +742,17 @@ async def execute_code_script(
     try:
         script_path = _validate_script_name(script_name)
     except ValueError as e:
-        return str(e)
+        return _contract_result("INVALID_INPUT", str(e), json_output)
 
     metadata = _parse_frontmatter(script_path)
     denied = _validate_args(script_path, args)
     if denied is not None:
-        return denied
+        return _contract_result("INVALID_INPUT", denied, json_output)
+
+    try:
+        _verify_approved(script_path)
+    except ManifestError as e:
+        return _contract_result(e.status, e.message, json_output)
 
     timeout_s = _script_timeout(script_path)
 
@@ -486,8 +808,15 @@ async def execute_code_script(
             await proc.wait()
             duration_ms = int((time.monotonic() - started) * 1000)
             return _build_result(
-                "", "", -1, timed_out=True, duration_ms=duration_ms,
-                metadata=metadata, json_output=json_output, timeout_s=timeout_s,
+                "",
+                "",
+                -1,
+                timed_out=True,
+                duration_ms=duration_ms,
+                metadata=metadata,
+                json_output=json_output,
+                timeout_s=timeout_s,
+                status="TIMEOUT",
             )
     except FileNotFoundError:
         return _build_result(
@@ -499,6 +828,7 @@ async def execute_code_script(
             metadata=metadata,
             json_output=json_output,
             timeout_s=timeout_s,
+            status="UNAVAILABLE",
         )
     except OSError as e:
         return _build_result(
@@ -510,10 +840,56 @@ async def execute_code_script(
             metadata=metadata,
             json_output=json_output,
             timeout_s=timeout_s,
+            status="UNAVAILABLE",
         )
 
 
+@mcp.tool(
+    name="approve_code_script",
+    description="Approve a .sh/.py script for execution by adding it to the "
+    "code-mode manifest with its SHA-256. Execution is opt-in: only approved "
+    "scripts with a matching hash run. Set json_output=true for structured JSON.",
+)
+async def approve_code_script(
+    script_name: str,
+    json_output: bool = False,
+) -> str | dict[str, Any]:
+    """Approve (or re-approve) a code-mode script.
+
+    Args:
+        script_name: Name of the script in the code-mode directory.
+        json_output: When True, return ``{"status", "message"}`` instead of a
+            ``[STATUS] message`` string.
+
+    Returns:
+        A contract-labelled result. ``OK`` on success, ``INVALID_INPUT`` when
+        the script name is invalid, or ``CORRUPT_DATA``/``UNAVAILABLE`` when
+        the manifest cannot be read or written.
+    """
+    status, message = _approve_script(script_name)
+    if json_output:
+        return {"status": status, "message": message}
+    return f"[{status}] {message}"
+
+
 # ── Main Entrypoint ───────────────────────────────────────────────────────────
 
-if __name__ == "__main__":
+
+def _cli() -> int:
+    """Handle CLI subcommands used by the installer; fall back to serving MCP."""
+    argv = sys.argv[1:]
+    if "--generate-manifest" in argv:
+        scripts_dir: Path | None = None
+        if "--scripts-dir" in argv:
+            index = argv.index("--scripts-dir")
+            if index + 1 < len(argv):
+                scripts_dir = Path(argv[index + 1])
+        count = _generate_manifest(scripts_dir)
+        print(f"code-mode manifest: {count} script(s) approved")
+        return 0
     mcp.run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_cli())