| # Copyright 2026 The Fuchsia Authors. All rights reserved. | |
| # Use of this source code is governed by a BSD-style license that can be | |
| # found in the LICENSE file. | |
| """Utility library for checking if a tool is being run by an automated agent.""" | |
| import os | |
| import pathlib | |
| import typing | |
| from importlib.resources import files | |
| try: | |
| from agents import data # type: ignore[attr-defined] | |
| except ImportError: | |
| data = None | |
| # Relative path from this file's directory to tools/devshell/lib/agents.txt in the source tree. | |
| _SOURCE_AGENTS_TXT_RELPATH = ( | |
| pathlib.Path("..") | |
| / ".." | |
| / ".." | |
| / "tools" | |
| / "devshell" | |
| / "lib" | |
| / "agents.txt" | |
| ) | |
| # Relative path from this file's directory to tools/devshell/lib/agent_session_ids.txt in the source tree. | |
| _SOURCE_AGENT_SESSION_IDS_TXT_RELPATH = ( | |
| pathlib.Path("..") | |
| / ".." | |
| / ".." | |
| / "tools" | |
| / "devshell" | |
| / "lib" | |
| / "agent_session_ids.txt" | |
| ) | |
| def _get_source_agents_txt_path( | |
| from_file: str | pathlib.Path, | |
| ) -> pathlib.Path: | |
| """Resolve the path to tools/devshell/lib/agents.txt relative to the given source file.""" | |
| base_file = pathlib.Path(from_file).resolve() | |
| return (base_file.parent / _SOURCE_AGENTS_TXT_RELPATH).resolve() | |
| def _get_source_agent_session_ids_txt_path( | |
| from_file: str | pathlib.Path, | |
| ) -> pathlib.Path: | |
| """Resolve the path to tools/devshell/lib/agent_session_ids.txt relative to the given source file.""" | |
| base_file = pathlib.Path(from_file).resolve() | |
| return (base_file.parent / _SOURCE_AGENT_SESSION_IDS_TXT_RELPATH).resolve() | |
| def _read_vars_file( | |
| resource_name: str, source_path: pathlib.Path | |
| ) -> typing.List[str]: | |
| if data is not None: | |
| try: | |
| with files(data).joinpath(resource_name).open( | |
| "r", encoding="utf-8" | |
| ) as f: | |
| return [ | |
| line.strip() | |
| for line in f | |
| if line.strip() and not line.strip().startswith("#") | |
| ] | |
| except (FileNotFoundError, TypeError): | |
| # importlib.resources.files() raises TypeError if `data` is not a | |
| # package (e.g. when mocked in tests or when imported outside a | |
| # packaged environment), and open() raises FileNotFoundError if | |
| # the file is missing from the package resources. In either case, | |
| # fall through to reading the file directly from the source tree. | |
| pass | |
| # Fallback to source tree location if imported without GN packaging. | |
| if source_path.is_file(): | |
| with source_path.open("r", encoding="utf-8") as f: | |
| return [ | |
| line.strip() | |
| for line in f | |
| if line.strip() and not line.strip().startswith("#") | |
| ] | |
| raise FileNotFoundError( | |
| f"Could not locate {resource_name} in packaged resources or at {source_path}" | |
| ) | |
| def get_agent_session_id_env_vars() -> typing.List[str]: | |
| """Read the list of agent session ID environment variable names from agent_session_ids.txt.""" | |
| return _read_vars_file( | |
| "agent_session_ids.txt", | |
| _get_source_agent_session_ids_txt_path(__file__), | |
| ) | |
| def get_agent_env_vars() -> typing.List[str]: | |
| """Read the list of agent environment variable names from agents.txt and agent_session_ids.txt.""" | |
| agent_vars = _read_vars_file( | |
| "agents.txt", _get_source_agents_txt_path(__file__) | |
| ) | |
| for var in get_agent_session_id_env_vars(): | |
| if var not in agent_vars: | |
| agent_vars.append(var) | |
| return agent_vars | |
| def is_invoked_by_agent(env: typing.Mapping[str, str] | None = None) -> bool: | |
| """Determine if the given environment (or os.environ) indicates execution by an AI agent. | |
| Args: | |
| env: Optional mapping representing the environment. Defaults to os.environ. | |
| Returns: | |
| bool: True if an agent environment variable is present, False otherwise. | |
| """ | |
| if env is None: | |
| env = os.environ | |
| for var in get_agent_env_vars(): | |
| if env.get(var) is not None: | |
| return True | |
| return False |