@knpkv/agent-usage 0.1.0

package/dist/core/Model.js

@@ -0,0 +1,125 @@
+/**
+ * The facts a store records: Usage Events, Limit Snapshots and Balance Readings.
+ *
+ * **Mental model**
+ *
+ * - **Facts, not conclusions.** A Usage Event carries token counts and Attribution Inputs; its
+ *   Booking and API-Equivalent Cost are derived when read (ADR 0002).
+ * - **Unknown is a value.** A limit or balance that could not be read is stored as `Unknown` with a
+ *   reason, so a gap on a graph is a gap and never a zero.
+ *
+ * @module
+ */
+import { Schema } from "effect";
+/** The closed set of coding-agent runtimes whose usage is recorded. */
+export const Agent = Schema.Literals(["claude", "codex"]);
+/** A token count: a whole number, never negative. */
+export const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/**
+ * One request's token counts, split the way pricing needs them.
+ *
+ * `input` is uncached input only, for both agents: Codex reports cache hits inside its input count
+ * and the readers subtract them, so the columns mean the same thing whichever agent wrote them.
+ * Codex reports one cache-write count; it is stored as `cacheWrite5m`. `output` excludes
+ * `reasoning` for both agents (Codex counts reasoning inside its output figure, Claude reports no
+ * split), so the six fields add up to every token the request moved.
+ */
+export const Tokens = Schema.Struct({
+    input: Count,
+    output: Count,
+    reasoning: Count,
+    cacheRead: Count,
+    cacheWrite5m: Count,
+    cacheWrite1h: Count
+});
+/** Every token a request moved, the sum the "tokens" measure plots. */
+export const totalTokens = (tokens) => tokens.input + tokens.output + tokens.reasoning + tokens.cacheRead + tokens.cacheWrite5m + tokens.cacheWrite1h;
+/** The facts captured with a Usage Event that decide its Booking. */
+export const AttributionInputs = Schema.Struct({
+    cwd: Schema.String,
+    branch: Schema.String,
+    activeTicket: Schema.NullOr(Schema.String)
+});
+/**
+ * One model request's token counts on one Machine. `dedupeKey` is unique per Agent: Claude's
+ * message id + request id, Codex's session id + the line's byte offset in its rollout.
+ */
+export const UsageEvent = Schema.Struct({
+    agent: Agent,
+    dedupeKey: Schema.NonEmptyString,
+    machine: Schema.NonEmptyString,
+    sessionId: Schema.NonEmptyString,
+    occurredAt: Schema.Int,
+    model: Schema.NonEmptyString,
+    /** Claude's fast mode: the same model billed at premium rates. */
+    fast: Schema.Boolean,
+    tokens: Tokens,
+    attribution: AttributionInputs
+});
+/** Why a limit or balance could not be read. */
+export const UnknownReason = Schema.Literals([
+    "NoAuth",
+    "AuthExpired",
+    "NotSupported",
+    "Fetch",
+    "Parse",
+    "NoData"
+]);
+/** Where a Limit Snapshot or Balance Reading came from. */
+export const ObservationSource = Schema.Literals(["claude-oauth-usage", "codex-rollout"]);
+/** A window's length in minutes, or Unknown for a provider key whose window nobody published. */
+export const WindowMinutes = Schema.NullOr(Schema.Int.check(Schema.isGreaterThan(0)));
+export const LimitReading = Schema.Union([
+    Schema.TaggedStruct("Known", {
+        usedPercent: Schema.Finite,
+        /** Epoch milliseconds; null when the provider gave no reset time. */
+        resetsAt: Schema.NullOr(Schema.Int)
+    }),
+    Schema.TaggedStruct("Unknown", { reason: UnknownReason })
+]);
+/**
+ * One observation of a Limit Window. `label` is the provider's own key (`five_hour`, `seven_day`,
+ * Codex's `primary`/`secondary`); an Unknown reading for a whole source uses label `*`.
+ */
+export const LimitSnapshot = Schema.Struct({
+    agent: Agent,
+    machine: Schema.NonEmptyString,
+    source: ObservationSource,
+    label: Schema.NonEmptyString,
+    windowMinutes: WindowMinutes,
+    observedAt: Schema.Int,
+    reading: LimitReading
+});
+export const Balance = Schema.Union([
+    /** Claude extra usage left this billing period, in minor units of `currency`. */
+    Schema.TaggedStruct("Amount", {
+        leftMinor: Schema.Finite,
+        limitMinor: Schema.Finite,
+        decimals: Schema.Int,
+        currency: Schema.String
+    }),
+    /** Codex credits, in Codex's own unit. */
+    Schema.TaggedStruct("Credits", { credits: Schema.Finite }),
+    Schema.TaggedStruct("Unlimited", {}),
+    Schema.TaggedStruct("Exhausted", {}),
+    /** Extra usage is switched off, so there is nothing to spend. */
+    Schema.TaggedStruct("Disabled", {})
+]);
+export const BalanceValue = Schema.Union([
+    Schema.TaggedStruct("Known", { balance: Balance }),
+    Schema.TaggedStruct("Unknown", { reason: UnknownReason })
+]);
+/** Which balance a reading is of. */
+export const BalanceKind = Schema.Literals(["claude-extra-usage", "codex-credits"]);
+export const BalanceReading = Schema.Struct({
+    kind: BalanceKind,
+    machine: Schema.NonEmptyString,
+    observedAt: Schema.Int,
+    value: BalanceValue
+});
+/** A ticket's Jira title, or why there is none. */
+export const TicketTitleValue = Schema.Union([
+    Schema.TaggedStruct("Known", { summary: Schema.String }),
+    Schema.TaggedStruct("Unknown", { reason: Schema.Literals(["NotFound", "NotLookedUp"]) })
+]);
+//# sourceMappingURL=Model.js.map

