agt-env 0.0.3__py3-none-any.whl

agt_env/__init__.py

@@ -0,0 +1,3 @@
+"""List the capabilities available to each coding agent on this machine."""
+
+__version__ = "0.0.3"

agt_env/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from agt_env.cli import main
+
+sys.exit(main())

agt_env/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""The adapter registry, in rank order."""
+
+from agt_env.adapters.antigravity import Antigravity
+from agt_env.adapters.base import Adapter
+from agt_env.adapters.claude_code import ClaudeCode
+from agt_env.adapters.codex import Codex
+from agt_env.adapters.opencode import OpenCode
+from agt_env.adapters.pi import Pi
+
+ADAPTERS: tuple[Adapter, ...] = (
+    ClaudeCode(),
+    Codex(),
+    OpenCode(),
+    Pi(),
+    Antigravity(),
+)

agt_env/adapters/antigravity.py

@@ -0,0 +1,306 @@
+"""Antigravity CLI adapter. The binary is `agy`.
+
+Discovery rules, official references, and undocumented findings are in
+docs/agents/antigravity.md. Update that file when these rules change. tests/test_antigravity_oracle.py
+compares results with the real agent.
+"""
+
+import os
+from pathlib import Path
+
+from agt_env.adapters.base import (
+    Context,
+    definition_item,
+    first_existing,
+    list_entries,
+    listed_paths,
+    load_once,
+    loads_skills,
+    mark_bundled,
+    mcp_item,
+    plugin_item,
+    read_json,
+    skill_item,
+)
+from agt_env.hooks import handler_content, handler_details, handlers
+from agt_env.mcp import remote_details, stdio_details
+from agt_env.model import AgentReport, Finding, Item, Kind, Scope, Status
+from agt_env.skills import FoundSkill, read_markdown, scan_skills
+
+_UNNAMED_SKILL = "SKILL"
+_NEEDS_NAME_AND_DESCRIPTION = "needs a name and a description, which Antigravity CLI requires"
+
+
+class Antigravity:
+    id = "antigravity"
+
+    def scan(self, context: Context) -> AgentReport:
+        gemini_dir = context.home / ".gemini"
+        cli_dir = gemini_dir / "antigravity-cli"
+        shared_dir = gemini_dir / "config"
+        workspace_dir = context.cwd / ".agents"
+        user_mcp = shared_dir / "mcp_config.json"
+        project_mcp = workspace_dir / "mcp_config.json"
+
+        user_skill_dirs = [cli_dir / "skills", shared_dir / "skills", gemini_dir / "skills"]
+        report = AgentReport(
+            agent=self.id,
+            installed=context.on_path("agy"),
+            config_path=first_existing(
+                cli_dir,
+                user_mcp,
+                project_mcp,
+                *user_skill_dirs[1:],
+                shared_dir / "plugins",
+                shared_dir / "agents",
+                shared_dir / "hooks.json",
+                gemini_dir / "agents",
+                workspace_dir / "agents",
+                workspace_dir / "hooks.json",
+            ),
+        )
+
+        settings, settings_ok = read_json(cli_dir / "settings.json", report.warnings)
+        project_status = _workspace_status(settings, settings_ok, context.cwd)
+
+        skill_roots = [
+            *[(Scope.USER, root, Status.ENABLED) for root in user_skill_dirs],
+            (Scope.PROJECT, workspace_dir / "skills", project_status),
+            (Scope.PROJECT, context.cwd / ".agent" / "skills", project_status),
+        ]
+        for scope, root, default in skill_roots:
+            found, warnings = scan_skills(root, include_hidden=True)
+            report.warnings.extend(warnings)
+            for skill in found:
+                report.items.append(self._skill(skill, scope, default))
+        report.items = load_once(report.items)
+
+        for path, scope, default in (
+            (user_mcp, Scope.USER, Status.ENABLED),
+            (project_mcp, Scope.PROJECT, project_status),
+        ):
+            report.items.extend(self._servers(path, scope, default, report))
+
+        state, state_ok = read_json(shared_dir / "config.json", report.warnings)
+        states = state.get("plugins")
+        states = states if isinstance(states, dict) else {}
+        for root, scope, default in (
+            (shared_dir / "plugins", Scope.USER, Status.ENABLED),
+            (workspace_dir / "plugins", Scope.PROJECT, project_status),
+        ):
+            plugins = self._plugins(root, scope, states, state_ok, report.warnings, default)
+            report.items.extend(plugins)
+            for plugin in plugins:
+                if loads_skills(plugin):
+                    report.items.extend(self._plugin_extras(plugin, report.warnings))
+            report.items.extend(
+                load_once(
+                    [
+                        skill
+                        for plugin in plugins
+                        if loads_skills(plugin)
+                        for skill in self._plugin_skills(plugin, report.warnings)
+                    ]
+                )
+            )
+
+        for root, scope, default in (
+            (cli_dir / "agents", Scope.USER, Status.ENABLED),
+            (shared_dir / "agents", Scope.USER, Status.ENABLED),
+            (gemini_dir / "agents", Scope.USER, Status.ENABLED),
+            (workspace_dir / "agents", Scope.PROJECT, project_status),
+            (context.cwd / ".agent" / "agents", Scope.PROJECT, project_status),
+        ):
+            report.items.extend(self._agents(root, scope, default, report.warnings))
+        for path, scope, default in (
+            (shared_dir / "hooks.json", Scope.USER, Status.ENABLED),
+            (workspace_dir / "hooks.json", Scope.PROJECT, project_status),
+        ):
+            report.items.extend(self._hooks(path, scope, default, report.warnings))
+        return report
+
+    def _agents(self, root: Path, scope: Scope, default: Status, warnings: list[str]) -> list[Item]:
+        """An agent is `<name>.md` or `<name>/agent.md`, one level down."""
+        items = []
+        for path in _hidden_included_entries(root, warnings):
+            file = path / "agent.md" if os.path.isdir(path) else path
+            if file.suffix != ".md" or not os.path.lexists(file):
+                continue
+            found = read_markdown(file, warnings)
+            fields = found.fields or {}
+            name, description = fields.get("name"), fields.get("description")
+            items.append(
+                definition_item(
+                    self.id,
+                    found,
+                    Kind.SUBAGENT,
+                    "agent",
+                    scope,
+                    default if name and description else Status.BROKEN,
+                    name=name or path.stem,
+                    description=description or "",
+                    problem=_NEEDS_NAME_AND_DESCRIPTION,
+                )
+            )
+        return items
+
+    def _hooks(self, path: Path, scope: Scope, default: Status, warnings: list[str]) -> list[Item]:
+        """The top-level keys are hook names, each with its own events."""
+        data, ok = read_json(path, warnings)
+        items = []
+        for name, entry in data.items():
+            fields = entry if isinstance(entry, dict) else {}
+            events = {key: value for key, value in fields.items() if key != "enabled"}
+            found = list(handlers(events))
+            summaries = [handler_details(handler.entry) for handler in found]
+            valid = isinstance(entry, dict) and bool(summaries) and all(summaries)
+            status = default if ok else Status.UNKNOWN
+            if fields.get("enabled") is False:
+                status = Status.DISABLED
+            details: dict[str, object] = {"event": list(events)}
+            if valid:
+                details["command"] = [s["command"] for s in summaries if s.get("command")]
+            items.append(
+                Item(
+                    name=name,
+                    kind=Kind.HOOK,
+                    native_kind="hook",
+                    agent=self.id,
+                    scope=scope,
+                    status=status if valid else Status.BROKEN,
+                    description="; ".join(
+                        content for handler in found if (content := handler_content(handler.entry))
+                    ),
+                    source_path=path,
+                    resolved_path=Path(os.path.realpath(path)),
+                    details=details,
+                    findings=[] if valid else [Finding("invalid hook entry")],
+                )
+            )
+        return items
+
+    def _plugin_extras(self, plugin: Item, warnings: list[str]) -> list[Item]:
+        items = self._agents(plugin.source_path / "agents", plugin.scope, plugin.status, warnings)
+        items += self._hooks(
+            plugin.source_path / "hooks.json", plugin.scope, plugin.status, warnings
+        )
+        for item in items:
+            mark_bundled(
+                item,
+                plugin,
+                item.name,
+                "plugin agent" if item.kind is Kind.SUBAGENT else "plugin hook",
+            )
+        return items
+
+    def _plugin_skills(self, plugin: Item, warnings: list[str]) -> list[Item]:
+        manifest, _ = read_json(_plugin_manifest(plugin.source_path), [])
+        items = []
+        # A manifest's paths add to the default directory.
+        for path in ("skills", *listed_paths(manifest.get("skills"))):
+            found, scan_warnings = scan_skills(plugin.source_path / path, include_hidden=True)
+            warnings.extend(scan_warnings)
+            for skill in found:
+                item = self._skill(skill, plugin.scope, plugin.status)
+                items.append(
+                    mark_bundled(
+                        item, plugin, f"{plugin.name}:{item.name}", prefix=f"{plugin.name}:"
+                    )
+                )
+        return items
+
+    def _skill(self, skill: FoundSkill, scope: Scope, default: Status) -> Item:
+        status = default if not skill.broken and skill.fields is not None else Status.BROKEN
+        if skill.fields is not None:
+            skill.fields["name"] = skill.fields.get("name") or _UNNAMED_SKILL
+        return skill_item(
+            self.id, skill, scope, status, "has no frontmatter, which Antigravity CLI requires"
+        )
+
+    def _servers(
+        self, path: Path, scope: Scope, default: Status, report: AgentReport
+    ) -> list[Item]:
+        data, ok = read_json(path, report.warnings, blank_ok=True)
+        servers = data.get("mcpServers")
+        items = []
+        for name, entry in servers.items() if isinstance(servers, dict) else ():
+            status = default if ok else Status.UNKNOWN
+            if isinstance(entry, dict) and entry.get("disabled") is True:
+                status = Status.DISABLED
+            items.append(mcp_item(self.id, name, _server_details(entry), scope, status, path))
+        return items
+
+    def _plugins(
+        self,
+        root: Path,
+        scope: Scope,
+        states: dict,
+        state_ok: bool,
+        warnings: list[str],
+        default: Status,
+    ) -> list[Item]:
+        items = []
+        for path in list_entries(root, warnings):
+            manifest_path = _plugin_manifest(path)
+            if not os.path.exists(manifest_path):
+                continue
+            manifest, _ = read_json(manifest_path, [])
+            description = manifest.get("description")
+            items.append(
+                plugin_item(
+                    self.id,
+                    path.name,
+                    "plugin",
+                    scope,
+                    _plugin_status(path.name, states, state_ok, default),
+                    path,
+                    description if isinstance(description, str) else "",
+                )
+            )
+        return items
+
+
+def _hidden_included_entries(root: Path, warnings: list[str]) -> list[Path]:
+    try:
+        return [root / name for name in sorted(os.listdir(root))]
+    except (FileNotFoundError, NotADirectoryError):
+        return []
+    except OSError as error:
+        warnings.append(f"cannot read {root}: {error.strerror}")
+        return []
+
+
+def _plugin_manifest(plugin_dir: Path) -> Path:
+    path = plugin_dir / "plugin.json"
+    return path if os.path.exists(path) else plugin_dir / ".antigravity-plugin" / "plugin.json"
+
+
+def _plugin_status(name: str, states: dict, state_ok: bool, default: Status) -> Status:
+    if not state_ok:
+        return Status.UNKNOWN
+    entry = states.get(name)
+    enabled = entry.get("enabled", True) if isinstance(entry, dict) else True
+    return Status.DISABLED if enabled is False else default
+
+
+def _workspace_status(settings: dict, settings_ok: bool, cwd: Path) -> Status:
+    if not settings_ok:
+        return Status.UNKNOWN
+    trusted = settings.get("trustedWorkspaces")
+    real = os.path.realpath(cwd)
+    if isinstance(trusted, list) and any(
+        isinstance(path, str) and os.path.realpath(path) == real for path in trusted
+    ):
+        return Status.ENABLED
+    return Status.PENDING
+
+
+def _server_details(entry: object) -> dict[str, object] | None:
+    if not isinstance(entry, dict):
+        return None
+    if isinstance(entry.get("command"), str):
+        return stdio_details(entry["command"], entry.get("env"))
+    url = entry.get("serverUrl", entry.get("url"))
+    if isinstance(url, str):
+        return remote_details("streamable_http", url, entry.get("headers"))
+    return None

agt_env/adapters/base.py

@@ -0,0 +1,266 @@
+"""The adapter interface and helpers shared by adapters."""
+
+import json
+import os
+import shutil
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from agt_env.jsonc import loads_jsonc
+from agt_env.model import AgentReport, Finding, Item, Kind, Scope, Status
+from agt_env.skills import FoundSkill
+
+
+@dataclass(frozen=True)
+class Context:
+    home: Path
+    cwd: Path
+    env: Mapping[str, str]
+    # Prefix for machine-wide locations, so tests never read the real system.
+    system_root: Path = field(default=Path("/"))
+
+    def on_path(self, binary: str) -> bool:
+        """Check PATH without executing anything; shims count as installed."""
+        return shutil.which(binary, path=self.env.get("PATH", "")) is not None
+
+
+INVALID_SERVER = Finding("invalid server entry")
+MISSING_PLUGIN = Finding("plugin files are missing")
+
+
+class Adapter(Protocol):
+    id: str
+
+    def scan(self, context: Context) -> AgentReport: ...
+
+
+def config_dir(context: Context, variable: str, default: Path) -> tuple[Path, str | None]:
+    """Return an agent's config directory and the variable that moved it, if any."""
+    value = context.env.get(variable)
+    if not value:
+        return default, None
+    path = Path(value).expanduser()
+    return path, variable if os.path.realpath(path) != os.path.realpath(default) else None
+
+
+def read_json(
+    path: Path, warnings: list[str], *, jsonc: bool = False, blank_ok: bool = False
+) -> tuple[dict, bool]:
+    """Return the file's top-level object and whether it could be read.
+
+    A missing file is normal. A non-object is treated as empty.
+    """
+    if not os.path.isfile(path):
+        return {}, True
+    try:
+        with open(path, encoding="utf-8") as file:
+            text = file.read()
+        if blank_ok and not text.strip():
+            return {}, True
+        data = loads_jsonc(text) if jsonc else json.loads(text)
+    except (OSError, ValueError) as error:
+        warnings.append(f"cannot read {path}: {error}")
+        return {}, False
+    return (data if isinstance(data, dict) else {}), True
+
+
+def first_existing(*paths: Path) -> Path | None:
+    return next((path for path in paths if os.path.exists(path)), None)
+
+
+def list_entries(directory: Path, warnings: list[str]) -> list[Path]:
+    """Return a directory's non-hidden entries. Only an unreadable directory warns."""
+    try:
+        with os.scandir(directory) as iterator:
+            names = sorted(entry.name for entry in iterator)
+    except (FileNotFoundError, NotADirectoryError):
+        return []
+    except OSError as error:
+        warnings.append(f"cannot read {directory}: {error.strerror}")
+        return []
+    return [directory / name for name in names if not name.startswith(".")]
+
+
+def skill_item(
+    agent: str, skill: FoundSkill, scope: Scope, status: Status, problem: str = ""
+) -> Item:
+    """Build a skill item. `problem` is why the agent refuses it, if it was readable."""
+    fields = skill.fields or {}
+    return Item(
+        name=fields.get("name") or skill.default_name,
+        kind=Kind.SKILL,
+        native_kind="skill",
+        agent=agent,
+        scope=scope,
+        status=status,
+        description=fields.get("description", ""),
+        source_path=skill.path,
+        resolved_path=skill.resolved_path,
+        findings=[Finding(skill.problem or problem)] if status is Status.BROKEN else [],
+    )
+
+
+def definition_item(
+    agent: str,
+    found: FoundSkill,
+    kind: Kind,
+    native_kind: str,
+    scope: Scope,
+    status: Status,
+    *,
+    name: str,
+    description: str = "",
+    problem: str = "",
+) -> Item:
+    """Build an item for a Markdown command or agent. `problem` is why the agent refuses it."""
+    if found.broken:
+        status = Status.BROKEN
+    return Item(
+        name=name,
+        kind=kind,
+        native_kind=native_kind,
+        agent=agent,
+        scope=scope,
+        status=status,
+        description=description,
+        source_path=found.path,
+        resolved_path=found.resolved_path,
+        findings=[Finding(found.problem or problem)] if status is Status.BROKEN else [],
+    )
+
+
+def first_line(text: str) -> str:
+    return next((line.strip() for line in text.splitlines() if line.strip()), "")
+
+
+def mcp_item(
+    agent: str, name: str, details: dict | None, scope: Scope, status: Status, path: Path
+) -> Item:
+    """Build a server item. Details of None mean the entry is invalid."""
+    return Item(
+        name=name,
+        kind=Kind.MCP,
+        native_kind="mcp server",
+        agent=agent,
+        scope=scope,
+        status=Status.BROKEN if details is None else status,
+        description="",
+        source_path=path,
+        resolved_path=Path(os.path.realpath(path)),
+        details=details or {},
+        findings=[INVALID_SERVER] if details is None else [],
+    )
+
+
+def plugin_item(
+    agent: str,
+    name: str,
+    native_kind: str,
+    scope: Scope,
+    status: Status,
+    path: Path,
+    description: str = "",
+) -> Item:
+    return Item(
+        name=name,
+        kind=Kind.PLUGIN,
+        native_kind=native_kind,
+        agent=agent,
+        scope=scope,
+        status=status,
+        description=description,
+        source_path=path,
+        resolved_path=Path(os.path.realpath(path)),
+        findings=[MISSING_PLUGIN] if status is Status.BROKEN else [],
+    )
+
+
+def loads_skills(plugin: Item) -> bool:
+    """A plugin that's turned off, replaced, or missing contributes no skills."""
+    return plugin.status not in (Status.DISABLED, Status.SHADOWED, Status.BROKEN)
+
+
+def marketplace_suffix(plugin_id: str) -> str:
+    """Return the `@marketplace` of a plugin ID."""
+    name, at, marketplace = plugin_id.rpartition("@")
+    return f"{at}{marketplace}" if name else ""
+
+
+def mark_bundled(
+    skill: Item,
+    plugin: Item,
+    name: str,
+    native_kind: str = "plugin skill",
+    *,
+    prefix: str = "",
+) -> Item:
+    """Make an item report the plugin it came from, under the name the agent gives it.
+
+    `prefix` is the part of the name that the plugin adds.
+    """
+    skill.name = name
+    skill.name_prefix = prefix
+    skill.native_kind = native_kind
+    skill.details["plugin"] = plugin.name
+    if skill.status is Status.ENABLED:
+        skill.status = plugin.status
+    return skill
+
+
+def listed_paths(value: object) -> list[str]:
+    """Read a manifest field that holds a path or a list of paths."""
+    values = value if isinstance(value, list) else [value]
+    return [entry for entry in values if isinstance(entry, str)]
+
+
+def is_inside_plugin(path: str) -> bool:
+    """Whether a manifest path has the form `./something`, staying inside the plugin."""
+    return path.startswith("./") and ".." not in Path(path).parts
+
+
+def mark_shadowed(
+    ranked: Iterable[Item],
+    *,
+    key: Callable[[Item], str] = lambda item: item.name,
+    winners: frozenset[Status] = frozenset({Status.ENABLED}),
+) -> None:
+    """Mark what loses to a same-named item. `ranked` is highest precedence first.
+
+    `winners` is the statuses that take the name. In some agents a turned-off item still does.
+    """
+    won: dict[str, Item] = {}
+    for item in ranked:
+        winner = won.get(key(item))
+        if winner is None:
+            if item.status in winners:
+                won[key(item)] = item
+        elif item.status is Status.ENABLED:
+            item.status = Status.SHADOWED
+            item.findings.append(Finding("shadowed by", winner.source_path))
+
+
+def load_once(items: list[Item]) -> list[Item]:
+    """Keep the first skill per real path: agents load a linked skill only once."""
+    seen: set[Path] = set()
+    unique = []
+    for item in items:
+        if item.kind is not Kind.SKILL or item.status is Status.BROKEN:
+            unique.append(item)
+        elif item.resolved_path not in seen:
+            seen.add(item.resolved_path)
+            unique.append(item)
+    return unique
+
+
+def unique_roots(roots: list[tuple[Scope, Path]]) -> list[tuple[Scope, Path]]:
+    """Drop roots that are the same directory, keeping the first (cwd may be HOME)."""
+    seen: set[str] = set()
+    unique = []
+    for label, root in roots:
+        real = os.path.realpath(root)
+        if real not in seen:
+            seen.add(real)
+            unique.append((label, root))
+    return unique