Class Chrome

java.lang.Object

uno.anahata.asi.agi.tool.ToolContext

uno.anahata.asi.agi.tool.AnahataToolkit

uno.anahata.asi.yam.tools.browser.AbstractBrowser

uno.anahata.asi.yam.tools.chrome.Chrome

All Implemented Interfaces:

ContextProvider, PropertyChangeSource, Rebindable

public class Chrome
extends AbstractBrowser

A toolkit for web automation and form filling using Chrome and Selenium.

This toolkit manages a fleet of BrowserDrone instances, supporting both headless execution and live connection to the user's active Chrome profiles.

Author:

anahata

Field Summary

Fields inherited from class AbstractBrowser

drones

Modifier and Type	Field	Description
protected final Map<String, BrowserDrone>	drones	The centralized registry mapping drone IDs to their stateful objects.

Fields inherited from class AnahataToolkit

childrenProviders, propertyChangeSupport

Modifier and Type	Field	Description
protected List<ContextProvider>	childrenProviders	The list of child context providers managed by this toolkit.
protected PropertyChangeSupport	propertyChangeSupport	Support for firing property change events.

Fields inherited from class ToolContext

toolkit

Modifier and Type	Field	Description
protected JavaObjectToolkit	toolkit	The toolkit instance that owns this context.

Constructor Summary

Constructors

Constructor	Description
Chrome()	Public constructor to instantiate the Chrome automation toolkit.

Method Summary

Modifier and Type	Method	Description
private String	clearSingletonLockInternal(String userDataDir)	Internal implementation to clear the Chrome Singleton Lock files.
String	connect(String droneId, String profile, Boolean headless, String dataDir, String binaryPath)	Scans the OS process table to find running Chrome instances bound to the requested dataDir.
private String	connectToExistingInternal(BrowserDrone d, int port)	Internal implementation to connect to an existing Chrome instance on a port.
private String	detectActiveProfile(String userDataDir)	Detects which profile is currently active in the user data directory.
private String	detectPortFromFiles(String userDataDir, String profileDir)	Detects the remote debugging port from active profile files.
private String	extractArg(String cmdLine, String argName)	Extracts an argument value from the command line string.
private String	getCommandLine(ProcessHandle p)	Attempts to resolve the full command line of a process.
org.openqa.selenium.WebDriver	getDriver(String droneId)	Resolves the active WebDriver for the requested drone.
private String	getProcessReport()	Generates a human-readable markdown report of all active Chrome processes on the host system.
List<String>	getSystemInstructions()	Gets a list of system instruction strings provided by this context provider.
private boolean	hasLock(File dir)	Checks if a directory contains any active lock files.
private void	initDriver(BrowserDrone d, org.openqa.selenium.chrome.ChromeOptions options, Map<String,String> environment)	Initializes the ChromeDriver instance with specified options and environment.
void	initialize()	Performs initial setup for a newly created toolkit instance.
String	killAll()	Closes all active browser processes.
private String	killAllInternal()	Internal implementation to kill all running Chrome and ChromeDriver processes.
private String	launchProfileChromeInternal(BrowserDrone d, String initialUrl)	Internal implementation to launch Chrome with a specific profile.
List<String>	listTabs(String droneId)	Lists all open tabs/windows in the specified drone.
void	populateMessage(RagMessage ragMessage)	Populates the given RagMessage with dynamic, just-in-time context parts.
private String	resetExitStateInternal(String userDataDir, String profileDir)	Internal implementation to reset Chrome's exit state.

Methods inherited from class AbstractBrowser

clickElement, close, executeScript, fillForm, getPageSource, getPageText, getScreenshot, getStatus, goBack, goForward, inspectForm, locateElementGracefully, navigate, openNewTab, refresh, scrollToElement, switchToTab, waitForElement

