crewly 1.14.0 → 1.15.0

package/dist/backend/backend/src/services/hierarchy/hierarchy-escalation-monitor.service.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Hierarchy Escalation Monitor
+ *
+ * Runtime wiring for {@link HierarchyEscalationService}, which documents
+ * the "TL unresponsive → bypass to the orchestrator" rule but had no
+ * consumers: nothing recorded TL responses, nothing checked the timeout,
+ * nothing routed the bypass.
+ *
+ * The signal we have today for "a worker escalated to their TL" is the
+ * verification handoff: `task:done_by_worker` puts a WorkItem in the TL's
+ * court, and `task:verified` / `task:rejected` is the TL's response. So:
+ *
+ *   - `task:done_by_worker`   → remember `{ workItemId, workerSession, since }`
+ *   - `task:verified|rejected` → forget it; `recordTLResponse(tlSession)`
+ *   - every {@link DEFAULT_SWEEP_INTERVAL_MS}: for each pending handoff
+ *     older than {@link DEFAULT_TL_ACK_TIMEOUT_MS} whose WI is still
+ *     `done_by_worker`, resolve the worker's TL from the team hierarchy,
+ *     call `handleTLUnresponsive` (publishes `hierarchy:escalation`) and
+ *     enqueue an `[ESCALATION]` system event to the orchestrator — once
+ *     per WorkItem.
+ *
+ * What is still missing for a fuller implementation: an explicit
+ * "TL acknowledged" signal distinct from the verdict (a TL who has *seen*
+ * the item but is still reviewing looks identical to one who is gone),
+ * and inclusion of non-verification escalations (a worker's free-text
+ * report-status escalation does not produce a WorkItem the monitor can
+ * track).
+ *
+ * @module services/hierarchy/hierarchy-escalation-monitor.service
+ */
+import { type ComponentLogger } from '../core/logger.service.js';
+import { HierarchyEscalationService } from './hierarchy-escalation.service.js';
+import type { EventBusService } from '../event-bus/event-bus.service.js';
+import type { Team } from '../../types/index.js';
+import type { WorkItem } from '../../types/v2/work-item.types.js';
+import { MESSAGE_SOURCES } from '../../constants.js';
+/** How long a TL may sit on a worker's handoff before the bypass fires. */
+export declare const DEFAULT_TL_ACK_TIMEOUT_MS: number;
+/** Cadence of the pending-handoff sweep. */
+export declare const DEFAULT_SWEEP_INTERVAL_MS: number;
+/** Conversation id stamped on the orchestrator-bound bypass message. */
+export declare const HIERARCHY_ESCALATION_CONVERSATION_ID = "system_hierarchy_escalation";
+/** Envelope prefix for the bypass message. */
+export declare const HIERARCHY_ESCALATION_ENVELOPE_PREFIX = "[ESCALATION]";
+/** Minimal pool surface. */
+export interface HierarchyMonitorTaskPool {
+    findWorkItem(id: string): Promise<WorkItem | null | undefined>;
+}
+/** Minimal queue surface. */
+export interface HierarchyMonitorMessageQueue {
+    enqueue(input: {
+        content: string;
+        conversationId: string;
+        source: typeof MESSAGE_SOURCES.SYSTEM_EVENT;
+        targetSession?: string;
+        sourceMetadata?: Record<string, unknown>;
+    }): unknown;
+}
+/** Injectable dependencies. */
+export interface HierarchyEscalationMonitorDependencies {
+    eventBus: EventBusService;
+    messageQueue: HierarchyMonitorMessageQueue;
+    taskPool?: HierarchyMonitorTaskPool;
+    getTeams?: () => Promise<Team[]>;
+    escalation?: HierarchyEscalationService;
+    logger?: ComponentLogger;
+    now?: () => Date;
+    /** Override the TL acknowledgement timeout (ms). */
+    ackTimeoutMs?: number;
+    /** Override the sweep cadence (ms). `0` disables the timer (tests call `sweep()`). */
+    sweepIntervalMs?: number;
+}
+/** Outcome of one sweep. */
+export interface HierarchySweepResult {
+    pending: number;
+    escalated: string[];
+    cleared: string[];
+}
+/**
+ * Tracks worker→TL handoffs and bypasses an unresponsive TL. See module docs.
+ */
+export declare class HierarchyEscalationMonitor {
+    private readonly eventBus;
+    private readonly messageQueue;
+    private readonly taskPool;
+    private readonly getTeams;
+    private readonly escalation;
+    private readonly logger;
+    private readonly now;
+    private readonly ackTimeoutMs;
+    private readonly sweepIntervalMs;
+    private readonly pending;
+    private readonly escalated;
+    private unsubscribers;
+    private timer;
+    private started;
+    private readonly pendingDispatches;
+    constructor(deps: HierarchyEscalationMonitorDependencies);
+    /**
+     * Production wiring helper.
+     *
+     * @param eventBus - Live event bus
+     * @param messageQueue - Orchestrator message queue
+     * @returns A monitor ready to `start()`
+     */
+    static boot(eventBus: EventBusService, messageQueue: HierarchyMonitorMessageQueue): HierarchyEscalationMonitor;
+    /** Subscribe + arm the sweep timer. Idempotent. */
+    start(): void;
+    /** Detach subscriptions and stop the timer. Idempotent. */
+    stop(): void;
+    /** Await in-flight event handlers. Test affordance. */
+    flushPending(): Promise<void>;
+    /** Number of handoffs currently awaiting a TL verdict. */
+    get pendingCount(): number;
+    private safeDispatch;
+    /** `task:done_by_worker` — open a pending handoff keyed on the WI. */
+    private onOpen;
+    /** `task:verified|rejected|cancelled` — the TL (or system) responded. */
+    private onClose;
+    /**
+     * Escalate every pending handoff older than the ack timeout whose WI is
+     * still waiting on the TL. Safe to call directly (tests, ops).
+     *
+     * @returns Summary of what happened
+     */
+    sweep(): Promise<HierarchySweepResult>;
+    /** Fire the documented bypass for one stale handoff. */
+    private escalate;
+    /** Publish `hierarchy:escalation` for the TL-at-root case (target = orchestrator). */
+    private publishBypassEvent;
+    /**
+     * Resolve a worker session to its team, member record and team lead. The
+     * TL is the worker's `parentMemberId` when set, else the team's canonical
+     * lead via {@link pickTeamLead}. Returns `null` when the session is not a
+     * team member.
+     */
+    private resolveChain;
+    private rememberEscalated;
+}
+//# sourceMappingURL=hierarchy-escalation-monitor.service.d.ts.map

