Can you see what every agent did, when, and at what cost? Yes — down to the individual model call, opt-in.

// Two usage events carry the whole audit trail. Both are plain domain types — no @mastra in the shape.

// 1) ONE swarm.usage per model generation, attributed to the agent that made the call.
{
  type: "swarm.usage",
  data: {
    slug: "researcher",            // WHICH agent generated (the orchestrator, or a delegate)
    modelId: "claude-sonnet-4-5",  // WHAT model actually ran (after tier routing)
    breakdown: { inputTokens, outputTokens, /* cache/reasoning classes… */ },
    cost: { usd: 0.0123 },         // the METERED (token-priced) cost — see "metered vs billed" below
    generationId: "run_abc:0:2",   // STABLE key: <runId>:<segmentIndex>:<within-segment #> — retry-safe, unique
  },
}

// 2) ONE swarm.turn_usage per segment (the billing unit for the turn), summing every generation in it —
//    the orchestrator AND every delegate — with a per-agent bySlug split.
{
  type: "swarm.turn_usage",
  data: {
    breakdown, cost,               // the segment total
    bySlug: [{ slug: "researcher", breakdown, cost }, /* … */ ],
  },
}

// 3) swarm.external_usage — non-LLM external spend (e.g. a paid tool/provider), flushed BEFORE the
//    turn_usage that itemizes it, so a segment's ledger is complete and correctly ordered.

import { defineSwarm } from "@nightowlsdev/core";

// PATH 1 — the synchronous observer. onEvent sees EVERY event, including every swarm.usage the instant a
// generation completes. This is the opt-in switch: no onEvent ⇒ nothing recorded, zero overhead. A throwing
// observer is isolated (the engine swallows it so a sink hiccup never breaks a run) — so log your own failures.
const swarm = defineSwarm({
  /* … model, agents, tools … */
  onEvent: (ev, ctx) => {
    if (ev.type === "swarm.usage") {
      audit.record({
        at: new Date(), runId: ctx.runId, tenant: ctx.tenantId,
        agent: ev.data.slug, model: ev.data.modelId,
        tokens: ev.data.breakdown, usd: ev.data.cost.usd,
        generationId: ev.data.generationId,   // idempotency key for exactly-once
      });
    }
  },
});

import { supabaseUsageSink } from "@nightowlsdev/storage-supabase";

// PATH 2 — the ready-made ledger. supabaseUsageSink IS an onEvent handler that upserts every swarm.usage into
// a host table, keyed idempotently by generationId ("on conflict (generation_id) do nothing"), so a realtime
// replay or a task retry inserts at most once. No OTel pipeline, no double-count under delegation.
const sink = supabaseUsageSink({ pool: storage.ctx.pool, table: "llm_usage_logs" });

const swarm = defineSwarm({ /* … */, onEvent: sink });
// Default row: generation_id, run_id, org_id, agent_slug, model_id, input_tokens, output_tokens, cost_usd.
// Pass `map` to reshape it to your own columns; return null to skip an event.

// PATH 3 — the durable event log. A StorageAdapter with an events table persists EVERY SwarmEvent (not just
// usage) under a monotonic `seq`, so the whole run is replayable and auditable long after it finished.
import { createSupabaseStorage } from "@nightowlsdev/storage-supabase";
const storage = createSupabaseStorage({ dbUrl: process.env.DATABASE_URL! });

// Read it back on demand — per run, or per conversation container (root thread + every lane sub-thread):
const events = await storage.events.list(tenantId, runId, /* sinceSeq */ 0);
const usage  = events.filter((e) => e.type === "swarm.usage");     // every model call this run made
const spend  = events.filter((e) => e.type === "swarm.turn_usage"); // the per-segment billing records

// Or stream live (the same feed the UI subscribes to over Realtime):
for await (const ev of storage.events.subscribe(runId)) { /* tee to your audit UI */ }

import { defineSwarm } from "@nightowlsdev/core";

// PATH 4 — OpenTelemetry-shaped spans, for an APM/trace backend. A telemetry exporter emits one root `run`
// span, one `generation` span per model call (carrying the per-call `costUsd`), and one span per
// tool_call → tool_result pair. Same measurements as the events, shaped as a trace.
const swarm = defineSwarm({
  /* … */
  telemetry: { export: async (spans) => { await myOtelPipeline.send(spans); } },
});
// Also: @nightowlsdev/metrics is a SEPARATE opt-in observation plane — (orgId, orgScope, metric, at, dims)
// → value with calendar bucketing and a fully-pinned period-over-period compare(). Its own package, its own
// pool, its own migration; wire none and a swarm is byte-identical.