{
  "name": "@forge-sdk/health",
  "language": "typescript",
  "version": "0.1.0",
  "description": "ANVIL health profiles, lifecycle state machine, and monitoring for the Forge SDK.",
  "manifest": "forge-ts/packages/forge-health/package.json",
  "manifestSha256": "9a70dea1100262e1ffb3a6a78606385e4d1bd24aef77ad683c289b43a280b179",
  "status": "source-reference",
  "registryPublicationVerified": false,
  "route": "/libraries/typescript/health",
  "features": {},
  "files": [
    {
      "path": "forge-ts/packages/forge-health/src/error.ts",
      "sha256": "63e498097776b9282ffba0e30e040471d25a75b9834436d0439407718e0473d4",
      "artifactSha256": "06b0c146f9043c6c5b1ac82a5c7f4da613c6f8737ae3b149112e049b3faa8380",
      "url": "/reference/source/forge-ts/packages/forge-health/src/error.ts.txt",
      "declarations": [
        {
          "name": "export const ForgeHealthErrorCode = {",
          "line": 21,
          "signature": "export const ForgeHealthErrorCode /* type inferred in source */;",
          "documentation": "Error codes for forge-health operations.\n\nEach code maps to a specific category of failure."
        },
        {
          "name": "ForgeHealthErrorCodeType",
          "line": 31,
          "signature": "export type ForgeHealthErrorCodeType =\n  (typeof ForgeHealthErrorCode)[keyof typeof ForgeHealthErrorCode];",
          "documentation": "A forge-health error code value."
        },
        {
          "name": "ForgeHealthError",
          "line": 52,
          "signature": "export class ForgeHealthError extends Error {\n  readonly code: ForgeHealthErrorCodeType;\n  readonly from?: LifecycleStateType;\n  readonly to?: LifecycleStateType;\n  static invalidTransition(\n    from: LifecycleStateType,\n    to: LifecycleStateType,\n    reason: string\n  ): ForgeHealthError;\n  static invalidState(state: LifecycleStateType, reason: string): ForgeHealthError;\n  static monitorError(reason: string): ForgeHealthError;\n}",
          "documentation": "Error type for lifecycle, health profile, and monitoring operations.\n\nEvery instance includes actionable context: what failed, why, and what the\ndeveloper should check. No generic \"something went wrong\" messages."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-health/src/events.ts",
      "sha256": "eeb71ad2c8428019f13e28dde3da71ff5b07913759ae34c5435f887af94c6459",
      "artifactSha256": "2b5f96c454f96b495aff216e3e865b468a57b984a2914921d395846fb1bbe5fa",
      "url": "/reference/source/forge-ts/packages/forge-health/src/events.ts.txt",
      "declarations": [
        {
          "name": "LifecycleEvent",
          "line": 54,
          "signature": "export class LifecycleEvent {\n  readonly transition: LifecycleTransition;\n  readonly agentDid: string | undefined;\n  readonly metadata: Record<string, unknown> | undefined;\n  static create(transition: LifecycleTransition): LifecycleEvent;\n  static withAgentDid(transition: LifecycleTransition, agentDid: string): LifecycleEvent;\n  withMetadata(metadata: Record<string, unknown>): LifecycleEvent;\n  toJSON(): Record<string, unknown>;\n}",
          "documentation": "A lifecycle event emitted when an agent transitions between states.\n\nLifecycle events are the primary mechanism for tracking agent state changes.\nThey are:\n- Emitted via the telemetry system as structured events\n- Recorded in the agent's audit trail\n- Signed by the agent's Ed25519 key (when identity is available)\n\nPer ANVIL Spec section 14.2, every lifecycle transition is recorded as an\naudit trail entry with the following data:\n- From state and to state\n- Timestamp\n- Agent DID\n- Optional metadata (e.g., error details for transitions to Error state)"
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-health/src/index.ts",
      "sha256": "ef9c74ad4983109e41313ece4899397fd8b07be9b538528745f05b419f449590",
      "artifactSha256": "a3fbad077256c53efcdd79f173c896979ebe0915b930396c03778565ce025558",
      "url": "/reference/source/forge-ts/packages/forge-health/src/index.ts.txt",
      "declarations": [
        {
          "name": "export {",
          "line": 24,
          "signature": "export {\n  LifecycleState,\n  type LifecycleStateType,\n  validTransitions,\n  isTerminal,\n  isOperational,\n  type LifecycleTransition,\n  LifecycleError,\n  LifecycleManager,\n} from './lifecycle.js';",
          "documentation": ""
        },
        {
          "name": "export { HealthProfile } from './profile.js';",
          "line": 36,
          "signature": "export { HealthProfile } from './profile.js';",
          "documentation": ""
        },
        {
          "name": "export { LifecycleEvent } from './events.js';",
          "line": 39,
          "signature": "export { LifecycleEvent } from './events.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 42,
          "signature": "export {\n  type HealthThresholds,\n  defaultHealthThresholds,\n  HealthMonitor,\n} from './monitoring.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 49,
          "signature": "export {\n  type HealthStatus,\n  healthy,\n  degraded,\n  critical,\n  isHealthy,\n  isCritical,\n  reasons,\n  HealthReport,\n} from './reporting.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 61,
          "signature": "export {\n  ForgeHealthErrorCode,\n  type ForgeHealthErrorCodeType,\n  ForgeHealthError,\n} from './error.js';",
          "documentation": ""
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-health/src/lifecycle.ts",
      "sha256": "5e78896b75c650331cd021c89be288c4112eaf7e690d1bfedb3b3cdc3e3af788",
      "artifactSha256": "94742ba5e67d573730980b374144c17ad8a96e6b79760d2b67822b40b6663ec7",
      "url": "/reference/source/forge-ts/packages/forge-health/src/lifecycle.ts.txt",
      "declarations": [
        {
          "name": "export const LifecycleState = {",
          "line": 26,
          "signature": "export const LifecycleState /* type inferred in source */;",
          "documentation": "ANVIL lifecycle states.\n\nThese six states and their valid transitions are **immutable** per\nANVIL Spec section 13.2. No states may be added, removed, or have their\ntransition rules changed without a formal specification amendment.\n\nMigration note: The previous 7-state model (Created, Initializing, Active,\nSuspended, Terminating, Terminated, Error) has been replaced with this\n6-state model per ANVIL Spec v2."
        },
        {
          "name": "LifecycleStateType",
          "line": 42,
          "signature": "export type LifecycleStateType = (typeof LifecycleState)[keyof typeof LifecycleState];",
          "documentation": "A lifecycle state value."
        },
        {
          "name": "validTransitions",
          "line": 86,
          "signature": "export function validTransitions(state: LifecycleStateType): readonly LifecycleStateType[];",
          "documentation": "Returns the set of valid target states from the given state."
        },
        {
          "name": "isTerminal",
          "line": 98,
          "signature": "export function isTerminal(state: LifecycleStateType): boolean;",
          "documentation": "Returns `true` if the given state is a terminal state (no outgoing transitions).\n\nCurrently, only `Terminated` is a terminal state."
        },
        {
          "name": "isOperational",
          "line": 112,
          "signature": "export function isOperational(state: LifecycleStateType): boolean;",
          "documentation": "Returns `true` if the agent can perform work in the given state.\n\nBoth `Ready` and `Running` states are operational per ANVIL Spec section 13.2.\n`Ready` means the agent can accept new work; `Running` means the agent is\nactively processing."
        },
        {
          "name": "LifecycleTransition",
          "line": 123,
          "signature": "export interface LifecycleTransition {\n  /** The state before the transition. */\n  readonly from: LifecycleStateType;\n  /** The state after the transition. */\n  readonly to: LifecycleStateType;\n  /** The UTC timestamp when the transition occurred. */\n  readonly timestamp: Timestamp;\n}",
          "documentation": "A record of a single lifecycle state transition.\n\nEvery transition is timestamped and stored in the LifecycleManager's\nhistory. Transitions are emitted as telemetry events and recorded in the\nagent's audit trail."
        },
        {
          "name": "LifecycleError",
          "line": 137,
          "signature": "export class LifecycleError extends Error {\n  readonly from: LifecycleStateType;\n  readonly to: LifecycleStateType;\n  constructor(from: LifecycleStateType, to: LifecycleStateType, reason: string);\n}",
          "documentation": "Error thrown when an invalid lifecycle transition is attempted.\n\nSee ANVIL Spec section 13.2 for the complete transition table."
        },
        {
          "name": "LifecycleManager",
          "line": 174,
          "signature": "export class LifecycleManager {\n  constructor();\n  get state(): LifecycleStateType;\n  get history(): readonly LifecycleTransition[];\n  transition(target: LifecycleStateType): LifecycleTransition;\n  canTransitionTo(target: LifecycleStateType): boolean;\n  validTransitions(): readonly LifecycleStateType[];\n}",
          "documentation": "Manages the ANVIL lifecycle state machine for a single agent.\n\nThe LifecycleManager enforces the immutable transition table from ANVIL Spec\nsection 13.2. It tracks the current state, validates all transitions, and\nmaintains a complete transition history."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-health/src/monitoring.ts",
      "sha256": "96b5feb299fbd89165168114311770588854b596322851e9a3d38bcd7ac3626a",
      "artifactSha256": "6686b84b90a4b57a50d74b9ac7af7a6585fe651aebe1882364d00a3efc981270",
      "url": "/reference/source/forge-ts/packages/forge-health/src/monitoring.ts.txt",
      "declarations": [
        {
          "name": "HealthThresholds",
          "line": 46,
          "signature": "export interface HealthThresholds {\n  /**\n   * Maximum acceptable error rate in errors per minute.\n   *\n   * When the computed error rate exceeds this threshold, the agent's\n   * health status becomes Degraded or Critical.\n   */\n  readonly maxErrorRate: number;\n\n  /**\n   * Maximum acceptable CPU usage percentage (0.0 to 100.0).\n   *\n   * When CPU usage exceeds this threshold, the agent's health status\n   * becomes Degraded.\n   */\n  readonly maxCpuPercent: number;\n\n  /**\n   * Maximum acceptable memory usage in bytes.\n   *\n   * When memory usage exceeds this threshold, the agent's health status\n   * becomes Critical.\n   */\n  readonly maxMemoryBytes: number;\n\n  /**\n   * Maximum acceptable inference latency in milliseconds.\n   *\n   * This threshold is informational -- it is reported in the health status\n   * reasons but does not directly cause status changes since latency is\n   * not tracked in the profile (it would require per-call timing).\n   */\n  readonly maxInferenceLatencyMs: number;\n}",
          "documentation": ""
        },
        {
          "name": "defaultHealthThresholds",
          "line": 98,
          "signature": "export function defaultHealthThresholds(): HealthThresholds;",
          "documentation": "Returns the default health thresholds.\n\nDefaults:\n- maxErrorRate: 10.0 errors per minute\n- maxCpuPercent: 90.0%\n- maxMemoryBytes: 4 GB (4,294,967,296 bytes)\n- maxInferenceLatencyMs: 5000 ms"
        },
        {
          "name": "HealthMonitor",
          "line": 132,
          "signature": "export class HealthMonitor {\n  readonly profile: HealthProfile;\n  readonly thresholds: HealthThresholds;\n  constructor(thresholds: HealthThresholds);\n  checkHealth(): HealthStatus;\n}",
          "documentation": ""
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-health/src/profile.ts",
      "sha256": "1bf459b6e003ea620d596a93680a9427fd13659c8993d0e80ac6b9f7cc5c74c1",
      "artifactSha256": "d49270f424422e5360a2a45ec0b63977c9cd29c2025bd48bbfe485a5a3fcd967",
      "url": "/reference/source/forge-ts/packages/forge-health/src/profile.ts.txt",
      "declarations": [
        {
          "name": "HealthProfile",
          "line": 56,
          "signature": "export class HealthProfile {\n  uptimeSeconds: number;\n  errorCount: number;\n  toolInvocations: number;\n  inferenceCalls: number;\n  inferenceTokens: number;\n  cpuUsagePercent: number;\n  memoryUsageBytes: number;\n  activeTasks: number;\n  completedTasks: number;\n  errorRate: number;\n  avgLatencyMs: number;\n  toolSuccessRate: number;\n  generationSuccessRate: number;\n  lastUpdated: Timestamp;\n  constructor();\n  recordToolInvocation(): void;\n  recordInference(tokens: number): void;\n  recordError(): void;\n  updateResources(cpu: number, memory: number): void;\n  updateUptime(seconds: number): void;\n  recordToolSuccess(): void;\n  recordToolFailure(): void;\n  recordGenerationSuccess(): void;\n  recordGenerationFailure(): void;\n  recordInferenceLatency(latencyMs: number): void;\n  startTask(): void;\n  completeTask(): void;\n  toJSON(): Record<string, unknown>;\n  static fromJSON(obj: Record<string, unknown>): HealthProfile;\n}",
          "documentation": "Runtime health metrics for an ANVIL-compliant agent.\n\nThe health profile tracks operational statistics that enable health\nmonitoring, capacity planning, and audit trail generation. All counters\nare monotonically increasing -- they are never reset during an agent's\nlifetime."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-health/src/reporting.ts",
      "sha256": "c0437f725edf2fc0a1356473f4099994d519a36ab2a068cb54690a895139629b",
      "artifactSha256": "26598b4f72699f7f80f39c1498210ef8177bc9e394ff9dfc77849b4466074f4a",
      "url": "/reference/source/forge-ts/packages/forge-health/src/reporting.ts.txt",
      "declarations": [
        {
          "name": "HealthStatus",
          "line": 40,
          "signature": "export type HealthStatus =\n  | { readonly status: 'healthy' }\n  | { readonly status: 'degraded'; readonly reasons: readonly string[] }\n  | { readonly status: 'critical'; readonly reasons: readonly string[] };",
          "documentation": ""
        },
        {
          "name": "healthy",
          "line": 50,
          "signature": "export function healthy(): HealthStatus;",
          "documentation": "Creates a Healthy status."
        },
        {
          "name": "degraded",
          "line": 60,
          "signature": "export function degraded(reasons: string[]): HealthStatus;",
          "documentation": "Creates a Degraded status with the given reasons."
        },
        {
          "name": "critical",
          "line": 70,
          "signature": "export function critical(reasons: string[]): HealthStatus;",
          "documentation": "Creates a Critical status with the given reasons."
        },
        {
          "name": "isHealthy",
          "line": 86,
          "signature": "export function isHealthy(status: HealthStatus): boolean;",
          "documentation": "Returns `true` if the status is Healthy."
        },
        {
          "name": "isCritical",
          "line": 102,
          "signature": "export function isCritical(status: HealthStatus): boolean;",
          "documentation": "Returns `true` if the status is Critical."
        },
        {
          "name": "reasons",
          "line": 118,
          "signature": "export function reasons(status: HealthStatus): readonly string[];",
          "documentation": "Returns the list of reasons, or an empty array if healthy."
        },
        {
          "name": "HealthReport",
          "line": 151,
          "signature": "export class HealthReport {\n  readonly status: HealthStatus;\n  readonly profile: HealthProfile;\n  readonly lifecycleState: LifecycleStateType;\n  readonly generatedAt: Timestamp;\n  constructor(\n    status: HealthStatus,\n    profile: HealthProfile,\n    lifecycleState: LifecycleStateType\n  );\n  toJSON(): Record<string, unknown>;\n}",
          "documentation": "A structured health report combining status, profile, and lifecycle state.\n\nHealth reports are the primary output of the health monitoring system.\nThey are used for:\n- Audit trail entries (signed by the agent's Ed25519 key)\n- Telemetry emission (health check spans)\n- External health check endpoints (e.g., HTTP /health)\n- Lifecycle decision-making (auto-suspend on critical status)"
        }
      ]
    }
  ]
}