@knpkv/agent-usage 0.1.0

package/dist/core/Report.js

@@ -0,0 +1,270 @@
+/**
+ * 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 { Data, Effect, Option } from "effect";
+import { attribute, bookingId, projectOf } from "./Attribution.js";
+import { totalTokens } from "./Model.js";
+import { groupCost } from "./Pricing.js";
+import { BUCKET_MILLIS } from "./Store.js";
+export class UnknownTimeZone extends Data.TaggedError("UnknownTimeZone") {
+}
+/**
+ * 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 const checkTimeZone = (zone) => Effect.try({
+    try: () => new Intl.DateTimeFormat("en-CA", { timeZone: zone }).resolvedOptions().timeZone,
+    catch: () => new UnknownTimeZone({ zone })
+}).pipe(Effect.as(zone));
+const formatters = new Map();
+const formatterFor = (timeZone) => {
+    const cached = formatters.get(timeZone);
+    if (cached !== undefined)
+        return cached;
+    const created = new Intl.DateTimeFormat("en-CA", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        hourCycle: "h23",
+        timeZoneName: "longOffset"
+    });
+    formatters.set(timeZone, created);
+    return created;
+};
+const pad = (value) => String(value).padStart(2, "0");
+/** The local period an instant falls in, as a sortable key. */
+const periodKey = (instant, timeZone, bucket) => {
+    const parts = new Map(formatterFor(timeZone).formatToParts(instant).map((part) => [part.type, part.value]));
+    const year = Number(parts.get("year"));
+    const month = Number(parts.get("month"));
+    const day = Number(parts.get("day"));
+    // The offset keeps the hour that repeats when clocks go back apart from its first occurrence.
+    if (bucket === "hour") {
+        return `${year}-${pad(month)}-${pad(day)}T${parts.get("hour") ?? "00"}${parts.get("timeZoneName") ?? ""}`;
+    }
+    if (bucket === "day")
+        return `${year}-${pad(month)}-${pad(day)}`;
+    // Calendar arithmetic on the local date alone: back up to Monday.
+    const date = new Date(Date.UTC(year, month - 1, day));
+    const sinceMonday = (date.getUTCDay() + 6) % 7;
+    const monday = new Date(Date.UTC(year, month - 1, day - sinceMonday));
+    return `${monday.getUTCFullYear()}-${pad(monday.getUTCMonth() + 1)}-${pad(monday.getUTCDate())}`;
+};
+/** Every local period the range touches, each with the first 15-minute instant inside the range. */
+export const periodsOf = (options) => {
+    const periods = [];
+    const first = options.from - (options.from % BUCKET_MILLIS);
+    for (let instant = first; instant < options.to; instant += BUCKET_MILLIS) {
+        const key = periodKey(instant, options.timeZone, options.bucket);
+        if (periods.at(-1)?.key !== key)
+            periods.push({ key, start: Math.max(instant, options.from) });
+    }
+    return periods;
+};
+/** Which period a bucket start belongs to, by binary search over period starts. */
+const periodIndex = (periods, bucketStart, end) => {
+    const first = periods[0]?.start;
+    if (first === undefined)
+        return null;
+    // The range may start inside a 15-minute bucket; the store already kept only the events inside
+    // the range, so that first partial bucket belongs to the first period.
+    const instant = bucketStart < first && bucketStart + BUCKET_MILLIS > first ? first : bucketStart;
+    if (instant < first || instant >= end)
+        return null;
+    let low = 0;
+    let high = periods.length - 1;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if ((periods[middle]?.start ?? 0) <= instant)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return low;
+};
+const zeroTokens = { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite5m: 0, cacheWrite1h: 0 };
+const addTokens = (left, right) => ({
+    input: left.input + right.input,
+    output: left.output + right.output,
+    reasoning: left.reasoning + right.reasoning,
+    cacheRead: left.cacheRead + right.cacheRead,
+    cacheWrite5m: left.cacheWrite5m + right.cacheWrite5m,
+    cacheWrite1h: left.cacheWrite1h + right.cacheWrite1h
+});
+/**
+ * Usage per period and Booking. `end` bounds the last period; groups outside every period are
+ * dropped. Titles are looked up by ticket key.
+ */
+export const buildUsageReport = (groups, periods, titles, projects, end = Number.POSITIVE_INFINITY) => {
+    const bookings = new Map();
+    const cells = new Map();
+    const unpricedModels = new Set();
+    let unpricedTokens = 0;
+    const ignored = new Map();
+    for (const group of groups) {
+        const period = periodIndex(periods, group.bucketStart, end);
+        if (period === null)
+            continue;
+        const { booking, ignoredKey } = attribute(group.attribution, projects);
+        if (ignoredKey !== null) {
+            const prefix = projectOf(ignoredKey);
+            ignored.set(prefix, (ignored.get(prefix) ?? 0) + group.requests);
+        }
+        const id = bookingId(booking);
+        const tokens = totalTokens(group.tokens);
+        const cost = groupCost(group);
+        const costUsd = Option.getOrElse(cost, () => 0);
+        const unpriced = Option.isNone(cost) ? tokens : 0;
+        if (Option.isNone(cost)) {
+            unpricedModels.add(group.model);
+            unpricedTokens += tokens;
+        }
+        const existing = bookings.get(id);
+        const current = existing ?? {
+            summary: {
+                id,
+                booking,
+                title: booking._tag === "Ticket" ? titles[booking.key] ?? { _tag: "Unknown", reason: "NotLookedUp" } : null,
+                requests: 0,
+                tokens: zeroTokens,
+                costUsd: 0,
+                unpricedTokens: 0
+            },
+            agents: new Set(),
+            unpricedModels: new Set()
+        };
+        current.agents.add(group.agent);
+        if (Option.isNone(cost))
+            current.unpricedModels.add(group.model);
+        bookings.set(id, {
+            ...current,
+            summary: {
+                ...current.summary,
+                requests: current.summary.requests + group.requests,
+                tokens: addTokens(current.summary.tokens, group.tokens),
+                costUsd: current.summary.costUsd + costUsd,
+                unpricedTokens: current.summary.unpricedTokens + unpriced
+            }
+        });
+        const cellKey = `${period}\u0000${id}`;
+        const cell = cells.get(cellKey) ?? { period, booking: id, tokens: 0, costUsd: 0, unpricedTokens: 0 };
+        cells.set(cellKey, {
+            ...cell,
+            tokens: cell.tokens + tokens,
+            costUsd: cell.costUsd + costUsd,
+            unpricedTokens: cell.unpricedTokens + unpriced
+        });
+    }
+    const summaries = [...bookings.values()]
+        .map((booking) => ({
+        ...booking.summary,
+        agents: [...booking.agents].sort(),
+        unpricedModels: [...booking.unpricedModels].sort()
+    }))
+        .sort((left, right) => right.costUsd - left.costUsd || totalTokens(right.tokens) - totalTokens(left.tokens) ||
+        left.id.localeCompare(right.id));
+    const order = new Map(summaries.map((summary, index) => [summary.id, index]));
+    return {
+        periods,
+        bookings: summaries,
+        cells: [...cells.values()].sort((left, right) => left.period - right.period || (order.get(left.booking) ?? 0) - (order.get(right.booking) ?? 0)),
+        unpriced: { tokens: unpricedTokens, models: [...unpricedModels].sort() },
+        ignoredKeys: [...ignored]
+            .map(([prefix, requests]) => ({ prefix, requests }))
+            .sort((left, right) => right.requests - left.requests || left.prefix.localeCompare(right.prefix))
+    };
+};
+/**
+ * Which series a snapshot continues. Codex reports windows by slot (`primary`, `secondary`) and a
+ * plan change moves the weekly window between slots, so Codex series follow the window's length.
+ * Claude names each window, and two weekly windows (`seven_day`, `seven_day_opus`) are different
+ * allowances, so Claude series follow the name.
+ */
+const seriesKey = (snapshot) => snapshot.source === "codex-rollout" && snapshot.windowMinutes !== null
+    ? `${snapshot.agent}\u0000${snapshot.windowMinutes}m`
+    : `${snapshot.agent}\u0000${snapshot.label}`;
+const sameReading = (left, right) => left._tag === "Known" && right._tag === "Known"
+    ? left.usedPercent === right.usedPercent && left.resetsAt === right.resetsAt
+    : left._tag === "Unknown" && right._tag === "Unknown" && left.reason === right.reason;
+/**
+ * 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 const buildLimitsReport = (snapshots, range) => {
+    const series = new Map();
+    const latest = new Map();
+    const append = (entry, at, reading) => {
+        const point = { at: Math.max(at, range.from), reading };
+        // Before the range, only the newest reading matters: it becomes the left-edge point.
+        if (at < range.from) {
+            entry.points = [point];
+            return;
+        }
+        // An unchanged reading continues the step it repeats; a failed poll in between has already
+        // broken it with an Unknown point, so a recovery still starts a new one.
+        const last = entry.points.at(-1);
+        if (last !== undefined && sameReading(last.reading, reading))
+            return;
+        entry.points.push(point);
+    };
+    const ordered = [...snapshots].sort((left, right) => left.observedAt - right.observedAt);
+    for (const snapshot of ordered) {
+        if (snapshot.observedAt >= range.to)
+            continue;
+        const key = seriesKey(snapshot);
+        // The tiles show the newest observation, so "read … ago" moves on with unchanged readings.
+        latest.set(key, snapshot);
+        const entry = series.get(key) ??
+            {
+                agent: snapshot.agent,
+                label: snapshot.label,
+                windowMinutes: snapshot.windowMinutes,
+                source: snapshot.source,
+                points: []
+            };
+        entry.label = snapshot.label;
+        entry.windowMinutes = snapshot.windowMinutes;
+        series.set(key, entry);
+        append(entry, snapshot.observedAt, snapshot.reading);
+        // A source that could not be read at all breaks every window it reports, so no level is
+        // carried across the outage.
+        if (snapshot.label === "*") {
+            for (const [other, otherEntry] of series) {
+                if (other !== key && otherEntry.agent === snapshot.agent && otherEntry.source === snapshot.source) {
+                    append(otherEntry, snapshot.observedAt, snapshot.reading);
+                }
+            }
+        }
+    }
+    const byOrder = (left, right) => left.agent.localeCompare(right.agent) || left.label.localeCompare(right.label);
+    // A series with no Known reading still in force inside the range has nothing to draw.
+    const live = [...series.values()].map((entry) => ({
+        agent: entry.agent,
+        label: entry.label,
+        windowMinutes: entry.windowMinutes,
+        points: entry.points
+    })).filter((entry) => entry.points.some((point) => point.reading._tag === "Known" &&
+        (point.at > range.from || point.reading.resetsAt === null || point.reading.resetsAt > range.from)));
+    return {
+        series: live.sort(byOrder),
+        latest: [...latest.values()].sort(byOrder)
+    };
+};
+//# sourceMappingURL=Report.js.map

package/dist/core/Report.js.map

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

package/dist/core/Store.d.ts

@@ -0,0 +1,94 @@
+import { Context, Effect, Layer, Option, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { Agent, type BalanceReading, type LimitSnapshot, type UsageEvent } from "./Model.js";
+declare const StoreError_base: Schema.Class<StoreError, Schema.TaggedStruct<"StoreError", {
+    readonly operation: Schema.String;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+export declare class StoreError extends StoreError_base {
+}
+/** How far a source file has been read, and the reader state to resume with (reader-owned JSON). */
+export declare const Cursor: Schema.Struct<{
+    /** Device and inode: a file that was replaced reads from 0 again. */
+    readonly identity: Schema.String;
+    readonly offset: Schema.Int;
+    readonly state: Schema.String;
+}>;
+export type Cursor = typeof Cursor.Type;
+export interface Chunk {
+    readonly agent: Agent;
+    readonly fileKey: string;
+    readonly cursor: Cursor;
+    readonly events: ReadonlyArray<UsageEvent>;
+    readonly snapshots: ReadonlyArray<LimitSnapshot>;
+    readonly balances: ReadonlyArray<BalanceReading>;
+}
+/** A half-open time range in epoch milliseconds. */
+export interface Range {
+    readonly from: number;
+    readonly to: number;
+}
+/** A range on one Machine: every read is scoped to the Machine this server runs as (ADR 0001). */
+export interface MachineRange extends Range {
+    readonly machine: string;
+}
+/** Usage summed over one 15-minute bucket and every dimension that prices or books it. */
+export declare const UsageGroup: Schema.Struct<{
+    readonly bucketStart: Schema.Int;
+    readonly agent: Schema.Literals<readonly ["claude", "codex"]>;
+    readonly model: Schema.String;
+    readonly fast: Schema.Boolean;
+    readonly longPrompt: Schema.Boolean;
+    readonly attribution: Schema.Struct<{
+        readonly cwd: Schema.String;
+        readonly branch: Schema.String;
+        readonly activeTicket: Schema.NullOr<Schema.String>;
+    }>;
+    readonly requests: Schema.Int;
+    readonly tokens: Schema.Struct<{
+        readonly input: Schema.Int;
+        readonly output: Schema.Int;
+        readonly reasoning: Schema.Int;
+        readonly cacheRead: Schema.Int;
+        readonly cacheWrite5m: Schema.Int;
+        readonly cacheWrite1h: Schema.Int;
+    }>;
+}>;
+export type UsageGroup = typeof UsageGroup.Type;
+export declare const TicketTitle: Schema.Struct<{
+    readonly key: Schema.String;
+    /** Null when the lookup ran and found no title. */
+    readonly summary: Schema.NullOr<Schema.String>;
+    readonly fetchedAt: Schema.Int;
+}>;
+export type TicketTitle = typeof TicketTitle.Type;
+export declare const BUCKET_MILLIS: number;
+declare const UsageStore_base: Context.ServiceClass<UsageStore, "@knpkv/agent-usage/core/Store/UsageStore", {
+    readonly cursor: (agent: Agent, fileKey: string) => Effect.Effect<Option.Option<Cursor>, StoreError>;
+    /** Writes a chunk's events, observations and cursor in one transaction. */
+    readonly commitChunk: (chunk: Chunk) => Effect.Effect<{
+        readonly eventsAdded: number;
+    }, StoreError>;
+    /** Records observations made outside a file chunk, such as a limit poll. */
+    readonly recordObservations: (snapshots: ReadonlyArray<LimitSnapshot>, balances: ReadonlyArray<BalanceReading>) => Effect.Effect<void, StoreError>;
+    readonly usageGroups: (range: MachineRange) => Effect.Effect<ReadonlyArray<UsageGroup>, StoreError>;
+    /** Every distinct branch and working directory ever recorded: what vouches for Known Projects. */
+    readonly places: (machine: string) => Effect.Effect<ReadonlyArray<{
+        readonly branch: string;
+        readonly cwd: string;
+    }>, StoreError>;
+    /**
+     * A Machine's limit history for a range, compressed: per series, the last observation before the
+     * range, every change inside it (an equal reading after a failed poll counts as a change, so the
+     * recovery shows), and the last observation before the range ends.
+     */
+    readonly limitSnapshots: (range: MachineRange) => Effect.Effect<ReadonlyArray<LimitSnapshot>, StoreError>;
+    /** The newest reading of each balance kind on each machine. */
+    readonly latestBalances: (machine: string) => Effect.Effect<ReadonlyArray<BalanceReading>, StoreError>;
+    readonly tickets: (keys: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<TicketTitle>, StoreError>;
+    readonly saveTicket: (ticket: TicketTitle) => Effect.Effect<void, StoreError>;
+}>;
+export declare class UsageStore extends UsageStore_base {
+    static readonly layer: Layer.Layer<UsageStore, StoreError, SqlClient.SqlClient>;
+}
+export {};