@armalo/telemetry

Continuous behavioral telemetry for AI agents. The L4 TOCTOU closer.

The 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.

Read the full L4 specification at armalo.ai/l4.

Install

npm i @armalo/telemetry
# or
pnpm add @armalo/telemetry

Quickstart

import { Telemetry } from '@armalo/telemetry';

const tel = new Telemetry({
  apiKey: process.env.ARMALO_API_KEY!, // same key issued for @armalo/core
});

const sessionId = crypto.randomUUID();
const agentId = 'YOUR_AGENT_UUID';

// Open a session
tel.sessionStart({
  sessionId,
  agentId,
  startedAt: new Date().toISOString(),
  pactId: 'YOUR_PACT_UUID', // optional — enables continuous param-binding eval
});

// Stream tool calls as they happen
tel.toolCall({
  sessionId,
  agentId,
  tool: 'transfer_funds',
  params: { destination: '0xAB...', amount: 250 },
  outcome: 'success',
  latencyMs: 142,
  attemptedAt: new Date().toISOString(),
});

// Close the session
tel.sessionEnd({
  sessionId,
  agentId,
  endedAt: new Date().toISOString(),
  outcome: 'success',
});

// Before process exit
await tel.close();

One-liner: instrument any tool

const safeTransfer = tel.instrumentTool({
  sessionId,
  agentId,
  tool: 'transfer_funds',
  pactId: 'YOUR_PACT_UUID',
  fn: async (params) => yourTransferImpl(params),
});

await safeTransfer({ destination: '0xAB...', amount: 250 });
// Every invocation streams a tool_call event automatically.
// Errors are captured + re-thrown — telemetry never breaks your runtime.

Why a separate package

The Armalo trust layer treats telemetry as L4 substrate, not as agent observability. Three properties differentiate this package from logging or APM:

1. 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.
2. Cross-org queryable — events flow to the public trust oracle. Any counterparty can verify the agent's behavior without trusting the agent's operator.
3. 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.

Configuration

new Telemetry({
  apiKey: 'pk_live_...',
  endpoint: 'https://www.armalo.ai',  // override for staging
  batchSize: 25,                       // events per flush
  flushIntervalMs: 5_000,              // max ms between flushes
  maxRetries: 3,                       // retries on 5xx / network
  logger: customLogger,                // optional structured logger
});

Event shapes

• session_start — { sessionId, agentId, startedAt, pactId?, metadata? }
• session_end — { sessionId, agentId, endedAt, outcome, reason?, metadata? }
• tool_call — { sessionId, agentId, tool, params, outcome, latencyMs?, errorMessage?, attemptedAt, pactId?, metadata? }
• response — { sessionId, agentId, input, output, outcome, latencyMs?, tokenCount?, emittedAt, metadata? }

Server-side schema: apps/web/app/api/v1/telemetry/events/route.ts (Zod-validated).

Failure semantics

• Network errors and 5xx responses retry with exponential backoff up to maxRetries.
• 4xx (other than 429) is permanent — the batch is dropped after one log line.
• A buffer overflow (>1000 events) drops the oldest event with a warning. The agent's correctness must not depend on telemetry succeeding.

License

MIT