package/dist/core/Model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Model.js","sourceRoot":"","sources":["../../src/core/Model.ts"],"names":[],"mappings":"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"}

package/dist/core/Pricing.d.ts

@@ -0,0 +1,42 @@
+/**
+ * API-Equivalent Cost: what a Usage Event's tokens would cost at today's list price.
+ *
+ * **Mental model**
+ *
+ * - **Priced when read** (ADR 0002). Nothing here is persisted, so updating a rate or adding a model
+ *   reprices every event already stored, past ones included. The UI says so.
+ * - **Unknown is not free.** A model missing from the table, or a cache rate the table lacks for
+ *   tokens that were actually cached, yields `Option.none()`.
+ * - **No network.** The tables are a snapshot: Claude's from Anthropic's list prices, Codex's from
+ *   the models.dev catalog. Updating them is a release.
+ *
+ * @module
+ */
+import { Option } from "effect";
+import type { Agent, Tokens } from "./Model.js";
+/** A Codex request whose prompt exceeds this many tokens is billed at its model's long-context tier. */
+export declare const LONG_PROMPT_TOKENS = 272000;
+/** Every token of a request's prompt: uncached input, cache reads and cache writes. */
+export declare const promptTokens: (tokens: Tokens) => number;
+/** True when one request's prompt falls in the long-context tier. */
+export declare const isLongPrompt: (tokens: Tokens) => boolean;
+/** `claude-opus-5[1m]` and `claude-opus-5-20260101` both price as `claude-opus-5`. */
+export declare const normalizeClaudeModel: (model: string) => string;
+/** Requests that price alike: one agent, model and speed, all Long Prompts or none. */
+export interface PricedGroup {
+    readonly agent: Agent;
+    readonly model: string;
+    readonly fast: boolean;
+    readonly longPrompt: boolean;
+    /** The group's summed tokens. Pricing is linear within a group, so a sum prices like its parts. */
+    readonly tokens: Tokens;
+}
+/** A group's cost at current list price, or none when its model or a needed rate is unpriced. */
+export declare const groupCost: (group: PricedGroup) => Option.Option<number>;
+/** One request's cost at current list price, or none when its model or a needed rate is unpriced. */
+export declare const apiEquivalentCost: (request: {
+    readonly agent: Agent;
+    readonly model: string;
+    readonly fast: boolean;
+    readonly tokens: Tokens;
+}) => Option.Option<number>;

package/dist/core/Pricing.js