Modifier and Type	Method	Description
String	clickElement(String droneId, String identifier)	Performs a stateful click by first attempting to locate the element using a multi-strategy search (ID, Name, Link Text, XPath text content).
String	close(String droneId)	Closes the browser session and removes it from the registry.
Object	executeScript(String droneId, String script)	Executes arbitrary JavaScript in the current browser session.
String	fillForm(String droneId, Map<String,String> data)	Fills a web form with the provided data.
String	getPageSource(String droneId)	Gets the full HTML source of the current page.
String	getPageText(String droneId)	Gets the visible text content of the current page.
String	getScreenshot(String droneId, String name)	Takes a screenshot of the current page and attaches it to the session.
String	getStatus(String droneId)	Gets the current status of the browser driver for a specific drone.
String	goBack(String droneId)	Navigates back in the browser history.
String	goForward(String droneId)	Navigates forward in the browser history.
String	inspectForm(String droneId)	Inspects the current page for input fields and buttons.
protected org.openqa.selenium.WebElement	locateElementGracefully(org.openqa.selenium.WebDriver driver, String identifier)	Helper method to safely locate elements using a cascading fallback strategy.
String	navigate(String droneId, String url)	Navigates the specified drone to a new URL.
String	openNewTab(String droneId, String url)
String	refresh(String droneId)	Refreshes the current page.
String	scrollToElement(String droneId, String identifier)	Scrolls the specified element into view.
String	switchToTab(String droneId, int index)	Switches the active tab/window by its index.
String	waitForElement(String droneId, String cssSelector, int timeoutSeconds)	Safely executes a CSS-based visibility check using WebDriverWait.

Methods inherited from class AnahataToolkit

getChildrenProviders, getDescription, getId, getName, getParentProvider, getPropertyChangeSupport, isEffectivelyProviding, postActivate, rebind

Modifier and Type	Method	Description
List<ContextProvider>	getChildrenProviders()	Gets the list of immediate child context providers.
String	getDescription()	Gets a detailed description of what this context provider does.
String	getId()	Gets the unique identifier for this context provider.
String	getName()	Gets the human-readable name of this context provider.
ContextProvider	getParentProvider()	Gets the parent context provider in the hierarchy, if any.
PropertyChangeSupport	getPropertyChangeSupport()	Gets the PropertyChangeSupport instance for this object.
boolean	isEffectivelyProviding()	Override to also take into consideration the AbstractToolkit.enabled
void	postActivate()	Callback method triggered by the Asi Container once the Agi session has been fully deserialized and associated to the ASI container.
void	rebind()	Rebinds the toolkit after deserialization.

Methods inherited from class ToolContext

addAttachment, addAttachment, addAttachment, addAttachment, error, error, error, getAgi, getApplicationMap, getAsiContainer, getAsiContainerMap, getCall, getExecutorService, getModelId, getModelMessage, getResourceManager, getResponse, getSessionMap, getThreadSafeLogger, getTool, getToolContext, getToolkit, getToolManager, getTurnMap, isToolExecution, log, peekResponse, runAsync

Modifier and Type	Method	Description
void	addAttachment(byte[] data, String mimeType)	Attaches a binary blob to the current tool's response.
void	addAttachment(byte[] data, String mimeType, Path sourcePath)	Attaches a binary blob to the current tool's response with source file path traceability.
void	addAttachment(File file)	Convenience method to attach a file to the current tool's response.
void	addAttachment(Path path)	Convenience method to attach a file from a Path to the current tool's response.
void	error(String message)	Adds an error message to the current tool's response.
void	error(String message, Throwable t)	Adds an error message and exception stack trace to the current tool's response.
void	error(Throwable t)	Adds an exceptions stack trace to the current tool's response.
Agi	getAgi()	Convenience method to get the parent agi container for the current execution.
Map	getApplicationMap()	Gets a static, application-scoped map for sharing objects across all containers in the current JVM.
AbstractAsiContainer	getAsiContainer()	Gets the current ASI container hosting this Agi container is running.
Map	getAsiContainerMap()	Gets a map for sharing objects across all sessions within the current ASI container.
JavaMethodToolCall	getCall()	Convenience method to get the current tool call that initiated this execution.
ExecutorService	getExecutorService()	Convenience method to get the executor service for the current agi session.
String	getModelId()	The id of model that is executing the tool.
AbstractModelMessage	getModelMessage()	The id of model that is executing the tool.
ResourceManager	getResourceManager()	Convenience method to get the application's ResourceManager.
JavaMethodToolResponse	getResponse()	Gets the current tool response from the thread-local context.
Map	getSessionMap()	Gets a shared map for storing state across turns within the current agi session.
Consumer<String>	getThreadSafeLogger()	Gets a thread-safe logging consumer that automatically propagates the current tool execution context whenever a message is logged.
JavaMethodTool	getTool()	Convenience method to get the metadata for the tool currently being executed.
ToolContext	getToolContext()	Returns a thread-safe snapshot of this context.
<T> T	getToolkit(Class<T> toolkitClass)	Retrieves the singleton instance of a registered toolkit class.
ToolManager	getToolManager()	Convenience method to get the application's global ToolManager.
Map	getTurnMap()	Gets a shared map for storing state across turns within the current agi session.
boolean	isToolExecution()	Checks if the current thread or this context instance is associated with an active tool execution.
void	log(String message)	Adds a standard log message to the current tool's response.
protected JavaMethodToolResponse	peekResponse()	Internal helper to retrieve the response if it exists, without throwing an exception.
void	runAsync(String taskName, Runnable task)	Executes a task asynchronously in the session's executor service, automatically propagating the current tool execution context to the background thread.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ContextProvider

