{"_id":"@agentsforge/healthkit","_rev":"2-3f73a88a80932fcb062362090c6507c9","name":"@agentsforge/healthkit","dist-tags":{"latest":"0.3.1"},"versions":{"0.1.0":{"name":"@agentsforge/healthkit","version":"0.1.0","keywords":["ai","agents","health-monitoring","cluster-management","soul-drift","agentsforge","openclaw","langchain","autogen"],"author":{"name":"Jakebot Labs"},"license":"MIT","_id":"@agentsforge/healthkit@0.1.0","maintainers":[{"name":"jakebotlabs","email":"email.jasonbennett@gmail.com"}],"homepage":"https://agentsforge.dev","bugs":{"url":"https://github.com/Jakebot-ops/agentforge/issues"},"dist":{"shasum":"98828bc0d181f127ba424b255cc6a1b011c88bef","tarball":"https://registry.npmjs.org/@agentsforge/healthkit/-/healthkit-0.1.0.tgz","fileCount":19,"integrity":"sha512-nFIdv8NdA4lvrpV8itooSTB1GvPR/OBLlIZYtWr5PIzoIA0Ib0JsmDc8YONoYmbcKCmOc4V1FnAXsVSpxxNj8Q==","signatures":[{"sig":"MEYCIQDh4EhsWBTMtEOb1c/iYQGgOXvsp8cKie1OqR0bqputtwIhAPl6vC6VeaHdzugWie24kIjOe6px+jCFk4A2sLbFeL73","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42514},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"ad046149aeabd1ae645a8c88d6b7bfd30623486b","scripts":{"test":"echo \"No tests yet\" && exit 0","build":"tsc && tsc -p tsconfig.esm.json","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"jakebotlabs","email":"email.jasonbennett@gmail.com"},"repository":{"url":"git+https://github.com/Jakebot-ops/agentforge.git","type":"git"},"_npmVersion":"10.9.4","description":"Health monitoring and cluster management for AI agents. Monitor soul drift, manage multi-agent clusters, and ensure agent identity preservation.","directories":{},"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^25.3.2"},"peerDependencies":{"yaml":"^2.0.0"},"peerDependenciesMeta":{"yaml":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/healthkit_0.1.0_1772150327867_0.8728135498456058","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@agentsforge/healthkit","version":"0.3.1","description":"Health monitoring and cluster management for AI agents. Monitor soul drift, manage multi-agent clusters, and ensure agent identity preservation.","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc && tsc -p tsconfig.esm.json","typecheck":"tsc --noEmit","test":"echo \"No tests yet\" && exit 0","prepublishOnly":"npm run build"},"keywords":["ai","agents","health-monitoring","cluster-management","soul-drift","agentsforge","openclaw","langchain","autogen"],"author":{"name":"Jakebot Labs"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Jakebot-ops/agentforge.git"},"homepage":"https://agentsforge.dev","bugs":{"url":"https://github.com/Jakebot-ops/agentforge/issues"},"engines":{"node":">=16.0.0"},"devDependencies":{"@types/node":"^25.3.2","typescript":"^5.3.0"},"peerDependencies":{"yaml":"^2.0.0"},"peerDependenciesMeta":{"yaml":{"optional":true}},"_id":"@agentsforge/healthkit@0.3.1","gitHead":"cbb21c044c0c958b67e3bc892b51702828d39f67","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-SZEMwN6jv9YdRbR0ZKAr7ODQVP07z49t4bO+nBoC3MuhvhtTa0CqTCrYU1JKxY7o67ArUviso5MVp/oHozzivg==","shasum":"cbaf681ff29d1626c6f1f36ee623d6cd7248d8bf","tarball":"https://registry.npmjs.org/@agentsforge/healthkit/-/healthkit-0.3.1.tgz","fileCount":19,"unpackedSize":42514,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCOh0uSCaF4ucfVCdJetqWAaO7yj+KO9/oeZl141AHyAAIgbzy82raPiSUOCaJfPTZBqkTJhbxA/FViggDJIYGmBgs="}]},"_npmUser":{"name":"jakebotlabs","email":"email.jasonbennett@gmail.com"},"directories":{},"maintainers":[{"name":"jakebotlabs","email":"email.jasonbennett@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/healthkit_0.3.1_1772650210210_0.799326892539389"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-26T23:58:47.472Z","modified":"2026-03-04T18:50:10.506Z","0.1.0":"2026-02-26T23:58:48.028Z","0.3.1":"2026-03-04T18:50:10.360Z"},"bugs":{"url":"https://github.com/Jakebot-ops/agentforge/issues"},"author":{"name":"Jakebot Labs"},"license":"MIT","homepage":"https://agentsforge.dev","keywords":["ai","agents","health-monitoring","cluster-management","soul-drift","agentsforge","openclaw","langchain","autogen"],"repository":{"type":"git","url":"git+https://github.com/Jakebot-ops/agentforge.git"},"description":"Health monitoring and cluster management for AI agents. Monitor soul drift, manage multi-agent clusters, and ensure agent identity preservation.","maintainers":[{"name":"jakebotlabs","email":"email.jasonbennett@gmail.com"}],"readme":"# @agentsforge/healthkit\n\n[![npm version](https://img.shields.io/npm/v/@agentsforge/healthkit.svg)](https://www.npmjs.com/package/@agentsforge/healthkit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nHealth monitoring and cluster management for AI agents. Monitor soul drift, manage multi-agent clusters, and ensure agent identity preservation.\n\n## Features\n\n- 🧠 **Soul Drift Detection** — Alert when agent identity files lose weight in context\n- 🔄 **Cluster Management** — Deploy and manage multi-agent configurations\n- 📊 **Health Monitoring** — Real-time cluster health status via REST API\n- ⚡ **Local Mode** — Validate configs without running a server\n- 🔌 **Framework Agnostic** — Works with OpenClaw, LangChain, AutoGen, or standalone\n\n## Installation\n\n```bash\nnpm install @agentsforge/healthkit\n\n# Optional: for YAML config support\nnpm install yaml\n```\n\n## Quick Start\n\n### API Mode (with HealthKit server)\n\n```typescript\nimport { HealthKit, ClusterManager } from '@agentsforge/healthkit';\n\n// Connect to HealthKit API\nconst kit = new HealthKit({ host: 'http://localhost:7842' });\n\n// Check cluster health\nconst status = await kit.getStatus();\nconsole.log(status);\n// Output: { status: \"Locked\", drift_risk: \"0%\", header_efficiency: \"94%\" }\n\n// Get soul drift metrics\nconst drift = await kit.getDriftRisk();\nconsole.log(drift.soul_drift_risk); // \"low\" | \"medium\" | \"high\"\n```\n\n### Local Mode (no server required)\n\n```typescript\nimport { ClusterManager } from '@agentsforge/healthkit';\n\nconst config = {\n  cluster_id: \"my-cluster\",\n  agents: [\n    { id: \"main\", identity_path: \"./SOUL.md\", memory_buffer: 4096 },\n    { id: \"helper\", identity_path: \"./AGENTS.md\", memory_buffer: 2048 }\n  ],\n  health_check: {\n    soul_drift_threshold: 0.15\n  }\n};\n\nconst cluster = new ClusterManager(config, { localOnly: true });\n\n// Validate configuration\nconst validation = cluster.validate();\nconsole.log(validation);\n// Output: { valid: true, errors: [], warnings: [] }\n\n// Deploy (in local mode, this validates only)\nconst result = await cluster.deploy();\nconsole.log(result.success); // true\n```\n\n### With YAML Config\n\n```typescript\nimport { ClusterManager } from '@agentsforge/healthkit';\nimport fs from 'fs';\n\n// Load cluster.yaml\nconst yamlContent = fs.readFileSync('./cluster.yaml', 'utf-8');\nconst cluster = new ClusterManager(yamlContent);\n\nawait cluster.deploy();\nconst health = await cluster.getHealthStatus();\nconsole.log(health.status); // \"Locked\"\n```\n\n## API Reference\n\n### HealthKit\n\nREST client for the HealthKit API server.\n\n```typescript\nconst kit = new HealthKit({\n  host: 'http://localhost:7842', // API server URL\n  apiKey: 'optional-api-key',    // For authenticated endpoints\n  timeout: 10000                  // Request timeout (ms)\n});\n\n// Methods\nawait kit.getStatus(): Promise<HealthStatus>\nawait kit.getDriftRisk(threshold?: number): Promise<DriftReport>\nawait kit.checkCluster(configPath?: string): Promise<ClusterReport>\nawait kit.ping(): Promise<boolean>\n```\n\n### ClusterManager\n\nManages multi-agent cluster configuration and health.\n\n```typescript\nconst cluster = new ClusterManager(config, {\n  host: 'http://localhost:7842', // API server URL\n  apiKey: 'optional-api-key',    // For authenticated endpoints\n  localOnly: false               // true = validation only, no API calls\n});\n\n// Methods\ncluster.validate(): ValidationResult\nawait cluster.deploy(): Promise<DeploymentResult>\nawait cluster.getHealthStatus(): Promise<HealthStatus>\ncluster.getConfig(): ClusterConfig\ncluster.getClusterId(): string\ncluster.getAgentIds(): string[]\n```\n\n### loadCluster\n\nConvenience function to create a ClusterManager.\n\n```typescript\nimport { loadCluster } from '@agentsforge/healthkit';\n\nconst cluster = loadCluster(yamlOrJsonString, { localOnly: true });\n```\n\n## cluster.yaml Schema\n\n```yaml\ncluster_id: \"my-cluster\"\n\norchestration:\n  version: \"2026.1-compat\"\n  global_anchors:\n    - path: \"./SOUL.md\"\n      priority: high\n      persistence: locked\n\nagents:\n  - id: \"primary\"\n    identity_path: \"./SOUL.md\"\n    memory_buffer: 4096\n    context_isolation: true\n  \n  - id: \"aux\"\n    identity_path: \"./AGENTS.md\"\n    memory_buffer: 2048\n    context_isolation: false\n\nsync_protocol:\n  mode: \"differential\"          # differential | full | none\n  frequency: \"real-time\"        # real-time | periodic | manual\n\nhealth_check:\n  auto_fix_overflow: true\n  alert_on_soul_drift: true\n  soul_drift_threshold: 0.15    # Alert if identity < 15% of context\n```\n\n## Types\n\n```typescript\ninterface HealthStatus {\n  status: 'Locked' | 'Warning' | 'Critical' | 'Unknown';\n  drift_risk: string;           // \"0%\", \"15%\", etc.\n  header_efficiency: string;    // \"94%\", etc.\n  agents: AgentHealthStatus[];\n  timestamp: string;\n  cluster_id: string;\n}\n\ninterface DriftReport {\n  soul_drift_risk: 'low' | 'medium' | 'high';\n  drift_score: number;          // 0-1, higher = more identity preserved\n  identity_tokens: number;\n  context_tokens: number;\n  threshold: number;\n  alert: boolean;\n  message: string;\n}\n\ninterface ValidationResult {\n  valid: boolean;\n  errors: string[];\n  warnings: string[];\n}\n```\n\n## Soul Drift Explained\n\n**Soul drift** measures how much your agent's identity files (SOUL.md, AGENTS.md) are being diluted by context accumulation (MEMORY.md, conversation history).\n\n```\ndrift_score = identity_tokens / (identity_tokens + context_tokens)\n```\n\n- **drift_score ≥ 0.30**: LOW risk — Identity well preserved\n- **drift_score ≥ 0.15**: MEDIUM risk — Monitor context growth\n- **drift_score < 0.15**: HIGH risk — Agent losing core identity\n\nWhen drift is high, consider:\n- Trimming MEMORY.md\n- Archiving old context\n- Increasing identity file content\n\n## Python Backend\n\nThis package is a TypeScript client for the Python HealthKit API. Install the full stack:\n\n```bash\n# Install AgentForge (includes Python backend)\ncurl -fsSL https://agentsforge.dev/install.sh | bash\n\n# Or manually\npip install agentforge\nagentforge install\n```\n\nStart the API server:\n\n```bash\nagentforge start\n# API available at http://localhost:7842\n```\n\n## Requirements\n\n- Node.js 16+\n- Optional: `yaml` package for YAML config parsing\n- For API mode: Python HealthKit server running\n\n## License\n\nMIT — Free to use, modify, and distribute.\n\n---\n\nBuilt by [Jakebot Labs](https://jakebotlabs.com) · [AgentForge](https://agentsforge.dev) · [GitHub](https://github.com/Jakebot-ops/agentforge)\n","readmeFilename":"README.md"}