@sentropic/agent-stats-core 0.1.0

package/README.md

@@ -0,0 +1,4 @@
+# @sentropic/agent-stats-core
+
+Parsers and aggregations for Claude Code and Codex CLI session jsonl files.
+See [`../../plan.md`](../../plan.md) for the implementation roadmap (WP2-WP3).

package/dist/aggregations.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Weekly aggregations.
+ *
+ * Two-pass algorithm:
+ *   1. Group events by `sessionId` and compute a `SessionMeta` per session
+ *      (start ts, total usage, sub-agent depth, etc.).
+ *   2. Bucket sessions by (weekStart × projectCwd × tool × model) and sum
+ *      the metrics into `WeeklyAggregation` rows.
+ *
+ * Cost is split by currency: Codex credits and Claude USD cents are
+ * tracked separately so they never get mixed.
+ */
+import { type SessionEvent, type Tool, type Usage } from './schema.js';
+import { type ModelRates } from './rate-card.js';
+export interface SessionAggregate {
+    sessionId: string;
+    tool: Tool;
+    projectCwd: string;
+    model: string;
+    startTs: string;
+    endTs: string;
+    durationMs: number;
+    turns: number;
+    totalUsage: Usage;
+    isSubagent: boolean;
+    forkedFromId?: string;
+    toolCalls: number;
+    toolCallsByCategory: Record<string, number>;
+    toolCallsByName: Record<string, number>;
+    skillInvocations: number;
+    skillsByName: Record<string, number>;
+    compactions: number;
+    estimatedCost: {
+        codexCredits: number;
+        claudeUsdCents: number;
+        unknown: number;
+    };
+    rateLimitMax?: {
+        primaryPercent: number;
+        secondaryPercent: number;
+    };
+}
+export interface WeeklyAggregation {
+    /** ISO date of the Monday opening the week (UTC). */
+    weekStart: string;
+    projectCwd: string;
+    tool: Tool;
+    model: string;
+    sessions: number;
+    subagentSessions: number;
+    uniqueParents: number;
+    totalDurationMs: number;
+    turns: number;
+    totalUsage: Usage;
+    toolCalls: number;
+    toolCallsByCategory: Record<string, number>;
+    toolCallsByName: Record<string, number>;
+    skillInvocations: number;
+    skillsByName: Record<string, number>;
+    compactions: number;
+    estimatedCost: {
+        codexCredits: number;
+        claudeUsdCents: number;
+        unknown: number;
+    };
+    rateLimitMax?: {
+        primaryPercent: number;
+        secondaryPercent: number;
+    };
+}
+export interface AggregateOptions {
+    /** Override the rate card; defaults to `DEFAULT_RATE_CARD`. */
+    rateCard?: Record<string, ModelRates>;
+}
+/** Monday 00:00 UTC of the ISO week containing `iso`. */
+export declare function weekStartIso(iso: string): string;
+export declare function aggregateSessions(events: AsyncIterable<SessionEvent> | Iterable<SessionEvent>, opts?: AggregateOptions): Promise<SessionAggregate[]>;
+/** Roll SessionAggregates into weekly rows. */
+export declare function bucketWeekly(sessions: SessionAggregate[]): WeeklyAggregation[];
+/**
+ * High-level helper: events → SessionAggregate[] → WeeklyAggregation[].
+ * The caller does not need to know about the two passes.
+ */
+export declare function aggregateWeekly(events: AsyncIterable<SessionEvent> | Iterable<SessionEvent>, opts?: AggregateOptions): Promise<WeeklyAggregation[]>;
+/** Cache-efficiency ratio (cached input tokens / total input tokens). */
+export declare function cacheEfficiency(usage: Usage): number;
+//# sourceMappingURL=aggregations.d.ts.map

package/dist/aggregations.d.ts.map

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

package/dist/aggregations.js