getAgi, getContextPosition, getFlattenedHierarchy, getFullyQualifiedId, getHeader, getIconId, getInstructionsTokenCount, getRagTokenCount, isProviding, setParentProvider, setProviding

Modifier and Type	Method	Description
Agi	getAgi()	Gets the parent AGI session this context provider is registered under.
default ContextPosition	getContextPosition()	Gets the designated position of this provider's content in the AI prompt.
default List<ContextProvider>	getFlattenedHierarchy(boolean providingOnly)	Gets a flattened list of this provider and all its descendants in the hierarchy.
default String	getFullyQualifiedId()	Gets the fully qualified ID of this provider, reflecting its position in the hierarchy.
default String	getHeader()	Generates a machine-readable header string for this context provider, used to identify the source of injected context in the final prompt.
default String	getIconId()	Gets an optional icon identifier for this provider.
default int	getInstructionsTokenCount()	Calculates the token count for the system instructions provided by this instance using the active model.
default int	getRagTokenCount()	Calculates the token count for the RAG content provided by this instance using the active model.
boolean	isProviding()	Checks if this context provider is currently active and providing context.
default void	setParentProvider(ContextProvider parent)	Sets the parent context provider for this instance.
default void	setProviding(boolean enabled)	Sets whether this context provider is enabled.

Constructor Details

Chrome

public Chrome()

Public constructor to instantiate the Chrome automation toolkit.

Method Details

initialize

public void initialize()

Performs initial setup for a newly created toolkit instance.

This method is called exactly once by the ToolManager after the toolkit has been instantiated and registered. It provides a clean hook for toolkits to perform one-time initialization logic that requires the tool environment to be fully configured, such as scanning for project instructions or registering default resources.

Implementation details: Disables the toolkit by default to prevent accidental drone spawns in environments without local browsers.

Overrides:

initialize in class AnahataToolkit

getSystemInstructions

public List<String> getSystemInstructions()

Gets a list of system instruction strings provided by this context provider. These are typically prepended to the conversation as high-level guidance.

Provides context-specific instructions to the ASI regarding Chrome automation.

Returns:

A list of system instruction strings.

populateMessage

public void populateMessage(RagMessage ragMessage)

Populates the given RagMessage with dynamic, just-in-time context parts. These parts are appended to the end of the user's prompt (RAG).

Populates the RAG message with current Chrome environment state.

Parameters:

ragMessage - The message to be augmented with context.

connect

public String connect(String droneId,
 String profile,
 Boolean headless,
 String dataDir,
 String binaryPath)
               throws AgiToolException

Scans the OS process table to find running Chrome instances bound to the requested dataDir. If a matching process is found in debug mode, it attaches to the existing port; otherwise, it launches a fresh instance with a dynamic debug port.

Parameters:

droneId - A unique ID for this drone.

profile - An optional profile name (e.g., 'Default', 'Profile 1').

headless - Whether to launch in an invisible headless mode.

dataDir - The path to the user data directory.

binaryPath - Optional absolute path to the chrome executable.

Returns:

A status message confirming the connection.

Throws:

