crewly 1.20.302 → 1.20.304

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.store.js.map

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

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Usage ledger types: the immutable facts behind per-ticket time and token
+ * accounting (specs/2026-10-11-usage-ledger.md).
+ *
+ * A "unit" is one trace (a ticket, a request, a work item thread, an owner
+ * conversation). Facts only ever get appended; every statistic (category,
+ * team, owner minutes) is computed from them at report time.
+ *
+ * @module services/usage-ledger/usage-ledger.types
+ */
+/** Schema version written on every fact. */
+export declare const LEDGER_VERSION = 1;
+/**
+ * How a fact was tied to its unit.
+ * - `recorded`: the harness knew the unit when it happened.
+ * - `inferred`: rebuilt afterwards from timestamps (history backfill).
+ */
+export type Attribution = 'recorded' | 'inferred';
+/** Id of the pseudo-unit that holds an agent's usage while it worked on no ticket. */
+export declare const UNTICKETED_PREFIX = "~none:";
+/** Fields every fact carries. */
+interface FactBase {
+    v: typeof LEDGER_VERSION;
+    /** ISO time of the thing that happened (the covered hour's start, for usage / busy) */
+    ts: string;
+}
+/** What is known about a unit. Several of these merge field by field, first value wins. */
+export interface UnitMetaFact extends FactBase {
+    kind: 'unit.meta';
+    unitId: string;
+    /** `TKT-12` or a project ticket id (`CE-7`) */
+    ticketId?: string;
+    requestId?: string;
+    /** What started the trace (`request`, `owner_message`, `ticket`, …) */
+    rootKind?: string;
+    title?: string;
+    /** The owner's words / the ticket description, cut */
+    excerpt?: string;
+    team?: string;
+    project?: string;
+    /** Where the request came from (`slack-dm`, `chat`, …) */
+    channel?: string;
+    /** Conversation thread the request lives in (Slack thread ref) */
+    threadRef?: string;
+    /** When the unit began */
+    openedAt?: string;
+    attribution: Attribution;
+}
+/** An agent worked on a unit (written once per agent and unit). */
+export interface UnitAgentFact extends FactBase {
+    kind: 'unit.agent';
+    unitId: string;
+    agent: string;
+    team?: string;
+    project?: string;
+    attribution: Attribution;
+}
+/** The unit reached a terminal status. */
+export interface UnitClosedFact extends FactBase {
+    kind: 'unit.closed';
+    unitId: string;
+    status: string;
+    attribution: Attribution;
+}
+/**
+ * Token usage of one agent on one unit within one hour (a delta: the sum of
+ * the facts is the total). `share` is the fraction of the underlying events
+ * this unit carries (1, or 1/n when the turn was about n tickets); token
+ * fields are the raw event sums, before the share.
+ */
+export interface UsageFact extends FactBase {
+    kind: 'usage';
+    unitId: string;
+    agent: string;
+    team?: string;
+    model: string;
+    runtime?: string;
+    events: number;
+    share: number;
+    /** Every input token, cached ones included (see eventTokens) */
+    input: number;
+    cachedInput: number;
+    output: number;
+    cacheWrite: number;
+    /** Cost-weighted tokens (see eventTokens) */
+    budget: number;
+    /** Estimated USD at the model's rate (cache-aware) */
+    costUsd: number;
+    attribution: Attribution;
+}
+/** Agent busy time on one unit within one hour (a delta, like {@link UsageFact}). */
+export interface BusyFact extends FactBase {
+    kind: 'busy';
+    unitId: string;
+    agent: string;
+    team?: string;
+    turns: number;
+    busyMs: number;
+    share: number;
+    attribution: Attribution;
+}
+/** The owner wrote to a unit (a message delivered to an agent on it). */
+export interface OwnerMessageFact extends FactBase {
+    kind: 'owner.message';
+    unitId: string;
+    attribution: Attribution;
+}
+/** Any ledger fact. */
+export type LedgerFact = UnitMetaFact | UnitAgentFact | UnitClosedFact | UsageFact | BusyFact | OwnerMessageFact;
+/** Where a fact is written. */
+export type LedgerFile = 'live' | 'backfill';
+/** One tokens + cost tally. */
+export interface Tally {
+    input: number;
+    cachedInput: number;
+    output: number;
+    cacheWrite: number;
+    /** Raw total: input (cached included) + output */
+    total: number;
+    /** Cost-weighted total */
+    budget: number;
+    costUsd: number;
+}
+/** A zeroed {@link Tally}. */
+export declare function emptyTally(): Tally;
+export {};
+//# sourceMappingURL=usage-ledger.types.d.ts.map

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.types.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.types.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.types.js