@@ -0,0 +1,242 @@
+/**
+ * Weekly aggregations.
+ *
+ * Two-pass algorithm:
+ *   1. Group events by `sessionId` and compute a `SessionMeta` per session
+ *      (start ts, total usage, sub-agent depth, etc.).
+ *   2. Bucket sessions by (weekStart × projectCwd × tool × model) and sum
+ *      the metrics into `WeeklyAggregation` rows.
+ *
+ * Cost is split by currency: Codex credits and Claude USD cents are
+ * tracked separately so they never get mixed.
+ */
+import { ZERO_USAGE, addUsage } from './schema.js';
+import { DEFAULT_RATE_CARD, estimateCost, resolveRates } from './rate-card.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const ZERO_COST = { codexCredits: 0, claudeUsdCents: 0, unknown: 0 };
+function addCost(a, b) {
+    return {
+        codexCredits: a.codexCredits + b.codexCredits,
+        claudeUsdCents: a.claudeUsdCents + b.claudeUsdCents,
+        unknown: a.unknown + b.unknown,
+    };
+}
+/** Monday 00:00 UTC of the ISO week containing `iso`. */
+export function weekStartIso(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return '';
+    const day = d.getUTCDay(); // 0 = Sun .. 6 = Sat
+    const diff = day === 0 ? -6 : 1 - day;
+    const monday = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + diff));
+    return monday.toISOString().slice(0, 10);
+}
+function emptySessionAggregate() {
+    return {
+        sessionId: '',
+        tool: 'claude',
+        projectCwd: '',
+        model: 'unknown',
+        startTs: '',
+        endTs: '',
+        durationMs: 0,
+        turns: 0,
+        totalUsage: { ...ZERO_USAGE },
+        isSubagent: false,
+        toolCalls: 0,
+        toolCallsByCategory: {},
+        toolCallsByName: {},
+        skillInvocations: 0,
+        skillsByName: {},
+        compactions: 0,
+        estimatedCost: { ...ZERO_COST },
+    };
+}
+// ---------------------------------------------------------------------------
+// Pass 1: events → SessionAggregate[]
+// ---------------------------------------------------------------------------
+export async function aggregateSessions(events, opts = {}) {
+    const card = opts.rateCard ?? DEFAULT_RATE_CARD;
+    const map = new Map();
+    const ensure = (key, ev) => {
+        let s = map.get(key);
+        if (!s) {
+            s = emptySessionAggregate();
+            s.sessionId = ev.sessionId;
+            s.tool = ev.tool;
+            s.projectCwd = ev.projectCwd;
+            s.startTs = ev.ts;
+            s.endTs = ev.ts;
+            map.set(key, s);
+        }
+        return s;
+    };
+    for await (const ev of events) {
+        if (!ev.sessionId)
+            continue;
+        const s = ensure(ev.sessionId, ev);
+        if (ev.ts && (!s.startTs || ev.ts < s.startTs))
+            s.startTs = ev.ts;
+        if (ev.ts && (!s.endTs || ev.ts > s.endTs))
+            s.endTs = ev.ts;
+        switch (ev.kind) {
+            case 'session_start': {
+                if (ev.model)
+                    s.model = ev.model;
+                s.isSubagent = ev.isSubagent;
+                if (ev.forkedFromId)
+                    s.forkedFromId = ev.forkedFromId;
+                break;
+            }
+            case 'session_end':
+                // ts already absorbed above.
+                break;
+            case 'turn': {
+                s.turns += 1;
+                if (ev.model && s.model === 'unknown')
+                    s.model = ev.model;
+                s.totalUsage = addUsage(s.totalUsage, ev.usage);
+                const rates = resolveRates(ev.model, card);
+                const cost = estimateCost(ev.usage, rates);
+                if (cost.currency === 'codex_credits')
+                    s.estimatedCost.codexCredits += cost.amount;
+                else if (cost.currency === 'claude_usd_cents')
+                    s.estimatedCost.claudeUsdCents += cost.amount;
+                else
+                    s.estimatedCost.unknown += cost.amount;
+                if (ev.rateLimit) {
+                    const prev = s.rateLimitMax;
+                    const next = {
+                        primaryPercent: Math.max(prev?.primaryPercent ?? 0, ev.rateLimit.primaryPercent),
+                        secondaryPercent: Math.max(prev?.secondaryPercent ?? 0, ev.rateLimit.secondaryPercent),
+                    };
+                    s.rateLimitMax = next;
+                }
+                break;
+            }
+            case 'tool_call': {
+                s.toolCalls += 1;
+                s.toolCallsByCategory[ev.category] = (s.toolCallsByCategory[ev.category] ?? 0) + 1;
+                s.toolCallsByName[ev.name] = (s.toolCallsByName[ev.name] ?? 0) + 1;
+                break;
+            }
+            case 'skill_invoke': {
+                s.skillInvocations += 1;
+                s.skillsByName[ev.name] = (s.skillsByName[ev.name] ?? 0) + 1;
+                break;
+            }
+            case 'compaction':
+                s.compactions += 1;
+                break;
+            case 'user_prompt':
+                // ts already absorbed; no other update for now.
+                break;
+        }
+    }
+    // duration
+    for (const s of map.values()) {
+        const start = Date.parse(s.startTs);
+        const end = Date.parse(s.endTs);
+        if (!Number.isNaN(start) && !Number.isNaN(end)) {
+            s.durationMs = Math.max(0, end - start);
+        }
+    }
+    return [...map.values()].sort((a, b) => a.startTs.localeCompare(b.startTs));
+}
+function weeklyKey(weekStart, projectCwd, tool, model) {
+    return `${weekStart}|${projectCwd}|${tool}|${model}`;
+}
+function emptyWeekly(weekStart, projectCwd, tool, model) {
+    return {
+        weekStart,
+        projectCwd,
+        tool,
+        model,
+        sessions: 0,
+        subagentSessions: 0,
+        uniqueParents: 0,
+        totalDurationMs: 0,
+        turns: 0,
+        totalUsage: { ...ZERO_USAGE },
+        toolCalls: 0,
+        toolCallsByCategory: {},
+        toolCallsByName: {},
+        skillInvocations: 0,
+        skillsByName: {},
+        compactions: 0,
+        estimatedCost: { ...ZERO_COST },
+        parentIds: new Set(),
+    };
+}
+function mergeCounts(target, src) {
+    for (const [k, v] of Object.entries(src)) {
+        target[k] = (target[k] ?? 0) + v;
+    }
+}
+/** Roll SessionAggregates into weekly rows. */
+export function bucketWeekly(sessions) {
+    const buckets = new Map();
+    for (const s of sessions) {
+        const week = weekStartIso(s.startTs);
+        if (!week)
+            continue;
+        const key = weeklyKey(week, s.projectCwd, s.tool, s.model);
+        let acc = buckets.get(key);
+        if (!acc) {
+            acc = emptyWeekly(week, s.projectCwd, s.tool, s.model);
+            buckets.set(key, acc);
+        }
+        acc.sessions += 1;
+        if (s.isSubagent)
+            acc.subagentSessions += 1;
+        if (s.forkedFromId)
+            acc.parentIds.add(s.forkedFromId);
+        acc.totalDurationMs += s.durationMs;
+        acc.turns += s.turns;
+        acc.totalUsage = addUsage(acc.totalUsage, s.totalUsage);
+        mergeCounts(acc.toolCallsByCategory, s.toolCallsByCategory);
+        mergeCounts(acc.toolCallsByName, s.toolCallsByName);
+        acc.toolCalls += s.toolCalls;
+        mergeCounts(acc.skillsByName, s.skillsByName);
+        acc.skillInvocations += s.skillInvocations;
+        acc.compactions += s.compactions;
+        acc.estimatedCost = addCost(acc.estimatedCost, s.estimatedCost);
+        if (s.rateLimitMax) {
+            const prev = acc.rateLimitMax;
+            acc.rateLimitMax = {
+                primaryPercent: Math.max(prev?.primaryPercent ?? 0, s.rateLimitMax.primaryPercent),
+                secondaryPercent: Math.max(prev?.secondaryPercent ?? 0, s.rateLimitMax.secondaryPercent),
+            };
+        }
+    }
+    return [...buckets.values()]
+        .map((a) => {
+        a.uniqueParents = a.parentIds.size;
+        // strip the helper Set before returning.
+        const { parentIds, ...rest } = a;
+        void parentIds;
+        return rest;
+    })
+        .sort((a, b) => a.weekStart.localeCompare(b.weekStart) ||
+        a.projectCwd.localeCompare(b.projectCwd) ||
+        a.tool.localeCompare(b.tool) ||
+        a.model.localeCompare(b.model));
+}
+/**
+ * High-level helper: events → SessionAggregate[] → WeeklyAggregation[].
+ * The caller does not need to know about the two passes.
+ */
+export async function aggregateWeekly(events, opts = {}) {
+    const sessions = await aggregateSessions(events, opts);
+    return bucketWeekly(sessions);
+}
+/** Cache-efficiency ratio (cached input tokens / total input tokens). */
+export function cacheEfficiency(usage) {
+    const total = usage.newInputTokens + usage.cachedInputTokens + usage.cacheWriteTokens;
+    if (total === 0)
+        return 0;
+    return usage.cachedInputTokens / total;
+}
+//# sourceMappingURL=aggregations.js.map

