@genesislcap/ai-assistant 15.23.3 → 15.24.0

package/dist/esm/main/cost-ledger-controller.js

@@ -0,0 +1,498 @@
+import { __decorate } from "tslib";
+import { observable, volatile } from '@genesislcap/web-core';
+import { deleteBankedBaseline, getBankedBaseline, setBankedBaseline, } from '../utils/banked-usage-baselines';
+import { collectSessionModels } from '../utils/collect-session-models';
+import { clearCostSessionHistory, isCostSessionRecord, loadCostSessionHistory, resolveBankedUsage, saveCostSessionHistory, sortRecordsByRecency, upsertRecord, } from '../utils/cost-session-history';
+import { deriveCostSessionTitleFromMessages, resolveCostSessionTitle, } from '../utils/derive-cost-session-title';
+import { logger } from '../utils/logger';
+import { resolveCostHistoryConfig, } from '../utils/resolve-cost-history-config';
+import { addUsage, emptyUsage, totalTokens } from '../utils/sum-usage';
+/**
+ * How long cost-ledger writes coalesce. Comfortably longer than the gap between the turns of a
+ * tool loop, so a multi-step run writes once rather than per turn, and short enough that a flush
+ * has landed well before a user could close the tab. Nothing reads the stored ledger while the
+ * assistant is running — the Usage tab renders the in-memory list — so the delay is invisible.
+ */
+const LEDGER_FLUSH_DEBOUNCE_MS = 2000;
+/**
+ * The cost ledger: this session's usage, the persisted per-project build history it
+ * upserts into, and the pre-transcript ("banked") spend that makes a row report a
+ * project's LIFETIME total rather than whatever is currently on screen (GENC-1475).
+ *
+ * The invariant the whole file protects: **a row moves forward, never backwards.**
+ * Every figure is derived from state rather than incremented, so the several element
+ * instances one session sees — layout re-renders, popout, docking — write the same
+ * row instead of each adding a contribution. `cost-session-banking.test.ts` pins the
+ * cases where earlier attempts got this wrong in both directions.
+ *
+ * @internal
+ */
+export class CostLedgerController {
+    constructor(deps) {
+        this.deps = deps;
+        /**
+         * Persisted rows, newest write wins. Observable because the Usage tab renders them
+         * (through the host's `costSessionHistory` and `sortedCostSessionHistory`), and
+         * because the derived lifetime totals below have to re-run when a row lands.
+         */
+        this.history = [];
+        /**
+         * Title tracked for the in-flight session, and the session key it accrued under so
+         * a title change can tell a rename (same key) from a project switch (key already
+         * flipped) — see {@link CostLedgerController.syncActiveTitle}.
+         *
+         * Not observable: read only by the title getter's own fallback chain, which already
+         * depends on `chatConfig` and `messages`, and written only from lifecycle hooks.
+         */
+        this.activeTitle = '';
+        // NOTE: the pre-transcript ("banked") spend is deliberately NOT held here either. It
+        // is keyed by session in `banked-usage-baselines` so the many element instances a
+        // single session sees share one baseline. See `bankedUsageFor`.
+        /**
+         * What the last read of the backing store told us, and the two gates every write
+         * consults. Neither is observable — nothing renders them.
+         *
+         * `loaded`: whether the row list reflects storage yet. Gates writes so a project's
+         * banked spend is never derived from a ledger that simply hasn't arrived.
+         *
+         * `unreadable`: set when a provider read failed, latching writes off for this
+         * page-load. `saveCostHistory` replaces the whole stored list, so writing anything
+         * derived from the empty list we fell back to would destroy rows we never read.
+         *
+         * Private, though `cost-session-banking.test.ts` drives both to model a provider
+         * read that is in flight or has failed. That works because the test reaches them
+         * through an `as unknown as { costLedger: … }` structural cast, which erases the
+         * class type — so exposing them bought nothing and only put a mutable latch on the
+         * surface of an `@internal` controller (PR #2503 review).
+         */
+        this.loaded = false;
+        this.unreadable = false;
+        /** Pending (adopted but unwritten) ledger changes — see {@link CostLedgerController.persist}. */
+        this.dirty = false;
+    }
+    /** Resolved cost tab and build-history settings from `chatConfig.costHistory`. */
+    get config() {
+        return resolveCostHistoryConfig(this.deps.chatConfig());
+    }
+    /**
+     * Distinct models the registry currently resolves to — the live session's model chips.
+     *
+     * `providerStatuses` carries one entry per registry SLOT, so a vendor configured across several
+     * tiers that happen to resolve to the same model reports it once per tier, and the chips
+     * rendered it once per tier too. Which tier a model came from is not what these chips are for.
+     *
+     * Deduped on the label actually displayed, not on `status.model`: a slot whose provider reports
+     * no model falls back to the slot's own name, and those are distinct per slot, so keying on the
+     * label keeps them from collapsing into one another.
+     */
+    get uniqueProviderModels() {
+        var _a, _b, _c, _d;
+        const seen = new Map();
+        for (const entry of this.deps.providerStatuses()) {
+            const model = (_b = (_a = entry.status) === null || _a === void 0 ? void 0 : _a.model) !== null && _b !== void 0 ? _b : entry.name;
+            if (!model)
+                continue;
+            const existing = seen.get(model);
+            if (!existing) {
+                seen.set(model, { model, provider: (_c = entry.status) === null || _c === void 0 ? void 0 : _c.provider });
+                continue;
+            }
+            // Keep whichever tier knew the vendor, so the chip still gets its colour when one slot
+            // reports a provider and another does not.
+            if (existing.provider === undefined && ((_d = entry.status) === null || _d === void 0 ? void 0 : _d.provider) !== undefined) {
+                existing.provider = entry.status.provider;
+            }
+        }
+        return [...seen.values()];
+    }
+    /**
+     * Build history for display: most recently worked on first.
+     *
+     * The stored order is insertion order (see `upsertRecord`), which leaves a project returned to
+     * sitting wherever it was first seen — so ordering is applied here, on read, where it also
+     * covers rows a host provider supplied.
+     */
+    get sortedHistory() {
+        return sortRecordsByRecency(this.history);
+    }
+    /**
+     * Lifetime usage across every project in the history scope — cost and all four token
+     * buckets. What the Usage tab's lifetime section renders.
+     *
+     * Rows ONLY — deliberately not rows + live session. Each row holds a project's lifetime
+     * usage and the active project's row is kept current on every transcript change, so
+     * adding the live total would count this project's spend twice. That double-count is what
+     * made the figure grow on every refresh: a page-hide banked a row while the restored
+     * session still carried the same spend.
+     */
+    get cumulativeUsage() {
+        void this.history;
+        // With history off there are no rows to sum, so the live session IS all we know.
+        if (!this.config.enabled)
+            return this.deps.sessionUsage();
+        return this.history.reduce((total, record) => addUsage(total, record.usage), emptyUsage());
+    }
+    /** Lifetime USD across every project in the history scope. */
+    get cumulativeCostUsd() {
+        return this.cumulativeUsage.costUsd;
+    }
+    /**
+     * Whether the live session figures amount to this project's whole history, which is true
+     * exactly when the transcript is restored on load. Drives the Usage tab's live labels
+     * ("Project cost" vs "Session cost") so they state the scope rather than imply one.
+     *
+     * Note this is NOT what makes the *rows* lifetime — those bank their pre-transcript spend
+     * (see `CostSessionRecord.banked`) and are lifetime either way.
+     */
+    get liveUsageIsProjectLifetime() {
+        return this.deps.persistenceActive();
+    }
+    /** Label shown on the Usage tab for the in-flight session (app title or first user phrase). */
+    get liveTitle() {
+        var _a;
+        const messages = this.deps.messages();
+        const appTitle = ((_a = this.config.title) === null || _a === void 0 ? void 0 : _a.trim()) || this.activeTitle.trim();
+        if (appTitle)
+            return appTitle;
+        return deriveCostSessionTitleFromMessages(messages);
+    }
+    /**
+     * Write this session's usage into persisted build history as a single row keyed by the
+     * session key, replacing any existing row for that key.
+     *
+     * **Idempotent** — safe to call per turn, on tab close, and on a title change alike.
+     * The name is historical: it does NOT end the session or reset the running totals.
+     * Resetting them is what used to double-count spend, since the row was banked while the
+     * persisted transcript still carried the same usage, so a reload restored it and the
+     * Usage tab counted both.
+     *
+     * No-op unless `chatConfig.costHistory.enabled` is `true`, when the live session has no
+     * usage yet, or when the session has no key to upsert against. Gating on the *live*
+     * figures (not the banked total) means a reload that restores nothing rewrites nothing.
+     */
+    finalize(options) {
+        if (!this.config.enabled)
+            return;
+        // Wait for the rows before writing: a provider read is async, and banking from a
+        // not-yet-loaded ledger would read as "nothing came before" and rewrite this project's
+        // row down to the current transcript. Skipping is free — this is called on every
+        // transcript change, so the next one writes.
+        if (!this.loaded)
+            return;
+        const live = this.deps.sessionUsage();
+        const tokensConsumed = totalTokens(live);
+        if (live.costUsd <= 0 && tokensConsumed <= 0)
+            return;
+        // The session key identifies the work — a project id, for hosts that key sessions
+        // per project. Without one there is nothing stable to upsert against, so skip
+        // rather than write a row that can never be matched again.
+        const projectKey = this.deps.stateKey();
+        if (!projectKey)
+            return;
+        const messages = this.deps.messages();
+        const title = resolveCostSessionTitle({
+            explicit: options === null || options === void 0 ? void 0 : options.title,
+            appTitle: this.config.title,
+            messages,
+            headerTitle: this.deps.headerTitle(),
+        });
+        // Lifetime = what came before this transcript + what this transcript proves. Both
+        // terms are derived from state, never incremented, so the two element instances that
+        // share a session write the same row rather than each adding their own contribution.
+        const banked = this.bankedUsageFor(projectKey);
+        const record = {
+            // Stable per project so repeat upserts replace the row instead of stacking, and
+            // so the delete action keeps targeting the same row across reloads.
+            id: projectKey,
+            projectKey,
+            title,
+            updatedAt: new Date().toISOString(),
+            usage: addUsage(banked, live),
+            banked,
+            models: collectSessionModels(messages, this.deps.providerStatuses()),
+        };
+        this.persist(upsertRecord(this.history, record));
+        // NOTE: the live counters are deliberately NOT reset here. Resetting was what
+        // double-counted spend — the row was banked while the persisted transcript still
+        // carried the same usage, so a reload restored it and the Usage tab added both.
+        // The row is a projection of the session totals, not a transfer out of them.
+    }
+    /**
+     * Spend for `projectKey` that predates the current transcript, resolved once per SESSION and
+     * shared by every element instance wired to it (see `banked-usage-baselines`), so it cannot
+     * drift as the row it came from is rewritten by our own upserts.
+     *
+     * The two cases turn on whether the transcript is authoritative for this project:
+     *
+     * - **Transcript restored** (`persistenceActive`): it already accounts for everything after
+     *   the previous row's own banked figure, so carry that figure forward unchanged. Re-banking
+     *   `usage` here would add the restored history to itself on every reload.
+     * - **Transcript starts empty**: nothing on screen accounts for the previous total, so the
+     *   whole of it becomes banked. Without this the next turn would rewrite the row downwards
+     *   to just that turn, losing the project's earlier spend.
+     *
+     * The baseline is deliberately NOT element or controller state. This element is remounted
+     * repeatedly inside a single session (the host re-rendering its layout, popping out, docking)
+     * and a fresh instance re-deriving would take the second branch against rows that already hold
+     * the live transcript — banking the session as its own baseline. Keying on the session instead
+     * means a remount inherits the baseline that transcript was paired with.
+     */
+    bankedUsageFor(projectKey) {
+        const resolved = getBankedBaseline(projectKey);
+        if (resolved)
+            return resolved;
+        const existing = this.history.find((r) => r.projectKey === projectKey);
+        // `persistenceActive` is what decides whether the transcript speaks for the project's
+        // history: it is on only when a provider is wired AND the user is remembering the chat.
+        const banked = resolveBankedUsage(existing, this.deps.persistenceActive());
+        setBankedBaseline(projectKey, banked);
+        return banked;
+    }
+    /**
+     * Re-baseline this session against an emptied transcript: what came before, plus what the
+     * transcript being discarded proved. `discarded` must be read BEFORE the live figures are
+     * reset, since that is the only record of the latter.
+     *
+     * Not the same as dropping the baseline. Dropping it re-derives through `persistenceActive`,
+     * and with persistence ON that carries the row's *old* banked figure forward — discarding
+     * every turn between the last baseline and the clear. The transcript is gone either way, so
+     * the branch that reads it as authoritative no longer applies.
+     *
+     * Derived from the memoised baseline and the live figure rather than from the project's row,
+     * because a row is only as current as the last {@link CostLedgerController.finalize} — which
+     * skips its write while the ledger is unloaded, and while the session has no usage yet.
+     */
+    rebaselineOnClearedTranscript(key, discarded) {
+        // Already resolved for this session? Then the new baseline is fully determined without
+        // consulting the ledger at all — `bankedUsageFor` would short-circuit on this same value — so
+        // answer before the guard below, which would otherwise discard a figure that is both correct
+        // and independent of the rows. Losing it costs real spend: with a row at `usage: 120,
+        // banked: 90` and 30 on screen, a clear during a reload would drop the memoised 90, and the
+        // next turn would re-derive `row.banked` and rewrite the row BACKWARDS from 120 to 95.
+        const resolved = getBankedBaseline(key);
+        if (resolved) {
+            setBankedBaseline(key, addUsage(resolved, discarded));
+            return;
+        }
+        // Nothing memoised, so a baseline can only come from the rows — and a stamped one is STICKY
+        // (`bankedUsageFor` short-circuits on any stored entry, and a zero usage is a *resolved* value
+        // there, not "unresolved"). So unless the rows are genuinely known, do not guess:
+        //
+        //  - `enabled` false: `reload` sets `loaded` TRUE over a deliberately empty list, meaning
+        //    "nothing will be loaded" rather than "rows are known". The flag alone therefore is not
+        //    enough. Reachable because `enabled` is `cost?.enabled === true` — false for an unbound
+        //    `chatConfig`, and for any host resolving it from an async setting, exactly as
+        //    `chatConfigChanged` already expects.
+        //  - Provider read in flight: the list is emptied and the flag cleared synchronously, on
+        //    connect and again on every `chatConfig` rebind.
+        //  - Unreadable: the rows we hold are a fallback, not the ledger.
+        //
+        // In all three, pinning would bury this project's real total the moment it arrived — a later
+        // load does NOT invalidate baselines (deliberately, see `reload`), so the next write would
+        // replace the row off the pinned figure and lose everything before it.
+        //
+        // Dropping instead leaves the next write to re-derive from rows that actually arrived. It
+        // under-banks `discarded` in that window — a bounded loss, and what every clear did before
+        // this method existed. Nothing is written while disabled, so there is no banked value to
+        // preserve in that case either.
+        if (!this.config.enabled || !this.loaded || this.unreadable) {
+            deleteBankedBaseline(key);
+            return;
+        }
+        setBankedBaseline(key, addUsage(this.bankedUsageFor(key), discarded));
+    }
+    /** Remove one entry from persisted build history. */
+    remove(id) {
+        // Deleting a row discards its banked spend by intent, so drop the baseline too —
+        // otherwise the next turn would rewrite the row we just removed, restoring the total the
+        // user asked to be rid of.
+        //
+        // Resolve the row first: `id` is a row id while baselines are keyed by projectKey. They
+        // match only for rows this element wrote (`finalize` sets `id: projectKey`); a row from a
+        // host provider can carry any id, and deleting by the wrong namespace would silently leave
+        // the baseline in place.
+        const removed = this.history.find((record) => record.id === id);
+        if (removed)
+            deleteBankedBaseline(removed.projectKey);
+        this.persist(this.history.filter((record) => record.id !== id));
+    }
+    /** Clear all persisted build history for this assistant scope. */
+    clear() {
+        // Every row is gone, so nothing is banked any more — without this the next turn would
+        // resurrect the pre-clear total. Dropped per row rather than for the active session alone,
+        // so a project whose row was cleared while another session was displaying it does not keep
+        // a baseline pointing at spend that no longer exists anywhere.
+        for (const record of this.history)
+            deleteBankedBaseline(record.projectKey);
+        // Provider-backed: write an empty ledger through. The `localStorage` path instead
+        // removes its key outright rather than leaving an empty array behind.
+        if (this.costHistoryProvider()) {
+            this.persist([]);
+            return;
+        }
+        clearCostSessionHistory(this.scope());
+        this.history = [];
+    }
+    scope() {
+        const scope = this.config.scope;
+        if (scope)
+            return scope;
+        return this.deps.elementId() || 'default';
+    }
+    /** Re-read the ledger for the current scope. Runs on connect and on every `chatConfig` rebind. */
+    reload() {
+        // NOTE: deliberately does NOT invalidate the banked figure. This runs again whenever
+        // `chatConfig` rebinds — hosts commonly build it in a template expression, so a new
+        // object arrives mid-session — and by then the rows include our own upserts, whose
+        // `usage` already contains the live transcript. Re-deriving from those would add the
+        // current session to itself. `bankedUsageFor` keys its memo on the project instead,
+        // which handles a genuine session switch without trusting reload timing.
+        this.loaded = false;
+        this.unreadable = false;
+        if (!this.config.enabled) {
+            this.history = [];
+            this.loaded = true;
+            return;
+        }
+        const scope = this.scope();
+        const provider = this.costHistoryProvider();
+        if (!provider) {
+            this.history = loadCostSessionHistory(scope);
+            this.loaded = true;
+            return;
+        }
+        // Provider reads are async, so the Usage tab renders an empty list for a tick before
+        // this lands. Seeded empty rather than left stale so a scope change can't briefly show
+        // the previous scope's rows.
+        this.history = [];
+        void provider.loadCostHistory(scope)
+            .then((records) => {
+            // Guard against a scope change while the load was in flight — a late result must
+            // not overwrite the rows of whatever scope is current now.
+            if (this.scope() === scope) {
+                // Filtered exactly as the localStorage path is. A host's rows are as capable of
+                // being malformed as a hand-edited storage entry, and an unchecked one poisons
+                // every total with NaN or throws in the sort during render.
+                this.history = (records !== null && records !== void 0 ? records : []).filter(isCostSessionRecord);
+                this.loaded = true;
+            }
+        })
+            .catch((e) => {
+            logger.warn('Cost history unreadable — recording locally only this page-load', e);
+            // Writes stay blocked, and `persist` will not save even if something else calls it.
+            // `saveCostHistory` REPLACES the stored list, so writing an upsert against the empty
+            // list we fell back to would delete every other project's row and reset this
+            // project's banked total — destroying data we simply failed to read. The row
+            // rebuilds from the transcript on the next successful load.
+            this.unreadable = true;
+        });
+    }
+    /**
+     * The persistence provider, but only when it implements BOTH cost-history methods.
+     *
+     * Both or neither: a provider that can save but not load would silently accumulate a
+     * ledger nobody ever reads back, so a partial implementation is treated as absent and
+     * falls back to `localStorage`.
+     */
+    costHistoryProvider() {
+        const provider = this.deps.provider();
+        return (provider === null || provider === void 0 ? void 0 : provider.loadCostHistory) && provider.saveCostHistory ? provider : undefined;
+    }
+    /**
+     * Adopt `records` as the live list, and schedule a write to whichever backend owns cost
+     * history — the provider when the host implements it, else `localStorage`.
+     *
+     * The list is adopted synchronously because that is what the Usage tab renders; only the
+     * *write* is deferred. This runs on every usage change (about once per LLM call, plus once
+     * per sub-agent turn) and each write serialises the whole ledger, so coalescing cuts a
+     * per-turn `localStorage.setItem` or network round-trip down to one per quiet period. Safe
+     * because the write is a full replace of idempotent state: the newest call wins and no
+     * intermediate state is meaningful. Flushed on `pagehide` and disconnect so nothing is lost.
+     */
+    persist(records) {
+        this.history = records;
+        // A ledger we could not read must never be written back — see `reload`. Guarded here
+        // rather than only at the finalize gate so it also covers the row-removal and clear
+        // paths, which write directly.
+        if (this.unreadable)
+            return;
+        this.dirty = true;
+        if (this.flushTimer !== undefined)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = setTimeout(() => this.flush(), LEDGER_FLUSH_DEBOUNCE_MS);
+    }
+    /**
+     * Write the pending ledger now. Safe to call when nothing is pending.
+     *
+     * Provider writes are fire-and-forget and best-effort: the ledger is accounting, not
+     * conversation content, so a failed write is logged and never surfaced into the chat. On
+     * `pagehide` the `localStorage` path completes synchronously; a provider write is subject to
+     * the same unload race as every other network save the assistant makes.
+     */
+    flush() {
+        if (this.flushTimer !== undefined) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        if (!this.dirty || this.unreadable)
+            return;
+        this.dirty = false;
+        const records = this.history;
+        const scope = this.scope();
+        const provider = this.costHistoryProvider();
+        if (!provider) {
+            saveCostSessionHistory(scope, records);
+            return;
+        }
+        void provider.saveCostHistory(scope, records).catch((e) => {
+            logger.warn('Cost history save failed', e);
+        });
+    }
+    /**
+     * Finalize the previous session when the host-provided title changes — a rename should land on
+     * the row under its old name rather than silently relabelling accrued spend.
+     *
+     * Only when the session key still matches the one that title accrued under. Hosts change
+     * `costHistory.title` on project SWITCH too, and if the key has already flipped, this would
+     * upsert the outgoing project's live usage onto the incoming project's row as
+     * `banked + old live`, inflating it. Under the old append model a mis-keyed write left a stray
+     * row; with the upsert it overwrites a real one.
+     */
+    syncActiveTitle() {
+        var _a, _b;
+        const previous = this.activeTitle;
+        const next = (_b = (_a = this.config.title) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : '';
+        const key = this.deps.stateKey();
+        if (previous && previous !== next && this.activeKey === key) {
+            this.finalize({ title: previous });
+        }
+        if (previous !== next) {
+            this.activeTitle = next;
+            this.activeKey = key;
+        }
+    }
+}
+__decorate([
+    observable
+], CostLedgerController.prototype, "history", void 0);
+__decorate([
+    volatile
+], CostLedgerController.prototype, "config", null);
+__decorate([
+    volatile
+], CostLedgerController.prototype, "uniqueProviderModels", null);
+__decorate([
+    volatile
+], CostLedgerController.prototype, "sortedHistory", null);
+__decorate([
+    volatile
+], CostLedgerController.prototype, "cumulativeUsage", null);
+__decorate([
+    volatile
+], CostLedgerController.prototype, "cumulativeCostUsd", null);
+__decorate([
+    volatile
+], CostLedgerController.prototype, "liveUsageIsProjectLifetime", null);
+__decorate([
+    volatile
+], CostLedgerController.prototype, "liveTitle", null);