Class Debugger

java.lang.Object

uno.anahata.asi.agi.tool.ToolContext

uno.anahata.asi.agi.tool.AnahataToolkit

uno.anahata.asi.intellij.tools.debugger.Debugger

All Implemented Interfaces:

ContextProvider, PropertyChangeSource, Rebindable

public class Debugger
extends AnahataToolkit

A toolkit for driving the IntelliJ debugger (breakpoints, debug sessions, expression evaluation).

The IntelliJ counterpart of the NetBeans debugger integration. It is built entirely on the platform-agnostic com.intellij.xdebugger API rather than the language-specific (Java/Kotlin) debugger implementations, mirroring the design of the Gradle toolkit: line breakpoints are created against whichever registered XLineBreakpointType accepts a given location, so the toolkit works for any JVM language the running IDE supports without compiling against those plugins' classes. Because xdebugger lives in com.intellij.modules.platform and concrete breakpoint types are contributed by com.intellij.modules.java (both already declared in plugin.xml), no additional plugin dependency is required.

The XDebugger frame/value APIs are asynchronous (results arrive on the debugger's own threads via callbacks); the evaluation and variable-inspection tools bridge that back to the synchronous tool-call model with bounded CountDownLatch waits, so a hung debuggee cannot block a tool call indefinitely.

Author:

anahata

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static final class	Debugger.CapturingValueNode	An XValueNode that captures a value's textual presentation into an AtomicReference and releases a latch, bridging the asynchronous presentation callback to the synchronous evaluate tool.
private static final class	Debugger.CollectingCompositeNode	An XCompositeNode that collects computed children as name = value lines into a StringBuilder, bridging the asynchronous children callback to the synchronous variable-listing tool.
private static final class	Debugger.TextAccumulatingRenderer	An XValuePresentation.XValueTextRenderer that accumulates every rendered fragment into a single string, so a value's rich presentation can be flattened to plain text.

Field Summary

Fields

Modifier and Type	Field	Description
private static final int	DEFAULT_TIMEOUT_SECONDS	The default bounded wait, in seconds, for asynchronous debugger operations.

Fields inherited from class AnahataToolkit

childrenProviders, propertyChangeSupport

Fields inherited from class ToolContext

toolkit

Constructor Summary

Constructors

Constructor	Description
Debugger()	Constructs the Debugger toolkit (instantiated reflectively via its public no-arg constructor).

Method Summary

Modifier and Type	Method	Description
private static <P extends com.intellij.xdebugger.breakpoints.XBreakpointProperties> com.intellij.xdebugger.breakpoints.XLineBreakpoint<P>	addLineBreakpoint(com.intellij.xdebugger.breakpoints.XBreakpointManager mgr, com.intellij.xdebugger.breakpoints.XLineBreakpointType<P> type, com.intellij.openapi.vfs.VirtualFile file, int zeroLine)	Adds a line breakpoint, capturing the breakpoint type's property generic so the wildcard-typed XLineBreakpointType can be passed to XBreakpointManager.addLineBreakpoint(XLineBreakpointType, String, int, T, boolean).
private static void	awaitLatch(CountDownLatch latch, Integer timeoutSeconds, String what)	Waits on a latch for a bounded time, mapping timeout/interruption to an AgiToolException.
String	clearAllBreakpoints()	Removes all line breakpoints across all open projects.
private String	debugConfiguration(com.intellij.openapi.project.Project project, com.intellij.execution.RunnerAndConfigurationSettings settings, Integer timeoutSeconds)	Debugs a resolved configuration, optionally bridging the asynchronous session lifecycle (start → pause/stop) back to a bounded synchronous wait.
String	debugRunConfiguration(String name, Integer timeoutSeconds)	Launches a run configuration under the debugger and (optionally) waits for it to pause or stop.
private static String	describeState(com.intellij.xdebugger.XDebugSession session)	Describes a debug session's runtime state compactly.
String	evaluateExpression(String expression, Integer timeoutSeconds)	Evaluates an expression in the top frame of the current (paused) debug session.
private static com.intellij.xdebugger.breakpoints.XLineBreakpointType<?>	findLineBreakpointType(com.intellij.openapi.vfs.VirtualFile file, int zeroLine, com.intellij.openapi.project.Project project)	Finds the first registered line breakpoint type that accepts the given location.
String	listBreakpoints()	Lists every line breakpoint currently configured across all open projects.
String	listDebugSessions()	Lists the active debug sessions across all open projects and their current state.
String	listFrameVariables(Integer timeoutSeconds)	Lists the variables visible in the top frame of the current (paused) debug session.
private static String	positionOf(com.intellij.xdebugger.XSourcePosition position)	Formats a source position as file:line (1-based), or "unknown" if null.
String	removeLineBreakpoint(String filePath, int line)	Removes any line breakpoint at the given source location.
private com.intellij.xdebugger.XDebugSession	requireCurrentSession()	Returns the current debug session of the first open project that has one.
private com.intellij.xdebugger.XDebugSession	requireSuspendedSession()	Returns the current debug session, requiring it to be suspended (paused).
private com.intellij.openapi.vfs.VirtualFile	resolveFile(String filePath)	Resolves a source file path to a VirtualFile, refreshing the VFS if necessary.
private com.intellij.openapi.project.Project	resolveProjectForFile(com.intellij.openapi.vfs.VirtualFile file)	Resolves the open project best associated with a file (content-root prefix match, else the first open project).
String	resumeDebugSession()	Resumes the current (paused) debug session.
String	setLineBreakpoint(String filePath, int line)	Sets a line breakpoint at the given source location.
String	stepInto()	Steps into the call at the current line in the current (paused) debug session.
String	stepOut()	Steps out of the current method in the current (paused) debug session.
String	stepOver()	Steps over the current line in the current (paused) debug session.
String	stopDebugSession()	Stops (terminates) the current debug session.

Methods inherited from class AnahataToolkit

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

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

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, getSystemInstructions, isProviding, populateMessage, setParentProvider, setProviding

Field Details

DEFAULT_TIMEOUT_SECONDS

private static final int DEFAULT_TIMEOUT_SECONDS

The default bounded wait, in seconds, for asynchronous debugger operations.

See Also:

• Constant Field Values

Constructor Details

Debugger

public Debugger()

Constructs the Debugger toolkit (instantiated reflectively via its public no-arg constructor).

Method Details

listBreakpoints

public String listBreakpoints()

Lists every line breakpoint currently configured across all open projects.

Returns:

a Markdown listing of line breakpoints (file, line, enabled state, condition).

setLineBreakpoint

public String setLineBreakpoint(String filePath,
 int line)
                         throws AgiToolException

Sets a line breakpoint at the given source location.

Parameters:

filePath - the absolute path of the source file.

line - the 1-based line number on which to place the breakpoint.

Returns:

a confirmation message, or a message explaining why no breakpoint could be placed.

Throws:

AgiToolException - if the file cannot be resolved or no project hosts it.

removeLineBreakpoint

public String removeLineBreakpoint(String filePath,
 int line)
                            throws AgiToolException

Removes any line breakpoint at the given source location.

Parameters:

filePath - the absolute path of the source file.

line - the 1-based line number.

Returns:

a confirmation message reporting how many breakpoints were removed.

Throws:

AgiToolException - if the file cannot be resolved or no project hosts it.

clearAllBreakpoints

public String clearAllBreakpoints()

Removes all line breakpoints across all open projects.

Returns:

a confirmation message reporting how many breakpoints were removed.

listDebugSessions

public String listDebugSessions()

Lists the active debug sessions across all open projects and their current state.

Returns:

a Markdown listing of active debug sessions.

debugRunConfiguration

public String debugRunConfiguration(String name,
 Integer timeoutSeconds)
                             throws AgiToolException

Launches a run configuration under the debugger and (optionally) waits for it to pause or stop.

Parameters:

name - the exact run configuration name.

timeoutSeconds - optional bounded wait, in seconds, for the session to pause at a breakpoint or terminate; 0 or null launches asynchronously.

Returns:

a structured summary of the debug launch outcome.

Throws:

AgiToolException - if no configuration with that name exists or the wait is interrupted.

debugConfiguration

private String debugConfiguration(com.intellij.openapi.project.Project project,
 com.intellij.execution.RunnerAndConfigurationSettings settings,
 Integer timeoutSeconds)
                           throws AgiToolException

Debugs a resolved configuration, optionally bridging the asynchronous session lifecycle (start → pause/stop) back to a bounded synchronous wait.

Parameters:

project - the host project.

settings - the configuration to debug.

timeoutSeconds - optional bounded wait in seconds; 0/null is async.

Returns:

a structured launch/outcome summary.

Throws:

AgiToolException - if the wait is interrupted.

resumeDebugSession

public String resumeDebugSession()
                          throws AgiToolException

Resumes the current (paused) debug session.

Returns:

a confirmation message.

Throws:

AgiToolException - if there is no current debug session.

stepOver

public String stepOver()
                throws AgiToolException

Steps over the current line in the current (paused) debug session.

Returns:

a confirmation message.

Throws:

AgiToolException - if there is no current debug session.

stepInto

public String stepInto()
                throws AgiToolException

Steps into the call at the current line in the current (paused) debug session.

Returns:

a confirmation message.

Throws:

AgiToolException - if there is no current debug session.

stepOut

public String stepOut()
               throws AgiToolException

Steps out of the current method in the current (paused) debug session.

Returns:

a confirmation message.

Throws:

AgiToolException - if there is no current debug session.

stopDebugSession

public String stopDebugSession()
                        throws AgiToolException

Stops (terminates) the current debug session.

Returns:

a confirmation message.

Throws:

AgiToolException - if there is no current debug session.

evaluateExpression

public String evaluateExpression(String expression,
 Integer timeoutSeconds)
                          throws AgiToolException

Evaluates an expression in the top frame of the current (paused) debug session.

Parameters:

expression - the expression to evaluate, in the debuggee's language.

timeoutSeconds - optional bounded wait in seconds (default 30).

Returns:

the evaluated value's presentation, or an error message from the evaluator.

Throws:

AgiToolException - if there is no suspended session, no evaluator, or the wait times out.

listFrameVariables

public String listFrameVariables(Integer timeoutSeconds)
                          throws AgiToolException

Lists the variables visible in the top frame of the current (paused) debug session.

Parameters:

timeoutSeconds - optional bounded wait in seconds (default 30).

Returns:

a Markdown listing of name = value pairs for the top-frame variables.

Throws:

AgiToolException - if there is no suspended session or active stack frame, or the wait times out.

addLineBreakpoint

private static <P extends com.intellij.xdebugger.breakpoints.XBreakpointProperties>
com.intellij.xdebugger.breakpoints.XLineBreakpoint<P> addLineBreakpoint(com.intellij.xdebugger.breakpoints.XBreakpointManager mgr,
 com.intellij.xdebugger.breakpoints.XLineBreakpointType<P> type,
 com.intellij.openapi.vfs.VirtualFile file,
 int zeroLine)

Adds a line breakpoint, capturing the breakpoint type's property generic so the wildcard-typed XLineBreakpointType can be passed to XBreakpointManager.addLineBreakpoint(XLineBreakpointType, String, int, T, boolean).

Type Parameters:

P - the breakpoint properties type of type.

Parameters:

mgr - the breakpoint manager.

type - the (capture of the) line breakpoint type.

file - the source file.

zeroLine - the 0-based line number.

Returns:

the created breakpoint.

findLineBreakpointType

private static com.intellij.xdebugger.breakpoints.XLineBreakpointType<?> findLineBreakpointType(com.intellij.openapi.vfs.VirtualFile file,
 int zeroLine,
 com.intellij.openapi.project.Project project)

Finds the first registered line breakpoint type that accepts the given location.

Parameters:

file - the source file.

zeroLine - the 0-based line number.

project - the host project.

Returns:

an accepting breakpoint type, or null if none can be placed there.

resolveFile

private com.intellij.openapi.vfs.VirtualFile resolveFile(String filePath)
                                                  throws AgiToolException

Resolves a source file path to a VirtualFile, refreshing the VFS if necessary.

Parameters:

filePath - the absolute file path.

Returns:

the resolved virtual file.

Throws:

AgiToolException - if the file does not exist.

resolveProjectForFile

private com.intellij.openapi.project.Project resolveProjectForFile(com.intellij.openapi.vfs.VirtualFile file)
                                                            throws AgiToolException

Resolves the open project best associated with a file (content-root prefix match, else the first open project).

Parameters:

file - the source file.

Returns:

the hosting project.

Throws:

AgiToolException - if no project is open.

requireCurrentSession

private com.intellij.xdebugger.XDebugSession requireCurrentSession()
                                                            throws AgiToolException

Returns the current debug session of the first open project that has one.

Returns:

the current debug session.

Throws:

AgiToolException - if there is no current debug session in any open project.

requireSuspendedSession

private com.intellij.xdebugger.XDebugSession requireSuspendedSession()
                                                              throws AgiToolException

Returns the current debug session, requiring it to be suspended (paused).

Returns:

the suspended current debug session.

Throws:

AgiToolException - if there is no current session or it is not suspended.

awaitLatch

private static void awaitLatch(CountDownLatch latch,
 Integer timeoutSeconds,
 String what)
                        throws AgiToolException

Waits on a latch for a bounded time, mapping timeout/interruption to an AgiToolException.

Parameters:

latch - the latch to await.

timeoutSeconds - the optional timeout in seconds (default 30).

what - a short description of the awaited operation, for error messages.

Throws:

AgiToolException - if the wait times out or is interrupted.

describeState

private static String describeState(com.intellij.xdebugger.XDebugSession session)

Describes a debug session's runtime state compactly.

Parameters:

session - the debug session.

Returns:

a short human-readable state description.

positionOf

private static String positionOf(com.intellij.xdebugger.XSourcePosition position)

Formats a source position as file:line (1-based), or "unknown" if null.

Parameters:

position - the source position, possibly null.

Returns:

a compact file:line description.