@julioborges/gantry 1.0.1 → 1.0.4

package/.agents/skills/gantry/scripts/caveman.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Caveman lite discovery, installation guidance, and activation resolution."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from common import repo_root, resolve_policy
+
+
+def get_install_guidance(harness: str | None = None) -> str:
+    """Return verified upstream skill-only installation guidance for the host harness."""
+    h = (harness or "claude-code").lower()
+    if "antigravity" in h or "agy" in h:
+        return (
+            "Clone Caveman into your Antigravity skills directory:\n"
+            "  git clone https://github.com/JuliusBrussee/caveman.git ~/.gemini/config/skills/caveman\n"
+            "  (or inside repository at .agents/skills/caveman)"
+        )
+    elif "opencode" in h:
+        return (
+            "Clone Caveman into your OpenCode skills directory:\n"
+            "  git clone https://github.com/JuliusBrussee/caveman.git ~/.config/opencode/skills/caveman\n"
+            "  (or inside repository at .agents/skills/caveman)"
+        )
+    elif "codex" in h:
+        return (
+            "Clone Caveman into your skills directory:\n"
+            "  git clone https://github.com/JuliusBrussee/caveman.git .agents/skills/caveman"
+        )
+    else:  # Claude Code / default
+        return (
+            "Install Caveman skill using npx skills:\n"
+            "  npx skills add caveman\n"
+            "  (or git clone https://github.com/JuliusBrussee/caveman.git ~/.claude/skills/caveman)"
+        )
+
+
+def check_availability(harness: str | None = None, root: Path | None = None) -> dict:
+    """Verify that the host harness can discover and read the Caveman skill."""
+    root_path = root.resolve() if root else repo_root()
+    home = Path.home()
+
+    # Allow environment override for testing/fixtures without touching global paths
+    env_override = os.environ.get("GANTRY_CAVEMAN_PATH")
+    candidate_paths: list[Path] = []
+    if env_override:
+        p = Path(env_override)
+        candidate_paths.append(p if p.name == "SKILL.md" else p / "SKILL.md")
+
+    # In-repository skill
+    candidate_paths.append(root_path / ".agents" / "skills" / "caveman" / "SKILL.md")
+
+    h = (harness or "").lower()
+    if "antigravity" in h:
+        candidate_paths.extend([
+            home / ".gemini" / "config" / "skills" / "caveman" / "SKILL.md",
+            home / ".agents" / "skills" / "caveman" / "SKILL.md",
+        ])
+    elif "opencode" in h:
+        candidate_paths.extend([
+            home / ".config" / "opencode" / "skills" / "caveman" / "SKILL.md",
+            home / ".agents" / "skills" / "caveman" / "SKILL.md",
+        ])
+    elif "codex" in h:
+        candidate_paths.extend([
+            home / ".codex" / "skills" / "caveman" / "SKILL.md",
+            home / ".agents" / "skills" / "caveman" / "SKILL.md",
+        ])
+    else:  # Claude Code or generic
+        candidate_paths.extend([
+            root_path / ".claude" / "skills" / "caveman" / "SKILL.md",
+            home / ".claude" / "skills" / "caveman" / "SKILL.md",
+            home / ".agents" / "skills" / "caveman" / "SKILL.md",
+        ])
+
+    for candidate in candidate_paths:
+        if candidate.is_file():
+            try:
+                candidate.read_text(encoding="utf-8")
+                return {
+                    "available": True,
+                    "path": str(candidate.resolve()),
+                    "harness": harness or "auto",
+                }
+            except (OSError, PermissionError) as exc:
+                return {
+                    "available": False,
+                    "reason": f"unreadable: {exc}",
+                    "path": str(candidate.resolve()),
+                    "install_guidance": get_install_guidance(harness),
+                }
+
+    return {
+        "available": False,
+        "reason": "not_found",
+        "install_guidance": get_install_guidance(harness),
+    }
+
+
+def resolve_activation(
+    policy: dict,
+    harness: str | None = None,
+    root: Path | None = None,
+    warned: bool = False,
+) -> dict:
+    """Resolve Caveman activation state and handle once-per-Run warning deduplication."""
+    pref = policy.get("caveman", False)
+    # Handle boolean or dict representation safely
+    preference_enabled = bool(pref.get("enabled", True) if isinstance(pref, dict) else pref)
+
+    if not preference_enabled:
+        return {
+            "preference": False,
+            "active": False,
+            "scope": "none",
+            "warning": None,
+            "warned": warned,
+        }
+
+    avail = check_availability(harness=harness, root=root)
+    if avail["available"]:
+        return {
+            "preference": True,
+            "active": True,
+            "skill_path": avail["path"],
+            "scope": "conversational_and_summaries",
+            "warning": None,
+            "warned": warned,
+        }
+
+    # Preference enabled, but skill unavailable
+    warning = None
+    new_warned = warned
+    if not warned:
+        guidance = avail.get("install_guidance", get_install_guidance(harness))
+        warning = (
+            "Warning: Caveman lite is enabled in repository policy, but the Caveman skill was not "
+            "found or is unreadable in the host environment. Continuing with normal behavior.\n"
+            f"{guidance}"
+        )
+        new_warned = True
+
+    return {
+        "preference": True,
+        "active": False,
+        "scope": "none",
+        "warning": warning,
+        "warned": new_warned,
+    }
+
+
+def get_coordinating_instructions(active: bool = True) -> str:
+    """Return coordinating agent instructions for Caveman lite conversational scope."""
+    if not active:
+        return ""
+    return (
+        "Caveman lite is active for this Run: use concise phrasing for conversational messages and "
+        "summaries. Specs, Issues, documentation, PR descriptions, Result Contracts, exact commands, "
+        "exact errors, and acceptance criteria retain full detail."
+    )
+
+
+def get_planning_instructions(active: bool = True) -> str:
+    """Return planning agent prompt instructions for Caveman lite conversational scope."""
+    if not active:
+        return ""
+    return (
+        "Caveman lite is active: use concise phrasing for conversational messages and summaries. "
+        "Specs, draft Issues, persisted role results, exact errors, commands, and acceptance criteria "
+        "retain full detail."
+    )
+
+
+def get_round_instructions(active: bool = True) -> str:
+    """Return round agent prompt instructions for Caveman lite conversational scope."""
+    if not active:
+        return ""
+    return (
+        "Caveman lite is active: use concise phrasing for conversational messages and summaries. "
+        "Code, documentation, lesson candidates, PR descriptions, Result Contracts, exact commands, "
+        "exact errors, acceptance criteria, and verification evidence retain full detail."
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command")
+
+    check_parser = subparsers.add_parser("check", help="check host-harness skill discovery and readability")
+    check_parser.add_argument("--harness", default="claude-code", help="host harness name")
+    check_parser.add_argument("--cwd", default=".", help="repository root path")
+    check_parser.add_argument("--json", action="store_true", help="output JSON")
+
+    resolve_parser = subparsers.add_parser("resolve", help="resolve effective Caveman activation for Run")
+    resolve_parser.add_argument("--harness", default="claude-code", help="host harness name")
+    resolve_parser.add_argument("--cwd", default=".", help="repository root path")
+    resolve_parser.add_argument("--warned", action="store_true", help="whether warning was already emitted")
+    resolve_parser.add_argument("--json", action="store_true", help="output JSON")
+
+    subparsers.add_parser("guidance", help="print installation guidance")
+
+    args = parser.parse_args()
+
+    if args.command == "check":
+        root = Path(args.cwd).resolve()
+        res = check_availability(harness=args.harness, root=root)
+        if args.json:
+            print(json.dumps(res, indent=2))
+        else:
+            if res["available"]:
+                print(f"Caveman available: {res['path']}")
+            else:
+                print(f"Caveman not available: {res['reason']}")
+                print(res["install_guidance"])
+        return 0 if res["available"] else 1
+
+    elif args.command == "resolve":
+        root = Path(args.cwd).resolve()
+        policy = resolve_policy(root)
+        res = resolve_activation(policy, harness=args.harness, root=root, warned=args.warned)
+        if args.json:
+            print(json.dumps(res, indent=2))
+        else:
+            print(f"Caveman preference: {res['preference']}, active: {res['active']}")
+            if res["warning"]:
+                print(res["warning"])
+        return 0
+
+    elif args.command == "guidance":
+        print(get_install_guidance())
+        return 0
+
+    else:
+        parser.print_help()
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/gantry/scripts/common.py

@@ -28,6 +28,8 @@ DEFAULT_POLICY = {
     "hooks": {"record": [], "deny": []},
     "budget": {"corrections": 2, "contextShare": 0.15},
     "dashboard": {"staleAfterSeconds": 900},
+    "caveman": False,
+    "execution": {"roles": {}},
 }
 
 REF_RE = re.compile(r"`?([a-z0-9][a-z0-9-]*)#(\d{2,})`?")

package/.agents/skills/gantry/scripts/discovery.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Runtime model and effort discovery across supported harnesses."""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+SUPPORTED_HARNESSES = {"antigravity", "claude-code", "codex", "opencode"}
+PROGRESS_CHAR_RE = re.compile(r"^[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏\s\r\x1b\[0-9;]*Fetching available models\.\.\.", re.MULTILINE)
+ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+
+
+class DiscoveryError(Exception):
+    """Raised when runtime model or effort discovery cannot be established."""
+
+
+def clean_ansi(text: str) -> str:
+    """Remove ANSI escape sequences and carriage returns."""
+    return ANSI_ESCAPE_RE.sub("", text).replace("\r", "")
+
+
+def parse_agy_models_output(
+    raw_output: str,
+    metadata_lookup: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    """Parse stdout from `agy models` into a structured list of model dicts without inventing windows."""
+    cleaned = clean_ansi(raw_output)
+    models: list[dict[str, Any]] = []
+    seen: set[str] = set()
+
+    for line in cleaned.splitlines():
+        line = line.strip()
+        if not line or line.startswith("Fetching available models") or line.startswith("Usage:"):
+            continue
+        parts = line.split(None, 1)
+        if not parts:
+            continue
+        model_id = parts[0].strip()
+        display_name = parts[1].strip() if len(parts) > 1 else model_id
+
+        if model_id in seen:
+            continue
+        seen.add(model_id)
+
+        entry: dict[str, Any] = {
+            "id": model_id,
+            "name": display_name,
+        }
+
+        # Attach verified context metadata or effort if declared/verified
+        if metadata_lookup and model_id in metadata_lookup:
+            meta = metadata_lookup[model_id]
+            if isinstance(meta, dict):
+                if "contextWindow" in meta:
+                    entry["contextWindow"] = meta["contextWindow"]
+                if "supportedEfforts" in meta:
+                    entry["supportedEfforts"] = meta["supportedEfforts"]
+                if "effort" in meta:
+                    entry["effort"] = meta["effort"]
+
+        models.append(entry)
+
+    return models
+
+
+def fetch_paginated_catalog(fetcher: Callable[[str | None], dict[str, Any]]) -> list[dict[str, Any]]:
+    """Fetch all pages from a paginated catalog source."""
+    all_models: list[dict[str, Any]] = []
+    page_token: str | None = None
+
+    while True:
+        res = fetcher(page_token)
+        models = res.get("models", [])
+        all_models.extend(models)
+        page_token = res.get("next_page_token") or res.get("nextPageToken")
+        if not page_token:
+            break
+
+    return all_models
+
+
+def discover_antigravity_models(runner: Callable[..., subprocess.CompletedProcess[str]] | None = None) -> list[dict[str, Any]]:
+    """Discover executable models via `agy models`."""
+    agy_path = shutil.which("agy")
+    if not agy_path:
+        raise DiscoveryError("Missing discovery: agy CLI not found in PATH")
+
+    run_cmd = runner or subprocess.run
+    try:
+        proc = run_cmd([agy_path, "models"], capture_output=True, text=True, check=False)
+    except OSError as exc:
+        raise DiscoveryError(f"Missing discovery: failed to run agy models: {exc}") from exc
+
+    if proc.returncode != 0:
+        err = proc.stderr.strip() or proc.stdout.strip()
+        raise DiscoveryError(f"Missing discovery: agy models returned exit code {proc.returncode}: {err}")
+
+    cap_file = Path(__file__).resolve().parents[1] / "capabilities" / "antigravity.json"
+    metadata_lookup = {}
+    if cap_file.exists():
+        try:
+            metadata_lookup = json.loads(cap_file.read_text(encoding="utf-8")).get("models", {})
+        except Exception:
+            pass
+
+    models = parse_agy_models_output(proc.stdout, metadata_lookup=metadata_lookup)
+    if not models:
+        raise DiscoveryError("Missing discovery: agy models returned an empty model list")
+    return models
+
+
+def discover_models(harness: str, runner: Callable[..., Any] | None = None) -> list[dict[str, Any]]:
+    """Discover executable models for the given harness; fail closed on missing discovery."""
+    h = (harness or "").lower()
+    if h not in SUPPORTED_HARNESSES:
+        raise DiscoveryError(f"Missing discovery: unsupported harness {harness!r}. Supported: {sorted(SUPPORTED_HARNESSES)}")
+
+    if h == "antigravity":
+        return discover_antigravity_models(runner=runner)
+    elif h == "claude-code":
+        claude_path = shutil.which("claude")
+        if not claude_path:
+            raise DiscoveryError("Missing discovery: claude CLI not found in PATH")
+        cap_file = Path(__file__).resolve().parents[1] / "capabilities" / "claude-code.json"
+        if cap_file.exists():
+            cap = json.loads(cap_file.read_text(encoding="utf-8"))
+            return [{"id": m, "contextWindow": d["contextWindow"]} for m, d in cap.get("models", {}).items()]
+        raise DiscoveryError("Missing discovery: claude capability declaration missing")
+    elif h == "opencode":
+        opencode_path = shutil.which("opencode")
+        if not opencode_path:
+            raise DiscoveryError("Missing discovery: opencode CLI not found in PATH")
+        cap_file = Path(__file__).resolve().parents[1] / "capabilities" / "opencode.json"
+        if cap_file.exists():
+            cap = json.loads(cap_file.read_text(encoding="utf-8"))
+            return [{"id": m, "contextWindow": d["contextWindow"]} for m, d in cap.get("models", {}).items()]
+        raise DiscoveryError("Missing discovery: opencode capability declaration missing")
+    elif h == "codex":
+        codex_path = shutil.which("codex")
+        if not codex_path:
+            raise DiscoveryError("Missing discovery: codex CLI not found in PATH")
+        cap_file = Path(__file__).resolve().parents[1] / "capabilities" / "codex.json"
+        if cap_file.exists():
+            cap = json.loads(cap_file.read_text(encoding="utf-8"))
+            return [{"id": m, "contextWindow": d["contextWindow"]} for m, d in cap.get("models", {}).items()]
+        raise DiscoveryError("Missing discovery: codex capability declaration missing")
+
+    raise DiscoveryError(f"Missing discovery: unhandled harness {harness}")
+
+
+def sanitize_no_credentials(data: Any) -> Any:
+    """Recursively scrub credential keys from dictionary."""
+    if isinstance(data, dict):
+        cleaned: dict[str, Any] = {}
+        for k, v in data.items():
+            k_lower = str(k).lower()
+            if any(secret in k_lower for secret in ("token", "secret", "password", "api_key", "auth")):
+                continue
+            cleaned[k] = sanitize_no_credentials(v)
+        return cleaned
+    elif isinstance(data, list):
+        return [sanitize_no_credentials(item) for item in data]
+    return data
+
+
+def create_catalog_entry(
+    harness: str,
+    models: list[dict[str, Any]],
+    provider: str = "",
+    account: str = "",
+    source_command: str = "",
+) -> dict[str, Any]:
+    """Create a catalog entry with provenance, freshness, and no credentials."""
+    entry = {
+        "harness": harness,
+        "provider": provider,
+        "account": account,
+        "models": models,
+        "provenance": {
+            "source": source_command or f"{harness} discovery",
+            "discovered_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            "freshness_seconds": 3600,
+        },
+    }
+    return sanitize_no_credentials(entry)
+
+
+def is_catalog_valid(
+    catalog: dict[str, Any],
+    current_provider: str = "",
+    current_account: str = "",
+) -> bool:
+    """Check whether a catalog entry is valid for the current provider and account."""
+    if not isinstance(catalog, dict) or "models" not in catalog:
+        return False
+    if current_provider and catalog.get("provider") != current_provider:
+        return False
+    if current_account and catalog.get("account") != current_account:
+        return False
+    return True
+
+
+def validate_effort(
+    model_id: str,
+    effort: str | None,
+    supported_efforts: list[str] | None = None,
+) -> dict[str, Any]:
+    """Validate that the requested reasoning effort is supported by the model."""
+    if not effort:
+        return {"valid": True}
+    if not supported_efforts:
+        return {
+            "valid": False,
+            "error": f"Model {model_id} does not declare supported reasoning effort values.",
+        }
+    normalized_supported = [e.lower() for e in supported_efforts]
+    if effort.lower() not in normalized_supported:
+        return {
+            "valid": False,
+            "error": f"Unsupported effort value {effort!r} for model {model_id}. Supported: {supported_efforts}",
+        }
+    return {"valid": True}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--harness", default="antigravity", help="harness to discover models for")
+    parser.add_argument("--json", action="store_true", help="output JSON")
+    args = parser.parse_args()
+
+    try:
+        models = discover_models(args.harness)
+        catalog = create_catalog_entry(
+            harness=args.harness,
+            models=models,
+            source_command=f"gantry discovery --harness {args.harness}",
+        )
+        if args.json:
+            print(json.dumps(catalog, indent=2))
+        else:
+            print(f"Discovered {len(models)} model(s) for {args.harness}:")
+            for m in models:
+                eff = f" (effort: {m['effort']})" if "effort" in m else ""
+                print(f"  - {m['id']}: window={m.get('contextWindow')}{eff}")
+        return 0
+    except DiscoveryError as exc:
+        if args.json:
+            print(json.dumps({"error": str(exc)}, indent=2))
+        else:
+            print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())