com.l1fe.forge:forge-agent

import com.l1fe.forge.agent.*

public data class AgentConfig(
val name: String,
val model: LanguageModel,
val tools: List<ToolDefinition>;

public data class AgentSummary(
val name: String,
val state: LifecycleState,
val healthStatus: HealthStatus,
)

/**
* An agent that wraps the ANVIL tool loop with lifecycle management.
*
* Manages the full lifecycle per ANVIL Spec Section 13.2:
* Initializing -> Ready -> Running -> Ready (idle) or Terminated.
* The agent must be initialized before running, and can be terminated
* when no longer needed.
*
* ANVIL Spec Section 10.2
*
* @param config The agent configuration.
*/
public class ToolLoopAgent(
private val config: AgentConfig,
)

public class ToolLoopAgent(
private val config: AgentConfig,
)

public val name: String get();

public val state: LifecycleState get();

public val health: HealthProfile get();

public fun initialize()

public suspend fun run(
messages: List<ModelMessage>,
additionalStopConditions: List<StopCondition>;

public fun pause()

public fun resume()

public fun terminate(reason: String;

public fun summary(): AgentSummary;

public sealed class ForgeAgentError(
message: String,
cause: Throwable?;

public class MaxIterationsExceeded(
public val maxIterations: Int,
public val completedIterations: Int,
) : ForgeAgentError(
"tool loop exceeded maximum iterations: completed $completedIterations " +
"of $maxIterations allowed (see ANVIL Spec SS10.1)"
)

/**
* The tool loop exceeded the maximum total token budget.
*
* @property maxTokens The configured maximum token budget.
* @property consumedTokens The number of tokens consumed before the limit.
*/
public class MaxTokensExceeded(
public val maxTokens: Long,
public val consumedTokens: Long,
) : ForgeAgentError(
"tool loop exceeded maximum token budget: consumed $consumedTokens " +
"tokens of $maxTokens allowed"
)

/**
* A tool referenced by the model was not found in the registry.
*
* @property toolName The name of the tool that was not found.

public val maxIterations: Int,
public val completedIterations: Int,
) : ForgeAgentError(
"tool loop exceeded maximum iterations: completed $completedIterations " +
"of $maxIterations allowed (see ANVIL Spec SS10.1)"
)

/**
* The tool loop exceeded the maximum total token budget.
*
* @property maxTokens The configured maximum token budget.
* @property consumedTokens The number of tokens consumed before the limit.
*/
public class MaxTokensExceeded(
public val maxTokens: Long,
public val consumedTokens: Long,
) : ForgeAgentError(
"tool loop exceeded maximum token budget: consumed $consumedTokens " +
"tokens of $maxTokens allowed"
)

/**
* A tool referenced by the model was not found in the registry.
*
* @property toolName The name of the tool that was not found.
* @property available The list of registered tool names.

public val completedIterations: Int,
) : ForgeAgentError(
"tool loop exceeded maximum iterations: completed $completedIterations " +
"of $maxIterations allowed (see ANVIL Spec SS10.1)"
)

/**
* The tool loop exceeded the maximum total token budget.
*
* @property maxTokens The configured maximum token budget.
* @property consumedTokens The number of tokens consumed before the limit.
*/
public class MaxTokensExceeded(
public val maxTokens: Long,
public val consumedTokens: Long,
) : ForgeAgentError(
"tool loop exceeded maximum token budget: consumed $consumedTokens " +
"tokens of $maxTokens allowed"
)

/**
* A tool referenced by the model was not found in the registry.
*
* @property toolName The name of the tool that was not found.
* @property available The list of registered tool names.
*/

public class MaxTokensExceeded(
public val maxTokens: Long,
public val consumedTokens: Long,
) : ForgeAgentError(
"tool loop exceeded maximum token budget: consumed $consumedTokens " +
"tokens of $maxTokens allowed"
)

/**
* A tool referenced by the model was not found in the registry.
*
* @property toolName The name of the tool that was not found.
* @property available The list of registered tool names.
*/
public class ToolNotFound(
public val toolName: String,
public val available: List<String>,
) : ForgeAgentError(
"tool '$toolName' not found in registry; " +

public val maxTokens: Long,
public val consumedTokens: Long,
) : ForgeAgentError(
"tool loop exceeded maximum token budget: consumed $consumedTokens " +
"tokens of $maxTokens allowed"
)

/**
* A tool referenced by the model was not found in the registry.
*
* @property toolName The name of the tool that was not found.
* @property available The list of registered tool names.
*/
public class ToolNotFound(
public val toolName: String,
public val available: List<String>,
) : ForgeAgentError(
"tool '$toolName' not found in registry; " +

public val consumedTokens: Long,
) : ForgeAgentError(
"tool loop exceeded maximum token budget: consumed $consumedTokens " +
"tokens of $maxTokens allowed"
)

/**
* A tool referenced by the model was not found in the registry.
*
* @property toolName The name of the tool that was not found.
* @property available The list of registered tool names.
*/
public class ToolNotFound(
public val toolName: String,
public val available: List<String>,
) : ForgeAgentError(
"tool '$toolName' not found in registry; " +

public class ToolNotFound(
public val toolName: String,
public val available: List<String>,
) : ForgeAgentError(
"tool '$toolName' not found in registry; " +

public val toolName: String,
public val available: List<String>,
) : ForgeAgentError(
"tool '$toolName' not found in registry; " +

public val available: List<String>,
) : ForgeAgentError(
"tool '$toolName' not found in registry; " +

public class ToolExecutionFailed(
public val toolName: String,
public val reason: String,
cause: Throwable?;

public val toolName: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class ModelError(
public val detail: String,
cause: Throwable?;

public val detail: String,
cause: Throwable?;

public class InvalidState(
public val currentState: String,
public val requiredState: String,
) : ForgeAgentError(
"agent is in state '$currentState' but must be in '$requiredState' to perform this operation"
)

/**
* A workflow step failed.
*
* @property stepIndex The index of the failed step.
* @property stepName The name of the failed step (if available).
* @property reason The failure reason.
*/
public class WorkflowStepFailed(
public val stepIndex: Int,
public val stepName: String,
public val reason: String,
cause: Throwable?;

public val currentState: String,
public val requiredState: String,
) : ForgeAgentError(
"agent is in state '$currentState' but must be in '$requiredState' to perform this operation"
)

/**
* A workflow step failed.
*
* @property stepIndex The index of the failed step.
* @property stepName The name of the failed step (if available).
* @property reason The failure reason.
*/
public class WorkflowStepFailed(
public val stepIndex: Int,
public val stepName: String,
public val reason: String,
cause: Throwable?;

public val requiredState: String,
) : ForgeAgentError(
"agent is in state '$currentState' but must be in '$requiredState' to perform this operation"
)

/**
* A workflow step failed.
*
* @property stepIndex The index of the failed step.
* @property stepName The name of the failed step (if available).
* @property reason The failure reason.
*/
public class WorkflowStepFailed(
public val stepIndex: Int,
public val stepName: String,
public val reason: String,
cause: Throwable?;

public class WorkflowStepFailed(
public val stepIndex: Int,
public val stepName: String,
public val reason: String,
cause: Throwable?;

public val stepIndex: Int,
public val stepName: String,
public val reason: String,
cause: Throwable?;

public val stepName: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class DelegationFailed(
public val parentDid: String,
public val reason: String,
cause: Throwable?;

public val parentDid: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class MessagingError(
public val channelId: String,
public val reason: String,
) : ForgeAgentError("messaging error on channel '$channelId': $reason")
}

public val channelId: String,
public val reason: String,
) : ForgeAgentError("messaging error on channel '$channelId': $reason")
}

public val reason: String,
) : ForgeAgentError("messaging error on channel '$channelId': $reason")
}

public enum class AgentStopReason

public fun interface StopCondition

public fun evaluate(context: LoopContext): StopDecision
}

/**
* The decision from a [StopCondition] evaluation.
*
* @property shouldStop Whether the loop should stop.
* @property reason The stop reason (only meaningful if [shouldStop] is `true`).
* @property detail A human-readable detail message.
*/
public data class StopDecision(
val shouldStop: Boolean,
val reason: AgentStopReason,
val detail: String;

public data class StopDecision(
val shouldStop: Boolean,
val reason: AgentStopReason,
val detail: String;

public fun continueLoop(): StopDecision =

public fun stop(reason: AgentStopReason, detail: String;

public data class LoopContext(
val iteration: Int,
val totalTokens: Long,
val lastFinishReason: FinishReason?,
val terminated: Boolean;

public fun maxIterations(max: Int): StopCondition;

public fun maxTotalTokens(max: Long): StopCondition;

public fun modelStopsNaturally(): StopCondition;

public fun evaluateStopConditions(
conditions: List<StopCondition>,
context: LoopContext,
): StopDecision

public data class AgentMessage<T>(
val senderId: String,
val recipientId: String,
val payload: T,
val correlationId: String?;

public class AgentChannel<T>(
public val channelId: String,
capacity: Int;

public val channelId: String,
capacity: Int;

public suspend fun send(message: AgentMessage<T>)

public suspend fun receive(): AgentMessage<T>

public suspend fun receiveOrNull(timeoutMs: Long): AgentMessage<T>?

public fun trySend(message: AgentMessage<T>): Boolean

public fun tryReceive(): AgentMessage<T>?

public fun close()

public data class SubAgentConfig(
val name: String,
val model: LanguageModel,
val tools: List<ToolDefinition>;

public fun createSubAgent(
parent: ToolLoopAgent,
config: SubAgentConfig,
): ToolLoopAgent

public data class ToolLoopConfig(
val maxIterations: Int;

public data class ToolLoopIteration(
val iteration: Int,
val modelResult: GenerateResult,
val toolResults: List<ToolResult>,
)

/**
* The complete output of a tool loop execution.
*
* @property iterations The list of iterations executed.
* @property stopReason Why the tool loop stopped.
* @property totalUsage Cumulative token usage across all iterations.
* @property finalMessage The final model response message.
*/
public data class ToolLoopOutput(
val iterations: List<ToolLoopIteration>,
val stopReason: AgentStopReason,
val totalUsage: Usage,
val finalMessage: ModelMessage?,
)

public data class ToolLoopOutput(
val iterations: List<ToolLoopIteration>,
val stopReason: AgentStopReason,
val totalUsage: Usage,
val finalMessage: ModelMessage?,
)

public fun text(): String?;

public val iterationCount: Int get();

public suspend fun runToolLoop(
model: LanguageModel,
messages: List<ModelMessage>,
tools: List<ToolDefinition>,
executors: Map<String, ToolExecutor>,
config: ToolLoopConfig;

public data class WorkflowStep<T>(
val name: String,
val execute: suspend (T) -> T,
)

/**
* A sequential workflow that executes steps in order.
*
* Each step receives the output of the previous step. If any step
* fails, the workflow fails at that point.
*
* ANVIL Spec Section 10.3.1 -- Sequential Workflow
*
* @param T The type flowing through the workflow steps.
* @property name A human-readable name for the workflow.
* @property steps The ordered list of steps.
*/
public class SequentialWorkflow<T>(
public val name: String,
private val steps: List<WorkflowStep<T>>,
)

public class SequentialWorkflow<T>(
public val name: String,
private val steps: List<WorkflowStep<T>>,
)

public val name: String,
private val steps: List<WorkflowStep<T>>,
)

public suspend fun execute(input: T): T

public val stepCount: Int get();

public class ParallelWorkflow<I, O>(
public val name: String,
private val steps: List<ParallelStep<I, O>>,
)

public val name: String,
private val steps: List<ParallelStep<I, O>>,
)

public suspend fun execute(input: I): List<O>;

public val stepCount: Int get();

public data class ParallelStep<I, O>(
val name: String,
val execute: suspend (I) -> O,
)

/**
* A router workflow that selects a branch based on the input.
*
* The router function examines the input and returns a branch key.
* The corresponding step is then executed.
*
* ANVIL Spec Section 10.3.3 -- Router Workflow
*
* @param T The type flowing through the workflow.
* @property name A human-readable name for the workflow.
* @property router A function that selects a branch key from the input.
* @property branches A map of branch key to workflow step.
* @property fallback An optional default step if no branch matches.
*/
public class RouterWorkflow<T>(
public val name: String,
private val router: suspend (T) -> String,
private val branches: Map<String, WorkflowStep<T>>,
private val fallback: WorkflowStep<T>?;

public class RouterWorkflow<T>(
public val name: String,
private val router: suspend (T) -> String,
private val branches: Map<String, WorkflowStep<T>>,
private val fallback: WorkflowStep<T>?;

public val name: String,
private val router: suspend (T) -> String,
private val branches: Map<String, WorkflowStep<T>>,
private val fallback: WorkflowStep<T>?;

public suspend fun execute(input: T): T

public val branchCount: Int get();