{"_id":"@armalo/telemetry","name":"@armalo/telemetry","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@armalo/telemetry","version":"0.1.0","description":"Continuous behavioral telemetry for AI agents. Drop in, stream tool calls + sessions to Armalo Trust Oracle. Closes the L4 TOCTOU gap.","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"engines":{"node":">=18.0.0"},"dependencies":{},"devDependencies":{"typescript":"^5.7.0"},"keywords":["ai-agents","telemetry","behavioral-trust","L4","armalo","agent-trust","TOCTOU","tool-call-audit","agent-observability"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/armalo-ai/armalo.git","directory":"packages/telemetry"},"publishConfig":{"access":"public"},"scripts":{"build":"rm -rf dist && tsc","type-check":"tsc --noEmit"},"_id":"@armalo/telemetry@0.1.0","bugs":{"url":"https://github.com/armalo-ai/armalo/issues"},"homepage":"https://github.com/armalo-ai/armalo#readme","_integrity":"sha512-5ZHU9wCimMRf51ge1LZXQ7ahcKrwX9qNi+5DIKwimBuHC1QqM81OfaHq5bFRfCFkxeW7W0moJHNpqcxCJ3x4WQ==","_resolved":"/private/var/folders/14/n0ylldy508xgs8tcyqslfdt80000gn/T/7dd9671e3eb894d24eb2302484d24afb/armalo-telemetry-0.1.0.tgz","_from":"file:armalo-telemetry-0.1.0.tgz","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-5ZHU9wCimMRf51ge1LZXQ7ahcKrwX9qNi+5DIKwimBuHC1QqM81OfaHq5bFRfCFkxeW7W0moJHNpqcxCJ3x4WQ==","shasum":"44c4a9a2112bb58fb5a5bf2d2106ef24fb8cce80","tarball":"https://registry.npmjs.org/@armalo/telemetry/-/telemetry-0.1.0.tgz","fileCount":8,"unpackedSize":18980,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEBiYWMuQ+92ekEf12/sy3LALPo9ySLTQ8w3j9rShYQAAiEAnG6qWqelwddC/i9SvZ7VUhbmNve14i1HkaGWKVg6/og="}]},"_npmUser":{"name":"armalo","email":"ryan@armalo.ai"},"directories":{},"maintainers":[{"name":"armalo","email":"ryan@armalo.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telemetry_0.1.0_1778719084248_0.2784809780620512"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T00:38:04.146Z","0.1.0":"2026-05-14T00:38:04.389Z","modified":"2026-05-14T00:38:04.585Z"},"maintainers":[{"name":"armalo","email":"ryan@armalo.ai"}],"description":"Continuous behavioral telemetry for AI agents. Drop in, stream tool calls + sessions to Armalo Trust Oracle. Closes the L4 TOCTOU gap.","homepage":"https://github.com/armalo-ai/armalo#readme","keywords":["ai-agents","telemetry","behavioral-trust","L4","armalo","agent-trust","TOCTOU","tool-call-audit","agent-observability"],"repository":{"type":"git","url":"git+https://github.com/armalo-ai/armalo.git","directory":"packages/telemetry"},"bugs":{"url":"https://github.com/armalo-ai/armalo/issues"},"license":"MIT","readme":"# `@armalo/telemetry`\n\n> **Continuous behavioral telemetry for AI agents.** The L4 TOCTOU closer.\n\nThe L4 layer of the agent identity stack — cross-org behavioral trust — requires continuous behavioral telemetry that is captured out-of-band and is queryable by counterparties. This package is that telemetry client. Drop it into your runtime (or run it as a sidecar), stream tool calls and sessions to the Armalo trust oracle, and your agent earns a verifiable behavioral record that any counterparty can query.\n\nRead the full L4 specification at **[armalo.ai/l4](https://www.armalo.ai/l4)**.\n\n---\n\n## Install\n\n```bash\nnpm i @armalo/telemetry\n# or\npnpm add @armalo/telemetry\n```\n\n## Quickstart\n\n```ts\nimport { Telemetry } from '@armalo/telemetry';\n\nconst tel = new Telemetry({\n  apiKey: process.env.ARMALO_API_KEY!, // same key issued for @armalo/core\n});\n\nconst sessionId = crypto.randomUUID();\nconst agentId = 'YOUR_AGENT_UUID';\n\n// Open a session\ntel.sessionStart({\n  sessionId,\n  agentId,\n  startedAt: new Date().toISOString(),\n  pactId: 'YOUR_PACT_UUID', // optional — enables continuous param-binding eval\n});\n\n// Stream tool calls as they happen\ntel.toolCall({\n  sessionId,\n  agentId,\n  tool: 'transfer_funds',\n  params: { destination: '0xAB...', amount: 250 },\n  outcome: 'success',\n  latencyMs: 142,\n  attemptedAt: new Date().toISOString(),\n});\n\n// Close the session\ntel.sessionEnd({\n  sessionId,\n  agentId,\n  endedAt: new Date().toISOString(),\n  outcome: 'success',\n});\n\n// Before process exit\nawait tel.close();\n```\n\n## One-liner: instrument any tool\n\n```ts\nconst safeTransfer = tel.instrumentTool({\n  sessionId,\n  agentId,\n  tool: 'transfer_funds',\n  pactId: 'YOUR_PACT_UUID',\n  fn: async (params) => yourTransferImpl(params),\n});\n\nawait safeTransfer({ destination: '0xAB...', amount: 250 });\n// Every invocation streams a tool_call event automatically.\n// Errors are captured + re-thrown — telemetry never breaks your runtime.\n```\n\n## Why a separate package\n\nThe Armalo trust layer treats telemetry as L4 substrate, not as agent observability. Three properties differentiate this package from logging or APM:\n\n1. **Non-blocking by default** — the client retries transient failures and drops events under backpressure so your agent's correctness never depends on telemetry delivery. For strong isolation, run it in a separate process/sidecar with a dedicated key.\n2. **Cross-org queryable** — events flow to the public trust oracle. Any counterparty can verify the agent's behavior without trusting the agent's operator.\n3. **Bound to behavioral pacts** — when a `pactId` is attached, the server validates each `tool_call` against the pact's `param_binding` conditions in continuous time. Violations are recorded immediately.\n\n## Configuration\n\n```ts\nnew Telemetry({\n  apiKey: 'pk_live_...',\n  endpoint: 'https://www.armalo.ai',  // override for staging\n  batchSize: 25,                       // events per flush\n  flushIntervalMs: 5_000,              // max ms between flushes\n  maxRetries: 3,                       // retries on 5xx / network\n  logger: customLogger,                // optional structured logger\n});\n```\n\n## Event shapes\n\n- `session_start` — `{ sessionId, agentId, startedAt, pactId?, metadata? }`\n- `session_end` — `{ sessionId, agentId, endedAt, outcome, reason?, metadata? }`\n- `tool_call` — `{ sessionId, agentId, tool, params, outcome, latencyMs?, errorMessage?, attemptedAt, pactId?, metadata? }`\n- `response` — `{ sessionId, agentId, input, output, outcome, latencyMs?, tokenCount?, emittedAt, metadata? }`\n\nServer-side schema: `apps/web/app/api/v1/telemetry/events/route.ts` (Zod-validated).\n\n## Failure semantics\n\n- Network errors and 5xx responses retry with exponential backoff up to `maxRetries`.\n- 4xx (other than 429) is permanent — the batch is dropped after one log line.\n- A buffer overflow (>1000 events) drops the oldest event with a warning. The agent's correctness must not depend on telemetry succeeding.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-b52507ad19f06b3ced450813790e9889"}