NIP-AM ====== Agent Turn Metrics ------------------ `draft` `optional` `relay` This NIP defines a durable, encrypted event kind for recording per-turn token usage and estimated cost of AI agent sessions. An agent publishes one `kind:44200` event per completed turn, NIP-44 encrypted to its owner, so the owner can account for token usage across agents and harnesses without the relay — or any third party — learning what the agent did or what it cost. ## Motivation AI agent harnesses consume model tokens on every turn. Owners running fleets of agents need durable, harness-independent usage accounting — the equivalent of a metered bill — for cost attribution, budgeting, and capacity planning. [NIP-AO](NIP-AO.md) (kind 24200) already streams encrypted session telemetry between agent and owner, but it is deliberately ephemeral: relays MUST NOT persist it, so it cannot answer "how many tokens did my agents use last week?". Transcript-grade durable telemetry is explicitly out of scope — the persistence-averse reasoning behind NIP-AO's ephemerality contract applies to conversation content, not to a small usage record. Kind 44200 stores only the metric: token counts, an estimated cost, and correlation identifiers, all encrypted to the owner. ## Definitions - **Agent**: an AI process with its own Nostr keypair, executing sessions on behalf of an owner. - **Owner**: the human (or system) whose pubkey the agent was provisioned under. - **Turn**: one prompt→response cycle of an agent session, as bounded by the harness (e.g. one ACP `session/prompt` round trip). - **Turn metric**: a single kind 44200 event recording the usage of one turn. ## Event `kind:44200` is a regular event by Buzz convention (alongside 44100/44101): stored, append-only, never replaced. Each completed turn produces exactly one event. ```json { "kind": 44200, "pubkey": "", "created_at": , "content": "", "tags": [ ["p", ""], ["agent", ""] ], "sig": "..." } ``` Events MUST have exactly one `p` tag (the owner) and exactly one `agent` tag (equal to `pubkey`). The tag layout deliberately mirrors NIP-AO telemetry frames so existing owner-scoped tooling applies unchanged. No channel (`h`) tag is used. The channel a turn served is private usage metadata and lives inside the encrypted payload; keeping it out of the tags avoids leaking per-channel activity rates to the relay operator and keeps the event community-global (owner-scoped) rather than channel-scoped. ## Encryption `content` MUST be encrypted with NIP-44 v2 using `(agent_privkey, owner_pubkey)` — identical to NIP-AO telemetry. Plaintext SHOULD be zeroized after encrypt/decrypt. Decrypted payload MUST NOT exceed 65,535 bytes (payloads are typically well under 1 KB). ## Decrypted Payload The `content` field decrypts to a UTF-8 JSON object: ```jsonc { "harness": "goose", // REQUIRED: harness identifier "model": "claude-sonnet-4-5", // model id, or null if unknown "channelId": "" | null, "sessionId": "" | null, // REQUIRED when "cumulative" is present "turnId": "" | null, "turnSeq": 17 | null, // REQUIRED when "cumulative" is present "timestamp": "2026-07-01T20:11:03.213Z", // REQUIRED: RFC 3339, end of turn // Usage for THIS turn (computed delta). Fields are null when the harness // does not report them — a null MUST NOT be recorded or summed as zero. // Exception: cache fields (cacheReadTokens, cacheWriteTokens) MUST be // omitted rather than null when unavailable — see "Numeric validity" below. "turn": { "inputTokens": 1234 | null, "outputTokens": 567 | null, "totalTokens": 1801 | null, "costUsd": 0.0123 | null // estimated }, // Session-cumulative usage as reported at the end of this turn. "cumulative": { "inputTokens": 45210 | null, "outputTokens": 9876 | null, "totalTokens": 55086 | null, "costUsd": 0.41 | null // estimated }, // false when the publisher could not observe the previous turn's // cumulative baseline (e.g. harness restart mid-session), making the // "turn" object unreliable for this event. "deltaReliable": true, // Billing identity, present only when the publisher can prove applicability // from the actual endpoint (official provider API) and the actually-requested // model for the usage represented. Omit this field when applicability cannot // be proven — it is never inferred from the configured/session "model" field. // Consumers MUST treat omission as "price unknown"; they MUST NOT infer a // price from the session "model" field. pricingIdentity is OPTIONAL but NOT // nullable: when present, "authority" and "model" MUST be non-null strings; // "cacheClass" is omitted (not null) when it is not applicable. "pricingIdentity": { // OPTIONAL; omit entirely if unproven "authority": "api.anthropic.com", // billing authority (not transport provider) "model": "claude-sonnet-4-5", // actually-requested billable model id "cacheClass": "ephemeral" // cache-write class; omit when not applicable }, "stopReason": "end_turn" // optional } ``` `harness` and `timestamp` are REQUIRED. All other fields are OPTIONAL or nullable, except as constrained below: `pricingIdentity` is optional but not nullable (omit it entirely rather than set it to null). Consumers MUST ignore unknown fields (forward compatibility). ### Ordering and delta recomputation When a `cumulative` object is present, `sessionId` and `turnSeq` are REQUIRED. `turnSeq` is a per-session monotonically increasing integer starting at any value, incremented by the publisher on every published turn metric for that session; a publisher restart that loses the counter MUST start a new `sessionId` rather than reuse the old one with a reset `turnSeq`. Cumulative values form a series only *within* one `sessionId`, ordered by `turnSeq` — consumers MUST NOT diff cumulative values across different `sessionId`s, and MUST NOT rely on `created_at` (seconds precision, ambiguous for same-second turns) for ordering within a session. If a consumer recomputing deltas observes a cumulative counter that decreases between consecutive `turnSeq` values (counter reset, harness bug), it MUST treat the affected turn's usage as unknown (null), not as negative usage. Publishers likewise MUST NOT emit negative values in `turn`; when the computed delta would be negative or the previous baseline is unknown, the publisher sets the affected `turn` counters to null and `deltaReliable: false`. Where the harness reports only cumulative counters, the publisher computes `turn` as the difference between consecutive cumulative snapshots within one session. Consumers doing exact accounting SHOULD prefer recomputing deltas from consecutive `cumulative` values and treat `turn` as a convenience. ### Numeric validity and token semantics All token counts MUST be non-negative integers. `costUsd` MUST be a finite, non-negative number. `totalTokens` is the harness- or provider-reported total when available; publishers MUST NOT derive it by summing `inputTokens` and `outputTokens` (providers may count categories a simple sum misses) — when no total is reported, `totalTokens` is null. `inputTokens` is the inclusive input-side total: where the provider reports cache reads/writes separately (e.g. Anthropic `cache_read_input_tokens` / `cache_creation_input_tokens`), the publisher folds them into `inputTokens`. Where the provider exposes a cache component, publishers SHOULD report it in the optional `cacheReadTokens` / `cacheWriteTokens` fields inside `turn` and `cumulative`; these are informational subsets of `inputTokens`, not additions to it. Publishers MUST preserve an explicit zero when the provider reports zero and MUST omit the field (never null or fabricated zero) when that component is unavailable to the publisher — including when the provider supports the component but the harness does not surface it. Treating an unreported category as zero is incorrect. Note: the payload-wide null guidance above does not apply to these cache fields; omission is the only valid representation for an unavailable cache component. `costUsd` values are estimates (provider list prices at publish time, or a harness-reported estimate). They are advisory, not billing records. `pricingIdentity`, when present, identifies the billing authority and actually-requested model for the usage represented by this event. `authority` is a registered billing-namespace identifier: exact lowercase hostname, no scheme, no path, no trailing slash (registered values: `api.anthropic.com`, `api.openai.com`, `openrouter.ai`; the set extends only by amendment to this NIP). Pricing lookup is an exact string match on `(authority, model)` — any deviation loses the price. It is a billing namespace, distinct from the runtime transport provider. `model` is the billable model identifier as resolved at the point the request was made, not the configured/session model. `cacheClass` is the cache-write class when applicable (e.g. `ephemeral`). Publishers MUST omit `pricingIdentity` when any of the following apply: the request was routed through a custom or overridden base URL, a gateway (unless the gateway is the named billing authority), or an unresolved alias; the billed model identity cannot be confirmed — for direct connections to an official allowlisted endpoint, proof is the actually-requested resolved model; for all other routes, the response MUST supply authoritative billing identity; or the usage represented within this turn contains contributions from more than one billing identity (including a mix of identity-bearing and unresolved contributions). The existing `model` field retains its non-billing semantics (configured/session model) and is never overloaded by `pricingIdentity`. Consumers MUST treat omission of `pricingIdentity` as "price unknown". Consumers MAY recompute cost estimates using the billing identity and a pricing manifest; they MUST retain the provenance of any cost value (e.g. `manifest-estimated`, `wire-reported`). Consumers MUST NOT merge manifest-estimated and wire-reported costs into an unlabeled total. `stopReason`, when present, MUST be one of `end_turn`, `max_tokens`, `cancelled`, `error`, `unknown`. Consumers MUST treat unrecognized `stopReason` values as `unknown`; the token counts remain valid. ## Publisher Behavior - Publish exactly one event per completed turn, at turn completion, including turns that end in cancellation or error when usage was observed. - Do NOT publish an event for a turn with no observed usage (all counters unknown); an all-null metric carries no information. - `created_at` SHOULD equal the payload `timestamp` truncated to seconds. ## Relay Behavior On receiving a kind 44200 event, a relay MUST: 1. Validate the event signature per NIP-01. 2. Verify `event.pubkey` equals the `agent` tag and that `is_agent_owner(agent, owner)` holds for the `p` tag via authenticated ownership lookup. Tag matching alone is insufficient. 3. Store the event durably, scoped to the owner (community-global; no channel scope). 4. NOT index the event in any full-text search (the ciphertext is not searchable and must not enter search indexes). Reads MUST be gated: only an authenticated ([NIP-42](42.md)) reader whose pubkey equals the `#p` tag value may receive the event. This gate applies to **every** read path, including explicit `ids` filters — knowing an event id MUST NOT grant access. (Some p-gated kinds exempt id-addressed lookups on the theory that knowing the id implies authorization; kind 44200 events are long-lived and their cleartext envelope leaks turn activity, so no such exemption is permitted.) Unauthenticated publish or subscribe attempts MUST be rejected with `AUTH required`; authenticated attempts from a pubkey that is not the event owner MUST be rejected with `restricted:`. Relays SHOULD rate-limit kind 44200 to a rate consistent with real turn frequency (RECOMMENDED: 60 events/minute per agent pubkey). ## Client Behavior Owners recover usage history with: ```json {"kinds": [44200], "#p": [""], "since": } ``` On receiving an event, a client MUST verify the signature, decrypt with its own secret key and `event.pubkey`, and ignore events that fail to decrypt or parse. Clients SHOULD deduplicate by event id. For within-session ordering, clients MUST use `(sessionId, turnSeq)` from the decrypted payload as described above; `created_at` is suitable only for coarse time-window queries. ## Relationship to Other NIPs - [NIP-AO](NIP-AO.md): same agent↔owner encryption and tag scoping, but ephemeral and transcript-grade. NIP-AM events MUST NOT carry conversation content, tool calls, or protocol frames — usage numbers and identifiers only. - [NIP-09](09.md): the authoring agent (or its owner via relay policy) may request deletion; relays apply standard deletion semantics. - [NIP-40](40.md): publishers MAY set `expiration` to bound retention. ## Security Considerations **Metadata leakage.** `p`, `agent`, and `created_at` are cleartext: a relay operator learns that agent X completed turns for owner Y at some rate. Turn rate is already observable from the agent's channel messages; the token counts, cost, model, and channel remain encrypted. **No forward secrecy.** NIP-44 does not provide forward secrecy; compromise of the agent's private key allows decryption of captured ciphertexts. **Integrity of accounting.** Metrics are self-reported by the agent process. A compromised agent can under- or over-report. Owners requiring stronger guarantees must reconcile against provider-side billing.