@@ -0,0 +1,126 @@
+/**
+ * API-Equivalent Cost: what a Usage Event's tokens would cost at today's list price.
+ *
+ * **Mental model**
+ *
+ * - **Priced when read** (ADR 0002). Nothing here is persisted, so updating a rate or adding a model
+ *   reprices every event already stored, past ones included. The UI says so.
+ * - **Unknown is not free.** A model missing from the table, or a cache rate the table lacks for
+ *   tokens that were actually cached, yields `Option.none()`.
+ * - **No network.** The tables are a snapshot: Claude's from Anthropic's list prices, Codex's from
+ *   the models.dev catalog. Updating them is a release.
+ *
+ * @module
+ */
+import { Option } from "effect";
+const PER_MTOK = 1_000_000;
+// Cache writes cost more than fresh input; reads cost a tenth of it.
+const CLAUDE_CACHE_WRITE_5M = 1.25;
+const CLAUDE_CACHE_WRITE_1H = 2;
+const CLAUDE_CACHE_READ = 0.1;
+/** USD per million tokens, keyed by normalized model id. */
+const CLAUDE_STANDARD = new Map([
+    ["claude-fable-5-1", { input: 10, output: 50 }],
+    ["claude-fable-5", { input: 10, output: 50 }],
+    ["claude-mythos-5-1", { input: 10, output: 50 }],
+    ["claude-mythos-5", { input: 10, output: 50 }],
+    ["claude-opus-5-5", { input: 4, output: 20 }],
+    ["claude-opus-5", { input: 5, output: 25 }],
+    ["claude-opus-4-8", { input: 5, output: 25 }],
+    ["claude-opus-4-7", { input: 5, output: 25 }],
+    ["claude-opus-4-6", { input: 5, output: 25 }],
+    ["claude-opus-4-5", { input: 5, output: 25 }],
+    ["claude-sonnet-5", { input: 2, output: 10 }],
+    ["claude-sonnet-4-6", { input: 3, output: 15 }],
+    ["claude-sonnet-4-5", { input: 3, output: 15 }],
+    ["claude-haiku-4-5", { input: 1, output: 5 }]
+]);
+/** Fast mode: the same model at premium rates. */
+const CLAUDE_FAST = new Map([
+    ["claude-opus-5-5", { input: 8, output: 40 }],
+    ["claude-opus-5", { input: 10, output: 50 }],
+    ["claude-opus-4-8", { input: 10, output: 50 }]
+]);
+/** A Codex request whose prompt exceeds this many tokens is billed at its model's long-context tier. */
+export const LONG_PROMPT_TOKENS = 272_000;
+/** Every token of a request's prompt: uncached input, cache reads and cache writes. */
+export const promptTokens = (tokens) => tokens.input + tokens.cacheRead + tokens.cacheWrite5m + tokens.cacheWrite1h;
+/** True when one request's prompt falls in the long-context tier. */
+export const isLongPrompt = (tokens) => promptTokens(tokens) > LONG_PROMPT_TOKENS;
+const flat = (input, output, cacheRead) => ({
+    input,
+    output,
+    cacheRead,
+    cacheWrite: null,
+    longContext: null
+});
+const tiered = (base, long) => ({
+    ...base,
+    longContext: long
+});
+const rates = (input, output, cacheRead, cacheWrite) => ({
+    input,
+    output,
+    cacheRead,
+    cacheWrite
+});
+/** USD per million tokens from the models.dev catalog, for the models Codex runs. */
+const CODEX = new Map([
+    ["gpt-5", flat(1.25, 10, 0.125)],
+    ["gpt-5-mini", flat(0.25, 2, 0.025)],
+    ["gpt-5-nano", flat(0.05, 0.4, 0.005)],
+    ["gpt-5.1", flat(1.25, 10, 0.125)],
+    ["gpt-5.2", flat(1.75, 14, 0.175)],
+    ["gpt-5.3-codex", flat(1.75, 14, 0.175)],
+    ["gpt-5.3-codex-spark", flat(1.75, 14, 0.175)],
+    ["gpt-5.4", tiered(rates(2.5, 15, 0.25, null), rates(5, 22.5, 0.5, null))],
+    ["gpt-5.4-mini", flat(0.75, 4.5, 0.075)],
+    ["gpt-5.4-nano", flat(0.2, 1.25, 0.02)],
+    ["gpt-5.5", tiered(rates(5, 30, 0.5, null), rates(10, 45, 1, null))],
+    ["gpt-5.6", tiered(rates(4, 20, 0.4, 5), rates(8, 30, 0.8, 10))],
+    ["gpt-5.6-luna", tiered(rates(0.2, 1.2, 0.02, 0.25), rates(0.4, 1.8, 0.04, 0.5))],
+    ["gpt-5.6-sol", tiered(rates(4, 20, 0.4, 5), rates(8, 30, 0.8, 10))],
+    ["gpt-5.6-terra", tiered(rates(2, 12, 0.2, 2.5), rates(4, 18, 0.4, 5))],
+    ["gpt-6-astra", tiered(rates(10, 50, 1, 12.5), rates(20, 75, 2, 25))],
+    ["gpt-6-luna", tiered(rates(0.1, 0.5, 0.01, 0.125), rates(0.2, 0.75, 0.02, 0.25))],
+    ["gpt-6-sol", tiered(rates(2, 10, 0.2, 2.5), rates(4, 15, 0.4, 5))],
+    ["gpt-6.1-sol", tiered(rates(2, 10, 0.1, 2.5), rates(4, 15, 0.2, 5))]
+]);
+/** `claude-opus-5[1m]` and `claude-opus-5-20260101` both price as `claude-opus-5`. */
+export const normalizeClaudeModel = (model) => model.replace(/\[[^\]]*\]$/u, "").replace(/-\d{8}$/u, "");
+const claudeCost = (model, fast, tokens) => {
+    const id = normalizeClaudeModel(model);
+    // A fast request without a fast rate is unpriced, not priced at the standard rate.
+    const found = fast ? CLAUDE_FAST.get(id) : CLAUDE_STANDARD.get(id);
+    if (found === undefined)
+        return Option.none();
+    const input = tokens.input +
+        tokens.cacheWrite5m * CLAUDE_CACHE_WRITE_5M +
+        tokens.cacheWrite1h * CLAUDE_CACHE_WRITE_1H +
+        tokens.cacheRead * CLAUDE_CACHE_READ;
+    return Option.some((input * found.input + (tokens.output + tokens.reasoning) * found.output) / PER_MTOK);
+};
+const codexCost = (model, longPrompt, tokens) => {
+    const price = CODEX.get(model);
+    if (price === undefined)
+        return Option.none();
+    const cacheWrite = tokens.cacheWrite5m + tokens.cacheWrite1h;
+    const applied = longPrompt && price.longContext !== null ? price.longContext : price;
+    const cacheReadUsd = tokens.cacheRead === 0
+        ? 0
+        : applied.cacheRead === null
+            ? null
+            : tokens.cacheRead * applied.cacheRead;
+    const cacheWriteUsd = cacheWrite === 0 ? 0 : applied.cacheWrite === null ? null : cacheWrite * applied.cacheWrite;
+    if (cacheReadUsd === null || cacheWriteUsd === null)
+        return Option.none();
+    return Option.some((tokens.input * applied.input + cacheReadUsd + cacheWriteUsd +
+        (tokens.output + tokens.reasoning) * applied.output) / PER_MTOK);
+};
+/** A group's cost at current list price, or none when its model or a needed rate is unpriced. */
+export const groupCost = (group) => group.agent === "claude"
+    ? claudeCost(group.model, group.fast, group.tokens)
+    : codexCost(group.model, group.longPrompt, group.tokens);
+/** One request's cost at current list price, or none when its model or a needed rate is unpriced. */
+export const apiEquivalentCost = (request) => groupCost({ ...request, longPrompt: isLongPrompt(request.tokens) });
+//# sourceMappingURL=Pricing.js.map

