Package io.jenkins.plugins.aiagentjob

Class AiAgentTypeHandler

java.lang.Object

hudson.model.AbstractDescribableImpl<AiAgentTypeHandler>

io.jenkins.plugins.aiagentjob.AiAgentTypeHandler

All Implemented Interfaces:

ExtensionPoint, Describable<AiAgentTypeHandler>

Direct Known Subclasses:

AntigravityAgentHandler, ClaudeCodeAgentHandler, CodexAgentHandler, CursorAgentHandler, GeminiCliAgentHandler, GrokBuildAgentHandler, OpenCodeAgentHandler

public abstract class AiAgentTypeHandler
extends AbstractDescribableImpl<AiAgentTypeHandler>
implements ExtensionPoint

Describable extension point for an AI agent implementation.

Implementations must define:

• getId() — stable identifier
• getDefaultApiKeyEnvVar() — env var for the API key
• buildDefaultCommand(io.jenkins.plugins.aiagentjob.AiAgentConfiguration, java.lang.String) — CLI command to launch the agent
• getLogFormat() — parser for the agent's JSONL output
• getStatsExtractor() — usage stats extractor for the agent's JSONL output

Implementations may optionally override prepareExecution(io.jenkins.plugins.aiagentjob.AiAgentConfiguration, hudson.FilePath, hudson.model.TaskListener) to contribute agent-specific environment setup/cleanup.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	AiAgentTypeHandler.AcpExecutionSpec	Immutable settings for an Agent Client Protocol execution.
static final class	AiAgentTypeHandler.ModelSelection	Immutable runtime model and reasoning-effort selection.

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor	Description
AiAgentTypeHandler()

Method Summary

Modifier and Type	Method	Description
AiAgentTypeHandler.AcpExecutionSpec	buildAcpExecution(AiAgentConfiguration config)	Returns an ACP server command for a bidirectional approval channel, or null when manual approvals are unsupported.
abstract List<String>	buildDefaultCommand(AiAgentConfiguration config, String prompt)
abstract String	getDefaultApiKeyEnvVar()	Default API-key environment variable, or empty when the agent uses node-level auth.
abstract String	getId()	Stable identifier for this agent implementation.
abstract AiAgentLogFormat	getLogFormat()	Returns the log format parser for this agent's JSONL output.
abstract AiAgentStatsExtractor	getStatsExtractor()	Returns the stats extractor for this agent's JSONL output.
protected Set<String>	getSupportedReasoningEfforts()	Reasoning efforts recognized when appended to a model identifier.
AiAgentExecutionCustomization	prepareExecution(AiAgentConfiguration config, FilePath workspace, TaskListener listener)
int	resolveExitCode(int processExitCode, File rawLogFile)	Maps process exit status after complete output has been persisted.
final AiAgentTypeHandler.ModelSelection	resolveModelSelection(String configuredModel, String configuredReasoningEffort)	Resolves the model and optional model:effort shorthand for this handler.
boolean	supportsManualApprovals()	Whether this handler provides a bidirectional Jenkins approval channel.
void	validateExecution(AiAgentConfiguration config)	Rejects unsupported execution settings before any process or temporary file is created.

Methods inherited from class java.lang.Object

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

Methods inherited from interface hudson.model.Describable

getDescriptor

Constructor Details

AiAgentTypeHandler

public AiAgentTypeHandler()

Method Details

getId

public abstract String getId()

Stable identifier for this agent implementation.

getDefaultApiKeyEnvVar

public abstract String getDefaultApiKeyEnvVar()

Default API-key environment variable, or empty when the agent uses node-level auth.

validateExecution

public void validateExecution(AiAgentConfiguration config)

Rejects unsupported execution settings before any process or temporary file is created.

supportsManualApprovals

public boolean supportsManualApprovals()

Whether this handler provides a bidirectional Jenkins approval channel.

getSupportedReasoningEfforts

protected Set<String> getSupportedReasoningEfforts()

Reasoning efforts recognized when appended to a model identifier.

resolveModelSelection

public final AiAgentTypeHandler.ModelSelection resolveModelSelection(String configuredModel,
 String configuredReasoningEffort)

Resolves the model and optional model:effort shorthand for this handler.

buildDefaultCommand

public abstract List<String> buildDefaultCommand(AiAgentConfiguration config,
 String prompt)

buildAcpExecution

public AiAgentTypeHandler.AcpExecutionSpec buildAcpExecution(AiAgentConfiguration config)

Returns an ACP server command for a bidirectional approval channel, or null when manual approvals are unsupported.

prepareExecution

public AiAgentExecutionCustomization prepareExecution(AiAgentConfiguration config,
 FilePath workspace,
 TaskListener listener)
                                               throws IOException,
InterruptedException

Throws:

IOException

InterruptedException

resolveExitCode

public int resolveExitCode(int processExitCode,
 File rawLogFile)
                    throws IOException

Maps process exit status after complete output has been persisted. Agents that report terminal failures while exiting zero can override this method.

Throws:

IOException

getLogFormat

public abstract AiAgentLogFormat getLogFormat()

Returns the log format parser for this agent's JSONL output.

The returned format's AiAgentLogFormat.classify(long, net.sf.json.JSONObject) method should return null for any JSON it does not recognise, so the parser can fall through to the shared format and generic fallback.

getStatsExtractor

public abstract AiAgentStatsExtractor getStatsExtractor()

Returns the stats extractor for this agent's JSONL output.

The returned extractor's AiAgentStatsExtractor.extract(net.sf.json.JSONObject, io.jenkins.plugins.aiagentjob.AgentUsageStats) method should return false for any JSON it does not recognise, so the shared extractor handles it as a fallback.