crewly 1.20.302 → 1.20.304

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

@@ -0,0 +1,189 @@
+/**
+ * In-memory fold of the ledger files into per-unit rollups.
+ *
+ * Reads are incremental: each file's byte offset is remembered, so a refresh
+ * only parses what was appended since the last one (the first refresh after a
+ * restart reads everything once). The rollup is derived data; the files stay
+ * the source of truth.
+ *
+ * @module services/usage-ledger/ledger-rollup
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { UNTICKETED_PREFIX } from './usage-ledger.types.js';
+const READ_CHUNK = 1 << 20;
+/**
+ * Per-unit rollups of the ledger.
+ */
+export class LedgerRollup {
+    units = new Map();
+    offsets = new Map();
+    running = Promise.resolve();
+    /** Facts folded in so far */
+    factCount = 0;
+    /**
+     * Fold in whatever was appended since the last refresh. Calls are serialised.
+     *
+     * @param store - The ledger store
+     */
+    refresh(store) {
+        this.running = this.running.then(() => this.run(store)).catch(() => undefined);
+        return this.running;
+    }
+    async run(store) {
+        const files = await store.listFiles();
+        for (const name of files) {
+            const file = path.join(store.dir, name);
+            let size;
+            try {
+                size = (await fs.stat(file)).size;
+            }
+            catch {
+                continue;
+            }
+            const known = this.offsets.get(name) ?? 0;
+            if (size < known) {
+                // A file got shorter: the ledger was edited from outside. Start over.
+                this.units.clear();
+                this.offsets.clear();
+                this.factCount = 0;
+                await this.run(store);
+                return;
+            }
+            if (size === known)
+                continue;
+            this.offsets.set(name, known + (await this.readNew(file, known, size)));
+        }
+    }
+    /**
+     * Read complete lines from `from` to `size`.
+     *
+     * @returns Bytes consumed (up to and including the last newline)
+     */
+    async readNew(file, from, size) {
+        const handle = await fs.open(file, 'r');
+        try {
+            let consumed = 0;
+            let pending = Buffer.alloc(0);
+            let position = from;
+            while (position < size) {
+                const buf = Buffer.alloc(Math.min(READ_CHUNK, size - position));
+                const { bytesRead } = await handle.read(buf, 0, buf.length, position);
+                if (bytesRead === 0)
+                    break;
+                position += bytesRead;
+                pending = Buffer.concat([pending, buf.subarray(0, bytesRead)]);
+                const lastNewline = pending.lastIndexOf(0x0a);
+                if (lastNewline < 0)
+                    continue;
+                const complete = pending.subarray(0, lastNewline + 1).toString('utf-8');
+                pending = pending.subarray(lastNewline + 1);
+                consumed += Buffer.byteLength(complete);
+                for (const line of complete.split('\n'))
+                    this.foldLine(line);
+            }
+            return consumed;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    foldLine(line) {
+        if (!line.trim())
+            return;
+        try {
+            const fact = JSON.parse(line);
+            if (fact && typeof fact === 'object' && typeof fact.unitId === 'string')
+                this.fold(fact);
+        }
+        catch {
+            // a torn or foreign line
+        }
+    }
+    unit(unitId, ms) {
+        let u = this.units.get(unitId);
+        if (!u) {
+            u = {
+                unitId,
+                synthetic: unitId.startsWith(UNTICKETED_PREFIX),
+                firstMs: ms,
+                lastMs: ms,
+                agents: new Map(),
+                usage: [],
+                busy: [],
+                ownerMessages: [],
+                inferred: false,
+            };
+            this.units.set(unitId, u);
+        }
+        if (Number.isFinite(ms)) {
+            u.firstMs = Math.min(u.firstMs, ms);
+            u.lastMs = Math.max(u.lastMs, ms);
+        }
+        return u;
+    }
+    /**
+     * Fold one fact in.
+     *
+     * @param fact - A ledger fact
+     */
+    fold(fact) {
+        const ms = Date.parse(fact.ts);
+        const u = this.unit(fact.unitId, ms);
+        this.factCount += 1;
+        if (fact.attribution === 'inferred')
+            u.inferred = true;
+        switch (fact.kind) {
+            case 'unit.meta': {
+                // First value wins; later facts only fill gaps.
+                u.ticketId ??= fact.ticketId;
+                u.requestId ??= fact.requestId;
+                u.rootKind ??= fact.rootKind;
+                u.title ||= fact.title;
+                u.excerpt ||= fact.excerpt;
+                u.project ??= fact.project;
+                u.team ??= fact.team;
+                u.channel ??= fact.channel;
+                u.threadRef ??= fact.threadRef;
+                u.openedAt ??= fact.openedAt;
+                break;
+            }
+            case 'unit.agent': {
+                const known = u.agents.get(fact.agent);
+                u.agents.set(fact.agent, { team: known?.team ?? fact.team, project: known?.project ?? fact.project });
+                break;
+            }
+            case 'unit.closed': {
+                if (!u.closedAt || fact.ts > u.closedAt) {
+                    u.closedAt = fact.ts;
+                    u.closedStatus = fact.status;
+                }
+                break;
+            }
+            case 'usage':
+                u.usage.push({
+                    hourMs: ms,
+                    agent: fact.agent,
+                    team: fact.team,
+                    model: fact.model,
+                    share: fact.share,
+                    input: fact.input,
+                    cachedInput: fact.cachedInput,
+                    output: fact.output,
+                    cacheWrite: fact.cacheWrite,
+                    budget: fact.budget,
+                    costUsd: fact.costUsd,
+                    attribution: fact.attribution,
+                });
+                break;
+            case 'busy':
+                u.busy.push({ hourMs: ms, agent: fact.agent, team: fact.team, busyMs: fact.busyMs, share: fact.share, attribution: fact.attribution });
+                break;
+            case 'owner.message':
+                if (Number.isFinite(ms))
+                    u.ownerMessages.push(ms);
+                break;
+        }
+    }
+}
+//# sourceMappingURL=ledger-rollup.js.map

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * Owner time per ticket, from owner message times.
+ *
+ * Heuristic (specs/2026-10-11-usage-ledger.md): owner messages on one ticket
+ * that follow each other within {@link OWNER_SPAN_GAP_MS} form one active
+ * span. A span runs from its first message to its last message plus
+ * {@link OWNER_MESSAGE_CREDIT_MS} (the time spent writing that last message),
+ * so a single message counts for one minute. When spans of different tickets
+ * overlap in time, the overlap is split evenly between them, so the owner's
+ * minutes are never counted twice.
+ *
+ * @module services/usage-ledger/owner-spans
+ */
+/** Messages at most this far apart belong to the same span. */
+export declare const OWNER_SPAN_GAP_MS: number;
+/** Time credited to the last (or only) message of a span. */
+export declare const OWNER_MESSAGE_CREDIT_MS = 60000;
+/** One stretch of owner activity on a ticket. */
+export interface OwnerSpan {
+    unitId: string;
+    startMs: number;
+    endMs: number;
+}
+/**
+ * Group one ticket's owner message times into spans.
+ *
+ * @param unitId - Ticket (unit) id
+ * @param times - Message times (ms), any order, duplicates allowed
+ * @returns Spans, oldest first
+ */
+export declare function buildOwnerSpans(unitId: string, times: number[]): OwnerSpan[];
+/**
+ * Owner minutes per ticket inside a time window, with overlaps split evenly.
+ *
+ * @param spans - Spans of any tickets
+ * @param fromMs - Window start (ms)
+ * @param toMs - Window end (ms)
+ * @returns Ticket id → minutes
+ */
+export declare function ownerMinutesByUnit(spans: OwnerSpan[], fromMs: number, toMs: number): Map<string, number>;
+//# sourceMappingURL=owner-spans.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"owner-spans.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/owner-spans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,QAAc,CAAC;AAC7C,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAgB5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxG"}

package/dist/backend/backend/src/services/usage-ledger/owner-spans.js

@@ -0,0 +1,71 @@
+/**
+ * Owner time per ticket, from owner message times.
+ *
+ * Heuristic (specs/2026-10-11-usage-ledger.md): owner messages on one ticket
+ * that follow each other within {@link OWNER_SPAN_GAP_MS} form one active
+ * span. A span runs from its first message to its last message plus
+ * {@link OWNER_MESSAGE_CREDIT_MS} (the time spent writing that last message),
+ * so a single message counts for one minute. When spans of different tickets
+ * overlap in time, the overlap is split evenly between them, so the owner's
+ * minutes are never counted twice.
+ *
+ * @module services/usage-ledger/owner-spans
+ */
+/** Messages at most this far apart belong to the same span. */
+export const OWNER_SPAN_GAP_MS = 10 * 60_000;
+/** Time credited to the last (or only) message of a span. */
+export const OWNER_MESSAGE_CREDIT_MS = 60_000;
+/**
+ * Group one ticket's owner message times into spans.
+ *
+ * @param unitId - Ticket (unit) id
+ * @param times - Message times (ms), any order, duplicates allowed
+ * @returns Spans, oldest first
+ */
+export function buildOwnerSpans(unitId, times) {
+    const sorted = [...new Set(times.filter((t) => Number.isFinite(t)))].sort((a, b) => a - b);
+    const spans = [];
+    let start = null;
+    let last = 0;
+    for (const t of sorted) {
+        if (start !== null && t - last <= OWNER_SPAN_GAP_MS) {
+            last = t;
+            continue;
+        }
+        if (start !== null)
+            spans.push({ unitId, startMs: start, endMs: last + OWNER_MESSAGE_CREDIT_MS });
+        start = t;
+        last = t;
+    }
+    if (start !== null)
+        spans.push({ unitId, startMs: start, endMs: last + OWNER_MESSAGE_CREDIT_MS });
+    return spans;
+}
+/**
+ * Owner minutes per ticket inside a time window, with overlaps split evenly.
+ *
+ * @param spans - Spans of any tickets
+ * @param fromMs - Window start (ms)
+ * @param toMs - Window end (ms)
+ * @returns Ticket id → minutes
+ */
+export function ownerMinutesByUnit(spans, fromMs, toMs) {
+    const clipped = spans
+        .map((s) => ({ unitId: s.unitId, startMs: Math.max(s.startMs, fromMs), endMs: Math.min(s.endMs, toMs) }))
+        .filter((s) => s.endMs > s.startMs);
+    const points = [...new Set(clipped.flatMap((s) => [s.startMs, s.endMs]))].sort((a, b) => a - b);
+    const minutes = new Map();
+    for (let i = 0; i < points.length - 1; i++) {
+        const a = points[i];
+        const b = points[i + 1];
+        const active = clipped.filter((s) => s.startMs <= a && s.endMs >= b);
+        if (active.length === 0)
+            continue;
+        const units = [...new Set(active.map((s) => s.unitId))];
+        const each = (b - a) / 60_000 / units.length;
+        for (const u of units)
+            minutes.set(u, (minutes.get(u) ?? 0) + each);
+    }
+    return minutes;
+}
+//# sourceMappingURL=owner-spans.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"owner-spans.js","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/owner-spans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,GAAG,MAAM,CAAC;AAC7C,6DAA6D;AAC7D,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAS9C;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,KAAe;IAC9D,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3F,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,GAAG,IAAI,IAAI,iBAAiB,EAAE,CAAC;YACrD,IAAI,GAAG,CAAC,CAAC;YACT,SAAS;QACV,CAAC;QACD,IAAI,KAAK,KAAK,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,GAAG,uBAAuB,EAAE,CAAC,CAAC;QAClG,KAAK,GAAG,CAAC,CAAC;QACV,IAAI,GAAG,CAAC,CAAC;IACV,CAAC;IACD,IAAI,KAAK,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,GAAG,uBAAuB,EAAE,CAAC,CAAC;IAClG,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAkB,EAAE,MAAc,EAAE,IAAY;IAClF,MAAM,OAAO,GAAG,KAAK;SACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;SACxG,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChG,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;QACrE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAClC,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC7C,KAAK,MAAM,CAAC,IAAI,KAAK;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,47 @@
+/**
+ * Which team and project an agent session belongs to, read from the team
+ * configs under CREWLY_HOME (`teams/<id>/config.json`, `projects.json`).
+ * Cached; a stale cache is refreshed in the background so hot paths stay
+ * synchronous and cheap.
+ *
+ * @module services/usage-ledger/team-directory
+ */
+/** Team and project of a session. */
+export interface TeamInfo {
+    team?: string;
+    project?: string;
+}
+/** What the ledger asks of a directory. */
+export interface TeamLookup {
+    /** Team / project of an agent session (sync, from cache) */
+    lookup(session: string): TeamInfo | null;
+    /** Project name for a project id */
+    projectName(projectId: string): string | undefined;
+    /** Wait until the cache has been loaded at least once */
+    ready(): Promise<void>;
+}
+/**
+ * Reads team and project names from disk.
+ */
+export declare class TeamDirectory implements TeamLookup {
+    private readonly home;
+    private readonly now;
+    private sessions;
+    private projects;
+    private loadedAt;
+    private loading;
+    /**
+     * @param home - Crewly home (default CREWLY_HOME)
+     * @param now - Clock (ms)
+     */
+    constructor(home?: string, now?: () => number);
+    lookup(session: string): TeamInfo | null;
+    projectName(projectId: string): string | undefined;
+    ready(): Promise<void>;
+    /**
+     * Reload the cache (one load at a time).
+     */
+    refresh(): Promise<void>;
+    private load;
+}
+//# sourceMappingURL=team-directory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"team-directory.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/team-directory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IAC1B,4DAA4D;IAC5D,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IACzC,oCAAoC;IACpC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACnD,yDAAyD;IACzD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAmBD;;GAEG;AACH,qBAAa,aAAc,YAAW,UAAU;IAW9C,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAXrB,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAA8B;IAE7C;;;OAGG;gBAEe,IAAI,GAAE,MAA4B,EAClC,GAAG,GAAE,MAAM,MAAyB;IAGtD,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAMxC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAWV,IAAI;CAiClB"}

package/dist/backend/backend/src/services/usage-ledger/team-directory.js

@@ -0,0 +1,106 @@
+/**
+ * Which team and project an agent session belongs to, read from the team
+ * configs under CREWLY_HOME (`teams/<id>/config.json`, `projects.json`).
+ * Cached; a stale cache is refreshed in the background so hot paths stay
+ * synchronous and cheap.
+ *
+ * @module services/usage-ledger/team-directory
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+/** How long a loaded cache is trusted. */
+const TTL_MS = 60_000;
+/** The orchestrator's session is not in any team. */
+const ORCHESTRATOR_SESSION = /^crewly-orc(?:$|-)/;
+/**
+ * Reads team and project names from disk.
+ */
+export class TeamDirectory {
+    home;
+    now;
+    sessions = new Map();
+    projects = new Map();
+    loadedAt = 0;
+    loading = null;
+    /**
+     * @param home - Crewly home (default CREWLY_HOME)
+     * @param now - Clock (ms)
+     */
+    constructor(home = getCrewlyHomePath(), now = () => Date.now()) {
+        this.home = home;
+        this.now = now;
+    }
+    lookup(session) {
+        if (this.now() - this.loadedAt > TTL_MS)
+            void this.refresh();
+        if (ORCHESTRATOR_SESSION.test(session))
+            return { team: 'Orchestrator' };
+        return this.sessions.get(session) ?? null;
+    }
+    projectName(projectId) {
+        return this.projects.get(projectId);
+    }
+    async ready() {
+        if (this.loadedAt === 0)
+            await this.refresh();
+        else if (this.loading)
+            await this.loading;
+    }
+    /**
+     * Reload the cache (one load at a time).
+     */
+    refresh() {
+        if (!this.loading) {
+            this.loading = this.load()
+                .catch(() => undefined)
+                .finally(() => {
+                this.loading = null;
+            });
+        }
+        return this.loading;
+    }
+    async load() {
+        const projects = new Map();
+        try {
+            const list = JSON.parse(await fs.readFile(path.join(this.home, 'projects.json'), 'utf-8'));
+            for (const p of Array.isArray(list) ? list : [])
+                if (p?.id && p.name)
+                    projects.set(p.id, p.name);
+        }
+        catch {
+            // no projects file
+        }
+        const sessions = new Map();
+        try {
+            const teamsDir = path.join(this.home, 'teams');
+            for (const entry of await fs.readdir(teamsDir, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                try {
+                    const team = JSON.parse(await fs.readFile(path.join(teamsDir, entry.name, 'config.json'), 'utf-8'));
+                    if (!team?.name)
+                        continue;
+                    const project = team.projectIds?.map((id) => projects.get(id)).find((n) => !!n);
+                    const info = { team: team.name, ...(project ? { project } : {}) };
+                    for (const m of team.members ?? []) {
+                        if (m.sessionName)
+                            sessions.set(m.sessionName, info);
+                        if (m.agentId)
+                            sessions.set(m.agentId, info);
+                    }
+                }
+                catch {
+                    // unreadable team
+                }
+            }
+        }
+        catch {
+            // no teams dir
+        }
+        this.sessions = sessions;
+        this.projects = projects;
+        this.loadedAt = this.now();
+    }
+}
+//# sourceMappingURL=team-directory.js.map

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

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

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

@@ -0,0 +1,101 @@
+/**
+ * Puts tickets into categories at report time.
+ *
+ * Order of attempts, cheapest first:
+ * 1. Deterministic: keywords (or the comma-separated phrases of the
+ *    description), team and project hints.
+ * 2. Only for tickets nothing matched, and only when a model is available: one
+ *    small batched question to the default cheap model.
+ * 3. Otherwise `other`.
+ *
+ * With no definitions the category is the ticket's team (else its project).
+ *
+ * Results are cached per (category-set id, ticket); a fallback `other` that
+ * came from having no model is not cached, so it is retried later. The cache
+ * lives beside the ledger and is never part of the ticket facts.
+ *
+ * @module services/usage-ledger/unit-classifier
+ */
+import { type CategoryDef } from './usage-categories.store.js';
+/** Category of tickets that match nothing. */
+export declare const OTHER_CATEGORY = "other";
+/** Category of usage that belongs to no ticket. */
+export declare const NO_TICKET_CATEGORY = "(no ticket)";
+/** File with the classification cache. */
+export declare const CLASSIFICATION_CACHE_FILE = "classification-cache.json";
+/** What the classifier reads about a ticket. */
+export interface ClassifiableUnit {
+    unitId: string;
+    ticketId?: string;
+    title?: string;
+    excerpt?: string;
+    team?: string;
+    project?: string;
+}
+/** Asks a small model one question; null when none is available or it failed. */
+export type CategoryLlm = (prompt: string) => Promise<string | null>;
+/** Where tickets ended up. */
+export interface ClassifyResult {
+    /** Ticket → category */
+    categories: Map<string, string>;
+    /** Tickets answered by the model in this call */
+    llmClassified: number;
+    /** Tickets that matched nothing and had no model to ask */
+    unclassified: number;
+}
+/** Default classification (no user categories): the ticket's team, else its project. */
+export declare function defaultCategory(unit: ClassifiableUnit): string;
+/**
+ * Keywords of a definition: its explicit keywords, else the comma / semicolon
+ * separated phrases of its description (so "Xiaohongshu, Substack, LinkedIn"
+ * works as typed).
+ *
+ * @param def - Category definition
+ * @returns Lower-case keywords
+ */
+export declare function keywordsOf(def: CategoryDef): string[];
+/**
+ * Best category by keyword / team / project hints.
+ *
+ * @param unit - The ticket
+ * @param defs - Definitions
+ * @returns Category name, or null when nothing matched
+ */
+export declare function matchCategory(unit: ClassifiableUnit, defs: CategoryDef[]): string | null;
+/**
+ * Classifies tickets for reports.
+ */
+export declare class UnitClassifier {
+    private readonly llm;
+    private readonly cacheFile;
+    private cache;
+    /**
+     * @param dir - Ledger directory
+     * @param llm - Optional model (null: deterministic only)
+     */
+    constructor(dir: string, llm?: CategoryLlm | null);
+    private loadCache;
+    /**
+     * Classify tickets.
+     *
+     * @param units - Tickets (never the "(no ticket)" pseudo-units)
+     * @param defs - The user's categories; empty means the default (team / project)
+     * @returns Category per ticket
+     */
+    classify(units: ClassifiableUnit[], defs: CategoryDef[]): Promise<ClassifyResult>;
+    private saveCache;
+    /**
+     * Ask the model about tickets nothing matched.
+     *
+     * @returns Ticket → category (only tickets the model answered validly)
+     */
+    private askModel;
+}
+/**
+ * The default cheap model: a small Anthropic model when `ANTHROPIC_API_KEY`
+ * is set; none otherwise.
+ *
+ * @returns A question function, or null
+ */
+export declare function defaultCategoryLlm(): CategoryLlm | null;
+//# sourceMappingURL=unit-classifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"unit-classifier.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/unit-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE9E,8CAA8C;AAC9C,eAAO,MAAM,cAAc,UAAU,CAAC;AACtC,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD,0CAA0C;AAC1C,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAQrE,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAErE,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC9B,wBAAwB;IACxB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;CACrB;AAMD,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,EAAE,CAUrD;AAaD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,MAAM,GAAG,IAAI,CAaxF;AAED;;GAEG;AACH,qBAAa,cAAc;IAUzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IATrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,KAAK,CAA0B;IAEvC;;;OAGG;gBAEF,GAAG,EAAE,MAAM,EACM,GAAG,GAAE,WAAW,GAAG,IAAW;YAKlC,SAAS;IAWvB;;;;;;OAMG;IACG,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;YA2CzE,SAAS;IAcvB;;;;OAIG;YACW,QAAQ;CAsCtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,GAAG,IAAI,CAcvD"}