@substrate-ai/core 0.19.54

package/dist/telemetry/normalizer.js

@@ -0,0 +1,320 @@
+/**
+ * TelemetryNormalizer — transforms raw OTLP payloads into normalized models.
+ *
+ * Accepts raw OTLP JSON objects (traces or logs) and returns arrays of
+ * `NormalizedSpan` or `NormalizedLog` objects suitable for downstream analysis.
+ *
+ * Design invariants:
+ *   - Never throws from public methods — returns empty array on any error
+ *   - Constructor injection of ILogger for testability
+ *   - No external dependencies beyond built-in Node.js and internal modules
+ */
+import { estimateCost } from './cost-table.js';
+import { normalizeTimestamp } from './timestamp-normalizer.js';
+import { extractTokensFromAttributes, extractTokensFromBody, mergeTokenCounts, } from './token-extractor.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract a string value from an OTLP attribute array by key.
+ */
+function getAttrString(attrs, key) {
+    if (!Array.isArray(attrs))
+        return undefined;
+    const entry = attrs.find((a) => a?.key === key);
+    if (!entry?.value)
+        return undefined;
+    return (entry.value.stringValue ??
+        (entry.value.intValue !== undefined ? String(entry.value.intValue) : undefined) ??
+        (entry.value.doubleValue !== undefined ? String(entry.value.doubleValue) : undefined));
+}
+/**
+ * Determine source from resource attributes service.name.
+ */
+function resolveSource(resourceAttrs) {
+    const serviceName = getAttrString(resourceAttrs, 'service.name');
+    if (!serviceName)
+        return 'unknown';
+    const lower = serviceName.toLowerCase();
+    if (lower.includes('claude'))
+        return 'claude-code';
+    if (lower.includes('codex') || lower.includes('openai'))
+        return 'codex';
+    if (lower.includes('local'))
+        return 'local-llm';
+    return serviceName;
+}
+/**
+ * Resolve model from span attributes (tries multiple known keys).
+ */
+function resolveModel(attrs) {
+    const modelKeys = [
+        'gen_ai.request.model',
+        'gen_ai.response.model',
+        'llm.request.model',
+        'anthropic.model',
+        'openai.model',
+        'model',
+    ];
+    for (const key of modelKeys) {
+        const val = getAttrString(attrs, key);
+        if (val)
+            return val;
+    }
+    return undefined;
+}
+/**
+ * Resolve provider from span attributes.
+ */
+function resolveProvider(attrs, source) {
+    const providerVal = getAttrString(attrs, 'gen_ai.system');
+    if (providerVal)
+        return providerVal;
+    if (source === 'claude-code')
+        return 'anthropic';
+    if (source === 'codex')
+        return 'openai';
+    return undefined;
+}
+/**
+ * Extract the body string from a log record body field.
+ */
+function extractBodyString(body) {
+    if (!body)
+        return undefined;
+    if (typeof body === 'string')
+        return body;
+    if (typeof body === 'object' && body.stringValue)
+        return body.stringValue;
+    return undefined;
+}
+/**
+ * Generate a unique log record ID.
+ */
+let _logIdCounter = 0;
+function generateLogId() {
+    return `log-${Date.now()}-${++_logIdCounter}`;
+}
+// ---------------------------------------------------------------------------
+// TelemetryNormalizer
+// ---------------------------------------------------------------------------
+/**
+ * Transforms raw OTLP payloads into normalized telemetry models.
+ *
+ * Inject an `ILogger` for structured logging.
+ * All public methods return empty arrays on any error — never throw.
+ */
+export class TelemetryNormalizer {
+    _logger;
+    constructor(logger) {
+        this._logger = logger;
+    }
+    // -------------------------------------------------------------------------
+    // normalizeSpan
+    // -------------------------------------------------------------------------
+    /**
+     * Normalize a raw OTLP trace payload into an array of `NormalizedSpan`.
+     *
+     * @param raw - Raw OTLP trace payload (resourceSpans structure)
+     * @returns Array of normalized spans; empty on error or empty input
+     */
+    normalizeSpan(raw) {
+        try {
+            return this._normalizeSpanInternal(raw);
+        }
+        catch (err) {
+            this._logger.warn({ err }, 'TelemetryNormalizer.normalizeSpan: unexpected error');
+            return [];
+        }
+    }
+    _normalizeSpanInternal(raw) {
+        if (!raw || typeof raw !== 'object')
+            return [];
+        const payload = raw;
+        if (!Array.isArray(payload.resourceSpans))
+            return [];
+        const results = [];
+        for (const resourceSpan of payload.resourceSpans) {
+            if (!resourceSpan)
+                continue;
+            const resourceAttrs = resourceSpan.resource?.attributes;
+            const source = resolveSource(resourceAttrs);
+            if (!Array.isArray(resourceSpan.scopeSpans))
+                continue;
+            for (const scopeSpan of resourceSpan.scopeSpans) {
+                if (!Array.isArray(scopeSpan?.spans))
+                    continue;
+                for (const span of scopeSpan.spans) {
+                    if (!span)
+                        continue;
+                    try {
+                        const normalized = this._normalizeOneSpan(span, resourceAttrs, source);
+                        results.push(normalized);
+                    }
+                    catch (err) {
+                        this._logger.warn({ err, spanId: span.spanId }, 'Failed to normalize span — skipping');
+                    }
+                }
+            }
+        }
+        return results;
+    }
+    _normalizeOneSpan(span, resourceAttrs, source) {
+        const spanId = span.spanId ?? '';
+        const traceId = span.traceId ?? '';
+        const name = span.name ?? '';
+        const model = resolveModel(span.attributes) ?? resolveModel(resourceAttrs);
+        const provider = resolveProvider(span.attributes, source);
+        const operationName = getAttrString(span.attributes, 'gen_ai.operation.name') ?? name;
+        // Timestamps
+        const startTime = normalizeTimestamp(span.startTimeUnixNano);
+        const endTime = span.endTimeUnixNano ? normalizeTimestamp(span.endTimeUnixNano) : undefined;
+        const durationMs = endTime !== undefined ? endTime - startTime : 0;
+        // Token extraction
+        const fromAttrs = extractTokensFromAttributes(span.attributes);
+        const bodyStr = getAttrString(span.attributes, 'llm.response.body') ??
+            getAttrString(span.attributes, 'gen_ai.response.body');
+        const fromBody = extractTokensFromBody(bodyStr);
+        const tokens = mergeTokenCounts(fromAttrs, fromBody);
+        // Story key
+        const storyKey = getAttrString(span.attributes, 'substrate.story_key') ??
+            getAttrString(resourceAttrs, 'substrate.story_key');
+        // Cost
+        const costUsd = model ? estimateCost(model, tokens) : 0;
+        // Flatten attributes to record
+        const attributesRecord = {};
+        if (Array.isArray(span.attributes)) {
+            for (const attr of span.attributes) {
+                if (attr?.key) {
+                    attributesRecord[attr.key] =
+                        attr.value?.stringValue ??
+                            attr.value?.intValue ??
+                            attr.value?.doubleValue ??
+                            attr.value?.boolValue;
+                }
+            }
+        }
+        return {
+            spanId,
+            traceId,
+            ...(span.parentSpanId !== undefined && { parentSpanId: span.parentSpanId }),
+            name,
+            source,
+            ...(model !== undefined && { model }),
+            ...(provider !== undefined && { provider }),
+            operationName,
+            ...(storyKey !== undefined && { storyKey }),
+            inputTokens: tokens.input,
+            outputTokens: tokens.output,
+            cacheReadTokens: tokens.cacheRead,
+            cacheCreationTokens: tokens.cacheCreation,
+            costUsd,
+            durationMs,
+            startTime,
+            ...(endTime !== undefined && { endTime }),
+            attributes: attributesRecord,
+            ...(span.events !== undefined && { events: span.events }),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // normalizeLog
+    // -------------------------------------------------------------------------
+    /**
+     * Normalize a raw OTLP log payload into an array of `NormalizedLog`.
+     *
+     * @param raw - Raw OTLP log payload (resourceLogs structure)
+     * @param dispatchContext - Optional dispatch context to stamp on each log (Story 30-1)
+     * @returns Array of normalized logs; empty on error or empty input
+     */
+    normalizeLog(raw, dispatchContext) {
+        try {
+            return this._normalizeLogInternal(raw, dispatchContext);
+        }
+        catch (err) {
+            this._logger.warn({ err }, 'TelemetryNormalizer.normalizeLog: unexpected error');
+            return [];
+        }
+    }
+    _normalizeLogInternal(raw, dispatchContext) {
+        if (!raw || typeof raw !== 'object')
+            return [];
+        const payload = raw;
+        if (!Array.isArray(payload.resourceLogs))
+            return [];
+        const results = [];
+        for (const resourceLog of payload.resourceLogs) {
+            if (!resourceLog)
+                continue;
+            const resourceAttrs = resourceLog.resource?.attributes;
+            if (!Array.isArray(resourceLog.scopeLogs))
+                continue;
+            for (const scopeLog of resourceLog.scopeLogs) {
+                if (!Array.isArray(scopeLog?.logRecords))
+                    continue;
+                for (const record of scopeLog.logRecords) {
+                    if (!record)
+                        continue;
+                    try {
+                        const normalized = this._normalizeOneLog(record, resourceAttrs, dispatchContext);
+                        results.push(normalized);
+                    }
+                    catch (err) {
+                        this._logger.warn({ err }, 'Failed to normalize log record — skipping');
+                    }
+                }
+            }
+        }
+        return results;
+    }
+    _normalizeOneLog(record, resourceAttrs, dispatchContext) {
+        const logId = record.logRecordId ?? generateLogId();
+        const timestamp = normalizeTimestamp(record.timeUnixNano);
+        const bodyStr = extractBodyString(record.body);
+        // Extract from attributes
+        const fromAttrs = extractTokensFromAttributes(record.attributes);
+        const fromBody = extractTokensFromBody(bodyStr);
+        const tokens = mergeTokenCounts(fromAttrs, fromBody);
+        // Event name
+        const eventName = getAttrString(record.attributes, 'event.name') ??
+            getAttrString(record.attributes, 'gen_ai.event.name') ??
+            getAttrString(record.attributes, 'event_name');
+        // Session id
+        const sessionId = getAttrString(record.attributes, 'session.id') ??
+            getAttrString(record.attributes, 'gen_ai.session.id') ??
+            getAttrString(resourceAttrs, 'session.id');
+        // Tool name
+        const toolName = getAttrString(record.attributes, 'tool.name') ??
+            getAttrString(record.attributes, 'gen_ai.tool.name') ??
+            getAttrString(record.attributes, 'tool_name');
+        // Model
+        const model = resolveModel(record.attributes) ?? resolveModel(resourceAttrs);
+        // Story key
+        const storyKey = getAttrString(record.attributes, 'substrate.story_key') ??
+            getAttrString(resourceAttrs, 'substrate.story_key');
+        // Cost
+        const costUsd = model ? estimateCost(model, tokens) : 0;
+        return {
+            logId,
+            ...(record.traceId !== undefined && { traceId: record.traceId }),
+            ...(record.spanId !== undefined && { spanId: record.spanId }),
+            timestamp,
+            ...(record.severityText !== undefined && { severity: record.severityText }),
+            ...(bodyStr !== undefined && { body: bodyStr }),
+            ...(eventName !== undefined && { eventName }),
+            ...(sessionId !== undefined && { sessionId }),
+            ...(toolName !== undefined && { toolName }),
+            inputTokens: tokens.input,
+            outputTokens: tokens.output,
+            cacheReadTokens: tokens.cacheRead,
+            costUsd,
+            ...(model !== undefined && { model }),
+            ...(storyKey !== undefined && { storyKey }),
+            ...(dispatchContext !== undefined && {
+                taskType: dispatchContext.taskType,
+                phase: dispatchContext.phase,
+                dispatchId: dispatchContext.dispatchId,
+            }),
+        };
+    }
+}
+//# sourceMappingURL=normalizer.js.map

package/dist/telemetry/normalizer.js.map

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

package/dist/telemetry/recommender.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Recommender — analyzes telemetry context and generates actionable recommendations.
+ *
+ * Implements 9 rules across three categories:
+ *   - Consumer rules: biggest_consumers, large_file_reads, expensive_bash, repeated_tool_calls
+ *   - Context/trend rules: context_growth_spike, growing_categories
+ *   - Efficiency rules: cache_efficiency, per_model_comparison, cache_delta_regression
+ *
+ * Architecture constraints:
+ *   - Pure analysis service — no DB access; caller assembles RecommenderContext
+ *   - Constructor injection: accepts ILogger (defaults to console)
+ *   - No Math.random() or Date.now() — all timestamps injected via context.generatedAt
+ *   - ID generation: sha256(ruleId:storyKey:actionTarget:index) via node:crypto
+ *
+ * Migrated to @substrate-ai/core in story 41-6b.
+ */
+import type { ILogger } from '../dispatch/types.js';
+import type { Recommendation, RecommenderContext, IRecommender } from './types.js';
+export declare class Recommender implements IRecommender {
+    private readonly _logger;
+    constructor(logger?: ILogger);
+    /**
+     * Run all rules against the given context and return sorted recommendations.
+     * Output is sorted: critical → warning → info, then by potentialSavingsTokens descending.
+     * No Date.now() or Math.random() is called — generatedAt comes from context.
+     */
+    analyze(context: RecommenderContext): Recommendation[];
+    /**
+     * Generate a 16-char hex ID from the sha256 of `ruleId:storyKey:actionTarget:index`.
+     */
+    private _makeId;
+    /**
+     * Map a token percentage to a severity level.
+     * >25% → critical, >10% → warning, ≤10% → info.
+     */
+    private _assignSeverity;
+    /**
+     * Compute total tokens across all spans. Guards against empty arrays.
+     */
+    private _totalSpanTokens;
+    /**
+     * Minimum absolute token count for a consumer to be flagged.
+     * Below this, the consumer is too small to be actionable regardless of percentage.
+     */
+    private static readonly MIN_SIGNIFICANT_TOKENS;
+    /**
+     * Identify top 3 token consumers (by inputTokens + outputTokens) where pct >5%
+     * AND absolute tokens exceed MIN_SIGNIFICANT_TOKENS.
+     *
+     * Filters out model-only consumers (empty toolName, format "model|") since those
+     * just indicate which model ran — not an actionable optimization target.
+     *
+     * Severity factors both percentage share and absolute magnitude:
+     *   - percentage-based tier via _assignSeverity()
+     *   - capped at 'warning' when absolute tokens < 50,000
+     *   - capped at 'info' when absolute tokens < 20,000
+     */
+    private _runBiggestConsumers;
+    /**
+     * Flag file-read spans with inputTokens > 3000.
+     * Suggest using line ranges to reduce token count.
+     */
+    private _runLargeFileReads;
+    /**
+     * Flag bash/execute_command spans with outputTokens > 3000.
+     * Suggest filtering or truncating command output.
+     */
+    private _runExpensiveBash;
+    /**
+     * Detect tool calls with the same actionTarget appearing more than once.
+     * Suggests caching the result to avoid redundant token consumption.
+     */
+    private _runRepeatedToolCalls;
+    /**
+     * Flag turns where isContextSpike is true.
+     * Severity is always at least 'warning'.
+     */
+    private _runContextGrowthSpikes;
+    /**
+     * Categories whose growth is inherent to normal agentic work and not actionable.
+     * tool_outputs grows as the agent reads files, runs commands, etc. — expected behavior.
+     * conversation_history grows naturally as conversations progress.
+     */
+    private static readonly EXPECTED_GROWTH_CATEGORIES;
+    /**
+     * Flag semantic categories with trend === 'growing'.
+     * Severity is 'info' by default; 'warning' if percentage > 25%.
+     * Skips categories whose growth is inherent to normal agentic work.
+     */
+    private _runGrowingCategories;
+    /**
+     * If cache hit rate < 30%, flag the worst-performing operations and compute
+     * potential savings as totalCacheMissTokens * 0.5.
+     */
+    private _runCacheEfficiency;
+    /**
+     * Models known to be intentionally routed for lightweight tasks.
+     * These should not be flagged as "underperforming" — the orchestrator chose them
+     * deliberately for cost/speed reasons, not as a performance optimization target.
+     */
+    private static readonly INTENTIONAL_LIGHTWEIGHT_MODELS;
+    /**
+     * If more than one model is present, flag the underperforming model.
+     * Severity is 'info' by default; 'warning' if cache efficiency gap > 20pp.
+     * Skips flagging models that are intentionally routed for lightweight tasks.
+     */
+    private _runModelComparison;
+    /**
+     * Detect significant cache hit rate drops between consecutive dispatches.
+     * >30pp drop → warning; >50pp drop → critical.
+     * Requires dispatchScores with at least 2 entries; otherwise returns [].
+     */
+    private _runCacheDeltaRegression;
+    private _isToolNameMatch;
+}
+//# sourceMappingURL=recommender.d.ts.map

package/dist/telemetry/recommender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommender.d.ts","sourceRoot":"","sources":["../../src/telemetry/recommender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,YAAY,EAKb,MAAM,YAAY,CAAA;AAMnB,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,CAAC,EAAE,OAAO;IAQ5B;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,EAAE;IAkCtD;;OAEG;IACH,OAAO,CAAC,OAAO;IAOf;;;OAGG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAEvD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,oBAAoB;IAiD5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA2CzB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAgE7B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IA0C/B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAGhD;IAEF;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAiC7B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA6D3B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,8BAA8B,CAGpD;IAEF;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IA0C3B;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAuChC,OAAO,CAAC,gBAAgB;CAWzB"}