@substrate-ai/core 0.19.54

package/dist/telemetry/consumer-analyzer.js

@@ -0,0 +1,182 @@
+/**
+ * ConsumerAnalyzer — groups telemetry spans by consumer key and ranks by token
+ * consumption, producing ConsumerStats for each unique operation+tool combination.
+ *
+ * A "consumer key" is `operationName|toolName`, stable across runs and safe to
+ * store as a VARCHAR(300) primary-key component in Dolt.
+ *
+ * Architecture constraints:
+ *   - Constructor injection: accepts Categorizer and ILogger (logger defaults to console)
+ *   - Delegates classification to the injected Categorizer
+ *   - Zero external dependencies beyond types and Categorizer from this module
+ *
+ * Migrated to @substrate-ai/core in story 41-6b.
+ */
+// ---------------------------------------------------------------------------
+// ConsumerAnalyzer
+// ---------------------------------------------------------------------------
+export class ConsumerAnalyzer {
+    _categorizer;
+    _logger;
+    constructor(categorizer, logger) {
+        this._categorizer = categorizer;
+        this._logger = logger ?? console;
+    }
+    // ---------------------------------------------------------------------------
+    // analyze
+    // ---------------------------------------------------------------------------
+    /**
+     * Group spans by consumer key, rank by totalTokens descending, and return
+     * ConsumerStats for each non-zero-token group.
+     *
+     * @param spans - All NormalizedSpans for the story
+     */
+    analyze(spans) {
+        if (spans.length === 0)
+            return [];
+        const grandTotal = spans.reduce((sum, s) => sum + s.inputTokens + s.outputTokens, 0);
+        // Group spans by consumerKey
+        const groups = new Map();
+        for (const span of spans) {
+            const key = this._buildConsumerKey(span);
+            const existing = groups.get(key);
+            if (existing !== undefined) {
+                existing.push(span);
+            }
+            else {
+                groups.set(key, [span]);
+            }
+        }
+        const results = [];
+        for (const [consumerKey, groupSpans] of groups) {
+            const totalTokens = groupSpans.reduce((sum, s) => sum + s.inputTokens + s.outputTokens, 0);
+            // Exclude zero-token groups
+            if (totalTokens === 0)
+                continue;
+            const percentage = grandTotal > 0 ? Math.round((totalTokens / grandTotal) * 100 * 1000) / 1000 : 0;
+            const eventCount = groupSpans.length;
+            // Determine category using the first span's operation + tool name
+            const firstSpan = groupSpans[0];
+            const toolName = this._extractToolName(firstSpan);
+            const operationName = firstSpan.operationName ?? firstSpan.name ?? 'unknown';
+            const category = this._categorizer.classify(operationName, toolName);
+            // Top 20 invocations sorted by totalTokens descending
+            const sorted = groupSpans
+                .slice()
+                .sort((a, b) => b.inputTokens + b.outputTokens - (a.inputTokens + a.outputTokens));
+            const topInvocations = sorted.slice(0, 20).map((s) => ({
+                spanId: s.spanId,
+                name: s.name,
+                toolName: this._extractToolName(s),
+                totalTokens: s.inputTokens + s.outputTokens,
+                inputTokens: s.inputTokens,
+                outputTokens: s.outputTokens,
+            }));
+            results.push({
+                consumerKey,
+                category,
+                totalTokens,
+                percentage,
+                eventCount,
+                topInvocations,
+            });
+        }
+        this._logger.debug({ consumers: results.length, grandTotal }, 'Computed consumer stats');
+        return results.sort((a, b) => b.totalTokens - a.totalTokens);
+    }
+    // ---------------------------------------------------------------------------
+    // analyzeFromTurns
+    // ---------------------------------------------------------------------------
+    /**
+     * Group turns by consumer key (model|toolName), rank by totalTokens descending,
+     * and return ConsumerStats for each non-zero-token group.
+     *
+     * @param turns - All TurnAnalysis records for the story
+     */
+    analyzeFromTurns(turns) {
+        if (turns.length === 0)
+            return [];
+        const grandTotal = turns.reduce((sum, t) => sum + t.inputTokens + t.outputTokens, 0);
+        // Group turns by consumerKey (model|toolName)
+        const groups = new Map();
+        for (const turn of turns) {
+            const key = this._buildConsumerKeyFromTurn(turn);
+            const existing = groups.get(key);
+            if (existing !== undefined) {
+                existing.push(turn);
+            }
+            else {
+                groups.set(key, [turn]);
+            }
+        }
+        const results = [];
+        for (const [consumerKey, groupTurns] of groups) {
+            const totalTokens = groupTurns.reduce((sum, t) => sum + t.inputTokens + t.outputTokens, 0);
+            // Exclude zero-token groups
+            if (totalTokens === 0)
+                continue;
+            const percentage = grandTotal > 0 ? Math.round((totalTokens / grandTotal) * 100 * 1000) / 1000 : 0;
+            const eventCount = groupTurns.length;
+            // Determine category using the first turn's name + toolName
+            const firstTurn = groupTurns[0];
+            const category = this._categorizer.classify(firstTurn.name, firstTurn.toolName);
+            // Top 20 invocations sorted by totalTokens descending
+            const sorted = groupTurns
+                .slice()
+                .sort((a, b) => b.inputTokens + b.outputTokens - (a.inputTokens + a.outputTokens));
+            const topInvocations = sorted.slice(0, 20).map((t) => ({
+                spanId: t.spanId,
+                name: t.name,
+                toolName: t.toolName,
+                totalTokens: t.inputTokens + t.outputTokens,
+                inputTokens: t.inputTokens,
+                outputTokens: t.outputTokens,
+            }));
+            results.push({
+                consumerKey,
+                category,
+                totalTokens,
+                percentage,
+                eventCount,
+                topInvocations,
+            });
+        }
+        this._logger.debug({ consumers: results.length, grandTotal }, 'Computed consumer stats from turns');
+        return results.sort((a, b) => b.totalTokens - a.totalTokens);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Build a stable, collision-resistant consumer key from a span.
+     * Format: `operationName|toolName` (tool part is empty string if absent).
+     */
+    _buildConsumerKey(span) {
+        const operationPart = (span.operationName ?? span.name ?? 'unknown').slice(0, 200);
+        const toolPart = (this._extractToolName(span) ?? '').slice(0, 100);
+        return `${operationPart}|${toolPart}`;
+    }
+    /**
+     * Build a stable consumer key from a turn.
+     * Format: `model|toolName` (tool part is empty string if absent).
+     */
+    _buildConsumerKeyFromTurn(turn) {
+        const modelPart = (turn.model ?? 'unknown').slice(0, 200);
+        const toolPart = (turn.toolName ?? '').slice(0, 100);
+        return `${modelPart}|${toolPart}`;
+    }
+    /**
+     * Extract a tool name from span attributes, checking three known attribute keys
+     * in priority order.
+     */
+    _extractToolName(span) {
+        if (!span.attributes)
+            return undefined;
+        const attrs = span.attributes;
+        const name = attrs['tool.name'] ||
+            attrs['llm.tool.name'] ||
+            attrs['claude.tool_name'];
+        return name || undefined;
+    }
+}
+//# sourceMappingURL=consumer-analyzer.js.map

package/dist/telemetry/consumer-analyzer.js.map

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

package/dist/telemetry/cost-table.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Cost table for LLM model pricing.
+ *
+ * Provides per-million-token rates for known models and an `estimateCost()`
+ * function that computes cost from a TokenCounts object.
+ *
+ * Cache reads use the explicit `cacheReadPerMToken` from the table (already
+ * pre-discounted to 10% of input rate for Anthropic models).
+ *
+ * Returns 0 for unknown models without throwing.
+ */
+import type { TokenCounts, ModelPricing } from './types.js';
+/**
+ * Per-million-token pricing for known LLM models.
+ * All prices are in USD.
+ */
+export declare const COST_TABLE: Record<string, ModelPricing>;
+/**
+ * Resolve a model string to a key in COST_TABLE.
+ * Returns the matched key, or undefined if not found.
+ *
+ * Performs exact match first, then case-insensitive substring match.
+ */
+export declare function resolveModel(model: string): string | undefined;
+/**
+ * Estimate the cost in USD for a set of token counts and a model identifier.
+ *
+ * - Uses `cacheReadPerMToken` from the table directly (already discounted).
+ * - Returns 0 for unknown models without throwing.
+ *
+ * @param model - Model identifier string (exact or fuzzy match against COST_TABLE)
+ * @param tokens - Token counts object
+ * @returns Estimated cost in USD
+ */
+export declare function estimateCost(model: string, tokens: TokenCounts): number;
+//# sourceMappingURL=cost-table.d.ts.map

package/dist/telemetry/cost-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-table.d.ts","sourceRoot":"","sources":["../../src/telemetry/cost-table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAM3D;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAiDnD,CAAA;AAMD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsB9D;AAMD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAkBvE"}

package/dist/telemetry/cost-table.js

@@ -0,0 +1,127 @@
+/**
+ * Cost table for LLM model pricing.
+ *
+ * Provides per-million-token rates for known models and an `estimateCost()`
+ * function that computes cost from a TokenCounts object.
+ *
+ * Cache reads use the explicit `cacheReadPerMToken` from the table (already
+ * pre-discounted to 10% of input rate for Anthropic models).
+ *
+ * Returns 0 for unknown models without throwing.
+ */
+// ---------------------------------------------------------------------------
+// COST_TABLE
+// ---------------------------------------------------------------------------
+/**
+ * Per-million-token pricing for known LLM models.
+ * All prices are in USD.
+ */
+export const COST_TABLE = {
+    'claude-3-opus-20240229': {
+        inputPerMToken: 15.0,
+        outputPerMToken: 75.0,
+        cacheReadPerMToken: 1.5,
+        cacheCreationPerMToken: 18.75,
+    },
+    'claude-3-5-sonnet-20241022': {
+        inputPerMToken: 3.0,
+        outputPerMToken: 15.0,
+        cacheReadPerMToken: 0.3,
+        cacheCreationPerMToken: 3.75,
+    },
+    'claude-3-5-haiku-20241022': {
+        inputPerMToken: 0.8,
+        outputPerMToken: 4.0,
+        cacheReadPerMToken: 0.08,
+        cacheCreationPerMToken: 1.0,
+    },
+    'claude-3-haiku-20240307': {
+        inputPerMToken: 0.25,
+        outputPerMToken: 1.25,
+        cacheReadPerMToken: 0.03,
+        cacheCreationPerMToken: 0.3,
+    },
+    'claude-3-sonnet-20240229': {
+        inputPerMToken: 3.0,
+        outputPerMToken: 15.0,
+        cacheReadPerMToken: 0.3,
+        cacheCreationPerMToken: 3.75,
+    },
+    'gpt-4': {
+        inputPerMToken: 30.0,
+        outputPerMToken: 60.0,
+        cacheReadPerMToken: 3.0,
+        cacheCreationPerMToken: 30.0,
+    },
+    'gpt-4-turbo': {
+        inputPerMToken: 10.0,
+        outputPerMToken: 30.0,
+        cacheReadPerMToken: 1.0,
+        cacheCreationPerMToken: 10.0,
+    },
+    'gpt-3.5-turbo': {
+        inputPerMToken: 0.5,
+        outputPerMToken: 1.5,
+        cacheReadPerMToken: 0.05,
+        cacheCreationPerMToken: 0.5,
+    },
+};
+// ---------------------------------------------------------------------------
+// resolveModel
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a model string to a key in COST_TABLE.
+ * Returns the matched key, or undefined if not found.
+ *
+ * Performs exact match first, then case-insensitive substring match.
+ */
+export function resolveModel(model) {
+    // Exact match
+    if (model in COST_TABLE) {
+        return model;
+    }
+    // Case-insensitive exact match
+    const lower = model.toLowerCase();
+    for (const key of Object.keys(COST_TABLE)) {
+        if (key.toLowerCase() === lower) {
+            return key;
+        }
+    }
+    // Substring match (model string contains the key or key contains the model string)
+    for (const key of Object.keys(COST_TABLE)) {
+        if (lower.includes(key.toLowerCase()) || key.toLowerCase().includes(lower)) {
+            return key;
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// estimateCost
+// ---------------------------------------------------------------------------
+/**
+ * Estimate the cost in USD for a set of token counts and a model identifier.
+ *
+ * - Uses `cacheReadPerMToken` from the table directly (already discounted).
+ * - Returns 0 for unknown models without throwing.
+ *
+ * @param model - Model identifier string (exact or fuzzy match against COST_TABLE)
+ * @param tokens - Token counts object
+ * @returns Estimated cost in USD
+ */
+export function estimateCost(model, tokens) {
+    const resolvedKey = resolveModel(model);
+    if (resolvedKey === undefined) {
+        return 0;
+    }
+    const pricing = COST_TABLE[resolvedKey];
+    if (pricing === undefined) {
+        return 0;
+    }
+    const perM = 1_000_000;
+    const inputCost = (tokens.input / perM) * pricing.inputPerMToken;
+    const outputCost = (tokens.output / perM) * pricing.outputPerMToken;
+    const cacheReadCost = (tokens.cacheRead / perM) * pricing.cacheReadPerMToken;
+    const cacheCreationCost = (tokens.cacheCreation / perM) * pricing.cacheCreationPerMToken;
+    return inputCost + outputCost + cacheReadCost + cacheCreationCost;
+}
+//# sourceMappingURL=cost-table.js.map

package/dist/telemetry/cost-table.js.map

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

package/dist/telemetry/efficiency-scorer.d.ts

@@ -0,0 +1,103 @@
+/**
+ * EfficiencyScorer — computes composite 0-100 efficiency scores for story runs.
+ *
+ * The composite score combines four sub-scores (Epic 35 — Telemetry Scoring v2):
+ *   - cacheHitSubScore        (weight 25%): how well the story leverages prompt caching
+ *   - ioRatioSubScore         (weight 25%): logarithmic output/freshInput productivity curve
+ *   - contextManagement       (weight 25%): frequency of context spikes
+ *   - tokenDensitySubScore    (weight 25%): output tokens per turn vs task-type baseline
+ *
+ * Cold-start turns (first turn per dispatch) are excluded from sub-score
+ * computation but included in totalTurns for observability (Story 35-3).
+ *
+ * Architecture constraints:
+ *   - Constructor injection: accepts ILogger via constructor (defaults to console)
+ *   - Zero LLM calls — pure statistical computation
+ *   - No external dependencies beyond types from this module
+ *
+ * Migrated to @substrate-ai/core in story 41-6b.
+ */
+import type { ILogger } from '../dispatch/types.js';
+import type { TurnAnalysis, EfficiencyScore } from './types.js';
+import type { IEfficiencyScorer } from './telemetry-pipeline.js';
+export declare class EfficiencyScorer implements IEfficiencyScorer {
+    private readonly _logger;
+    constructor(logger?: ILogger);
+    /**
+     * Compute an efficiency score for a story given its turn analyses.
+     *
+     * Returns a zeroed `EfficiencyScore` immediately when `turns` is empty.
+     *
+     * @param storyKey - The story identifier (e.g. "27-6")
+     * @param turns    - Turn analysis records from `TurnAnalyzer.analyze()`
+     */
+    score(storyKey: string, turns: TurnAnalysis[]): EfficiencyScore;
+    /**
+     * Identify cold-start turns: the first turn per dispatchId.
+     * Returns a set of spanIds that should be excluded from scoring.
+     * Only considers turns with a non-empty dispatchId.
+     */
+    private _identifyColdStartTurns;
+    /**
+     * Infer the task type from turns. Returns the task type only when all turns
+     * with a taskType agree (unanimous). For mixed task types (story-level
+     * scoring across dispatches), returns undefined → default baseline.
+     */
+    private _inferTaskType;
+    /**
+     * Average cache hit rate across all turns, clamped to [0, 100].
+     * Formula: clamp(avgCacheHitRate × 100, 0, 100)
+     */
+    private _computeCacheHitSubScore;
+    /**
+     * I/O ratio sub-score: logarithmic output/freshInput productivity curve (Story 35-1).
+     *
+     * Replaces the old binary threshold (>=1 → 100) with a logarithmic curve
+     * that provides gradient across the observed range:
+     *   - score = clamp(log10(ratio) / log10(targetRatio) * 100, 0, 100)
+     *   - ratio = avg(outputTokens / max(freshInputTokens, 1)) across turns
+     *   - targetRatio is calibrated per task type (Story 35-2)
+     *
+     * Examples (TARGET=100): ratio 1→0, 10→50, 50→85, 100→100, 200→100(clamped)
+     */
+    private _computeIoRatioSubScore;
+    /**
+     * Context management sub-score: penalizes context spike frequency.
+     * Formula: clamp(100 - spikeRatio × 100, 0, 100)
+     * where spikeRatio = contextSpikeCount / max(totalTurns, 1)
+     */
+    private _computeContextManagementSubScore;
+    /**
+     * Token density sub-score: output tokens per turn vs task-type baseline (Story 35-4).
+     *
+     * Measures whether the agent is producing useful output or spinning:
+     *   - score = clamp(avgOutputPerTurn / expectedOutputPerTurn * 100, 0, 100)
+     *   - expectedOutputPerTurn is calibrated per task type (Story 35-2)
+     *
+     * Below-baseline dispatches get proportionally lower scores.
+     * At-or-above-baseline dispatches score 100.
+     */
+    private _computeTokenDensitySubScore;
+    private _computeAvgCacheHitRate;
+    /**
+     * Average I/O ratio: totalInput / max(outputTokens, 1) per turn.
+     * Total input = inputTokens (fresh) + cacheReadTokens (cached).
+     */
+    private _computeAvgIoRatio;
+    /**
+     * Group turns by model, computing per-group efficiency metrics.
+     * Turns with null/undefined model are grouped under "unknown".
+     */
+    private _buildPerModelBreakdown;
+    /**
+     * Group turns by source, computing a per-group composite score using the
+     * same formula as the overall score. Sources with zero turns are excluded.
+     */
+    private _buildPerSourceBreakdown;
+    private _clamp;
+}
+/**
+ * Create an EfficiencyScorer with the given logger.
+ */
+export declare function createEfficiencyScorer(logger?: ILogger): EfficiencyScorer;
+//# sourceMappingURL=efficiency-scorer.d.ts.map

package/dist/telemetry/efficiency-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"efficiency-scorer.d.ts","sourceRoot":"","sources":["../../src/telemetry/efficiency-scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAqC,MAAM,YAAY,CAAA;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAahE,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,CAAC,EAAE,OAAO;IAQ5B;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,eAAe;IAoF/D;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAmB/B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IActB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAKhC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;;;OAIG;IACH,OAAO,CAAC,iCAAiC;IAOzC;;;;;;;;;OASG;IACH,OAAO,CAAC,4BAA4B;IAWpC,OAAO,CAAC,uBAAuB;IAM/B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAwC/B;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IA4ChC,OAAO,CAAC,MAAM;CAGf;AAMD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEzE"}