package/dist/aggregations.js.map

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

package/dist/analyze.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `analyzeWithLlm(session, opts)` — qualitative analysis of a session.
+ *
+ * Phase 2 (LLM-driven) is intentionally pluggable: callers inject the
+ * `mesh` (an `LlmMesh` instance from `@sentropic/llm-mesh`) and the
+ * `model` id. The core lib does not import `@sentropic/llm-mesh`
+ * directly so that consumers without a mesh can still use the rest of
+ * the library; the type is duck-typed below.
+ *
+ * Outputs a JSON verdict (`AnalysisVerdict`) with `frustration_level`
+ * and `out_of_control_score` (0-10), a short summary, and an optional
+ * list of root causes.
+ */
+import type { SessionAggregate } from './aggregations.js';
+export interface AnalysisVerdict {
+    sessionId: string;
+    model: string;
+    frustrationLevel: number;
+    outOfControlScore: number;
+    summary: string;
+    rootCauses: string[];
+}
+/**
+ * Duck-typed subset of `LlmMesh` from `@sentropic/llm-mesh`. We don't
+ * import the real type so the core stays decoupled.
+ */
+export interface LlmMeshLike {
+    generate(request: {
+        model: string | {
+            providerId: string;
+            modelId: string;
+        };
+        messages?: Array<{
+            role: 'system' | 'user' | 'assistant';
+            content: string;
+        }>;
+        providerId?: string;
+        [k: string]: unknown;
+    }): Promise<{
+        message?: {
+            content?: string;
+        };
+        text?: string;
+        [k: string]: unknown;
+    }>;
+}
+export interface AnalyzeOptions {
+    mesh: LlmMeshLike;
+    /** Model id passed verbatim to the mesh `generate` call. */
+    model: string;
+    /** Optional storage adapter used for verdict cache. */
+    cache?: AnalyzeCache;
+}
+export interface AnalyzeCache {
+    read(key: string): Promise<AnalysisVerdict | null>;
+    write(key: string, verdict: AnalysisVerdict): Promise<void>;
+}
+/**
+ * Run the LLM analysis for a single session. Returns the verdict.
+ * On cache hit, the mesh is not called.
+ */
+export declare function analyzeWithLlm(session: SessionAggregate, opts: AnalyzeOptions): Promise<AnalysisVerdict>;
+/**
+ * Compare `n` LLM models on the same set of sessions and return per-model
+ * latency, predicted-vs-baseline alignment, and aggregate cost (best-effort).
+ *
+ * `baseline` is the heuristic verdict (or hand-labeled if available); it
+ * provides a reference frustration & out-of-control score per session.
+ */
+export interface BenchModelConfig {
+    model: string;
+    mesh: LlmMeshLike;
+}
+export interface BenchSampleBaseline {
+    sessionId: string;
+    frustrationLevel: number;
+    outOfControlScore: number;
+}
+export interface BenchModelResult {
+    model: string;
+    samples: number;
+    durationMs: number;
+    /** Mean absolute error vs baseline scores (combined, normalized 0..10). */
+    meanAbsoluteError: number;
+    errors: string[];
+}
+export interface BenchOptions {
+    models: BenchModelConfig[];
+    sessions: SessionAggregate[];
+    baselines: BenchSampleBaseline[];
+}
+export declare function benchModels(opts: BenchOptions): Promise<BenchModelResult[]>;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE;QAChB,KAAK,EAAE,MAAM,GAAG;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;QACxD,QAAQ,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;KACtB,GAAG,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACnD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAoED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,eAAe,CAAC,CA6B1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,SAAS,EAAE,mBAAmB,EAAE,CAAC;CAClC;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiCjF"}