AgiToolException - If the droneId is already in use.

killAll

public String killAll()

Closes all active browser processes.

Specified by:

killAll in class AbstractBrowser

Returns:

A status message describing the cleanup operations.

listTabs

public List<String> listTabs(String droneId)

Lists all open tabs/windows in the specified drone.

Implementations should ideally use native DevTools protocols to avoid forcing window focus and causing screen flickering.

Implementation details: Iterates over all window handles and uses the Chrome DevTools Protocol (CDP) Target.getTargetInfo command to retrieve titles and URLs without forcing window focus. Falls back to standard switchTo().window() if CDP fails.

Specified by:

listTabs in class AbstractBrowser

Parameters:

droneId - The ID of the drone to inspect.

Returns:

A list of strings describing each open tab.

getDriver

public org.openqa.selenium.WebDriver getDriver(String droneId)

Resolves the active WebDriver for the requested drone.

Implementation details: This is an internal lifecycle method. If the connection is lost, concrete implementations should attempt to re-establish it using the cached port and profile data.

Specified by:

getDriver in class AbstractBrowser

Parameters:

droneId - The unique ID of the drone.

Returns:

The active WebDriver, or null if it cannot be resolved.

initDriver

private void initDriver(BrowserDrone d,
 org.openqa.selenium.chrome.ChromeOptions options,
 Map<String,String> environment)

Initializes the ChromeDriver instance with specified options and environment.

Parameters:

d - the browser drone to initialize

options - the ChromeOptions to apply

environment - custom environment variables for the driver service

getProcessReport

private String getProcessReport()

Generates a human-readable markdown report of all active Chrome processes on the host system.

Uses ProcessHandle and OS-specific command line extraction (via /proc on Linux or wmic on Windows) to identify ports and data directories.

Returns:

A markdown string containing process PIDs, modes, and command lines.

getCommandLine

private String getCommandLine(ProcessHandle p)

Attempts to resolve the full command line of a process.

On Linux, this reads directly from /proc/[pid]/cmdline for maximum fidelity. On other platforms or as a fallback, it uses Shell-based queries.

Parameters:

p - The process handle to inspect.

Returns:

The full command line string.

extractArg

private String extractArg(String cmdLine,
 String argName)

Extracts an argument value from the command line string.

Parameters:

cmdLine - the full command line of the process

argName - the argument flag to search for

Returns:

the argument value, or null if not found

detectPortFromFiles

private String detectPortFromFiles(String userDataDir,
 String profileDir)

Detects the remote debugging port from active profile files.

Parameters:

userDataDir - the Chrome user data directory

profileDir - the specific profile directory

Returns:

the port string, or null if undetected

detectActiveProfile

private String detectActiveProfile(String userDataDir)

Detects which profile is currently active in the user data directory.

Parameters:

userDataDir - the Chrome user data directory

Returns:

the profile directory name

hasLock

private boolean hasLock(File dir)

Checks if a directory contains any active lock files.

Parameters:

dir - the directory to check

Returns:

true if a lock is detected, false otherwise

killAllInternal

private String killAllInternal()

Internal implementation to kill all running Chrome and ChromeDriver processes.

Returns:

status message describing the kill count

resetExitStateInternal

private String resetExitStateInternal(String userDataDir,
 String profileDir)

Internal implementation to reset Chrome's exit state.

Parameters:

userDataDir - the Chrome user data directory

profileDir - the specific profile directory

Returns:

status message describing the reset

clearSingletonLockInternal

private String clearSingletonLockInternal(String userDataDir)

Internal implementation to clear the Chrome Singleton Lock files.

Parameters:

userDataDir - the user data directory

Returns:

status message describing the operation

launchProfileChromeInternal

private String launchProfileChromeInternal(BrowserDrone d,
 String initialUrl)

Internal implementation to launch Chrome with a specific profile.

Parameters:

d - the browser drone

initialUrl - optional initial URL to navigate to

Returns:

status message describing the launch

connectToExistingInternal

private String connectToExistingInternal(BrowserDrone d,
 int port)

Internal implementation to connect to an existing Chrome instance on a port.

Parameters:

d - the browser drone

port - the remote debugging port

Returns:

status message of the connection