crewly 1.20.301 → 1.20.303

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

@@ -0,0 +1,294 @@
+/**
+ * One-time rebuild of the ledger for the time before it existed.
+ *
+ * Sources: the token ledger (usage events) and the run traces (ticket roots,
+ * deliveries, busy turns, status changes). The traces expire after 90 days,
+ * the ledger does not, so this keeps what they know.
+ *
+ * Attribution of a usage event:
+ * - it already carries a trace id (the harness stamped it): `recorded`;
+ * - otherwise it goes to the trace the session's latest delivery named,
+ *   when that delivery was at most {@link INFER_MAX_GAP_MS} before the event:
+ *   `inferred`;
+ * - otherwise it lands in the agent's "(no ticket)" unit.
+ *
+ * Only facts older than the cutoff (the moment live recording began) are
+ * written, so history and live facts never overlap. The result goes to
+ * `backfill.jsonl`; the run is recorded in `state.json` and never repeats.
+ *
+ * @module services/usage-ledger/usage-ledger.backfill
+ */
+import { createReadStream, promises as fs } from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { TRACE_CONSTANTS } from '../../constants.js';
+import { atomicWriteJson } from '../../utils/file-io.utils.js';
+import { eventCostUsd, eventTokens } from '../monitoring/token-usage.service.js';
+import { cleanText, cut, EXCERPT_MAX, titleFromSummary } from './excerpt.js';
+import { LEDGER_VERSION, UNTICKETED_PREFIX } from './usage-ledger.types.js';
+/** An unticketed event this soon after a delivery is credited to the delivery's trace. */
+export const INFER_MAX_GAP_MS = TRACE_CONSTANTS.IDLE_CLEAR_MS;
+/** File with the ledger's own bookkeeping. */
+export const STATE_FILE = 'state.json';
+/**
+ * Read the ledger bookkeeping.
+ *
+ * @param dir - Ledger directory
+ * @returns State (empty when none)
+ */
+export async function readLedgerState(dir) {
+    try {
+        return JSON.parse(await fs.readFile(path.join(dir, STATE_FILE), 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write the ledger bookkeeping.
+ *
+ * @param dir - Ledger directory
+ * @param state - State
+ */
+export async function writeLedgerState(dir, state) {
+    await fs.mkdir(dir, { recursive: true });
+    await atomicWriteJson(path.join(dir, STATE_FILE), state);
+}
+/**
+ * Note when live recording began (once).
+ *
+ * @param dir - Ledger directory
+ * @param now - Now (ms)
+ * @returns The cutoff
+ */
+export async function ensureLiveSince(dir, now = Date.now()) {
+    const state = await readLedgerState(dir);
+    if (state.liveSince)
+        return state.liveSince;
+    const liveSince = new Date(now).toISOString();
+    await writeLedgerState(dir, { ...state, liveSince });
+    return liveSince;
+}
+const hourOf = (ms) => new Date(Math.floor(ms / 3_600_000) * 3_600_000).toISOString();
+/** Stream the lines of a file. */
+async function* lines(file) {
+    const rl = readline.createInterface({ input: createReadStream(file, { encoding: 'utf-8' }), crlfDelay: Infinity });
+    for await (const line of rl)
+        yield line;
+}
+/**
+ * Rebuild history into `backfill.jsonl`.
+ *
+ * @param store - Ledger store
+ * @param sources - Where history comes from
+ * @param opts.cutoffMs - Only facts before this time are written
+ * @returns What happened
+ */
+export async function runBackfill(store, sources, opts) {
+    const state = await readLedgerState(store.dir);
+    if (state.backfill)
+        return { ran: false, reason: `already done at ${state.backfill.doneAt}`, facts: 0, usageEvents: 0, inferredEvents: 0, traces: 0 };
+    const cutoff = opts.cutoffMs;
+    const facts = [];
+    const push = (f) => {
+        facts.push(f);
+    };
+    // ---- traces ----
+    let index = null;
+    try {
+        index = JSON.parse(await fs.readFile(path.join(sources.traceDir, TRACE_CONSTANTS.INDEX_FILE), 'utf-8'));
+    }
+    catch {
+        index = null;
+    }
+    const traces = index?.traces ?? {};
+    const known = new Set(Object.keys(traces));
+    /** session → deliveries (ms, trace), sorted later */
+    const deliveries = new Map();
+    /** `session|ts` → traces that recorded the same busy turn */
+    const busyOwners = new Map();
+    const busyEvents = [];
+    const seenAgents = new Set();
+    const lastOwner = new Map();
+    for (const [traceId, entry] of Object.entries(traces)) {
+        const created = Date.parse(entry.root.createdAt);
+        if (created >= cutoff)
+            continue;
+        const root = entry.root;
+        push({
+            v: LEDGER_VERSION,
+            ts: root.createdAt,
+            kind: 'unit.meta',
+            unitId: traceId,
+            ...(root.refs.ticketId ? { ticketId: root.refs.ticketId } : {}),
+            ...(root.refs.requestId ? { requestId: root.refs.requestId } : {}),
+            rootKind: root.kind,
+            openedAt: root.createdAt,
+            title: titleFromSummary(root.summary),
+            excerpt: cut(cleanText(root.summary), EXCERPT_MAX),
+            attribution: 'recorded',
+        });
+        const file = path.join(sources.traceDir, `${traceId}.jsonl`);
+        try {
+            await fs.access(file);
+        }
+        catch {
+            continue;
+        }
+        for await (const line of lines(file)) {
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const at = Date.parse(event.ts);
+            if (!Number.isFinite(at) || at >= cutoff)
+                continue;
+            const session = event.refs?.session ?? event.actor?.session;
+            if (event.type === 'turn.delivered') {
+                if (session) {
+                    const list = deliveries.get(session) ?? [];
+                    list.push({ at, traceId });
+                    deliveries.set(session, list);
+                    const key = `${traceId}|${session}`;
+                    if (!seenAgents.has(key)) {
+                        seenAgents.add(key);
+                        const info = sources.directory.lookup(session);
+                        push({
+                            v: LEDGER_VERSION,
+                            ts: event.ts,
+                            kind: 'unit.agent',
+                            unitId: traceId,
+                            agent: session,
+                            ...(info?.team ? { team: info.team } : {}),
+                            ...(info?.project ? { project: info.project } : {}),
+                            attribution: 'recorded',
+                        });
+                    }
+                }
+                if (event.actor?.kind === 'owner' && event.data?.kind === 'owner_message') {
+                    const last = lastOwner.get(traceId);
+                    if (last === undefined || Math.abs(at - last) >= 2_000) {
+                        lastOwner.set(traceId, at);
+                        push({ v: LEDGER_VERSION, ts: event.ts, kind: 'owner.message', unitId: traceId, attribution: 'recorded' });
+                    }
+                }
+            }
+            else if (event.type === 'turn.ended') {
+                const busyMs = Number(event.data?.busyMs);
+                if (session && Number.isFinite(busyMs) && busyMs > 0) {
+                    busyEvents.push({ traceId, session, at, busyMs });
+                    const key = `${session}|${event.ts}`;
+                    busyOwners.set(key, [...(busyOwners.get(key) ?? []), traceId]);
+                }
+            }
+            else if (event.type === 'request.status' || event.type === 'ticket.status') {
+                const to = typeof event.data?.to === 'string' ? event.data.to : '';
+                const projectId = typeof event.data?.projectId === 'string' ? event.data.projectId : '';
+                const project = projectId ? sources.directory.projectName(projectId) : undefined;
+                if (project)
+                    push({ v: LEDGER_VERSION, ts: event.ts, kind: 'unit.meta', unitId: traceId, project, attribution: 'recorded' });
+                if (to === 'done' || to === 'cancelled')
+                    push({ v: LEDGER_VERSION, ts: event.ts, kind: 'unit.closed', unitId: traceId, status: to, attribution: 'recorded' });
+            }
+        }
+    }
+    for (const list of deliveries.values())
+        list.sort((a, b) => a.at - b.at);
+    // ---- busy time ----
+    const busy = new Map();
+    for (const b of busyEvents) {
+        const share = 1 / (busyOwners.get(`${b.session}|${new Date(b.at).toISOString()}`)?.length ?? 1);
+        const hour = hourOf(b.at);
+        const key = [b.traceId, b.session, hour, share].join('|');
+        const info = sources.directory.lookup(b.session);
+        const fact = busy.get(key) ??
+            { v: LEDGER_VERSION, ts: hour, kind: 'busy', unitId: b.traceId, agent: b.session, ...(info?.team ? { team: info.team } : {}), turns: 0, busyMs: 0, share, attribution: 'recorded' };
+        fact.turns += 1;
+        fact.busyMs += b.busyMs;
+        busy.set(key, fact);
+    }
+    facts.push(...busy.values());
+    // ---- usage ----
+    const usage = new Map();
+    const noticket = new Set();
+    let usageEvents = 0;
+    let inferredEvents = 0;
+    sources.forEachUsage((session, event) => {
+        const at = Date.parse(event.timestamp);
+        if (!Number.isFinite(at) || at >= cutoff)
+            return;
+        usageEvents += 1;
+        let unitId;
+        let attribution = 'recorded';
+        if (event.traceId && known.has(event.traceId)) {
+            unitId = event.traceId;
+        }
+        else {
+            const list = deliveries.get(session) ?? [];
+            let found;
+            for (let i = list.length - 1; i >= 0; i--) {
+                if (list[i].at <= at) {
+                    found = list[i];
+                    break;
+                }
+            }
+            if (found && at - found.at <= INFER_MAX_GAP_MS) {
+                unitId = found.traceId;
+                attribution = 'inferred';
+                inferredEvents += 1;
+            }
+            else {
+                unitId = `${UNTICKETED_PREFIX}${session}`;
+            }
+        }
+        if (unitId.startsWith(UNTICKETED_PREFIX) && !noticket.has(unitId)) {
+            noticket.add(unitId);
+            push({ v: LEDGER_VERSION, ts: new Date(at).toISOString(), kind: 'unit.meta', unitId, rootKind: 'none', title: `(no ticket) ${session}`, attribution: 'inferred' });
+        }
+        const hour = hourOf(at);
+        const key = [unitId, session, event.model, hour, attribution].join('|');
+        const info = sources.directory.lookup(session);
+        const tokens = eventTokens(event);
+        const fact = usage.get(key) ??
+            {
+                v: LEDGER_VERSION,
+                ts: hour,
+                kind: 'usage',
+                unitId,
+                agent: session,
+                ...(info?.team ? { team: info.team } : {}),
+                model: event.model,
+                ...(event.runtime ? { runtime: event.runtime } : {}),
+                events: 0,
+                share: 1,
+                input: 0,
+                cachedInput: 0,
+                output: 0,
+                cacheWrite: 0,
+                budget: 0,
+                costUsd: 0,
+                attribution,
+            };
+        fact.events += 1;
+        fact.input += tokens.input;
+        fact.cachedInput += tokens.cachedInput;
+        fact.output += tokens.output;
+        fact.cacheWrite += tokens.cacheWrite;
+        fact.budget += tokens.budget;
+        fact.costUsd += eventCostUsd(event);
+        usage.set(key, fact);
+    });
+    facts.push(...usage.values());
+    for (let i = 0; i < facts.length; i += 5000)
+        store.appendMany(facts.slice(i, i + 5000), 'backfill');
+    await store.flush();
+    await writeLedgerState(store.dir, {
+        ...(await readLedgerState(store.dir)),
+        backfill: { doneAt: new Date().toISOString(), cutoff: new Date(cutoff).toISOString(), facts: facts.length, usageEvents, inferredEvents },
+    });
+    return { ran: true, facts: facts.length, usageEvents, inferredEvents, traces: Object.keys(traces).length };
+}
+//# sourceMappingURL=usage-ledger.backfill.js.map

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

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

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

@@ -0,0 +1,102 @@
+/**
+ * Writes the usage ledger as work happens.
+ *
+ * Attribution comes from the trace context (which ticket an agent's turn is
+ * about, set when the harness delivers a message). The recorder listens to
+ * trace events and to token-usage events and appends facts; usage and busy
+ * time are summed per (unit, agent, model, hour) in memory and written as one
+ * delta fact per bucket on a timer, so the ledger stays small.
+ *
+ * Rules (specs/2026-10-11-usage-ledger.md):
+ * - A usage event belongs to the ticket(s) the agent's turn was about at the
+ *   event's time. One ticket: all of it. A delivery naming n tickets: 1/n
+ *   each. No ticket: a per-agent "(no ticket)" unit.
+ * - Busy time is recorded when a turn ends, in the ticket the turn started on
+ *   and the one it is on now, split evenly.
+ * - Owner messages delivered to an agent on a ticket are owner-message facts;
+ *   active spans are computed from them at report time.
+ *
+ * @module services/usage-ledger/usage-ledger.recorder
+ */
+import { type TokenUsageEvent } from '../monitoring/token-usage.service.js';
+import { type TraceContext } from '../trace/trace-context.service.js';
+import type { TraceEvent } from '../trace/trace.types.js';
+import { type RequestMeta } from './ledger-hooks.js';
+import type { TeamLookup } from './team-directory.js';
+import type { UsageLedgerStore } from './usage-ledger.store.js';
+/** Dependencies of the recorder. */
+export interface RecorderDeps {
+    store: UsageLedgerStore;
+    directory: TeamLookup;
+    /** Trace context accessor (default: the process-wide one) */
+    context?: () => TraceContext;
+    now?: () => number;
+    flushIntervalMs?: number;
+}
+/**
+ * Start of the UTC hour of a time.
+ *
+ * @param ms - Epoch ms
+ * @returns ISO string of the hour start
+ */
+export declare function hourStart(ms: number): string;
+/**
+ * Appends ledger facts from live events.
+ */
+export declare class UsageLedgerRecorder {
+    private readonly deps;
+    private readonly context;
+    private readonly now;
+    private readonly opened;
+    private readonly agentsSeen;
+    private readonly closed;
+    private readonly lastOwner;
+    private readonly usage;
+    private readonly busy;
+    private detach;
+    private timer;
+    constructor(deps: RecorderDeps);
+    /**
+     * Start listening (trace events, usage events, new requests) and flushing.
+     */
+    start(): void;
+    /**
+     * Stop listening and write what is buffered.
+     */
+    stop(): Promise<void>;
+    /**
+     * Write the buffered usage / busy buckets and wait for the files.
+     */
+    flush(): Promise<void>;
+    /**
+     * A token-usage event was recorded: attribute it to the ticket(s) its
+     * session was working on at that time.
+     *
+     * @param session - Agent session
+     * @param event - The usage event
+     */
+    noteUsage(session: string, event: TokenUsageEvent): void;
+    /**
+     * A request got its trace: record what the ticket is about.
+     *
+     * @param meta - Request facts
+     */
+    noteRequest(meta: RequestMeta): void;
+    /**
+     * Fold one trace event into facts.
+     *
+     * @param event - The trace event
+     * @param share - Fraction of a shared fact this trace carries
+     */
+    onTraceEvent(event: TraceEvent, share: number): void;
+    private addBusy;
+    private noteOwnerMessage;
+    private noteAgent;
+    /**
+     * Write a unit's descriptive fact the first time the unit is seen (this
+     * process): ticket id, title, excerpt, kind, start. Later facts (the
+     * request's description, thread, project) fill the gaps.
+     */
+    private ensureUnit;
+}
+//# sourceMappingURL=usage-ledger.recorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.recorder.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvG,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACvF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAkBhE,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,EAAE,UAAU,CAAC;IACtB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,YAAY,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAYnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAXjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA+B;IACpD,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,KAAK,CAA+B;gBAEf,IAAI,EAAE,YAAY;IAK/C;;OAEG;IACH,KAAK,IAAI,IAAI;IAcb;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAgDxD;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAiBpC;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IA2CpD,OAAO,CAAC,OAAO;IAuBf,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,SAAS;IAiBjB;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAmClB"}