package/dist/analyze.js

@@ -0,0 +1,143 @@
+/**
+ * `analyzeWithLlm(session, opts)` — qualitative analysis of a session.
+ *
+ * Phase 2 (LLM-driven) is intentionally pluggable: callers inject the
+ * `mesh` (an `LlmMesh` instance from `@sentropic/llm-mesh`) and the
+ * `model` id. The core lib does not import `@sentropic/llm-mesh`
+ * directly so that consumers without a mesh can still use the rest of
+ * the library; the type is duck-typed below.
+ *
+ * Outputs a JSON verdict (`AnalysisVerdict`) with `frustration_level`
+ * and `out_of_control_score` (0-10), a short summary, and an optional
+ * list of root causes.
+ */
+import { createHash } from 'node:crypto';
+const PROMPT = `You are an analyst grading a coding-agent session.
+Read the JSON aggregate below and return a JSON verdict with EXACTLY this shape:
+{
+  "frustrationLevel": <integer 0..10>,
+  "outOfControlScore": <integer 0..10>,
+  "summary": "<one sentence>",
+  "rootCauses": ["<short cause>", ...]
+}
+Frustration: estimate user frustration from retries, compactions, error rates.
+Out-of-control: estimate AI loops, runaway sessions, tool flailing.
+Return ONLY the JSON, no prose, no markdown fence.`;
+function sessionFingerprint(session) {
+    const payload = JSON.stringify({
+        id: session.sessionId,
+        turns: session.turns,
+        tools: session.toolCalls,
+        cat: session.toolCallsByCategory,
+        comp: session.compactions,
+        cost: session.estimatedCost,
+        dur: session.durationMs,
+        rl: session.rateLimitMax,
+    });
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+function extractJson(text) {
+    // The mesh sometimes wraps output in ```json ... ```; strip it.
+    const fenced = text.match(/```(?:json)?\s*([\s\S]+?)\s*```/);
+    const raw = (fenced?.[1] ?? text).trim();
+    return JSON.parse(raw);
+}
+function clampScore(x) {
+    const n = typeof x === 'number' ? x : Number(x);
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(10, Math.round(n)));
+}
+function buildPayload(session) {
+    return JSON.stringify({
+        sessionId: session.sessionId,
+        tool: session.tool,
+        model: session.model,
+        durationMs: session.durationMs,
+        turns: session.turns,
+        isSubagent: session.isSubagent,
+        forkedFromId: session.forkedFromId ?? null,
+        toolCalls: session.toolCalls,
+        toolCallsByCategory: session.toolCallsByCategory,
+        compactions: session.compactions,
+        estimatedCost: session.estimatedCost,
+        rateLimitMax: session.rateLimitMax ?? null,
+        totalInputTokens: session.totalUsage.newInputTokens +
+            session.totalUsage.cachedInputTokens +
+            session.totalUsage.cacheWriteTokens,
+        outputTokens: session.totalUsage.outputTokens,
+        reasoningTokens: session.totalUsage.reasoningTokens,
+    }, null, 2);
+}
+/**
+ * Run the LLM analysis for a single session. Returns the verdict.
+ * On cache hit, the mesh is not called.
+ */
+export async function analyzeWithLlm(session, opts) {
+    const key = `${session.sessionId}|${opts.model}|${sessionFingerprint(session)}`;
+    if (opts.cache) {
+        const cached = await opts.cache.read(key);
+        if (cached)
+            return cached;
+    }
+    const payload = buildPayload(session);
+    const result = await opts.mesh.generate({
+        model: opts.model,
+        messages: [
+            { role: 'system', content: PROMPT },
+            { role: 'user', content: payload },
+        ],
+    });
+    const text = result.message?.content ?? result.text ?? '';
+    if (!text)
+        throw new Error('analyzeWithLlm: mesh returned empty response');
+    const parsed = extractJson(text);
+    const verdict = {
+        sessionId: session.sessionId,
+        model: opts.model,
+        frustrationLevel: clampScore(parsed['frustrationLevel']),
+        outOfControlScore: clampScore(parsed['outOfControlScore']),
+        summary: typeof parsed['summary'] === 'string' ? parsed['summary'] : '',
+        rootCauses: Array.isArray(parsed['rootCauses'])
+            ? parsed['rootCauses'].filter((s) => typeof s === 'string')
+            : [],
+    };
+    if (opts.cache)
+        await opts.cache.write(key, verdict);
+    return verdict;
+}
+export async function benchModels(opts) {
+    const baselineById = new Map(opts.baselines.map((b) => [b.sessionId, b]));
+    const results = [];
+    for (const cfg of opts.models) {
+        const errors = [];
+        let mae = 0;
+        let counted = 0;
+        const t0 = Date.now();
+        for (const s of opts.sessions) {
+            const base = baselineById.get(s.sessionId);
+            try {
+                const v = await analyzeWithLlm(s, { mesh: cfg.mesh, model: cfg.model });
+                if (base) {
+                    const e = (Math.abs(v.frustrationLevel - base.frustrationLevel) +
+                        Math.abs(v.outOfControlScore - base.outOfControlScore)) /
+                        2;
+                    mae += e;
+                    counted += 1;
+                }
+            }
+            catch (e) {
+                errors.push(`${s.sessionId}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        results.push({
+            model: cfg.model,
+            samples: counted,
+            durationMs: Date.now() - t0,
+            meanAbsoluteError: counted ? mae / counted : 0,
+            errors,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=analyze.js.map

package/dist/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAsCzC,MAAM,MAAM,GAAG;;;;;;;;;;mDAUoC,CAAC;AAEpD,SAAS,kBAAkB,CAAC,OAAyB;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,EAAE,EAAE,OAAO,CAAC,SAAS;QACrB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,SAAS;QACxB,GAAG,EAAE,OAAO,CAAC,mBAAmB;QAChC,IAAI,EAAE,OAAO,CAAC,WAAW;QACzB,IAAI,EAAE,OAAO,CAAC,aAAa;QAC3B,GAAG,EAAE,OAAO,CAAC,UAAU;QACvB,EAAE,EAAE,OAAO,CAAC,YAAY;KACzB,CAAC,CAAC;IACH,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,gEAAgE;IAChE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAC7D,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,UAAU,CAAC,CAAU;IAC5B,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,YAAY,CAAC,OAAyB;IAC7C,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI;QAC1C,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI;QAC1C,gBAAgB,EACd,OAAO,CAAC,UAAU,CAAC,cAAc;YACjC,OAAO,CAAC,UAAU,CAAC,iBAAiB;YACpC,OAAO,CAAC,UAAU,CAAC,gBAAgB;QACrC,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,YAAY;QAC7C,eAAe,EAAE,OAAO,CAAC,UAAU,CAAC,eAAe;KACpD,EACD,IAAI,EACJ,CAAC,CACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAyB,EACzB,IAAoB;IAEpB,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,IAAI,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;IAChF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;IAC5B,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;QACtC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE;YACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;YACnC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE;SACnC;KACF,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,IAAI,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;IAC1D,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAA4B,CAAC;IAC5D,MAAM,OAAO,GAAoB;QAC/B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,gBAAgB,EAAE,UAAU,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACxD,iBAAiB,EAAE,UAAU,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;QAC1D,OAAO,EAAE,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE;QACvE,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YAC7C,CAAC,CAAE,MAAM,CAAC,YAAY,CAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;YACvF,CAAC,CAAC,EAAE;KACP,CAAC;IACF,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC;AACjB,CAAC;AAmCD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAkB;IAClD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAU,CAAC,CAAC,CAAC;IACnF,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACtB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAC3C,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,MAAM,cAAc,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;gBACxE,IAAI,IAAI,EAAE,CAAC;oBACT,MAAM,CAAC,GACL,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC;wBACnD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;wBACzD,CAAC,CAAC;oBACJ,GAAG,IAAI,CAAC,CAAC;oBACT,OAAO,IAAI,CAAC,CAAC;gBACf,CAAC;YACH,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,SAAS,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC/E,CAAC;QACH,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;YACX,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,OAAO,EAAE,OAAO;YAChB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE;YAC3B,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YAC9C,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/anomalies.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Anomaly detection heuristics (no LLM).
+ *
+ * Operates on a stream of `SessionEvent`s and emits `Anomaly` records
+ * flagging sessions that exhibit known costly or stuck patterns:
+ *   - runaway_compactions : auto-compaction triggered N+ times in one session.
+ *   - high_error_rate     : tool error rate > threshold (min 10 calls).
+ *   - prompt_retry_loop   : same user prompt textHash repeated N+ times.
+ *   - tool_loop           : same tool name called N+ times consecutively.
+ *   - zombie_session      : > N minutes between consecutive turns.
+ *
+ * Frustration via user-prompt content is intentionally out of scope for
+ * WP5; the parser stores only prompt hashes (privacy). That heuristic
+ * is deferred to WP7 (LLM phase 2).
+ */
+import type { SessionEvent } from './schema.js';
+export type AnomalyType = 'runaway_compactions' | 'high_error_rate' | 'prompt_retry_loop' | 'tool_loop' | 'zombie_session';
+export type AnomalySeverity = 'low' | 'medium' | 'high';
+export interface Anomaly {
+    sessionId: string;
+    tool: 'claude' | 'codex';
+    projectCwd: string;
+    type: AnomalyType;
+    severity: AnomalySeverity;
+    /** Free-form, machine-readable evidence. */
+    evidence: Record<string, number | string>;
+}
+export interface DetectAnomaliesOptions {
+    runawayCompactions?: number;
+    errorRateThreshold?: number;
+    minToolCallsForErrorRate?: number;
+    promptRetryCount?: number;
+    toolLoopCount?: number;
+    zombieGapMinutes?: number;
+}
+export declare function detectAnomalies(events: AsyncIterable<SessionEvent> | Iterable<SessionEvent>, opts?: DetectAnomaliesOptions): Promise<Anomaly[]>;
+//# sourceMappingURL=anomalies.d.ts.map

package/dist/anomalies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anomalies.d.ts","sourceRoot":"","sources":["../src/anomalies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,MAAM,WAAW,GACnB,qBAAqB,GACrB,iBAAiB,GACjB,mBAAmB,GACnB,WAAW,GACX,gBAAgB,CAAC;AAErB,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,sBAAsB;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAsCD,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,EAC5D,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,OAAO,EAAE,CAAC,CAqJpB"}