@forge-sdk/health

import * as api from '@forge-sdk/health';

export const ForgeHealthErrorCode /* type inferred in source */;

export type ForgeHealthErrorCodeType =
  (typeof ForgeHealthErrorCode)[keyof typeof ForgeHealthErrorCode];

export class ForgeHealthError extends Error {
  readonly code: ForgeHealthErrorCodeType;
  readonly from?: LifecycleStateType;
  readonly to?: LifecycleStateType;
  static invalidTransition(
    from: LifecycleStateType,
    to: LifecycleStateType,
    reason: string
  ): ForgeHealthError;
  static invalidState(state: LifecycleStateType, reason: string): ForgeHealthError;
  static monitorError(reason: string): ForgeHealthError;
}

export class LifecycleEvent {
  readonly transition: LifecycleTransition;
  readonly agentDid: string | undefined;
  readonly metadata: Record<string, unknown> | undefined;
  static create(transition: LifecycleTransition): LifecycleEvent;
  static withAgentDid(transition: LifecycleTransition, agentDid: string): LifecycleEvent;
  withMetadata(metadata: Record<string, unknown>): LifecycleEvent;
  toJSON(): Record<string, unknown>;
}

export {
  LifecycleState,
  type LifecycleStateType,
  validTransitions,
  isTerminal,
  isOperational,
  type LifecycleTransition,
  LifecycleError,
  LifecycleManager,
} from './lifecycle.js';

export { HealthProfile } from './profile.js';

export { LifecycleEvent } from './events.js';

export {
  type HealthThresholds,
  defaultHealthThresholds,
  HealthMonitor,
} from './monitoring.js';

export {
  type HealthStatus,
  healthy,
  degraded,
  critical,
  isHealthy,
  isCritical,
  reasons,
  HealthReport,
} from './reporting.js';

export {
  ForgeHealthErrorCode,
  type ForgeHealthErrorCodeType,
  ForgeHealthError,
} from './error.js';

export const LifecycleState /* type inferred in source */;

export type LifecycleStateType = (typeof LifecycleState)[keyof typeof LifecycleState];

export function validTransitions(state: LifecycleStateType): readonly LifecycleStateType[];

export function isTerminal(state: LifecycleStateType): boolean;

export function isOperational(state: LifecycleStateType): boolean;

export interface LifecycleTransition {
  /** The state before the transition. */
  readonly from: LifecycleStateType;
  /** The state after the transition. */
  readonly to: LifecycleStateType;
  /** The UTC timestamp when the transition occurred. */
  readonly timestamp: Timestamp;
}

export class LifecycleError extends Error {
  readonly from: LifecycleStateType;
  readonly to: LifecycleStateType;
  constructor(from: LifecycleStateType, to: LifecycleStateType, reason: string);
}

export class LifecycleManager {
  constructor();
  get state(): LifecycleStateType;
  get history(): readonly LifecycleTransition[];
  transition(target: LifecycleStateType): LifecycleTransition;
  canTransitionTo(target: LifecycleStateType): boolean;
  validTransitions(): readonly LifecycleStateType[];
}

export interface HealthThresholds {
  /**
   * Maximum acceptable error rate in errors per minute.
   *
   * When the computed error rate exceeds this threshold, the agent's
   * health status becomes Degraded or Critical.
   */
  readonly maxErrorRate: number;

  /**
   * Maximum acceptable CPU usage percentage (0.0 to 100.0).
   *
   * When CPU usage exceeds this threshold, the agent's health status
   * becomes Degraded.
   */
  readonly maxCpuPercent: number;

  /**
   * Maximum acceptable memory usage in bytes.
   *
   * When memory usage exceeds this threshold, the agent's health status
   * becomes Critical.
   */
  readonly maxMemoryBytes: number;

  /**
   * Maximum acceptable inference latency in milliseconds.
   *
   * This threshold is informational -- it is reported in the health status
   * reasons but does not directly cause status changes since latency is
   * not tracked in the profile (it would require per-call timing).
   */
  readonly maxInferenceLatencyMs: number;
}

export function defaultHealthThresholds(): HealthThresholds;

export class HealthMonitor {
  readonly profile: HealthProfile;
  readonly thresholds: HealthThresholds;
  constructor(thresholds: HealthThresholds);
  checkHealth(): HealthStatus;
}

export class HealthProfile {
  uptimeSeconds: number;
  errorCount: number;
  toolInvocations: number;
  inferenceCalls: number;
  inferenceTokens: number;
  cpuUsagePercent: number;
  memoryUsageBytes: number;
  activeTasks: number;
  completedTasks: number;
  errorRate: number;
  avgLatencyMs: number;
  toolSuccessRate: number;
  generationSuccessRate: number;
  lastUpdated: Timestamp;
  constructor();
  recordToolInvocation(): void;
  recordInference(tokens: number): void;
  recordError(): void;
  updateResources(cpu: number, memory: number): void;
  updateUptime(seconds: number): void;
  recordToolSuccess(): void;
  recordToolFailure(): void;
  recordGenerationSuccess(): void;
  recordGenerationFailure(): void;
  recordInferenceLatency(latencyMs: number): void;
  startTask(): void;
  completeTask(): void;
  toJSON(): Record<string, unknown>;
  static fromJSON(obj: Record<string, unknown>): HealthProfile;
}

export type HealthStatus =
  | { readonly status: 'healthy' }
  | { readonly status: 'degraded'; readonly reasons: readonly string[] }
  | { readonly status: 'critical'; readonly reasons: readonly string[] };

export function healthy(): HealthStatus;

export function degraded(reasons: string[]): HealthStatus;

export function critical(reasons: string[]): HealthStatus;

export function isHealthy(status: HealthStatus): boolean;

export function isCritical(status: HealthStatus): boolean;

export function reasons(status: HealthStatus): readonly string[];

export class HealthReport {
  readonly status: HealthStatus;
  readonly profile: HealthProfile;
  readonly lifecycleState: LifecycleStateType;
  readonly generatedAt: Timestamp;
  constructor(
    status: HealthStatus,
    profile: HealthProfile,
    lifecycleState: LifecycleStateType
  );
  toJSON(): Record<string, unknown>;
}