Tools

tools

AXM tools for the doctor — env_doctor and auth_status.

Both are deterministic :class:~axm.tools.base.AXMTool implementations, so they are reachable over MCP, the axm CLI and as DAG nodes from a single axm.tools entry-point declaration. They are strictly read-only: they wrap the central detect/orchestrate functions and never install anything.

They uphold the doctor's security invariant — mirror of vault_doctor — no tool ever serializes a token value. auth_status reports only the state and the recovery command (login_cmd); the credential value itself never transits axm_doctor.

AuthStatusTool

Report third-party auth state — never a token value (mirror of vault).

Source code in packages/axm-doctor/src/axm_doctor/tools.py

class AuthStatusTool:
    """Report third-party auth state — never a token value (mirror of vault)."""

    agent_hint = (
        "Report third-party binary auth state as {tool: {state, login_cmd}}; "
        "the token value is NEVER returned."
    )
    domain = "doctor"
    tags = frozenset({"doctor", "auth", "login"})

    @property
    def name(self) -> str:
        """Unique tool identifier."""
        return "auth_status"

    def execute(self) -> ToolResult:
        """Return value-free auth state; any error becomes a failure ToolResult."""
        try:
            auth = _auth_map()
            provenance = _credentials_map(collect_credential_provenance())
            credentials = {
                coordinate: {
                    "layer": entry["layer"],
                    "present": entry["present"],
                }
                for coordinate, entry in provenance.items()
            }
            rejections = _rejection_rows()
        except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
            return ToolResult(success=False, error=str(exc))
        auth_text = "\n".join(
            f"- {tool}: {entry['state']}"
            f"{' [no declaration]' if not entry['declaration_consulted'] else ''}"
            for tool, entry in auth.items()
        )
        return ToolResult(
            success=True,
            data={
                "auth": auth,
                "undetermined": [
                    tool
                    for tool, entry in auth.items()
                    if entry["state"] == "undetermined"
                ],
                "logged_out": [
                    tool
                    for tool, entry in auth.items()
                    if entry["state"] == "logged_out"
                ],
                "credentials": credentials,
                "rejections": rejections,
            },
            text=(
                f"Third-party auth:\n{auth_text}\n\n{_credentials_text(provenance)}"
                f"{_rejections_text(rejections)}"
            ),
        )

name property

Unique tool identifier.

execute()

Return value-free auth state; any error becomes a failure ToolResult.

Source code in packages/axm-doctor/src/axm_doctor/tools.py

def execute(self) -> ToolResult:
    """Return value-free auth state; any error becomes a failure ToolResult."""
    try:
        auth = _auth_map()
        provenance = _credentials_map(collect_credential_provenance())
        credentials = {
            coordinate: {
                "layer": entry["layer"],
                "present": entry["present"],
            }
            for coordinate, entry in provenance.items()
        }
        rejections = _rejection_rows()
    except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
        return ToolResult(success=False, error=str(exc))
    auth_text = "\n".join(
        f"- {tool}: {entry['state']}"
        f"{' [no declaration]' if not entry['declaration_consulted'] else ''}"
        for tool, entry in auth.items()
    )
    return ToolResult(
        success=True,
        data={
            "auth": auth,
            "undetermined": [
                tool
                for tool, entry in auth.items()
                if entry["state"] == "undetermined"
            ],
            "logged_out": [
                tool
                for tool, entry in auth.items()
                if entry["state"] == "logged_out"
            ],
            "credentials": credentials,
            "rejections": rejections,
        },
        text=(
            f"Third-party auth:\n{auth_text}\n\n{_credentials_text(provenance)}"
            f"{_rejections_text(rejections)}"
        ),
    )

EnvDoctorTool

Read-only env report: tool presence/version + auth + missing secrets.

Source code in packages/axm-doctor/src/axm_doctor/tools.py

class EnvDoctorTool:
    """Read-only env report: tool presence/version + auth + missing secrets."""

    agent_hint = (
        "Read-only env doctor: report each external tool's presence/version, "
        "third-party auth state, and missing (value-free) secrets. Never installs."
    )
    domain = "doctor"
    tags = frozenset({"doctor", "env", "bootstrap", "detect"})

    @property
    def name(self) -> str:
        """Unique tool identifier."""
        return "env_doctor"

    def execute(self) -> ToolResult:
        """Return the full env report; any error becomes a failure ToolResult."""
        try:
            tools = {
                name: {"state": status.state, "version": status.version}
                for name in PROBED_TOOLS
                for status in (detect_tool(name),)
            }
            secrets = [secret.model_dump() for secret in missing_secrets()]
        except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
            return ToolResult(success=False, error=str(exc))
        return ToolResult(
            success=True,
            data={
                "tools": tools,
                "auth": _auth_map(),
                "secrets": secrets,
                "config": _config_map(),
            },
        )

name property

Unique tool identifier.

execute()

Return the full env report; any error becomes a failure ToolResult.

Source code in packages/axm-doctor/src/axm_doctor/tools.py

def execute(self) -> ToolResult:
    """Return the full env report; any error becomes a failure ToolResult."""
    try:
        tools = {
            name: {"state": status.state, "version": status.version}
            for name in PROBED_TOOLS
            for status in (detect_tool(name),)
        }
        secrets = [secret.model_dump() for secret in missing_secrets()]
    except Exception as exc:  # noqa: BLE001 # MCP boundary: any error -> failure
        return ToolResult(success=False, error=str(exc))
    return ToolResult(
        success=True,
        data={
            "tools": tools,
            "auth": _auth_map(),
            "secrets": secrets,
            "config": _config_map(),
        },
    )