package/dist/core/Pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pricing.js","sourceRoot":"","sources":["../../src/core/Pricing.ts"],"names":[],"mappings":"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"}

package/dist/core/Readers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What the transcript and rollout readers share: the line they are handed and the result they give
+ * back. Readers are pure, so a chunk of a file and the state carried from the previous chunk are all
+ * they need; file access and cursors live in the ingest pass.
+ *
+ * @module
+ */
+import type { BalanceReading, LimitSnapshot, UsageEvent } from "./Model.js";
+/** One complete line of a source file and the byte offset it starts at. */
+export interface SourceLine {
+    readonly offset: number;
+    readonly text: string;
+}
+/** Which source file a chunk came from, as the reader stamps it onto what it records. */
+export interface SourceFile {
+    /** The file's path relative to its source root, unique per Agent. */
+    readonly fileKey: string;
+    readonly machine: string;
+    readonly sessionId: string;
+}
+/** How many lines that looked relevant were not recorded, by reason. */
+export interface SkipCounts {
+    readonly unparseableLine: number;
+    readonly missingTimestamp: number;
+    /** Lines too long to hold in memory, skipped whole. */
+    readonly oversizedLine: number;
+}
+export type SkipReason = keyof SkipCounts;
+export declare const noSkips: SkipCounts;
+export interface ReadResult<State> {
+    readonly events: ReadonlyArray<UsageEvent>;
+    readonly snapshots: ReadonlyArray<LimitSnapshot>;
+    readonly balances: ReadonlyArray<BalanceReading>;
+    readonly skipped: SkipCounts;
+    readonly state: State;
+}
+/** Adds one skip to a count, returning a new count. */
+export declare const countSkip: (counts: SkipCounts, reason: SkipReason) => SkipCounts;
+/** Sums two skip counts. */
+export declare const mergeSkips: (left: SkipCounts, right: SkipCounts) => SkipCounts;
+/** Epoch milliseconds of an ISO timestamp, or null when it does not parse. */
+export declare const parseInstant: (iso: string) => number | null;

package/dist/core/Readers.js