@@ -0,0 +1,19 @@
+/**
+ * Usage ledger types: the immutable facts behind per-ticket time and token
+ * accounting (specs/2026-10-11-usage-ledger.md).
+ *
+ * A "unit" is one trace (a ticket, a request, a work item thread, an owner
+ * conversation). Facts only ever get appended; every statistic (category,
+ * team, owner minutes) is computed from them at report time.
+ *
+ * @module services/usage-ledger/usage-ledger.types
+ */
+/** Schema version written on every fact. */
+export const LEDGER_VERSION = 1;
+/** Id of the pseudo-unit that holds an agent's usage while it worked on no ticket. */
+export const UNTICKETED_PREFIX = '~none:';
+/** A zeroed {@link Tally}. */
+export function emptyTally() {
+    return { input: 0, cachedInput: 0, output: 0, cacheWrite: 0, total: 0, budget: 0, costUsd: 0 };
+}
+//# sourceMappingURL=usage-ledger.types.js.map

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.types.js","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAShC,sFAAsF;AACtF,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAmH1C,8BAA8B;AAC9B,MAAM,UAAU,UAAU;IACzB,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AAChG,CAAC"}

package/dist/backend/backend/src/services/usage-ledger/usage-report.service.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Usage report: where the owner's time and the agents' tokens went, per
+ * category / team / project / agent / ticket.
+ *
+ * Everything is computed from the ledger facts at call time. Categories are
+ * applied here (see {@link UnitClassifier}) and never stored in the facts.
+ * Owner minutes follow the span heuristic of owner-spans.ts. Figures are
+ * summed per UTC hour, so a window edge is accurate to the hour.
+ *
+ * @module services/usage-ledger/usage-report.service
+ */
+import type { LedgerRollup } from './ledger-rollup.js';
+import type { TeamLookup } from './team-directory.js';
+import { type CategoryDef } from './usage-categories.store.js';
+import { UnitClassifier } from './unit-classifier.js';
+import { type Tally } from './usage-ledger.types.js';
+/** Ways to group a report. */
+export declare const REPORT_DIMENSIONS: readonly ["category", "team", "project", "agent", "ticket"];
+/** A grouping. */
+export type ReportDimension = (typeof REPORT_DIMENSIONS)[number];
+/** Request for a report. */
+export interface ReportQuery {
+    /** Window start (ms) */
+    sinceMs: number;
+    /** Window end (ms) */
+    untilMs: number;
+    by: ReportDimension;
+    /** Categories to use instead of the stored ones (ad hoc) */
+    categories?: CategoryDef[];
+    /** Keep only these groups (by name), e.g. two categories to compare */
+    only?: string[];
+    /** Groups returned (default 50) */
+    limit?: number;
+}
+/** One ticket in a group. */
+export interface TicketLine {
+    unitId: string;
+    ticketId?: string;
+    title: string;
+    team?: string;
+    ownerMinutes: number;
+    agentBusyMinutes: number;
+    tokens: number;
+    costUsd: number;
+    inferred: boolean;
+}
+/** One group of a report. */
+export interface ReportGroup {
+    key: string;
+    ownerMinutes: number;
+    agentBusyMinutes: number;
+    /** Token figures: `budget` is the cost-weighted headline, `total` the raw sum */
+    tokens: Tally;
+    costUsd: number;
+    ticketCount: number;
+    topTickets: TicketLine[];
+}
+/** A report. */
+export interface UsageReport {
+    window: {
+        since: string;
+        until: string;
+    };
+    by: ReportDimension;
+    categories: {
+        setId: string;
+        source: 'stored' | 'ad-hoc' | 'default';
+        names: string[];
+        llmClassified: number;
+        unclassified: number;
+    } | null;
+    totals: Omit<ReportGroup, 'key' | 'topTickets'>;
+    groups: ReportGroup[];
+    /** Voice / Slack friendly text */
+    summary: string;
+    notes: string[];
+}
+/** Where the report gets its inputs. */
+export interface ReportDeps {
+    rollup: LedgerRollup;
+    directory: TeamLookup;
+    classifier: UnitClassifier;
+    /** Stored category definitions */
+    categories: () => Promise<CategoryDef[]>;
+    /** Called before reading so buffered facts are on disk and in the rollup */
+    sync: () => Promise<void>;
+    now?: () => number;
+}
+/**
+ * Parse a window start.
+ *
+ * @param value - `7d`, `24h`, `2w`, `90m`, or an ISO date / time
+ * @param nowMs - Now (ms)
+ * @returns Epoch ms, or null when unreadable
+ */
+export declare function parseSince(value: string, nowMs: number): number | null;
+/**
+ * Format minutes for speech: `45m`, `2h10m`, `1d3h`.
+ *
+ * @param minutes - Minutes
+ * @returns Short text
+ */
+export declare function formatMinutes(minutes: number): string;
+/**
+ * Builds reports from the ledger.
+ */
+export declare class UsageReportService {
+    private readonly deps;
+    constructor(deps: ReportDeps);
+    /**
+     * Compute a report.
+     *
+     * @param query - Window, grouping, optional ad-hoc categories
+     * @returns The report
+     */
+    report(query: ReportQuery): Promise<UsageReport>;
+    private teamOf;
+    /** The team a ticket is credited to: the recorded one, else the team with the most spend. */
+    private primaryTeam;
+    private projectOf;
+    private labelOf;
+    private summarize;
+}
+//# sourceMappingURL=usage-report.service.d.ts.map

