Agent Turn Primitives

Primitives for reading a sequence of agent turns: RECURRING_CALL detection and monotonic cost/diff trend.

WHY IT EXISTS. A team reported a real bill: "Cursor charged us $1,382.59 in about an hour. One engineer, one loop, one afternoon. We caught it the same day, because every engineer's AI spend sits on a dashboard we built." They only caught it because they had already built the visibility layer. No single call in that hour was unusual; the SHAPE was.

WHAT IT DELIBERATELY IS NOT. There is no "is this session burning" verdict, and there never will be. "Cost per turn rising while diff size falls" is a policy threshold that legitimately differs by team and task — it has no ground truth independent of the buyer's opinion, so this package refuses to encode one. It reports facts; the caller decides.

WHAT SURVIVES AS FACT: an exact tool+arguments hash repeating across consecutive turns; monotonic rising, falling or mixed trends over caller-supplied cost and diff-size arrays; and UNDECIDABLE on insufficient data, never a silent default.

A BUG WORTH KNOWING ABOUT, because it is why the hash can be trusted. The canonicaliser originally collapsed every Date to {} — Object.keys(new Date()) is [] — so two turns 73 years apart hashed IDENTICALLY, falsifying the module's own guarantee and producing a false RECURRING_CALL. Dates are now serialised losslessly and tagged so they cannot collide with a lookalike string; Map, Set, RegExp and typed arrays are REFUSED, because their canonical form is contentious and baking one in would make this package's opinion part of your identity check. Seven regression tests pin it from both sides.

VERIFIED: 75 tests, plus evidence/verify-truth-table.mjs checking 23 rows across both decision tables and independently recomposing a SHA-256 digest against the implementation's own output — all 23 match.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateMonotonicTrend(values: number[], label: TrendLabel = "value"): TrendVerdict;
  export function pairCostAndDiffTrends(cost: number[], diffSize: number[]): PairedTrendVerdict;
  export function canonicalStringify(v: unknown): string;
  export function turnHash(tool: string, args: unknown): string;
  export function evaluateRecurringCalls(turns: Turn[]): RecurringCallVerdict;

  export type RecurringCallStatus = "RECURRING_CALL" | "NO_RECURRING_CALL" | "UNDECIDABLE";
  export type RecurringCallFindingCode = "INSUFFICIENT_TURNS" | "RECURRING_CALL" | "NO_RECURRING_CALL";
  export type Severity = "critical" | "warning" | "note";
  export type TrendLabel = "cost" | "diffSize" | (string & {});
  export type TrendDirection = "MONOTONIC_RISING" | "MONOTONIC_FALLING" | "MIXED";
  export type TrendStatus = TrendDirection | "UNDECIDABLE";