{"filename":"hol-hedera-typescript-cursorrules-prompt-file.mdc","content":"---\ndescription: \"Cursor rules for Hashgraph Online development with TypeScript, building AI agents on Hedera with RegistryBrokerClient.\"\nglobs: **/*\nalwaysApply: false\n---\n# Hashgraph Online (HOL) Development Rules\n\nYou are an expert TypeScript developer building applications with Hashgraph Online (HOL) - the open-source SDK for AI agents and decentralized applications on Hedera.\n\n## Technology Stack\n\n**Core:**\n- Language: TypeScript (strict mode)\n- Runtime: Node.js 20+\n- Package Manager: pnpm\n- Testing: Jest with @swc/jest\n\n**HOL SDK:**\n- @hashgraphonline/standards-sdk - Core SDK for HCS standards and Registry Broker\n- @hol-org/hashnet-mcp - MCP server for AI agent integration\n\n**Frontend (when applicable):**\n- Framework: Next.js 14+ (App Router)\n- UI: shadcn/ui + Tailwind CSS\n- Icons: react-icons (Lucide preferred)\n\n## Coding Standards\n\n### TypeScript Requirements\n- NEVER use `any` - define proper interfaces\n- NEVER use `as any` casting - use type guards\n- ALWAYS define explicit return types\n- ALWAYS use generics for flexible code\n- Validate external data with type guards or zod\n\n### File Naming\n- Use kebab-case: `registry-client.ts`, `topic-manager.ts`\n- Test files: `__tests__/registry-client.test.ts`\n- Components: `registry-browser.tsx`\n\n### Code Style\n- Max 500 lines per file - split larger files\n- No nested ternaries\n- No inline comments - use JSDoc only\n- No console.log - use Logger from standards-sdk\n- Prettier formatting required\n\n### React Patterns (when applicable)\n- NO render functions like `renderContent()`\n- NO inline callbacks in JSX\n- NO hooks in loops/conditionals\n- ALWAYS use separate child components\n- ALWAYS define Props interfaces\n\n## HOL SDK Usage\n\n### RegistryBrokerClient - Initialization\n```typescript\nimport { RegistryBrokerClient } from '@hashgraphonline/standards-sdk';\n\nconst client = new RegistryBrokerClient({\n  baseUrl: 'https://api.hol.org',\n  apiKey: process.env.HOL_API_KEY,\n});\n```\n\n### RegistryBrokerClient - Search Agents\n```typescript\nimport { RegistryBrokerClient, SearchParams, Logger } from '@hashgraphonline/standards-sdk';\n\nconst logger = new Logger({ module: 'AgentSearch', level: 'info' });\nconst client = new RegistryBrokerClient();\n\nconst searchParams: SearchParams = {\n  q: 'weather',\n  registry: 'hcs-10',\n  limit: 10,\n  page: 1,\n};\n\nconst results = await client.search(searchParams);\nlogger.info('Search completed', { total: results.total });\nresults.hits.forEach(agent => {\n  logger.debug('Agent found', { name: agent.name, description: agent.description });\n});\n```\n\n### RegistryBrokerClient - Resolve Agent (UAID)\n```typescript\nimport { RegistryBrokerClient, Logger } from '@hashgraphonline/standards-sdk';\n\nconst client = new RegistryBrokerClient();\nconst logger = new Logger({ module: 'AgentResolver', level: 'info' });\n\nconst agent = await client.resolveUaid('hcs10://0.0.123456/agent-name');\nlogger.info('Agent resolved', { \n  name: agent.name, \n  protocols: agent.protocols, \n  capabilities: agent.capabilities \n});\n```\n\n### RegistryBrokerClient - Register Agent\n```typescript\nimport { RegistryBrokerClient, AgentRegistrationRequest, Logger } from '@hashgraphonline/standards-sdk';\n\nconst client = new RegistryBrokerClient();\nconst logger = new Logger({ module: 'AgentRegistration', level: 'info' });\n\nconst registration: AgentRegistrationRequest = {\n  name: 'My Agent',\n  description: 'A helpful AI agent',\n  protocols: ['hcs-10'],\n  capabilities: ['chat', 'search'],\n  endpoint: 'https://my-agent.example.com',\n};\n\nconst response = await client.registerAgent(registration, {\n  autoTopUp: {\n    accountId: process.env.HEDERA_OPERATOR_ID!,\n    privateKey: process.env.HEDERA_OPERATOR_KEY!,\n  },\n});\n\nif (response.success) {\n  logger.info('Agent registered', { uaid: response.uaid });\n}\n```\n\n### RegistryBrokerClient - Chat with Agent\n```typescript\nimport { RegistryBrokerClient, StartChatOptions, Logger } from '@hashgraphonline/standards-sdk';\n\nconst client = new RegistryBrokerClient();\nconst logger = new Logger({ module: 'AgentChat', level: 'info' });\n\nconst options: StartChatOptions = {\n  uaid: 'hcs10://0.0.123456/agent-name',\n  auth: {\n    accountId: process.env.HEDERA_OPERATOR_ID!,\n    privateKey: process.env.HEDERA_OPERATOR_KEY!,\n  },\n};\n\nconst conversation = await client.chat.start(options);\n\nconst response = await conversation.send({\n  plaintext: 'Hello, can you help me?',\n});\n\nlogger.info('Agent response received', { sessionId: conversation.sessionId });\n```\n\n### RegistryBrokerClient - Get Stats\n```typescript\nimport { RegistryBrokerClient, Logger } from '@hashgraphonline/standards-sdk';\n\nconst client = new RegistryBrokerClient();\nconst logger = new Logger({ module: 'RegistryStats', level: 'info' });\n\nconst stats = await client.stats();\nlogger.info('Registry stats', { totalAgents: stats.totalAgents, protocols: stats.protocols });\n\nconst registries = await client.registries();\nregistries.forEach(r => logger.debug('Registry', { name: r.name }));\n```\n\n### RegistryBrokerClient - Vector Search\n```typescript\nimport { RegistryBrokerClient, VectorSearchRequest, Logger } from '@hashgraphonline/standards-sdk';\n\nconst client = new RegistryBrokerClient();\nconst logger = new Logger({ module: 'VectorSearch', level: 'info' });\n\nconst request: VectorSearchRequest = {\n  query: 'find me an agent that can help with weather forecasts',\n  limit: 5,\n  filter: {\n    registry: 'hcs-10',\n    protocols: ['a2a'],\n  },\n};\n\nconst results = await client.vectorSearch(request);\nresults.hits.forEach(hit => {\n  logger.info('Match found', { name: hit.agent.name, score: hit.score });\n});\n```\n\n## Testing Requirements\n\n### TDD Workflow\n1. RED: Write failing tests first\n2. GREEN: Implement minimum code to pass\n3. REFACTOR: Improve while keeping tests green\n\n### Test Structure\n```typescript\ndescribe('RegistryBrokerClient', () => {\n  let client: RegistryBrokerClient;\n\n  beforeEach(() => {\n    client = new RegistryBrokerClient();\n  });\n\n  describe('search', () => {\n    it('should return agents matching query', async () => {\n      const result = await client.search({ q: 'test' });\n      \n      expect(result.hits).toBeDefined();\n      expect(Array.isArray(result.hits)).toBe(true);\n    });\n  });\n\n  describe('resolveUaid', () => {\n    it('should resolve valid UAID', async () => {\n      const agent = await client.resolveUaid('hcs10://0.0.123456/test');\n      \n      expect(agent.name).toBeDefined();\n    });\n  });\n});\n```\n\n### Test Commands\n```bash\npnpm test                    # Run all tests\npnpm test -- --watch         # Watch mode\npnpm test -- --coverage      # Coverage report\npnpm test -- -t \"pattern\"    # Run specific tests\n```\n\n## Validation Checklist\n\nBefore completing any task:\n1. `pnpm run lint` - Zero violations\n2. `pnpm run typecheck` - Zero errors  \n3. `pnpm run build` - Must compile\n4. `pnpm test` - All tests pass\n\n## Environment Configuration\n\n```typescript\nimport 'dotenv/config';\n\nconst config = {\n  baseUrl: process.env.HOL_API_URL || 'https://api.hol.org',\n  apiKey: process.env.HOL_API_KEY,\n  network: process.env.HEDERA_NETWORK || 'testnet',\n  operatorId: process.env.HEDERA_OPERATOR_ID,\n  operatorKey: process.env.HEDERA_OPERATOR_KEY,\n};\n```\n\n## Resources\n\n- HOL Website: https://hol.org\n- HOL Registry: https://hol.org/registry\n- SDK Docs: https://hol.org/docs/libraries/standards-sdk/overview/\n- Registry Broker Client: https://hol.org/docs/libraries/standards-sdk/registry-broker-client/\n- GitHub: https://github.com/hashgraph-online\n- NPM: @hashgraphonline/standards-sdk\n"}