@substrate-ai/core 0.19.54

package/dist/telemetry/timestamp-normalizer.js

@@ -0,0 +1,133 @@
+/**
+ * Timestamp normalization for OTLP telemetry payloads.
+ *
+ * OTLP payloads use nanosecond integers for timestamps (e.g. `startTimeUnixNano`).
+ * Claude Code and other providers may emit timestamps in various formats.
+ *
+ * `normalizeTimestamp()` accepts any unknown value and returns a Unix millisecond
+ * number. Null/undefined/unparseable inputs fall back to `Date.now()`.
+ *
+ * Detection order (after ISO string check):
+ *   1. Nanoseconds  (>= 1e18)
+ *   2. Microseconds (>= 1e15)
+ *   3. Milliseconds (>= 1e12)
+ *   4. Seconds      (< 1e12)
+ */
+// ---------------------------------------------------------------------------
+// normalizeTimestamp
+// ---------------------------------------------------------------------------
+/**
+ * Normalize any timestamp value to Unix milliseconds.
+ *
+ * Handles:
+ *   - ISO 8601 strings (e.g. "2024-03-08T12:00:00Z")
+ *   - Nanosecond integers or numeric strings (>= 1e18)
+ *   - Microsecond integers or numeric strings (>= 1e15)
+ *   - Millisecond integers or numeric strings (>= 1e12)
+ *   - Second integers or numeric strings (< 1e12)
+ *   - BigInt string values from OTLP `startTimeUnixNano` (e.g. "1709900000000000000")
+ *   - null / undefined / unparseable → falls back to Date.now()
+ *
+ * @param value - Raw timestamp value of unknown type
+ * @returns Unix millisecond timestamp
+ */
+export function normalizeTimestamp(value) {
+    if (value === null || value === undefined) {
+        return Date.now();
+    }
+    // ISO 8601 string
+    if (typeof value === 'string') {
+        // Try ISO 8601 date string first (contains non-digit characters beyond just digits)
+        if (isIsoDateString(value)) {
+            const parsed = Date.parse(value);
+            if (!isNaN(parsed)) {
+                return parsed;
+            }
+        }
+        // Numeric string (potentially bigint nanosecond from OTLP)
+        // Use BigInt for large nanosecond values to avoid floating point precision loss
+        const trimmed = value.trim();
+        if (/^\d+$/.test(trimmed)) {
+            try {
+                const big = BigInt(trimmed);
+                return bigIntToMillis(big);
+            }
+            catch {
+                // fall through
+            }
+        }
+        return Date.now();
+    }
+    // BigInt
+    if (typeof value === 'bigint') {
+        return bigIntToMillis(value);
+    }
+    // Number
+    if (typeof value === 'number') {
+        if (!isFinite(value) || isNaN(value)) {
+            return Date.now();
+        }
+        return numericToMillis(value);
+    }
+    return Date.now();
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if the string looks like an ISO 8601 date string
+ * (contains letters or dashes/colons in date-like positions).
+ */
+function isIsoDateString(value) {
+    // Quick check: contains 'T' or '-' in date-like format, or ends with 'Z'
+    return (/^\d{4}-\d{2}-\d{2}/.test(value) ||
+        /Z$/.test(value) ||
+        /[+-]\d{2}:\d{2}$/.test(value) ||
+        value.includes('T'));
+}
+/**
+ * Convert a BigInt nanosecond/microsecond/millisecond/second value to milliseconds.
+ */
+function bigIntToMillis(value) {
+    const NS_THRESHOLD = BigInt('1000000000000000000'); // 1e18
+    const US_THRESHOLD = BigInt('1000000000000000'); // 1e15
+    const MS_THRESHOLD = BigInt('1000000000000'); // 1e12
+    if (value >= NS_THRESHOLD) {
+        // Nanoseconds → milliseconds
+        return Number(value / BigInt(1_000_000));
+    }
+    else if (value >= US_THRESHOLD) {
+        // Microseconds → milliseconds
+        return Number(value / BigInt(1_000));
+    }
+    else if (value >= MS_THRESHOLD) {
+        // Already milliseconds
+        return Number(value);
+    }
+    else {
+        // Seconds → milliseconds
+        return Number(value) * 1_000;
+    }
+}
+/**
+ * Convert a numeric value to milliseconds based on magnitude.
+ */
+function numericToMillis(value) {
+    if (value >= 1e18) {
+        // Nanoseconds
+        return Math.floor(value / 1_000_000);
+    }
+    else if (value >= 1e15) {
+        // Microseconds
+        return Math.floor(value / 1_000);
+    }
+    else if (value >= 1e12) {
+        // Milliseconds
+        return Math.floor(value);
+    }
+    else {
+        // Seconds
+        return Math.floor(value * 1_000);
+    }
+}
+//# sourceMappingURL=timestamp-normalizer.js.map

package/dist/telemetry/timestamp-normalizer.js.map

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

package/dist/telemetry/token-extractor.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Token extraction from OTLP span/log attributes and body JSON.
+ *
+ * OTLP payloads from different LLM providers use varying attribute naming
+ * conventions for token counts. This module provides fuzzy extraction via
+ * case-insensitive substring pattern matching.
+ *
+ * Priority: attributes take precedence over body for each field.
+ * Body fallback: parses JSON and recursively searches up to depth 4.
+ */
+import type { TokenCounts } from './types.js';
+/**
+ * A single OTLP attribute entry.
+ */
+interface OtlpAttributeValue {
+    stringValue?: string;
+    intValue?: string | number;
+    doubleValue?: string | number;
+    boolValue?: boolean;
+}
+interface OtlpAttribute {
+    key: string;
+    value: OtlpAttributeValue;
+}
+/**
+ * Extract token counts from an OTLP attributes array.
+ *
+ * Matches attribute keys case-insensitively against known patterns.
+ * The first matching value for each field wins.
+ *
+ * @param attributes - Array of OTLP attribute entries
+ * @returns Partial token counts (only fields found in attributes)
+ */
+export declare function extractTokensFromAttributes(attributes: OtlpAttribute[] | undefined | null): Partial<TokenCounts>;
+/**
+ * Extract token counts from a JSON body string via recursive search.
+ *
+ * Parses the body as JSON and recursively walks the object tree up to
+ * depth 4, looking for keys matching token patterns.
+ *
+ * @param body - Raw body string (may be JSON)
+ * @returns Partial token counts found in body
+ */
+export declare function extractTokensFromBody(body: string | undefined | null): Partial<TokenCounts>;
+/**
+ * Merge attribute-derived and body-derived token counts.
+ *
+ * Attributes take priority over body for each field.
+ * Missing fields default to 0.
+ *
+ * @param fromAttributes - Token counts from attributes (higher priority)
+ * @param fromBody - Token counts from body JSON (lower priority)
+ * @returns Complete TokenCounts with all fields
+ */
+export declare function mergeTokenCounts(fromAttributes: Partial<TokenCounts>, fromBody: Partial<TokenCounts>): TokenCounts;
+export {};
+//# sourceMappingURL=token-extractor.d.ts.map

package/dist/telemetry/token-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-extractor.d.ts","sourceRoot":"","sources":["../../src/telemetry/token-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAM7C;;GAEG;AACH,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,kBAAkB,CAAA;CAC1B;AAwBD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,aAAa,EAAE,GAAG,SAAS,GAAG,IAAI,GAC7C,OAAO,CAAC,WAAW,CAAC,CAmCtB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAa3F;AAMD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,OAAO,CAAC,WAAW,CAAC,EACpC,QAAQ,EAAE,OAAO,CAAC,WAAW,CAAC,GAC7B,WAAW,CAOb"}

package/dist/telemetry/token-extractor.js

@@ -0,0 +1,200 @@
+/**
+ * Token extraction from OTLP span/log attributes and body JSON.
+ *
+ * OTLP payloads from different LLM providers use varying attribute naming
+ * conventions for token counts. This module provides fuzzy extraction via
+ * case-insensitive substring pattern matching.
+ *
+ * Priority: attributes take precedence over body for each field.
+ * Body fallback: parses JSON and recursively searches up to depth 4.
+ */
+// ---------------------------------------------------------------------------
+// Pattern definitions
+// ---------------------------------------------------------------------------
+/**
+ * Patterns for matching attribute keys to token fields.
+ * Each pattern is checked case-insensitively via substring match.
+ *
+ * IMPORTANT: more-specific patterns (cacheRead, cacheCreation) MUST come first
+ * so that keys like `cache_read_input_tokens` match `cache_read` before `input_token`.
+ */
+const TOKEN_PATTERNS = {
+    cacheRead: ['cache_read'],
+    cacheCreation: ['cache_creation', 'cache_write'],
+    input: ['input_token', 'prompt_token'],
+    output: ['output_token', 'completion_token'],
+};
+// ---------------------------------------------------------------------------
+// extractTokensFromAttributes
+// ---------------------------------------------------------------------------
+/**
+ * Extract token counts from an OTLP attributes array.
+ *
+ * Matches attribute keys case-insensitively against known patterns.
+ * The first matching value for each field wins.
+ *
+ * @param attributes - Array of OTLP attribute entries
+ * @returns Partial token counts (only fields found in attributes)
+ */
+export function extractTokensFromAttributes(attributes) {
+    if (!Array.isArray(attributes) || attributes.length === 0) {
+        return {};
+    }
+    const result = {};
+    for (const attr of attributes) {
+        if (!attr?.key || !attr?.value)
+            continue;
+        const keyLower = attr.key.toLowerCase();
+        const numValue = resolveAttrValue(attr.value);
+        if (numValue === undefined)
+            continue;
+        // Each attribute maps to at most ONE field (first match in priority order wins).
+        // cacheRead/cacheCreation patterns are checked before input/output so that
+        // keys like `cache_read_input_tokens` do NOT also match `input_token`.
+        let matched = false;
+        for (const [field, patterns] of Object.entries(TOKEN_PATTERNS)) {
+            if (matched)
+                break;
+            if (result[field] !== undefined)
+                continue;
+            for (const pattern of patterns) {
+                if (keyLower.includes(pattern)) {
+                    ;
+                    result[field] = numValue;
+                    matched = true;
+                    break;
+                }
+            }
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// extractTokensFromBody
+// ---------------------------------------------------------------------------
+/**
+ * Extract token counts from a JSON body string via recursive search.
+ *
+ * Parses the body as JSON and recursively walks the object tree up to
+ * depth 4, looking for keys matching token patterns.
+ *
+ * @param body - Raw body string (may be JSON)
+ * @returns Partial token counts found in body
+ */
+export function extractTokensFromBody(body) {
+    if (!body || typeof body !== 'string') {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+    return searchObjectForTokens(parsed, 0);
+}
+// ---------------------------------------------------------------------------
+// mergeTokenCounts
+// ---------------------------------------------------------------------------
+/**
+ * Merge attribute-derived and body-derived token counts.
+ *
+ * Attributes take priority over body for each field.
+ * Missing fields default to 0.
+ *
+ * @param fromAttributes - Token counts from attributes (higher priority)
+ * @param fromBody - Token counts from body JSON (lower priority)
+ * @returns Complete TokenCounts with all fields
+ */
+export function mergeTokenCounts(fromAttributes, fromBody) {
+    return {
+        input: fromAttributes.input ?? fromBody.input ?? 0,
+        output: fromAttributes.output ?? fromBody.output ?? 0,
+        cacheRead: fromAttributes.cacheRead ?? fromBody.cacheRead ?? 0,
+        cacheCreation: fromAttributes.cacheCreation ?? fromBody.cacheCreation ?? 0,
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an OTLP attribute value to a number.
+ * OTLP integer values arrive as strings (e.g. `"intValue": "2048"`).
+ */
+function resolveAttrValue(value) {
+    if (value.intValue !== undefined) {
+        const n = Number(value.intValue);
+        return isFinite(n) ? n : undefined;
+    }
+    if (value.doubleValue !== undefined) {
+        const n = Number(value.doubleValue);
+        return isFinite(n) ? n : undefined;
+    }
+    if (value.stringValue !== undefined) {
+        const n = Number(value.stringValue);
+        if (!isNaN(n) && isFinite(n))
+            return n;
+    }
+    return undefined;
+}
+/**
+ * Recursively search an object for token count fields up to maxDepth.
+ */
+function searchObjectForTokens(obj, depth) {
+    if (depth >= 4 || obj === null || typeof obj !== 'object') {
+        return {};
+    }
+    const result = {};
+    if (Array.isArray(obj)) {
+        for (const item of obj) {
+            const found = searchObjectForTokens(item, depth + 1);
+            mergePartialInto(result, found);
+        }
+        return result;
+    }
+    const record = obj;
+    for (const [key, val] of Object.entries(record)) {
+        const keyLower = key.toLowerCase();
+        // Check if this key matches a token pattern.
+        // Each key maps to at most ONE field (first match in priority order wins).
+        let keyMatched = false;
+        for (const [field, patterns] of Object.entries(TOKEN_PATTERNS)) {
+            if (keyMatched)
+                break;
+            if (result[field] !== undefined)
+                continue;
+            for (const pattern of patterns) {
+                if (keyLower.includes(pattern)) {
+                    const num = typeof val === 'number' ? val : typeof val === 'string' ? Number(val) : NaN;
+                    if (!isNaN(num) && isFinite(num)) {
+                        ;
+                        result[field] = num;
+                    }
+                    keyMatched = true;
+                    break;
+                }
+            }
+        }
+        // Recurse into nested objects
+        if (val !== null && typeof val === 'object') {
+            const nested = searchObjectForTokens(val, depth + 1);
+            mergePartialInto(result, nested);
+        }
+    }
+    return result;
+}
+/**
+ * Merge source into target, only filling missing fields.
+ */
+function mergePartialInto(target, source) {
+    if (target.input === undefined && source.input !== undefined)
+        target.input = source.input;
+    if (target.output === undefined && source.output !== undefined)
+        target.output = source.output;
+    if (target.cacheRead === undefined && source.cacheRead !== undefined)
+        target.cacheRead = source.cacheRead;
+    if (target.cacheCreation === undefined && source.cacheCreation !== undefined)
+        target.cacheCreation = source.cacheCreation;
+}
+//# sourceMappingURL=token-extractor.js.map

package/dist/telemetry/token-extractor.js.map

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

package/dist/telemetry/turn-analyzer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TurnAnalyzer — computes per-turn token breakdowns from normalized spans.
+ *
+ * Takes a list of NormalizedSpan records and produces TurnAnalysis[], where
+ * each entry represents a root-level span (an agent "turn") with:
+ *   - Chronological ordering (by startTime)
+ *   - Sequential turnNumber assignment (1-N)
+ *   - freshTokens, cacheHitRate, contextSize, contextDelta metrics
+ *   - childSpans drill-down (tool calls within the turn)
+ *   - isContextSpike detection (inputTokens > 2× average)
+ *
+ * Architecture constraints:
+ *   - Constructor injection: accepts ILogger via constructor (defaults to console)
+ *   - No external dependencies beyond types from this module
+ *   - Zero LLM calls — pure statistical computation
+ *
+ * Migrated to @substrate-ai/core in story 41-6b.
+ */
+import type { ILogger } from '../dispatch/types.js';
+import type { NormalizedSpan, TurnAnalysis } from './types.js';
+import type { ITurnAnalyzer } from './telemetry-pipeline.js';
+export declare class TurnAnalyzer implements ITurnAnalyzer {
+    private readonly _logger;
+    constructor(logger?: ILogger);
+    /**
+     * Analyze a list of NormalizedSpan records and produce TurnAnalysis[].
+     *
+     * Returns an empty array immediately when spans is empty.
+     *
+     * @param spans - All spans for a story (root and child spans mixed)
+     */
+    analyze(spans: NormalizedSpan[]): TurnAnalysis[];
+}
+//# sourceMappingURL=turn-analyzer.d.ts.map

package/dist/telemetry/turn-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-analyzer.d.ts","sourceRoot":"","sources":["../../src/telemetry/turn-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAoB,MAAM,YAAY,CAAA;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAM5D,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,CAAC,EAAE,OAAO;IAQ5B;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,YAAY,EAAE;CA4EjD"}

package/dist/telemetry/turn-analyzer.js

@@ -0,0 +1,101 @@
+/**
+ * TurnAnalyzer — computes per-turn token breakdowns from normalized spans.
+ *
+ * Takes a list of NormalizedSpan records and produces TurnAnalysis[], where
+ * each entry represents a root-level span (an agent "turn") with:
+ *   - Chronological ordering (by startTime)
+ *   - Sequential turnNumber assignment (1-N)
+ *   - freshTokens, cacheHitRate, contextSize, contextDelta metrics
+ *   - childSpans drill-down (tool calls within the turn)
+ *   - isContextSpike detection (inputTokens > 2× average)
+ *
+ * Architecture constraints:
+ *   - Constructor injection: accepts ILogger via constructor (defaults to console)
+ *   - No external dependencies beyond types from this module
+ *   - Zero LLM calls — pure statistical computation
+ *
+ * Migrated to @substrate-ai/core in story 41-6b.
+ */
+// ---------------------------------------------------------------------------
+// TurnAnalyzer
+// ---------------------------------------------------------------------------
+export class TurnAnalyzer {
+    _logger;
+    constructor(logger) {
+        this._logger = logger ?? console;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Analyze a list of NormalizedSpan records and produce TurnAnalysis[].
+     *
+     * Returns an empty array immediately when spans is empty.
+     *
+     * @param spans - All spans for a story (root and child spans mixed)
+     */
+    analyze(spans) {
+        if (spans.length === 0) {
+            return [];
+        }
+        // Build set of all spanIds for root-span identification
+        const allSpanIds = new Set(spans.map((s) => s.spanId));
+        // Separate root spans from child spans
+        const rootSpans = spans.filter((s) => !s.parentSpanId || !allSpanIds.has(s.parentSpanId));
+        // Sort root spans chronologically
+        const ordered = [...rootSpans].sort((a, b) => a.startTime - b.startTime);
+        // Build child span index: parentSpanId → child spans
+        const childIndex = new Map();
+        for (const span of spans) {
+            if (span.parentSpanId && allSpanIds.has(span.parentSpanId)) {
+                const children = childIndex.get(span.parentSpanId) ?? [];
+                children.push(span);
+                childIndex.set(span.parentSpanId, children);
+            }
+        }
+        // First pass: build turns with metrics (context accumulation)
+        let runningContext = 0;
+        const turns = ordered.map((span, idx) => {
+            const prevContext = runningContext;
+            runningContext += span.inputTokens;
+            const freshTokens = span.inputTokens - span.cacheReadTokens;
+            const cacheHitRate = span.inputTokens > 0 ? span.cacheReadTokens / span.inputTokens : 0;
+            const childSpanSummaries = (childIndex.get(span.spanId) ?? []).map((child) => ({
+                spanId: child.spanId,
+                name: child.name,
+                toolName: child.attributes?.['tool.name'],
+                inputTokens: child.inputTokens,
+                outputTokens: child.outputTokens,
+                durationMs: child.durationMs,
+            }));
+            return {
+                spanId: span.spanId,
+                turnNumber: idx + 1,
+                name: span.name,
+                timestamp: span.startTime,
+                source: span.source,
+                model: span.model,
+                inputTokens: span.inputTokens,
+                outputTokens: span.outputTokens,
+                cacheReadTokens: span.cacheReadTokens,
+                freshTokens,
+                cacheHitRate,
+                costUsd: span.costUsd,
+                durationMs: span.durationMs,
+                contextSize: runningContext,
+                contextDelta: runningContext - prevContext,
+                toolName: span.attributes?.['tool.name'],
+                isContextSpike: false, // will be set in second pass
+                childSpans: childSpanSummaries,
+            };
+        });
+        // Second pass: spike detection
+        const avg = turns.reduce((sum, t) => sum + t.inputTokens, 0) / turns.length;
+        for (const turn of turns) {
+            turn.isContextSpike = avg > 0 && turn.inputTokens > 2 * avg;
+        }
+        this._logger.debug({ turnCount: turns.length, avg }, 'TurnAnalyzer.analyze complete');
+        return turns;
+    }
+}
+//# sourceMappingURL=turn-analyzer.js.map

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

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