package/dist/backend/backend/src/services/usage-ledger/usage-report.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-report.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-report.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/usage-ledger/usage-report.service.js

@@ -0,0 +1,372 @@
+/**
+ * Usage report: where the owner's time and the agents' tokens went, per
+ * category / team / project / agent / ticket.
+ *
+ * Everything is computed from the ledger facts at call time. Categories are
+ * applied here (see {@link UnitClassifier}) and never stored in the facts.
+ * Owner minutes follow the span heuristic of owner-spans.ts. Figures are
+ * summed per UTC hour, so a window edge is accurate to the hour.
+ *
+ * @module services/usage-ledger/usage-report.service
+ */
+import { compactTokens } from '../usage/token-format.js';
+import { buildOwnerSpans, ownerMinutesByUnit } from './owner-spans.js';
+import { categorySetId } from './usage-categories.store.js';
+import { NO_TICKET_CATEGORY, OTHER_CATEGORY } from './unit-classifier.js';
+import { emptyTally } from './usage-ledger.types.js';
+/** Ways to group a report. */
+export const REPORT_DIMENSIONS = ['category', 'team', 'project', 'agent', 'ticket'];
+const HOUR_MS = 3_600_000;
+/**
+ * Parse a window start.
+ *
+ * @param value - `7d`, `24h`, `2w`, `90m`, or an ISO date / time
+ * @param nowMs - Now (ms)
+ * @returns Epoch ms, or null when unreadable
+ */
+export function parseSince(value, nowMs) {
+    const rel = /^(\d+(?:\.\d+)?)\s*([mhdw])$/i.exec(value.trim());
+    if (rel) {
+        const unit = { m: 60_000, h: HOUR_MS, d: 24 * HOUR_MS, w: 7 * 24 * HOUR_MS }[rel[2].toLowerCase()];
+        return nowMs - Number(rel[1]) * unit;
+    }
+    const abs = Date.parse(value);
+    return Number.isFinite(abs) ? abs : null;
+}
+/**
+ * Format minutes for speech: `45m`, `2h10m`, `1d3h`.
+ *
+ * @param minutes - Minutes
+ * @returns Short text
+ */
+export function formatMinutes(minutes) {
+    const m = Math.round(minutes);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return m % 60 ? `${h}h${m % 60}m` : `${h}h`;
+    return h % 24 ? `${Math.floor(h / 24)}d${h % 24}h` : `${Math.floor(h / 24)}d`;
+}
+/** Add `weight` times a usage entry to a tally. */
+function addUsage(t, e) {
+    const w = e.share;
+    t.input += e.input * w;
+    t.cachedInput += e.cachedInput * w;
+    t.output += e.output * w;
+    t.cacheWrite += e.cacheWrite * w;
+    t.total += (e.input + e.output) * w;
+    t.budget += e.budget * w;
+    t.costUsd += e.costUsd * w;
+}
+function addTally(into, from) {
+    into.input += from.input;
+    into.cachedInput += from.cachedInput;
+    into.output += from.output;
+    into.cacheWrite += from.cacheWrite;
+    into.total += from.total;
+    into.budget += from.budget;
+    into.costUsd += from.costUsd;
+}
+function roundTally(t) {
+    return {
+        input: Math.round(t.input),
+        cachedInput: Math.round(t.cachedInput),
+        output: Math.round(t.output),
+        cacheWrite: Math.round(t.cacheWrite),
+        total: Math.round(t.total),
+        budget: Math.round(t.budget),
+        costUsd: Math.round(t.costUsd * 10_000) / 10_000,
+    };
+}
+const round1 = (n) => Math.round(n * 10) / 10;
+/**
+ * Builds reports from the ledger.
+ */
+export class UsageReportService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Compute a report.
+     *
+     * @param query - Window, grouping, optional ad-hoc categories
+     * @returns The report
+     */
+    async report(query) {
+        await this.deps.sync();
+        await this.deps.directory.ready();
+        const { rollup } = this.deps;
+        const from = query.sinceMs;
+        const to = query.untilMs;
+        // Owner minutes across every ticket (overlaps are shared, so all spans are needed)
+        const spans = [];
+        for (const u of rollup.units.values()) {
+            if (u.ownerMessages.length > 0)
+                spans.push(...buildOwnerSpans(u.unitId, u.ownerMessages));
+        }
+        const ownerMinutes = ownerMinutesByUnit(spans, from, to);
+        const windows = [];
+        for (const unit of rollup.units.values()) {
+            const w = { unit, tally: emptyTally(), busyMs: 0, owner: ownerMinutes.get(unit.unitId) ?? 0, byAgent: new Map(), byTeam: new Map() };
+            const slice = (m, key) => {
+                let s = m.get(key);
+                if (!s) {
+                    s = { tally: emptyTally(), busyMs: 0, ownerMinutes: 0 };
+                    m.set(key, s);
+                }
+                return s;
+            };
+            for (const e of unit.usage) {
+                if (e.hourMs + HOUR_MS <= from || e.hourMs >= to)
+                    continue;
+                addUsage(w.tally, e);
+                const one = emptyTally();
+                addUsage(one, e);
+                addTally(slice(w.byAgent, e.agent).tally, one);
+                addTally(slice(w.byTeam, this.teamOf(e.team, e.agent) ?? '(unknown team)').tally, one);
+            }
+            for (const e of unit.busy) {
+                if (e.hourMs + HOUR_MS <= from || e.hourMs >= to)
+                    continue;
+                const ms = e.busyMs * e.share;
+                w.busyMs += ms;
+                slice(w.byAgent, e.agent).busyMs += ms;
+                slice(w.byTeam, this.teamOf(e.team, e.agent) ?? '(unknown team)').busyMs += ms;
+            }
+            if (w.tally.total === 0 && w.busyMs === 0 && w.owner === 0)
+                continue;
+            w.team = this.primaryTeam(unit, w.byTeam);
+            windows.push(w);
+        }
+        // Categories
+        let categoryInfo = null;
+        let categoryOf = new Map();
+        if (query.by === 'category') {
+            const stored = await this.deps.categories();
+            const defs = query.categories ?? stored;
+            const source = query.categories ? 'ad-hoc' : stored.length > 0 ? 'stored' : 'default';
+            const units = windows
+                .filter((w) => !w.unit.synthetic)
+                .map((w) => ({
+                unitId: w.unit.unitId,
+                ticketId: w.unit.ticketId,
+                title: w.unit.title,
+                excerpt: w.unit.excerpt,
+                team: w.team,
+                project: this.projectOf(w.unit),
+            }));
+            const result = await this.deps.classifier.classify(units, defs);
+            categoryOf = result.categories;
+            categoryInfo = { setId: categorySetId(defs), source, names: defs.map((d) => d.name), llmClassified: result.llmClassified, unclassified: result.unclassified };
+        }
+        const groups = new Map();
+        const add = (key, unitId, tally, busyMs, owner) => {
+            let g = groups.get(key);
+            if (!g) {
+                g = { key, slices: new Map() };
+                groups.set(key, g);
+            }
+            let s = g.slices.get(unitId);
+            if (!s) {
+                s = { tally: emptyTally(), busyMs: 0, ownerMinutes: 0 };
+                g.slices.set(unitId, s);
+            }
+            addTally(s.tally, tally);
+            s.busyMs += busyMs;
+            s.ownerMinutes += owner;
+        };
+        for (const w of windows) {
+            const u = w.unit;
+            switch (query.by) {
+                case 'ticket':
+                    add(this.labelOf(u), u.unitId, w.tally, w.busyMs, w.owner);
+                    break;
+                case 'category':
+                    add(u.synthetic ? NO_TICKET_CATEGORY : (categoryOf.get(u.unitId) ?? OTHER_CATEGORY), u.unitId, w.tally, w.busyMs, w.owner);
+                    break;
+                case 'project':
+                    add(this.projectOf(u) ?? '(no project)', u.unitId, w.tally, w.busyMs, w.owner);
+                    break;
+                case 'team': {
+                    const primary = w.team ?? '(unknown team)';
+                    if (w.byTeam.size === 0)
+                        add(primary, u.unitId, w.tally, w.busyMs, w.owner);
+                    for (const [team, s] of w.byTeam)
+                        add(team, u.unitId, s.tally, s.busyMs, team === primary ? w.owner : 0);
+                    if (w.byTeam.size > 0 && !w.byTeam.has(primary) && w.owner > 0)
+                        add(primary, u.unitId, emptyTally(), 0, w.owner);
+                    break;
+                }
+                case 'agent':
+                    for (const [agent, s] of w.byAgent)
+                        add(agent, u.unitId, s.tally, s.busyMs, 0);
+                    break;
+            }
+        }
+        const teamOfUnit = new Map(windows.map((w) => [w.unit.unitId, w.team]));
+        const lineOf = (unitId, s) => {
+            const u = rollup.units.get(unitId);
+            return {
+                unitId,
+                ...(u.ticketId ? { ticketId: u.ticketId } : {}),
+                title: u.title || u.ticketId || unitId,
+                ...(teamOfUnit.get(unitId) ? { team: teamOfUnit.get(unitId) } : {}),
+                ownerMinutes: round1(s.ownerMinutes),
+                agentBusyMinutes: round1(s.busyMs / 60_000),
+                tokens: Math.round(s.tally.budget),
+                costUsd: Math.round(s.tally.costUsd * 10_000) / 10_000,
+                inferred: u.inferred,
+            };
+        };
+        let out = [...groups.values()].map((g) => {
+            const tally = emptyTally();
+            let busyMs = 0;
+            let owner = 0;
+            let tickets = 0;
+            for (const [unitId, s] of g.slices) {
+                addTally(tally, s.tally);
+                busyMs += s.busyMs;
+                owner += s.ownerMinutes;
+                if (!(rollup.units.get(unitId)?.synthetic ?? false))
+                    tickets += 1;
+            }
+            const top = [...g.slices.entries()]
+                .filter(([id]) => !(rollup.units.get(id)?.synthetic ?? false))
+                .sort((a, b) => b[1].tally.costUsd - a[1].tally.costUsd || b[1].busyMs - a[1].busyMs)
+                .slice(0, 5)
+                .map(([id, s]) => lineOf(id, s));
+            return {
+                key: g.key,
+                ownerMinutes: round1(owner),
+                agentBusyMinutes: round1(busyMs / 60_000),
+                tokens: roundTally(tally),
+                costUsd: Math.round(tally.costUsd * 10_000) / 10_000,
+                ticketCount: tickets,
+                topTickets: top,
+            };
+        });
+        if (query.only && query.only.length > 0) {
+            const wanted = new Set(query.only.map((n) => n.toLowerCase()));
+            out = out.filter((g) => wanted.has(g.key.toLowerCase()));
+        }
+        out.sort((a, b) => b.costUsd - a.costUsd || b.agentBusyMinutes - a.agentBusyMinutes || b.ownerMinutes - a.ownerMinutes);
+        const totalTally = emptyTally();
+        let totalBusy = 0;
+        let totalOwner = 0;
+        const tickets = new Set();
+        if (query.only && query.only.length > 0) {
+            // A filtered report totals only what it shows.
+            for (const g of out) {
+                for (const [unitId, s] of groups.get(g.key)?.slices ?? []) {
+                    addTally(totalTally, s.tally);
+                    totalBusy += s.busyMs;
+                    totalOwner += s.ownerMinutes;
+                    if (!(rollup.units.get(unitId)?.synthetic ?? false))
+                        tickets.add(unitId);
+                }
+            }
+        }
+        else {
+            for (const w of windows) {
+                addTally(totalTally, w.tally);
+                totalBusy += w.busyMs;
+                totalOwner += w.owner;
+                if (!w.unit.synthetic)
+                    tickets.add(w.unit.unitId);
+            }
+        }
+        const totals = {
+            ownerMinutes: round1(totalOwner),
+            agentBusyMinutes: round1(totalBusy / 60_000),
+            tokens: roundTally(totalTally),
+            costUsd: Math.round(totalTally.costUsd * 10_000) / 10_000,
+            ticketCount: tickets.size,
+        };
+        const limit = Math.max(1, query.limit ?? 50);
+        const shown = out.slice(0, limit);
+        const inferredUnits = windows.filter((w) => w.unit.inferred && !w.unit.synthetic).length;
+        const notes = [
+            'Tokens are cost-weighted (cache reads count 0.1x, cache writes 1.25x for Claude); tokens.total is the raw sum.',
+            'Owner minutes: messages on one ticket within 10 minutes form a span; overlapping spans share the time.',
+            ...(inferredUnits > 0 ? [`${inferredUnits} ticket(s) are partly rebuilt from history (attribution "inferred").`] : []),
+            ...(categoryInfo && categoryInfo.unclassified > 0 ? [`${categoryInfo.unclassified} ticket(s) matched no category and no model was available; shown as "${OTHER_CATEGORY}".`] : []),
+        ];
+        const report = {
+            window: { since: new Date(from).toISOString(), until: new Date(to).toISOString() },
+            by: query.by,
+            categories: categoryInfo,
+            totals,
+            groups: shown,
+            summary: '',
+            notes,
+        };
+        report.summary = this.summarize(report, out.length, to - from);
+        return report;
+    }
+    teamOf(recorded, agent) {
+        return recorded ?? this.deps.directory.lookup(agent)?.team;
+    }
+    /** The team a ticket is credited to: the recorded one, else the team with the most spend. */
+    primaryTeam(u, byTeam) {
+        if (u.team)
+            return u.team;
+        let best;
+        let score = -1;
+        for (const [team, s] of byTeam) {
+            const sc = s.tally.costUsd * 1000 + s.busyMs / 1000;
+            if (team !== '(unknown team)' && sc > score) {
+                score = sc;
+                best = team;
+            }
+        }
+        if (best)
+            return best;
+        for (const [agent, info] of u.agents) {
+            const team = this.teamOf(info.team, agent);
+            if (team)
+                return team;
+        }
+        for (const e of u.usage)
+            if (e.team)
+                return e.team;
+        return undefined;
+    }
+    projectOf(u) {
+        if (u.project)
+            return u.project;
+        for (const info of u.agents.values())
+            if (info.project)
+                return info.project;
+        return undefined;
+    }
+    labelOf(u) {
+        const id = u.ticketId ?? u.unitId;
+        return u.title ? `${id}: ${u.title}` : id;
+    }
+    summarize(report, groupCount, spanMs) {
+        const days = spanMs / (24 * HOUR_MS);
+        const label = days >= 1 ? `last ${Math.round(days * 10) / 10 === Math.round(days) ? Math.round(days) : Math.round(days * 10) / 10} days` : `last ${Math.max(1, Math.round(spanMs / HOUR_MS))} hours`;
+        const t = report.totals;
+        const lines = [
+            `Usage, ${label}: ${t.ticketCount} tickets, ${formatMinutes(t.agentBusyMinutes)} of agent work, ${formatMinutes(t.ownerMinutes)} of your time, ${compactTokens(t.tokens.budget)} tokens (about $${t.costUsd.toFixed(2)}).`,
+        ];
+        if (report.groups.length > 0) {
+            lines.push(`By ${report.by}:`);
+            for (const g of report.groups.slice(0, 6)) {
+                const parts = [
+                    g.ownerMinutes > 0 ? `${formatMinutes(g.ownerMinutes)} of you` : '',
+                    g.agentBusyMinutes > 0 ? `${formatMinutes(g.agentBusyMinutes)} agent work` : '',
+                    `${compactTokens(g.tokens.budget)} tokens ($${g.costUsd.toFixed(2)})`,
+                    report.by === 'ticket' || report.by === 'agent' || g.ticketCount === 0 ? '' : `${g.ticketCount} tickets`,
+                ].filter(Boolean);
+                lines.push(`- ${g.key}: ${parts.join(', ')}`);
+            }
+            if (groupCount > 6)
+                lines.push(`- and ${groupCount - 6} more`);
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=usage-report.service.js.map