{"_id":"@agentlair/telemetry","_rev":"2-81312392478bf3de711248df4c29c4f5","name":"@agentlair/telemetry","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agentlair/telemetry","version":"0.1.0","keywords":["ai-agent","telemetry","observability","behavioral-logging","agent-monitoring","agentlair","tool-calls","anthropic","mastra","langchain","agent-security"],"author":{"name":"AgentLair"},"license":"MIT","_id":"@agentlair/telemetry@0.1.0","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"homepage":"https://agentlair.dev","bugs":{"url":"https://github.com/piiiico/agentlair-telemetry/issues"},"dist":{"shasum":"210e8a8038240e1a3c6a14bac271b62195fe0dcb","tarball":"https://registry.npmjs.org/@agentlair/telemetry/-/telemetry-0.1.0.tgz","fileCount":39,"integrity":"sha512-l11fiSMfUtimVu036BX8IBiWlltYTEhJFUFl61fxgKb/xmKZJVogUd1nHP5RpCW5uIZXRBiCBAGSUVvE1Ipn8A==","signatures":[{"sig":"MEUCIQCD/eQckle3gIqPkCUNu0Uq5o8oXUq0ltvaPNrF1tHUiQIgakjpykTvQf0f1BY7GvCE7Ln8fY45MofKLnx8F8VREsc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":102539},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./query":{"types":"./dist/query.d.ts","import":"./dist/query.js"},"./mastra":{"types":"./dist/adapters/mastra.d.ts","import":"./dist/adapters/mastra.js"},"./anthropic":{"types":"./dist/adapters/anthropic.d.ts","import":"./dist/adapters/anthropic.js"}},"gitHead":"b0d510bdfd8302aa20f93b53f356d7f0ee9ba911","scripts":{"test":"bun test","build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"repository":{"url":"git+https://github.com/piiiico/agentlair-telemetry.git","type":"git"},"_npmVersion":"10.9.7","description":"Drop-in behavioral telemetry for AI agents. 3-line integration, local SQLite storage, framework-agnostic.","directories":{},"_nodeVersion":"22.22.2","_hasShrinkwrap":false,"devDependencies":{"bun-types":"^1.3.11","typescript":"^5.9.3","@types/node":"^22.0.0","@types/better-sqlite3":"^7.6.12"},"optionalDependencies":{"better-sqlite3":"^11.0.0"},"_npmOperationalInternal":{"tmp":"tmp/telemetry_0.1.0_1775981906226_0.7829765411424519","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agentlair/telemetry","version":"0.1.1","description":"Drop-in behavioral telemetry for AI agents. 3-line integration, local SQLite storage, framework-agnostic.","keywords":["ai-agent","telemetry","observability","behavioral-logging","agent-monitoring","agentlair","tool-calls","anthropic","mastra","langchain","agent-security"],"homepage":"https://agentlair.dev","repository":{"type":"git","url":"git+https://github.com/piiiico/agentlair-telemetry.git"},"license":"MIT","author":{"name":"AgentLair"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./anthropic":{"import":"./dist/adapters/anthropic.js","types":"./dist/adapters/anthropic.d.ts"},"./mastra":{"import":"./dist/adapters/mastra.js","types":"./dist/adapters/mastra.d.ts"},"./query":{"import":"./dist/query.js","types":"./dist/query.d.ts"}},"scripts":{"build":"tsc","test":"bun test","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"engines":{"node":">=18.0.0"},"devDependencies":{"@types/better-sqlite3":"^7.6.12","@types/node":"^22.0.0","bun-types":"^1.3.11","typescript":"^5.9.3"},"optionalDependencies":{"better-sqlite3":"^11.0.0"},"_id":"@agentlair/telemetry@0.1.1","gitHead":"cd420b7a32ee00f077f0dde55012d0507cfccb35","bugs":{"url":"https://github.com/piiiico/agentlair-telemetry/issues"},"_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-Va/2JH46Y+PKT9Z0LC8q1nh2JY4KFytJLi7n9qLOKymktfVljYsIKuo4uOsIUo75lPbsaniDZNSMET274LTq2A==","shasum":"d357381d7fe7d4ea01072f25f705988b617f5fd5","tarball":"https://registry.npmjs.org/@agentlair/telemetry/-/telemetry-0.1.1.tgz","fileCount":39,"unpackedSize":102367,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA8mBIDD6sxHuout2SobZMbKqAiZx4cv+k9Qx6rksOyKAiEA4nTGsg22vIyN0EqtehwTY2HBNkLWDNlwjgeQmlv3A64="}]},"_npmUser":{"name":"piiiico","email":"pico@amdal.dev"},"directories":{},"maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telemetry_0.1.1_1775987220489_0.13058549635693795"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-12T08:18:26.111Z","modified":"2026-04-12T09:47:00.757Z","0.1.0":"2026-04-12T08:18:26.385Z","0.1.1":"2026-04-12T09:47:00.640Z"},"bugs":{"url":"https://github.com/piiiico/agentlair-telemetry/issues"},"author":{"name":"AgentLair"},"license":"MIT","homepage":"https://agentlair.dev","keywords":["ai-agent","telemetry","observability","behavioral-logging","agent-monitoring","agentlair","tool-calls","anthropic","mastra","langchain","agent-security"],"repository":{"type":"git","url":"git+https://github.com/piiiico/agentlair-telemetry.git"},"description":"Drop-in behavioral telemetry for AI agents. 3-line integration, local SQLite storage, framework-agnostic.","maintainers":[{"name":"piiiico","email":"pico@amdal.dev"}],"readme":"# @agentlair/telemetry\n\nDrop-in behavioral telemetry for AI agents. 3-line integration, local SQLite storage, framework-agnostic.\n\n**Not governance. Not blocking. Pure observability.** This is the sensor layer that feeds [AgentLair](https://agentlair.dev)'s trust scoring.\n\n## Quick Start\n\n```ts\nimport { telemetry } from '@agentlair/telemetry';\n\nawait telemetry.start({ agent: 'my-agent' });\n// That's it — HTTP calls are auto-instrumented, events stored in local SQLite\n```\n\n## What It Captures\n\n| Category | Examples |\n|----------|----------|\n| `tool_call` | Tool invocations with input/output/duration |\n| `llm_request` / `llm_response` | Model calls, token usage, latency |\n| `http_request` | All fetch() calls (auto-instrumented) |\n| `file_write` / `file_read` | File system operations |\n| `error` | Failures with stack context |\n| `agent_start` / `agent_stop` | Session lifecycle |\n\n## Installation\n\n```bash\nnpm install @agentlair/telemetry\n# or\nbun add @agentlair/telemetry\n```\n\nSQLite storage works out of the box with Bun. For Node.js, install `better-sqlite3`:\n\n```bash\nnpm install better-sqlite3\n```\n\n## Manual Instrumentation\n\n```ts\nimport { telemetry } from '@agentlair/telemetry';\n\nawait telemetry.start({ agent: 'researcher' });\n\n// Instrument any async operation\nconst results = await telemetry.instrument('tool_call', 'web_search', async () => {\n  return await searchWeb(query);\n}, { input: query });\n\n// Record custom events\nawait telemetry.record({\n  category: 'custom',\n  action: 'decision',\n  success: true,\n  metadata: { reason: 'switching strategy' },\n});\n\n// Query and analyze\nconst stats = await telemetry.stats();\nconsole.log(`Error rate: ${(stats.errorRate * 100).toFixed(1)}%`);\nconsole.log('Top tools:', stats.topActions);\n\n// Cleanup\nawait telemetry.stop();\n```\n\n## Framework Adapters\n\n### Anthropic SDK\n\n```ts\nimport Anthropic from '@anthropic-ai/sdk';\nimport { instrumentAnthropicClient } from '@agentlair/telemetry/anthropic';\n\nconst client = instrumentAnthropicClient(new Anthropic(), { agent: 'researcher' });\n\n// Use normally — telemetry is automatic\nconst msg = await client.messages.create({\n  model: 'claude-opus-4-5',\n  max_tokens: 1024,\n  messages: [{ role: 'user', content: 'Hello' }],\n});\n\n// Access telemetry data\nconst stats = await client.telemetry.stats();\n```\n\n### Mastra\n\n```ts\nimport { Agent } from '@mastra/core';\nimport { withTelemetry } from '@agentlair/telemetry/mastra';\n\nconst agent = withTelemetry(\n  new Agent({ name: 'researcher', tools: { ... } }),\n  { agent: 'researcher' },\n);\n\n// Or use middleware\nimport { telemetryMiddleware } from '@agentlair/telemetry/mastra';\n\nconst agent = new Agent({\n  middleware: [telemetryMiddleware({ agent: 'researcher' })],\n});\n```\n\n### Generic (Any Framework)\n\n```ts\nimport { TelemetryCollector } from '@agentlair/telemetry';\n\nconst collector = new TelemetryCollector({ agent: 'my-agent' });\nawait collector.start();\n\n// Wrap your agent's tool execution\nasync function executeTool(name: string, input: unknown) {\n  return collector.instrument('tool_call', name, async () => {\n    return await tools[name].execute(input);\n  }, { input });\n}\n```\n\n## Querying Telemetry\n\n```ts\nimport { queryTelemetry, queryStats } from '@agentlair/telemetry/query';\n\n// Find slow tool calls\nconst slow = await queryTelemetry({\n  category: 'tool_call',\n  minDurationMs: 5000,\n});\n\n// Get error stats for the last hour\nconst stats = await queryStats({\n  after: new Date(Date.now() - 3600_000).toISOString(),\n});\n```\n\n## Storage Backends\n\n### SQLite (default)\n\n```ts\nimport { SQLiteStorage } from '@agentlair/telemetry';\n\nawait telemetry.start({\n  agent: 'my-agent',\n  storage: new SQLiteStorage({ path: './my-telemetry.db', maxEvents: 50_000 }),\n});\n```\n\n### In-Memory\n\n```ts\nimport { MemoryStorage } from '@agentlair/telemetry';\n\nawait telemetry.start({\n  agent: 'my-agent',\n  storage: new MemoryStorage(),\n});\n```\n\n### AgentLair Cloud Sync\n\nLocal-first with async cloud upload:\n\n```ts\nimport { SQLiteStorage, AgentLairSync } from '@agentlair/telemetry';\n\nawait telemetry.start({\n  agent: 'my-agent',\n  storage: new AgentLairSync({\n    local: new SQLiteStorage(),\n    apiKey: process.env.AGENTLAIR_API_KEY!,\n  }),\n});\n```\n\n## Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `agent` | `string` | *required* | Agent name/identifier |\n| `sessionId` | `string` | auto-generated | Session identifier |\n| `storage` | `StorageBackend` | SQLite (or Memory) | Storage backend |\n| `apiKey` | `string` | - | AgentLair API key for cloud sync |\n| `bufferSize` | `number` | `100` | Events buffered before flush |\n| `flushIntervalMs` | `number` | `5000` | Auto-flush interval |\n| `console` | `boolean` | `false` | Print events to console |\n| `instrumentFetch` | `boolean` | `true` | Auto-instrument global fetch |\n| `maxSummaryLength` | `number` | `200` | Max chars for input/output |\n\n## Privacy\n\n- Input/output values are **truncated** to `maxSummaryLength` (default 200 chars)\n- No raw prompts or completions stored by default\n- Local SQLite storage — your data stays on your machine\n- Cloud sync is opt-in and uses your AgentLair API key\n\n## License\n\nMIT\n","readmeFilename":"README.md"}