@@ -0,0 +1,18 @@
+export const noSkips = { unparseableLine: 0, missingTimestamp: 0, oversizedLine: 0 };
+/** Adds one skip to a count, returning a new count. */
+export const countSkip = (counts, reason) => ({
+    ...counts,
+    [reason]: counts[reason] + 1
+});
+/** Sums two skip counts. */
+export const mergeSkips = (left, right) => ({
+    unparseableLine: left.unparseableLine + right.unparseableLine,
+    missingTimestamp: left.missingTimestamp + right.missingTimestamp,
+    oversizedLine: left.oversizedLine + right.oversizedLine
+});
+/** Epoch milliseconds of an ISO timestamp, or null when it does not parse. */
+export const parseInstant = (iso) => {
+    const millis = Date.parse(iso);
+    return Number.isFinite(millis) ? millis : null;
+};
+//# sourceMappingURL=Readers.js.map

package/dist/core/Readers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Readers.js","sourceRoot":"","sources":["../../src/core/Readers.ts"],"names":[],"mappings":"AAiCA,MAAM,CAAC,MAAM,OAAO,GAAe,EAAE,eAAe,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAA;AAUhG,uDAAuD;AACvD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAkB,EAAE,MAAkB,EAAc,EAAE,CAAC,CAAC;IAChF,GAAG,MAAM;IACT,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;CAC7B,CAAC,CAAA;AAEF,4BAA4B;AAC5B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAgB,EAAE,KAAiB,EAAc,EAAE,CAAC,CAAC;IAC9E,eAAe,EAAE,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe;IAC7D,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC,gBAAgB;IAChE,aAAa,EAAE,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa;CACxD,CAAC,CAAA;AAEF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAW,EAAiB,EAAE;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC9B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAA;AAChD,CAAC,CAAA"}

package/dist/core/Report.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Turning stored facts into what the graphs draw: usage per local period and Booking, and limit
+ * series as steps.
+ *
+ * **Mental model**
+ *
+ * - **Periods are the viewer's.** The browser sends its IANA zone; hours, days and weeks start at
+ *   local midnight (weeks on Monday), so a daylight-saving day is 23 or 25 hours long. Each stored
+ *   15-minute bucket belongs to exactly one period, because every zone offset is a multiple of 15.
+ * - **Bookings and costs are derived here** (ADR 0002), from Attribution Inputs, the Known
+ *   Projects and today's prices. Typed keys of unknown projects are counted by prefix, not hidden.
+ *   Unpriced tokens are carried beside the cost, never folded into it as zero.
+ * - **A step line needs its starting value.** Each limit series begins at the range's left edge
+ *   with the reading in force there, taken from the last snapshot before it.
+ *
+ * @module
+ */
+import { Effect } from "effect";
+import type { LimitsReport, Period, UsageReport } from "../shared/contracts.js";
+import type { LimitSnapshot, TicketTitleValue } from "./Model.js";
+import { type Range, type UsageGroup } from "./Store.js";
+export type PeriodBucket = "hour" | "day" | "week";
+declare const UnknownTimeZone_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "UnknownTimeZone";
+} & Readonly<A>;
+export declare class UnknownTimeZone extends UnknownTimeZone_base<{
+    readonly zone: string;
+}> {
+}
+/**
+ * Accepts any zone `Intl.DateTimeFormat` accepts, aliases and `Etc/GMT+5` included. The list
+ * `Intl.supportedValuesOf` returns is narrower than what the formatter takes, and a browser sends
+ * whatever its own runtime resolved.
+ */
+export declare const checkTimeZone: (zone: string) => Effect.Effect<string, UnknownTimeZone>;
+/** Every local period the range touches, each with the first 15-minute instant inside the range. */
+export declare const periodsOf: (options: {
+    readonly from: number;
+    readonly to: number;
+    readonly timeZone: string;
+    readonly bucket: PeriodBucket;
+}) => ReadonlyArray<Period>;
+/**
+ * Usage per period and Booking. `end` bounds the last period; groups outside every period are
+ * dropped. Titles are looked up by ticket key.
+ */
+export declare const buildUsageReport: (groups: ReadonlyArray<UsageGroup>, periods: ReadonlyArray<Period>, titles: Readonly<Record<string, TicketTitleValue>>, projects: ReadonlySet<string>, end?: number) => UsageReport;
+/**
+ * Limit series over a range, from every snapshot up to its end in time order. Each series starts
+ * at `from` with the reading in force there when one exists.
+ */
+export declare const buildLimitsReport: (snapshots: ReadonlyArray<LimitSnapshot>, range: Range) => Omit<LimitsReport, "balances">;
+export {};