com.l1fe.forge:forge-health

import com.l1fe.forge.health.*

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

public class InvalidTransition(
public val from: LifecycleState,
public val to: LifecycleState,
public val validTargets: Set<LifecycleState>,
) : ForgeHealthError(
"invalid lifecycle transition from '$

public val from: LifecycleState,
public val to: LifecycleState,
public val validTargets: Set<LifecycleState>,
) : ForgeHealthError(
"invalid lifecycle transition from '$

public val to: LifecycleState,
public val validTargets: Set<LifecycleState>,
) : ForgeHealthError(
"invalid lifecycle transition from '$

public val validTargets: Set<LifecycleState>,
) : ForgeHealthError(
"invalid lifecycle transition from '$

public class ThresholdExceeded(
public val metric: String,
public val currentValue: Long,
public val threshold: Long,
public val severity: String,
) : ForgeHealthError(
"health threshold exceeded for metric '$metric': current value $currentValue " +
"exceeds $severity threshold $threshold"
)
}

public val metric: String,
public val currentValue: Long,
public val threshold: Long,
public val severity: String,
) : ForgeHealthError(
"health threshold exceeded for metric '$metric': current value $currentValue " +
"exceeds $severity threshold $threshold"
)
}

public val currentValue: Long,
public val threshold: Long,
public val severity: String,
) : ForgeHealthError(
"health threshold exceeded for metric '$metric': current value $currentValue " +
"exceeds $severity threshold $threshold"
)
}

public val threshold: Long,
public val severity: String,
) : ForgeHealthError(
"health threshold exceeded for metric '$metric': current value $currentValue " +
"exceeds $severity threshold $threshold"
)
}

public val severity: String,
) : ForgeHealthError(
"health threshold exceeded for metric '$metric': current value $currentValue " +
"exceeds $severity threshold $threshold"
)
}

public enum class HealthStatus

public data class MetricThreshold(
@SerialName("degraded_threshold")
val degradedThreshold: Long,
@SerialName("critical_threshold")
val criticalThreshold: Long,
)

public data class HealthMonitorConfig(
@SerialName("error_count")
val errorCountThreshold: MetricThreshold?;

public val DEFAULT: HealthMonitorConfig;

public data class HealthCheckResult(
val status: HealthStatus,
val details: List<MetricDetail>,
val snapshot: HealthProfileSnapshot,
)

/**
* Status detail for a single metric.
*
* @property metric The metric name.
* @property currentValue The current value.
* @property status The status for this metric.
*/
@Serializable
public data class MetricDetail(
val metric: String,
@SerialName("current_value")
val currentValue: Long,
val status: HealthStatus,
)

/**
* Monitors a [HealthProfile] against configurable thresholds.
*
* ANVIL Spec Section 5.3
*

public data class MetricDetail(
val metric: String,
@SerialName("current_value")
val currentValue: Long,
val status: HealthStatus,
)

/**
* Monitors a [HealthProfile] against configurable thresholds.
*
* ANVIL Spec Section 5.3
*
* @param config The threshold configuration.
*/
public class HealthMonitor(
private val config: HealthMonitorConfig;

public class HealthMonitor(
private val config: HealthMonitorConfig;

public fun check(profile: HealthProfile): HealthCheckResult

public fun status(profile: HealthProfile): HealthStatus;

public data class HealthProfileSnapshot(
@SerialName("inference_count")
val inferenceCount: Long,
@SerialName("total_tokens")
val totalTokens: Long,
@SerialName("tool_invocations")
val toolInvocations: Long,
@SerialName("error_count")
val errorCount: Int,
@SerialName("uptime_ms")
val uptimeMs: Long,
@SerialName("active_tasks")
val activeTasks: Int,
@SerialName("completed_tasks")
val completedTasks: Long,
@SerialName("error_rate")
val errorRate: Double,
@SerialName("avg_latency_ms")
val avgLatencyMs: Double,
@SerialName("tool_success_rate")
val toolSuccessRate: Double,
@SerialName("generation_success_rate")
val generationSuccessRate: Double,
val timestamp: Timestamp,
)


public class HealthProfile

public fun recordInference(tokens: Long)

public fun recordToolInvocation(success: Boolean;

public fun recordGeneration(success: Boolean;

public fun recordError()

public fun recordLatency(latencyMs: Long)

public fun taskStarted()

public fun taskCompleted()

public fun getInferenceCount(): Long;

public fun getTotalTokens(): Long;

public fun getToolInvocations(): Long;

public fun getErrorCount(): Int;

public fun getUptimeMs(): Long;

public fun getActiveTasks(): Int;

public fun getCompletedTasks(): Long;

public fun getErrorRate(): Double

public fun getAvgLatencyMs(): Double

public fun getToolSuccessRate(): Double

public fun getGenerationSuccessRate(): Double

public fun snapshot(): HealthProfileSnapshot;

public fun reset()

public data class LifecycleEvent(
val from: LifecycleState,
val to: LifecycleState,
val reason: String,
val timestamp: Timestamp,
)

/**
* Listener interface for lifecycle transition events.
*
* Implement this to react to agent lifecycle changes (e.g., logging,
* telemetry, audit trail entries).
*/
public fun interface LifecycleListener

public fun interface LifecycleListener

public fun onTransition(event: LifecycleEvent)
}

/**
* Manages the lifecycle state machine for an agent.
*
* Thread-safe. All state reads and transitions are synchronized.
* The manager starts in the [LifecycleState.INITIALIZING] state,
* which is the initial state for all agents per ANVIL Spec Section 13.2.
*
* ANVIL Spec Section 13.2
*
* @param listener Optional listener for transition events.
*/
public class LifecycleManager(
private val listener: LifecycleListener?;

public class LifecycleManager(
private val listener: LifecycleListener?;

public val currentState: LifecycleState
get();

public val transitionHistory: List<LifecycleEvent>
get();

public fun transition(to: LifecycleState, reason: String)

public fun tryTransition(to: LifecycleState, reason: String): Boolean

public val isTerminal: Boolean
get();

public val isOperational: Boolean
get();

public val validTargets: Set<LifecycleState>
get();

public enum class LifecycleState(public val value: String)

public fun isTerminal(): Boolean;

public fun isOperational(): Boolean;

public val VALID_TRANSITIONS: Map<LifecycleState, Set<LifecycleState>>;

public fun validTargets(from: LifecycleState): Set<LifecycleState> =

public fun isValidTransition(from: LifecycleState, to: LifecycleState): Boolean =