{"_id":"@agent-pulse/elizaos-plugin","_rev":"2-4eda0475bbe125ed09840421895aa583","name":"@agent-pulse/elizaos-plugin","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agent-pulse/elizaos-plugin","version":"0.1.0","keywords":["elizaos","plugin","agent-pulse","liveness","base","ethereum"],"license":"MIT","_id":"@agent-pulse/elizaos-plugin@0.1.0","maintainers":[{"name":"consensuscli","email":"openclaw@consensus.run"}],"dist":{"shasum":"b599c4d38b1660c2ed5bde494a1e3c3c59e05d11","tarball":"https://registry.npmjs.org/@agent-pulse/elizaos-plugin/-/elizaos-plugin-0.1.0.tgz","fileCount":4,"integrity":"sha512-64/x6JC1CC96F4k8+C6dFW/Jq+slSMIYivH9G1wpaSgdPaqb5Mxvg7sW1nbixqn/f/HqUwoqW9CW+sSxa+2XJA==","signatures":[{"sig":"MEYCIQCdPNzmekH9wMZCb5QTprXSqGslmxWqGTJCeKcBU3NgUQIhAKQAe7FHVqwJ1uhMPJ8QD2Yblk3zu8rO/u8KPrMmZ2xH","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":136869},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"6426e3445e830e80a39ce72bec20266f61a85d23","scripts":{"dev":"tsup src/index.ts --format esm,cjs --dts --watch","lint":"eslint src --ext .ts","build":"tsup src/index.ts --format esm,cjs --dts --clean","typecheck":"tsc --noEmit"},"_npmUser":{"name":"consensuscli","email":"openclaw@consensus.run"},"_npmVersion":"10.9.4","description":"ElizaOS plugin for Agent Pulse protocol with gate functionality - on-chain liveness signaling","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^3.22.0","viem":"^2.0.0","@elizaos/core":"^1.7.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.3.0","@types/node":"^20.0.0"},"peerDependencies":{"@elizaos/core":"^1.7.0"},"_npmOperationalInternal":{"tmp":"tmp/elizaos-plugin_0.1.0_1770520474177_0.021149476685807134","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agent-pulse/elizaos-plugin","version":"0.1.1","description":"ElizaOS plugin for Agent Pulse protocol with gate functionality - on-chain liveness signaling","type":"module","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","require":"./dist/index.cjs","types":"./dist/index.d.ts"}},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts --clean","dev":"tsup src/index.ts --format esm,cjs --dts --watch","lint":"eslint src --ext .ts","typecheck":"tsc --noEmit"},"dependencies":{"@elizaos/core":"^1.7.0","viem":"^2.0.0","zod":"^3.22.0"},"devDependencies":{"@types/node":"^20.0.0","tsup":"^8.0.0","typescript":"^5.3.0"},"peerDependencies":{"@elizaos/core":"^1.7.0"},"keywords":["elizaos","plugin","agent-pulse","liveness","base","ethereum"],"license":"MIT","_id":"@agent-pulse/elizaos-plugin@0.1.1","gitHead":"47ca298eb25f1964778e70ee805dd3feec82b332","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-smfpMvor0h5EkLBYzTElGzjQTx2t9H5L8dwzKkig/PAuohS6KiwcbSatrdUa8NsSzWz9bUIYe8aItXUX0qwPbQ==","shasum":"441f9173d79e52a96bdd4d25a46d1977267f9a74","tarball":"https://registry.npmjs.org/@agent-pulse/elizaos-plugin/-/elizaos-plugin-0.1.1.tgz","fileCount":4,"unpackedSize":136859,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCkEkjnT6XDxU2kWg4oasHeLsybSjOi+7l8bHroN0eBFQIhAOjESWfw0EUWAyPjQea3o36KeNoo65kkL7lW88arTwg8"}]},"_npmUser":{"name":"consensuscli","email":"openclaw@consensus.run"},"directories":{},"maintainers":[{"name":"consensuscli","email":"openclaw@consensus.run"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/elizaos-plugin_0.1.1_1770548339358_0.1471895116508839"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-08T03:14:34.099Z","modified":"2026-02-08T10:58:59.687Z","0.1.0":"2026-02-08T03:14:34.380Z","0.1.1":"2026-02-08T10:58:59.508Z"},"license":"MIT","keywords":["elizaos","plugin","agent-pulse","liveness","base","ethereum"],"description":"ElizaOS plugin for Agent Pulse protocol with gate functionality - on-chain liveness signaling","maintainers":[{"name":"consensuscli","email":"openclaw@consensus.run"}],"readme":"# @agent-pulse/elizaos-plugin\n\nElizaOS plugin for the [Agent Pulse](https://agentpulse.io) protocol with **gate functionality** for secure agent-to-agent interactions.\n\n## Overview\n\nAgent Pulse is a decentralized liveness protocol where agents prove they're alive by transferring PULSE tokens to a signal sink. This plugin extends the base functionality with **gate capabilities** that validate incoming/outgoing interactions based on on-chain liveness signals.\n\n### Features\n\n- ✅ **Standard Pulse Actions**: Send pulses, check status, monitor protocol health\n- 🔒 **Inbound Gate**: Validates incoming messages from external agents before processing\n- 🚪 **Outbound Gate**: Checks target agent status before sending responses\n- 📊 **v2 Analytics**: Reliability metrics, liveness proofs, global stats, peer correlation\n- ⚙️ **Multiple Modes**: Strict, permissive, and audit modes for different security needs\n\n## Installation\n\n```bash\nnpm install @agent-pulse/elizaos-plugin\n```\n\n## Quick Start\n\n### 1. Add to Your Character File\n\n```json\n{\n  \"name\": \"MyAgent\",\n  \"plugins\": [\"@agent-pulse/elizaos-plugin\"],\n  \"settings\": {\n    \"pulse\": {\n      \"gate\": {\n        \"enabled\": true,\n        \"mode\": \"strict\",\n        \"threshold\": \"24h\"\n      },\n      \"contractAddress\": \"0xe61C615743A02983A46aFF66Db035297e8a43846\",\n      \"chainId\": 84532\n    }\n  }\n}\n```\n\n### 2. Environment Variables (Optional)\n\n```bash\nAGENT_PULSE_RPC_URL=https://sepolia.base.org\nAGENT_PULSE_API_URL=https://api.agentpulse.io\nAGENT_PULSE_TOKEN_ADDRESS=0x21111B39A502335aC7e45c4574Dd083A69258b07\nAGENT_PULSE_REGISTRY_ADDRESS=0xe61C615743A02983A46aFF66Db035297e8a43846\n```\n\n## Gate Configuration\n\nThe gate reads configuration from `character.settings.pulse`:\n\n```json\n{\n  \"settings\": {\n    \"pulse\": {\n      \"gate\": {\n        \"enabled\": true,      // Enable/disable the gate\n        \"mode\": \"strict\",     // \"strict\" | \"permissive\" | \"audit\"\n        \"threshold\": \"24h\"    // Max age for considering agent alive\n      },\n      \"contractAddress\": \"0xe61C615743A02983A46aFF66Db035297e8a43846\",\n      \"chainId\": 84532,\n      \"rpcUrl\": \"https://sepolia.base.org\"  // Optional override\n    }\n  }\n}\n```\n\n### Gate Modes\n\n| Mode | Behavior | Use Case |\n|------|----------|----------|\n| `strict` | Block messages from agents that fail `isAlive()` check | High-security environments |\n| `permissive` | Allow all messages, flag suspicious ones with warnings | Balanced security/UX |\n| `audit` | Always allow, log all checks (dry-run) | Testing and monitoring |\n\n### Threshold Format\n\nThe threshold accepts ISO 8601 duration formats:\n\n- `\"24h\"` - 24 hours\n- `\"1d\"` - 1 day  \n- `\"12h\"` - 12 hours\n- `\"PT6H\"` - 6 hours (ISO format)\n\n## How the Gate Works\n\n### Inbound Gate (Evaluator)\n\nRuns **before all other evaluators** for every message:\n\n1. **Identity Extraction**: Extracts sender's Ethereum address from:\n   - Message text (e.g., \"I'm agent 0x1234...\")\n   - User metadata\n   - Sender ID (if it looks like an address)\n\n2. **Agent Detection**: Determines if sender is likely an agent using heuristics:\n   - Contains Ethereum addresses\n   - Agent-specific keywords (pulse, stake, smart contract)\n   - Agent-like metadata markers\n\n3. **IsAlive Check**: Calls Pulse API to verify:\n   - Is the agent registered?\n   - When was the last pulse?\n   - Is it within the threshold?\n\n4. **Decision**: Based on mode:\n   - `strict`: Block if not alive\n   - `permissive`: Allow but flag\n   - `audit`: Allow and log\n\n### Outbound Gate (Action Wrapper)\n\nWraps all action handlers to check target agents:\n\n1. **Target Extraction**: Identifies recipient from:\n   - Action options (`targetAddress`)\n   - State from inbound gate (replying to an agent)\n   - Message content\n\n2. **Status Check**: Verifies target's liveness\n\n3. **Action Control**: Blocks or proceeds based on decision\n\n## Edge Cases\n\nThe gate handles these scenarios gracefully:\n\n| Scenario | Behavior |\n|----------|----------|\n| **No pulse settings** | Gate is no-op (disabled), all interactions allowed |\n| **RPC unreachable** | Degrades per mode: strict=block, permissive/audit=allow |\n| **Non-agent user** | Skips gate entirely (humans pass through) |\n| **No identity found** | strict=block, others=skip |\n| **Agent never pulsed** | Treated as not alive (fails check) |\n| **Cache expired** | Re-checks status with 1-minute caching |\n\n## Example Character\n\nSee [example-gated-character.json](./example-gated-character.json) for a complete example of an agent configured with:\n\n- Strict gate mode enabled\n- 24-hour liveness threshold\n- Security-focused personality\n- Helpful responses for verified agents\n\n## Actions\n\n### SEND_PULSE\nSend a liveness pulse to prove the agent is alive.\n\n```\nUser: \"Send a pulse for my agent\"\nAgent: \"✅ Pulse sent successfully! Transaction: 0xabc... Streak: 5\"\n```\n\n### GET_AGENT_STATUS\nGet the current status of an agent.\n\n```\nUser: \"Check my agent status\"\nAgent: \"**Agent Status: 0x742d...0bEb**\n🟢 Alive\n• Last Pulse: 2 hours ago\n• Streak: 🔥 5 days\n• Hazard Score: ✅ 0/100\"\n```\n\n### GET_RELIABILITY (v2 - Paid)\nGet comprehensive reliability metrics.\n\n```\nUser: \"Check reliability\"\nAgent: \"Agent reliability: 92.3%\nUptime: 99.1%\nJitter: 0.08\nHazard Rate: 0.02\"\n```\n\n**Price:** $0.01 USDC\n\n### GET_LIVENESS_PROOF (v2 - Paid)\nGet a cryptographically signed proof of liveness.\n\n```\nUser: \"Get liveness proof\"\nAgent: \"✅ Alive | Proof: eyJhbG...\"\n```\n\n**Price:** $0.005 USDC\n\n### GET_GLOBAL_STATS (v2 - Paid)\nGet network-wide aggregate statistics.\n\n```\nUser: \"Show network stats\"\nAgent: \"Active Agents: 1,500\nAverage Streak: 30.5 days\nNetwork Health: ✅ Healthy\"\n```\n\n**Price:** $0.03 USDC\n\n### GET_PEER_CORRELATION (v2 - Paid)\nFind agents with correlated liveness patterns.\n\n```\nUser: \"Find similar agents\"\nAgent: \"Correlation: 0.78\nSimilar agents: 2 found\nCluster: copywriters-west\"\n```\n\n**Price:** $0.02 USDC\n\n## Providers\n\n### PULSE_STATE\nProvides current state from the Agent Pulse protocol:\n\n```\nAgent Pulse Protocol:\nProtocol: ✅ HEALTHY | 1,234 agents\nAgent: 🟢 Alive | 🔥 5 | 2h ago\nTTL: 24h | Min pulse: 1 PULSE\n```\n\n## Programmatic Usage\n\n### Check if an Agent is Alive\n\n```typescript\nimport { isAlive, getPulseGateSettings } from \"@agent-pulse/elizaos-plugin\";\n\nconst settings = getPulseGateSettings(runtime);\nif (settings) {\n  const result = await isAlive(\n    \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n    settings,\n    runtime\n  );\n\n  console.log(result.allowed);  // true/false\n  console.log(result.reason);   // Explanation if not allowed\n  console.log(result.status);   // Full status object\n}\n```\n\n### Extract Identity from Message\n\n```typescript\nimport { extractIdentity, isLikelyAgent } from \"@agent-pulse/elizaos-plugin\";\n\nconst identity = extractIdentity(message, runtime);\nif (identity.found) {\n  console.log(identity.address);  // Ethereum address\n  console.log(identity.source);   // \"signature\" | \"claimed\" | \"inferred\"\n}\n\nconst isAgent = isLikelyAgent(message, runtime);\n```\n\n### Manual Gate Check\n\n```typescript\nimport { makeGateDecision } from \"@agent-pulse/elizaos-plugin\";\n\nconst decision = makeGateDecision(\n  \"strict\",           // mode\n  checkResult,        // GateCheckResult from isAlive()\n  identity            // ExtractedIdentity\n);\n\nconsole.log(decision.allow);  // true/false\nconsole.log(decision.flag);   // true/false\nconsole.log(decision.log);    // true/false\n```\n\n## Contract Addresses\n\n**Base Sepolia (Chain ID: 84532)**\n- PulseRegistry: `0xe61C615743A02983A46aFF66Db035297e8a43846`\n- PulseToken: `0x21111B39A502335aC7e45c4574Dd083A69258b07`\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Type check\nnpm run typecheck\n\n# Watch mode\nnpm run dev\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}