crewly 1.20.194 → 1.20.196

package/dist/backend/backend/src/services/trace/trace-metrics.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Autonomy metrics of one run trace, computed from its events only: where the
+ * time went (agents working, waiting on the owner, waiting on an agent, idle),
+ * owner touches, rework, stalls with a cause, harness interventions, tokens
+ * and cost, and the outcome.
+ *
+ * Pure: no I/O, no clock unless none is given. The definitions are in
+ * specs/2026-10-03-autonomy-metrics.md; keep the two in step.
+ *
+ * @module services/trace/trace-metrics
+ */
+import type { TraceEvent, TraceRoot } from './trace.types.js';
+/** Why nothing moved during a stall. */
+export type StallCause = 'runtime_quota' | 'delivery_failure' | 'waiting_on_owner' | 'waiting_on_agent' | 'nobody_pushing';
+/** Every stall cause, in the order they are checked. */
+export declare const STALL_CAUSES: readonly StallCause[];
+/** One gap with no progress longer than the threshold. */
+export interface TraceStall {
+    /** ISO start (the last progress before it) */
+    start: string;
+    /** ISO end (the next progress, or now for an ongoing stall) */
+    end: string;
+    ms: number;
+    cause: StallCause;
+    /** One English line: what it waited on */
+    detail: string;
+    /** Agent sessions it waited on, when known */
+    sessions?: string[];
+    /** Still going: the trace is open and nothing happened since `start` */
+    ongoing?: boolean;
+}
+/** Overall state of the run. */
+export type TraceOutcomeState = 'done' | 'cancelled' | 'failed' | 'waiting_on_owner' | 'in_progress' | 'no_open_work';
+/** Tokens and cost of one agent or model. */
+export interface UsageBreakdown {
+    /** Agent session or model id */
+    key: string;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    /** input (cached included) + output */
+    totalTokens: number;
+    costUsd: number;
+}
+/** Everything computed for one trace. */
+export interface TraceMetrics {
+    traceId: string;
+    /** The window: root → last event */
+    window: {
+        start: string;
+        end: string;
+    };
+    /** Events looked at (the root excluded) */
+    eventCount: number;
+    /** Agent sessions that appear in the trace */
+    agents: string[];
+    time: {
+        wallMs: number;
+        activeMs: number;
+        waitingOwnerMs: number;
+        waitingAgentMs: number;
+        idleMs: number;
+        /** Where busy periods came from */
+        activeSource: 'turn_events' | 'inferred' | 'mixed' | 'none';
+    };
+    /**
+     * `manual` (dashboard writes, `owner.action`) is NOT COLLECTED YET: the
+     * dashboard marker is not authenticated (an agent could send it), so it is
+     * left out of `total` and not shown until owner sessions (#999) land.
+     */
+    ownerTouches: {
+        answered: number;
+        approved: number;
+        sentBack: number;
+        corrected: number;
+        manual: number;
+        total: number;
+    };
+    rework: {
+        sendBacks: number;
+        retries: number;
+        failedVerifications: number;
+        subagentSendBacks: number;
+        total: number;
+    };
+    stalls: {
+        thresholdMinutes: number;
+        count: number;
+        /** Ongoing stall included */
+        totalMs: number;
+        byCause: Record<StallCause, number>;
+        /** Chronological; at most METRICS_MAX_STALL_ITEMS (the longest) */
+        items: TraceStall[];
+    };
+    interventions: {
+        nudges: number;
+        redeliveries: number;
+        wakes: number;
+        corrections: number;
+        guardBlocks: number;
+        misroutes: number;
+        total: number;
+    };
+    usage: {
+        inputTokens: number;
+        cachedInputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        costUsd: number;
+        /** Most expensive first */
+        byAgent: UsageBreakdown[];
+        byModel: UsageBreakdown[];
+    };
+    outcome: {
+        state: TraceOutcomeState;
+        /** Last status of the trace's (first) Request */
+        requestStatus?: string;
+        workItems: {
+            total: number;
+            done: number;
+            failed: number;
+            open: number;
+        };
+        experiment?: {
+            id: string;
+            status?: string;
+            verdict?: string;
+        };
+    };
+    /** Each owner touch with its time (only with `detail`) */
+    ownerTouchEvents?: OwnerTouchEvent[];
+}
+/** The few numbers embedded in `GET /api/traces` rows. */
+export interface TraceMetricsSummary {
+    wallMs: number;
+    activeMs: number;
+    waitingOwnerMs: number;
+    waitingAgentMs: number;
+    idleMs: number;
+    ownerTouches: number;
+    rework: number;
+    stalls: number;
+    stallMs: number;
+    ongoingStall: boolean;
+    interventions: number;
+    totalTokens: number;
+    costUsd: number;
+    state: TraceOutcomeState;
+}
+/** Options of {@link computeTraceMetrics}. */
+export interface TraceMetricsOptions {
+    /** Stall threshold (default {@link defaultStallMinutes}) */
+    stallMinutes?: number;
+    /** Clock for the ongoing stall (default: now) */
+    now?: Date;
+    /**
+     * Keep every stall item (no METRICS_MAX_STALL_ITEMS cap) and list each
+     * owner touch with its time in `ownerTouchEvents` — for callers that
+     * split a run by day (the autopilot stats).
+     */
+    detail?: boolean;
+}
+/** One owner touch and when it happened (`detail` only). */
+export interface OwnerTouchEvent {
+    kind: 'answered' | 'approved' | 'sentBack' | 'corrected';
+    at: string;
+}
+/**
+ * Stall threshold: `CREWLY_TRACE_STALL_MINUTES`, else
+ * {@link TRACE_CONSTANTS.STALL_MINUTES}.
+ *
+ * @returns Minutes
+ */
+export declare function defaultStallMinutes(): number;
+/**
+ * A caller's stall threshold within bounds.
+ *
+ * @param minutes - Requested minutes
+ * @returns Minutes within STALL_MINUTES_MIN..STALL_MINUTES_MAX
+ */
+export declare function clampStallMinutes(minutes: number): number;
+/** `[start, end]` in ms. */
+type Interval = [number, number];
+/**
+ * Sort and merge overlapping intervals; empty ones are dropped.
+ *
+ * @param list - Intervals
+ * @returns Disjoint, sorted intervals
+ */
+export declare function mergeIntervals(list: ReadonlyArray<Interval>): Interval[];
+/**
+ * `a` minus `b`; both merged.
+ *
+ * @param a - Intervals
+ * @param b - Intervals to remove
+ * @returns What is in `a` and not in `b`
+ */
+export declare function subtractIntervals(a: ReadonlyArray<Interval>, b: ReadonlyArray<Interval>): Interval[];
+/** An event with its parsed time and file order. */
+interface Timed {
+    e: TraceEvent;
+    t: number;
+}
+/**
+ * The agent session an event is about: its agent actor, else `refs.session`.
+ *
+ * @param e - Event
+ * @returns Session, or undefined
+ */
+export declare function sessionOfEvent(e: TraceEvent): string | undefined;
+/**
+ * Whether an event moved the run forward (see the spec's Stalls section).
+ *
+ * @param e - Event
+ * @returns True for progress
+ */
+export declare function isProgressEvent(e: TraceEvent): boolean;
+/**
+ * Tokens and cost of a `usage` event (the Usage page's unit and prices).
+ *
+ * @param e - Event
+ * @returns Tokens (input incl. cached + output) and USD, or null for other events
+ */
+export declare function usageOfEvent(e: TraceEvent): {
+    input: number;
+    cachedInput: number;
+    output: number;
+    total: number;
+    costUsd: number;
+} | null;
+/**
+ * Sorted events with a valid time (the root excluded).
+ *
+ * @param events - Raw events
+ * @returns Events with times, in time order (file order breaks ties)
+ */
+export declare function sortTraceEvents(events: ReadonlyArray<TraceEvent>): Timed[];
+/**
+ * Compute the autonomy metrics of a trace.
+ *
+ * @param root - The trace root
+ * @param events - Its events, in any order (the root event is ignored)
+ * @param options - Stall threshold, clock
+ * @returns The metrics
+ *
+ * @example
+ * ```typescript
+ * const page = await store.read(id, 0, TRACE_CONSTANTS.MAX_PAGE_SIZE);
+ * const m = computeTraceMetrics(page.root, page.events, { stallMinutes: 30 });
+ * m.time.waitingOwnerMs; // time the run sat on the owner
+ * ```
+ */
+export declare function computeTraceMetrics(root: TraceRoot, events: ReadonlyArray<TraceEvent>, options?: TraceMetricsOptions): TraceMetrics;
+/**
+ * The numbers embedded in list rows.
+ *
+ * @param m - Full metrics
+ * @returns Summary
+ */
+export declare function summarizeTraceMetrics(m: TraceMetrics): TraceMetricsSummary;
+export {};
+//# sourceMappingURL=trace-metrics.d.ts.map

package/dist/backend/backend/src/services/trace/trace-metrics.d.ts.map

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