package/dist/backend/backend/src/services/hierarchy/hierarchy-escalation-monitor.service.d.ts.map

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

package/dist/backend/backend/src/services/hierarchy/hierarchy-escalation-monitor.service.js

@@ -0,0 +1,346 @@
+/**
+ * Hierarchy Escalation Monitor
+ *
+ * Runtime wiring for {@link HierarchyEscalationService}, which documents
+ * the "TL unresponsive → bypass to the orchestrator" rule but had no
+ * consumers: nothing recorded TL responses, nothing checked the timeout,
+ * nothing routed the bypass.
+ *
+ * The signal we have today for "a worker escalated to their TL" is the
+ * verification handoff: `task:done_by_worker` puts a WorkItem in the TL's
+ * court, and `task:verified` / `task:rejected` is the TL's response. So:
+ *
+ *   - `task:done_by_worker`   → remember `{ workItemId, workerSession, since }`
+ *   - `task:verified|rejected` → forget it; `recordTLResponse(tlSession)`
+ *   - every {@link DEFAULT_SWEEP_INTERVAL_MS}: for each pending handoff
+ *     older than {@link DEFAULT_TL_ACK_TIMEOUT_MS} whose WI is still
+ *     `done_by_worker`, resolve the worker's TL from the team hierarchy,
+ *     call `handleTLUnresponsive` (publishes `hierarchy:escalation`) and
+ *     enqueue an `[ESCALATION]` system event to the orchestrator — once
+ *     per WorkItem.
+ *
+ * What is still missing for a fuller implementation: an explicit
+ * "TL acknowledged" signal distinct from the verdict (a TL who has *seen*
+ * the item but is still reviewing looks identical to one who is gone),
+ * and inclusion of non-verification escalations (a worker's free-text
+ * report-status escalation does not produce a WorkItem the monitor can
+ * track).
+ *
+ * @module services/hierarchy/hierarchy-escalation-monitor.service
+ */
+import { LoggerService } from '../core/logger.service.js';
+import { StorageService } from '../core/storage.service.js';
+import { TaskPoolService } from '../task-pool/task-pool.service.js';
+import { HierarchyEscalationService } from './hierarchy-escalation.service.js';
+import { pickTeamLead } from '../../utils/team.utils.js';
+import { formatError } from '../../utils/format-error.js';
+import { MESSAGE_SOURCES, ORCHESTRATOR_SESSION_NAME } from '../../constants.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** How long a TL may sit on a worker's handoff before the bypass fires. */
+export const DEFAULT_TL_ACK_TIMEOUT_MS = 15 * 60 * 1000;
+/** Cadence of the pending-handoff sweep. */
+export const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+/** Conversation id stamped on the orchestrator-bound bypass message. */
+export const HIERARCHY_ESCALATION_CONVERSATION_ID = 'system_hierarchy_escalation';
+/** Envelope prefix for the bypass message. */
+export const HIERARCHY_ESCALATION_ENVELOPE_PREFIX = '[ESCALATION]';
+/** Bounded size of the escalated-WI dedup list. */
+const ESCALATED_DEDUP_CAPACITY = 1000;
+/** WorkItem status meaning "waiting on the TL". */
+const AWAITING_TL_STATUS = 'done_by_worker';
+/** Events that open a pending handoff. */
+const OPEN_EVENTS = ['task:done_by_worker'];
+/** Events that close a pending handoff (the TL responded). */
+const CLOSE_EVENTS = ['task:verified', 'task:rejected', 'task:cancelled'];
+// ---------------------------------------------------------------------------
+// Monitor
+// ---------------------------------------------------------------------------
+/**
+ * Tracks worker→TL handoffs and bypasses an unresponsive TL. See module docs.
+ */
+export class HierarchyEscalationMonitor {
+    eventBus;
+    messageQueue;
+    taskPool;
+    getTeams;
+    escalation;
+    logger;
+    now;
+    ackTimeoutMs;
+    sweepIntervalMs;
+    pending = new Map();
+    escalated = [];
+    unsubscribers = [];
+    timer = null;
+    started = false;
+    pendingDispatches = new Set();
+    constructor(deps) {
+        this.eventBus = deps.eventBus;
+        this.messageQueue = deps.messageQueue;
+        this.taskPool = deps.taskPool ?? TaskPoolService.getInstance();
+        this.getTeams = deps.getTeams ?? (() => StorageService.getInstance().getTeams());
+        this.escalation = deps.escalation ?? HierarchyEscalationService.getInstance();
+        this.logger =
+            deps.logger ??
+                LoggerService.getInstance().createComponentLogger('HierarchyEscalationMonitor');
+        this.now = deps.now ?? (() => new Date());
+        this.ackTimeoutMs = deps.ackTimeoutMs ?? DEFAULT_TL_ACK_TIMEOUT_MS;
+        this.sweepIntervalMs = deps.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+    }
+    /**
+     * Production wiring helper.
+     *
+     * @param eventBus - Live event bus
+     * @param messageQueue - Orchestrator message queue
+     * @returns A monitor ready to `start()`
+     */
+    static boot(eventBus, messageQueue) {
+        return new HierarchyEscalationMonitor({ eventBus, messageQueue });
+    }
+    /** Subscribe + arm the sweep timer. Idempotent. */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.escalation.setEventBus(this.eventBus);
+        this.escalation.setUnresponsiveTimeout(this.ackTimeoutMs);
+        for (const type of OPEN_EVENTS) {
+            this.unsubscribers.push(this.eventBus.onInProcess(type, (e) => this.safeDispatch(e, this.onOpen)));
+        }
+        for (const type of CLOSE_EVENTS) {
+            this.unsubscribers.push(this.eventBus.onInProcess(type, (e) => this.safeDispatch(e, this.onClose)));
+        }
+        if (this.sweepIntervalMs > 0) {
+            this.timer = setInterval(() => {
+                this.sweep().catch((err) => {
+                    this.logger.warn('Hierarchy escalation sweep failed', { error: formatError(err) });
+                });
+            }, this.sweepIntervalMs);
+            this.timer.unref?.();
+        }
+        this.logger.info('HierarchyEscalationMonitor started', {
+            ackTimeoutMs: this.ackTimeoutMs,
+            sweepIntervalMs: this.sweepIntervalMs,
+        });
+    }
+    /** Detach subscriptions and stop the timer. Idempotent. */
+    stop() {
+        for (const u of this.unsubscribers) {
+            try {
+                u();
+            }
+            catch (err) {
+                this.logger.warn('HierarchyEscalationMonitor unsubscribe threw', { error: formatError(err) });
+            }
+        }
+        this.unsubscribers = [];
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.started = false;
+    }
+    /** Await in-flight event handlers. Test affordance. */
+    async flushPending() {
+        while (this.pendingDispatches.size > 0) {
+            await Promise.allSettled(Array.from(this.pendingDispatches));
+        }
+    }
+    /** Number of handoffs currently awaiting a TL verdict. */
+    get pendingCount() {
+        return this.pending.size;
+    }
+    // -------------------------------------------------------------------------
+    // Event handlers
+    // -------------------------------------------------------------------------
+    safeDispatch(event, handler) {
+        const promise = (async () => {
+            try {
+                await handler(event);
+            }
+            catch (err) {
+                this.logger.warn('HierarchyEscalationMonitor handler threw — swallowed', {
+                    eventType: event.type,
+                    eventId: event.id,
+                    error: formatError(err),
+                });
+            }
+        })();
+        this.pendingDispatches.add(promise);
+        promise.finally(() => this.pendingDispatches.delete(promise));
+        return promise;
+    }
+    /** `task:done_by_worker` — open a pending handoff keyed on the WI. */
+    onOpen = async (event) => {
+        if (!event.workItemId)
+            return;
+        const wi = await this.taskPool.findWorkItem(event.workItemId);
+        if (!wi || !wi.target)
+            return;
+        this.pending.set(wi.id, {
+            workItemId: wi.id,
+            workerSession: wi.target,
+            since: this.now().getTime(),
+        });
+    };
+    /** `task:verified|rejected|cancelled` — the TL (or system) responded. */
+    onClose = async (event) => {
+        if (!event.workItemId)
+            return;
+        const handoff = this.pending.get(event.workItemId);
+        this.pending.delete(event.workItemId);
+        if (!handoff || event.type === 'task:cancelled')
+            return;
+        const resolved = await this.resolveChain(handoff.workerSession);
+        if (resolved?.teamLead) {
+            this.escalation.recordTLResponse(resolved.teamLead.sessionName);
+        }
+    };
+    // -------------------------------------------------------------------------
+    // Sweep
+    // -------------------------------------------------------------------------
+    /**
+     * Escalate every pending handoff older than the ack timeout whose WI is
+     * still waiting on the TL. Safe to call directly (tests, ops).
+     *
+     * @returns Summary of what happened
+     */
+    async sweep() {
+        const nowMs = this.now().getTime();
+        const result = { pending: this.pending.size, escalated: [], cleared: [] };
+        for (const handoff of Array.from(this.pending.values())) {
+            if (nowMs - handoff.since < this.ackTimeoutMs)
+                continue;
+            const wi = await this.taskPool.findWorkItem(handoff.workItemId);
+            if (!wi || wi.status !== AWAITING_TL_STATUS) {
+                // Resolved out-of-band (or gone) — nothing to escalate.
+                this.pending.delete(handoff.workItemId);
+                result.cleared.push(handoff.workItemId);
+                continue;
+            }
+            if (this.escalated.includes(handoff.workItemId)) {
+                this.pending.delete(handoff.workItemId);
+                continue;
+            }
+            try {
+                await this.escalate(handoff, wi);
+                result.escalated.push(handoff.workItemId);
+            }
+            catch (err) {
+                this.logger.warn('Hierarchy escalation failed for handoff', {
+                    workItemId: handoff.workItemId,
+                    error: formatError(err),
+                });
+            }
+            finally {
+                this.pending.delete(handoff.workItemId);
+            }
+        }
+        return result;
+    }
+    /** Fire the documented bypass for one stale handoff. */
+    async escalate(handoff, wi) {
+        this.rememberEscalated(handoff.workItemId);
+        const chain = await this.resolveChain(handoff.workerSession);
+        const waitedMin = Math.round((this.now().getTime() - handoff.since) / 60_000);
+        const message = `Team lead has not acted on "${wi.title}" (${wi.id}) submitted by ${handoff.workerSession} ` +
+            `${waitedMin} min ago — bypassing to the orchestrator.`;
+        let target = ORCHESTRATOR_SESSION_NAME;
+        if (chain?.teamLead && chain.worker) {
+            const routed = this.escalation.handleTLUnresponsive(chain.teamLead.sessionName, chain.worker, chain.team.members, wi.id, message, { teamId: chain.team.id, teamName: chain.team.name });
+            // The service routes to the TL's parent when one exists and publishes
+            // `hierarchy:escalation` itself. A TL at the top of its team's tree
+            // (the common shape) has no parent inside the team, so the service
+            // returns null without publishing — the orchestrator is the documented
+            // fallback and we publish the event here so subscribers still see it.
+            if (routed?.target.sessionName) {
+                target = routed.target.sessionName;
+            }
+            else {
+                this.publishBypassEvent(chain.team, chain.worker, chain.teamLead, wi.id);
+            }
+        }
+        this.messageQueue.enqueue({
+            content: `${HIERARCHY_ESCALATION_ENVELOPE_PREFIX} ${message}`,
+            conversationId: HIERARCHY_ESCALATION_CONVERSATION_ID,
+            source: MESSAGE_SOURCES.SYSTEM_EVENT,
+            targetSession: target,
+            sourceMetadata: {
+                workItemId: wi.id,
+                workerSession: handoff.workerSession,
+                teamLeadSession: chain?.teamLead?.sessionName,
+                teamId: chain?.team.id,
+                reason: 'tl_unresponsive',
+            },
+        });
+        this.logger.info('Hierarchy escalation: TL unresponsive — bypassed', {
+            workItemId: wi.id,
+            workerSession: handoff.workerSession,
+            teamLeadSession: chain?.teamLead?.sessionName,
+            target,
+        });
+    }
+    /** Publish `hierarchy:escalation` for the TL-at-root case (target = orchestrator). */
+    publishBypassEvent(team, worker, teamLead, taskId) {
+        try {
+            this.eventBus.publish({
+                id: `hierarchy:escalation:${taskId}`,
+                type: 'hierarchy:escalation',
+                timestamp: this.now().toISOString(),
+                teamId: team.id,
+                teamName: team.name,
+                memberId: worker.id,
+                memberName: worker.name,
+                sessionName: worker.sessionName,
+                previousValue: teamLead.sessionName,
+                newValue: ORCHESTRATOR_SESSION_NAME,
+                changedField: 'hierarchyAction',
+                taskId,
+                hierarchyLevel: worker.hierarchyLevel,
+                parentMemberId: worker.parentMemberId,
+            });
+        }
+        catch (err) {
+            this.logger.warn('hierarchy:escalation publish threw', { taskId, error: formatError(err) });
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Resolve a worker session to its team, member record and team lead. The
+     * TL is the worker's `parentMemberId` when set, else the team's canonical
+     * lead via {@link pickTeamLead}. Returns `null` when the session is not a
+     * team member.
+     */
+    async resolveChain(workerSession) {
+        let teams;
+        try {
+            teams = await this.getTeams();
+        }
+        catch (err) {
+            this.logger.warn('Team lookup failed during hierarchy escalation', { error: formatError(err) });
+            return null;
+        }
+        for (const team of teams) {
+            const worker = team.members.find((m) => m.sessionName === workerSession);
+            if (!worker)
+                continue;
+            const parent = worker.parentMemberId
+                ? (team.members.find((m) => m.id === worker.parentMemberId) ?? null)
+                : null;
+            const teamLead = parent ?? pickTeamLead(team);
+            // A worker who IS the lead has nobody above them inside the team.
+            return { team, worker, teamLead: teamLead && teamLead.id !== worker.id ? teamLead : null };
+        }
+        return null;
+    }
+    rememberEscalated(workItemId) {
+        this.escalated.push(workItemId);
+        if (this.escalated.length > ESCALATED_DEDUP_CAPACITY)
+            this.escalated.shift();
+    }
+}
+//# sourceMappingURL=hierarchy-escalation-monitor.service.js.map

package/dist/backend/backend/src/services/hierarchy/hierarchy-escalation-monitor.service.js.map

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

package/dist/backend/backend/src/services/monitoring/token-usage.service.d.ts

@@ -22,6 +22,18 @@ export interface TokenUsageEvent {
     model: string;
     /** Optional task ID for per-task tracking */
     taskId?: string;
+    /**
+     * Portion of `input` the provider served from its prompt cache (billed at
+     * a fraction of the input rate). Absent when the runtime cannot tell.
+     */
+    cachedInput?: number;
+    /** Model round-trips the run took (agentic steps). Absent when unknown. */
+    steps?: number;
+}
+/** Optional per-event detail beyond the raw input/output counts. */
+export interface TokenUsageDetail {
+    cachedInput?: number;
+    steps?: number;
 }
 /**
  * Per-session token usage record containing all events and aggregates
@@ -37,6 +49,8 @@ export interface SessionUsageRecord {
     totalOutput: number;
     /** Number of usage events recorded */
     eventCount: number;
+    /** Total cached (cache-hit) input tokens across all events; absent on records written before 2026-09-18 */
+    totalCachedInput?: number;
     /** Individual usage events */
     events: TokenUsageEvent[];
 }
@@ -65,6 +79,8 @@ export interface SessionUsageSummary {
     totalOutput: number;
     /** Number of events */
     eventCount: number;
+    /** Total cache-hit input tokens, when the runtime reports them */
+    totalCachedInput?: number;
     /** Computed cost in USD based on model pricing */
     cost: number;
     /** Per-model breakdown of token usage */
@@ -90,16 +106,22 @@ export interface ModelUsageBreakdown {
 export declare const TOKEN_COSTS: Record<string, {
     input: number;
     output: number;
+    cachedInput?: number;
 }>;
 /**
  * Calculate the cost for a given number of tokens and model.
  *
- * @param inputTokens - Number of input tokens (excluding cache tokens)
+ * When the model has a `cachedInput` rate and the caller passes how many of
+ * the input tokens were cache hits, those tokens are billed at the hit rate
+ * and only the remainder at the full input rate.
+ *
+ * @param inputTokens - Total input tokens for the call(s), cache hits included
  * @param outputTokens - Number of output tokens
  * @param model - Model identifier
+ * @param cachedInputTokens - Portion of `inputTokens` served from cache (default 0)
  * @returns Cost in USD
  */
-export declare function calculateCost(inputTokens: number, outputTokens: number, model: string): number;
+export declare function calculateCost(inputTokens: number, outputTokens: number, model: string, cachedInputTokens?: number): number;
 /**
  * Set a cost override for a session. When present, getSummary() uses this
  * instead of recalculating from events.
@@ -159,8 +181,10 @@ export declare class TokenUsageService {
      * @param input - Number of input tokens consumed
      * @param output - Number of output tokens generated
      * @param model - AI model identifier used
+     * @param taskId - Optional task the usage belongs to
+     * @param detail - Optional cache-hit and step counts for this event
      */
-    recordUsage(sessionName: string, agentId: string, input: number, output: number, model: string, taskId?: string): void;
+    recordUsage(sessionName: string, agentId: string, input: number, output: number, model: string, taskId?: string, detail?: TokenUsageDetail): void;
     /**
      * Set a cache-aware cost override for a session.
      * Used when the caller has pre-calculated cost with proper cache pricing.

package/dist/backend/backend/src/services/monitoring/token-usage.service.d.ts.map

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