@substrate-ai/core 0.19.54

package/dist/telemetry/ingestion-server.js

@@ -0,0 +1,315 @@
+/**
+ * IngestionServer — local OTLP HTTP/JSON endpoint for Claude Code telemetry.
+ *
+ * Starts an HTTP server that accepts OTLP-formatted telemetry payloads from
+ * Claude Code sub-agents. The server binds to a configurable port (default 4318)
+ * and exposes `getOtlpEnvVars()` to retrieve the 5 environment variables that
+ * configure Claude Code to export telemetry to this endpoint.
+ *
+ * When a `TelemetryPipeline` is injected, received payloads are parsed and
+ * buffered via `BatchBuffer`, which flushes to the pipeline on size or time
+ * triggers. Without a pipeline, the server operates in stub mode (acknowledge
+ * and discard), preserving backwards-compatibility.
+ *
+ * Usage:
+ *   const server = new IngestionServer({ port: 4318 })
+ *   await server.start()
+ *   const envVars = server.getOtlpEnvVars()  // inject into sub-agents
+ *   await server.stop()
+ */
+import { createServer } from 'node:http';
+import { createGunzip, createInflate } from 'node:zlib';
+import { BatchBuffer } from './batch-buffer.js';
+import { detectSource } from './source-detector.js';
+// ---------------------------------------------------------------------------
+// TelemetryError
+// ---------------------------------------------------------------------------
+/**
+ * Error thrown by IngestionServer for server lifecycle violations.
+ * Extends Error with a machine-readable `code` property.
+ * (In the monolith, callers may import TelemetryError from the shim which
+ * re-exports this class from @substrate-ai/core.)
+ */
+export class TelemetryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TelemetryError';
+        this.code = code;
+    }
+}
+// ---------------------------------------------------------------------------
+// IngestionServer
+// ---------------------------------------------------------------------------
+/**
+ * Local HTTP server that accepts OTLP payloads from Claude Code sub-agents.
+ *
+ * Binds to `port` (default 4318). Use port 0 in tests for an OS-assigned port.
+ */
+export class IngestionServer {
+    _server = null;
+    _port;
+    _batchSize;
+    _flushIntervalMs;
+    _buffer;
+    _pendingBatches = new Set();
+    _logger;
+    constructor(options = {}) {
+        this._port = options.port ?? 4318;
+        this._batchSize = options.batchSize ?? 100;
+        this._flushIntervalMs = options.flushIntervalMs ?? 5000;
+        this._logger = options.logger ?? console;
+        if (options.pipeline !== undefined) {
+            this._initPipeline(options.pipeline);
+        }
+    }
+    /**
+     * Wire a TelemetryPipeline before the server is started.
+     * Must be called before start() — has no effect if called after start().
+     */
+    setPipeline(pipeline) {
+        if (this._server !== null) {
+            this._logger.warn('IngestionServer.setPipeline() called after start() — ignoring');
+            return;
+        }
+        this._initPipeline(pipeline);
+    }
+    _initPipeline(pipeline) {
+        this._buffer = new BatchBuffer({
+            batchSize: this._batchSize,
+            flushIntervalMs: this._flushIntervalMs,
+        });
+        // Wire: batch flush → pipeline processBatch
+        // Track each in-flight processBatch() promise so stop() can await them.
+        this._buffer.on('flush', (items) => {
+            const pending = pipeline.processBatch(items).catch((err) => {
+                this._logger.warn({ err }, 'TelemetryPipeline.processBatch failed (batch flush)');
+            });
+            this._pendingBatches.add(pending);
+            void pending.then(() => {
+                this._pendingBatches.delete(pending);
+            });
+        });
+    }
+    /**
+     * Force-flush buffered OTLP payloads and await all in-flight processBatch() calls.
+     * Call this between story dispatches to ensure story N's telemetry (including
+     * recommendations) is fully persisted before story N+1 begins.
+     *
+     * No-op when no TelemetryPipeline is wired.
+     */
+    async flushAndAwait() {
+        if (this._buffer === undefined)
+            return;
+        this._buffer.flush();
+        if (this._pendingBatches.size > 0) {
+            await Promise.all([...this._pendingBatches]);
+        }
+    }
+    /**
+     * Start the HTTP ingestion server.
+     * Resolves when the server is listening and ready to accept connections.
+     * On EADDRINUSE, retries up to 10 consecutive ports before failing.
+     */
+    async start() {
+        if (this._server !== null) {
+            this._logger.warn('IngestionServer.start() called while already started — ignoring');
+            return;
+        }
+        const maxRetries = 10;
+        let lastErr;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            const port = this._port + attempt;
+            try {
+                await this._tryListen(port);
+                return;
+            }
+            catch (err) {
+                const nodeErr = err;
+                if (nodeErr.code === 'EADDRINUSE' && attempt < maxRetries) {
+                    this._logger.warn({ port, attempt: attempt + 1 }, `Port ${port} in use — trying ${port + 1}`);
+                    lastErr = nodeErr;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw lastErr ?? new Error('IngestionServer: exhausted port retry attempts');
+    }
+    _tryListen(port) {
+        return new Promise((resolve, reject) => {
+            const server = createServer(this._handleRequest.bind(this));
+            server.on('error', (err) => {
+                server.close();
+                reject(err);
+            });
+            server.listen(port, '127.0.0.1', () => {
+                this._server = server;
+                const addr = server.address();
+                this._logger.info({ port: addr.port, requestedPort: this._port }, 'IngestionServer listening');
+                // Start the batch buffer timer (if pipeline is wired)
+                this._buffer?.start();
+                resolve();
+            });
+        });
+    }
+    /**
+     * Stop the HTTP ingestion server.
+     * Drains the batch buffer before closing the HTTP server.
+     * Resolves when the server has closed all connections.
+     */
+    async stop() {
+        const server = this._server;
+        if (server === null) {
+            return;
+        }
+        this._server = null;
+        // Stop (and drain) the batch buffer first
+        this._buffer?.stop();
+        // Await any in-flight processBatch() calls
+        if (this._pendingBatches.size > 0) {
+            await Promise.all([...this._pendingBatches]);
+        }
+        return new Promise((resolve, reject) => {
+            server.close((err) => {
+                if (err !== undefined && err !== null) {
+                    reject(err);
+                }
+                else {
+                    this._logger.info('IngestionServer stopped');
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Return the 5 OTLP environment variables to inject into sub-agent processes.
+     *
+     * @throws {TelemetryError} ERR_TELEMETRY_NOT_STARTED if the server is not started.
+     */
+    getOtlpEnvVars() {
+        const addr = this._server?.address();
+        if (addr === null || addr === undefined || typeof addr === 'string') {
+            throw new TelemetryError('ERR_TELEMETRY_NOT_STARTED', 'IngestionServer is not started — call start() before getOtlpEnvVars()');
+        }
+        const endpoint = `http://localhost:${addr.port}`;
+        return {
+            CLAUDE_CODE_ENABLE_TELEMETRY: '1',
+            OTEL_LOGS_EXPORTER: 'otlp',
+            OTEL_METRICS_EXPORTER: 'otlp',
+            OTEL_EXPORTER_OTLP_PROTOCOL: 'http/json',
+            OTEL_EXPORTER_OTLP_ENDPOINT: endpoint,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Substrate resource attributes extracted from an OTLP payload.
+     * These are set by ClaudeCodeAdapter via OTEL_RESOURCE_ATTRIBUTES env var.
+     */
+    _extractSubstrateAttributes(body) {
+        if (!body || typeof body !== 'object')
+            return {};
+        const payload = body;
+        const extractFromResources = (resources) => {
+            const result = {};
+            if (!Array.isArray(resources))
+                return result;
+            for (const entry of resources) {
+                if (!entry || typeof entry !== 'object')
+                    continue;
+                const resource = entry.resource;
+                if (!resource || typeof resource !== 'object')
+                    continue;
+                const attrs = resource.attributes;
+                if (!Array.isArray(attrs))
+                    continue;
+                for (const attr of attrs) {
+                    if (!attr || typeof attr !== 'object')
+                        continue;
+                    const a = attr;
+                    const key = a.key;
+                    if (key !== undefined && key.startsWith('substrate.')) {
+                        const val = a.value;
+                        if (val && typeof val.stringValue === 'string') {
+                            result[key] = val.stringValue;
+                        }
+                    }
+                }
+            }
+            return result;
+        };
+        const attrs = {
+            ...extractFromResources(payload.resourceSpans),
+            ...extractFromResources(payload.resourceLogs),
+        };
+        return {
+            ...(attrs['substrate.story_key'] !== undefined && {
+                storyKey: attrs['substrate.story_key'],
+            }),
+            ...(attrs['substrate.task_type'] !== undefined && {
+                taskType: attrs['substrate.task_type'],
+            }),
+            ...(attrs['substrate.dispatch_id'] !== undefined && {
+                dispatchId: attrs['substrate.dispatch_id'],
+            }),
+        };
+    }
+    _handleRequest(req, res) {
+        // Health check support
+        if (req.url === '/health' && req.method === 'GET') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok' }));
+            return;
+        }
+        // Collect body, decompressing gzip/deflate if needed
+        const encoding = req.headers['content-encoding'];
+        let stream = req;
+        if (encoding === 'gzip' || encoding === 'deflate') {
+            stream = encoding === 'gzip' ? req.pipe(createGunzip()) : req.pipe(createInflate());
+        }
+        const chunks = [];
+        stream.on('data', (chunk) => {
+            chunks.push(chunk);
+        });
+        stream.on('end', () => {
+            const bodyStr = Buffer.concat(chunks).toString('utf-8');
+            this._logger.debug({ url: req.url, bodyLength: bodyStr.length }, 'OTLP payload received');
+            // If a pipeline is wired, parse and buffer the payload
+            if (this._buffer !== undefined) {
+                try {
+                    const body = JSON.parse(bodyStr);
+                    const source = detectSource(body);
+                    const { storyKey, taskType, dispatchId } = this._extractSubstrateAttributes(body);
+                    // Dispatch context is extracted directly from OTLP resource attributes
+                    // (set by ClaudeCodeAdapter via OTEL_RESOURCE_ATTRIBUTES env var).
+                    const dispatchContext = taskType !== undefined && dispatchId !== undefined
+                        ? { taskType, phase: taskType, dispatchId }
+                        : undefined;
+                    const payload = {
+                        body,
+                        source,
+                        receivedAt: Date.now(),
+                        ...(storyKey !== undefined && { storyKey }),
+                        ...(dispatchContext !== undefined && { dispatchContext }),
+                    };
+                    this._buffer.push(payload);
+                }
+                catch (err) {
+                    this._logger.warn({ err, url: req.url }, 'Failed to parse OTLP payload JSON — discarding');
+                }
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end('{}');
+        });
+        stream.on('error', (err) => {
+            this._logger.warn({ err }, 'Error reading OTLP request body');
+            if (!res.headersSent) {
+                res.writeHead(400);
+                res.end('Bad Request');
+            }
+        });
+    }
+}
+//# sourceMappingURL=ingestion-server.js.map

package/dist/telemetry/ingestion-server.js.map

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

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

@@ -0,0 +1,35 @@
+/**
+ * LogTurnAnalyzer — computes per-turn token breakdowns from normalized log records.
+ *
+ * Takes a list of NormalizedLog records and produces TurnAnalysis[], where
+ * each entry represents an LLM turn derived from log data with:
+ *   - Chronological ordering (by timestamp)
+ *   - Sequential turnNumber assignment (1-N)
+ *   - freshTokens, cacheHitRate, contextSize, contextDelta metrics
+ *   - isContextSpike detection (inputTokens > 2× average)
+ *   - Deduplication by traceId+spanId combination
+ *
+ * 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
+ *   - Never throws from public methods
+ *
+ * Migrated to @substrate-ai/core in story 41-6b.
+ */
+import type { ILogger } from '../dispatch/types.js';
+import type { NormalizedLog, TurnAnalysis } from './types.js';
+import type { ILogTurnAnalyzer } from './telemetry-pipeline.js';
+export declare class LogTurnAnalyzer implements ILogTurnAnalyzer {
+    private readonly _logger;
+    constructor(logger?: ILogger);
+    /**
+     * Analyze a list of NormalizedLog records and produce TurnAnalysis[].
+     *
+     * Returns an empty array immediately when logs is empty or on any error.
+     *
+     * @param logs - All log records for a story
+     */
+    analyze(logs: NormalizedLog[]): TurnAnalysis[];
+}
+//# sourceMappingURL=log-turn-analyzer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"log-turn-analyzer.d.ts","sourceRoot":"","sources":["../../src/telemetry/log-turn-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAkB/D,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,CAAC,EAAE,OAAO;IAQ5B;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,YAAY,EAAE;CA8G/C"}

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

@@ -0,0 +1,132 @@
+/**
+ * LogTurnAnalyzer — computes per-turn token breakdowns from normalized log records.
+ *
+ * Takes a list of NormalizedLog records and produces TurnAnalysis[], where
+ * each entry represents an LLM turn derived from log data with:
+ *   - Chronological ordering (by timestamp)
+ *   - Sequential turnNumber assignment (1-N)
+ *   - freshTokens, cacheHitRate, contextSize, contextDelta metrics
+ *   - isContextSpike detection (inputTokens > 2× average)
+ *   - Deduplication by traceId+spanId combination
+ *
+ * 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
+ *   - Never throws from public methods
+ *
+ * Migrated to @substrate-ai/core in story 41-6b.
+ */
+// ---------------------------------------------------------------------------
+// LogTurnAnalyzer
+// ---------------------------------------------------------------------------
+export class LogTurnAnalyzer {
+    _logger;
+    constructor(logger) {
+        this._logger = logger ?? console;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Analyze a list of NormalizedLog records and produce TurnAnalysis[].
+     *
+     * Returns an empty array immediately when logs is empty or on any error.
+     *
+     * @param logs - All log records for a story
+     */
+    analyze(logs) {
+        try {
+            if (!Array.isArray(logs) || logs.length === 0) {
+                return [];
+            }
+            // Filter out invalid/malformed entries and non-LLM logs (zero tokens = noise)
+            const validLogs = logs.filter((log) => log != null &&
+                typeof log === 'object' &&
+                ((log.inputTokens ?? 0) > 0 || (log.outputTokens ?? 0) > 0));
+            if (validLogs.length === 0) {
+                this._logger.debug('LogTurnAnalyzer: no LLM logs with tokens to analyze');
+                return [];
+            }
+            // Group by traceId+spanId for deduplication.
+            // Key: `${traceId}:${spanId}` when both present; otherwise fallback to logId.
+            const grouped = new Map();
+            for (const log of validLogs) {
+                const key = log.traceId != null && log.spanId != null
+                    ? `${log.traceId}:${log.spanId}`
+                    : log.logId;
+                const group = grouped.get(key) ?? [];
+                group.push(log);
+                grouped.set(key, group);
+            }
+            // Merge each group: sum token counts, use earliest log as representative
+            const merged = [];
+            for (const group of grouped.values()) {
+                const sorted = [...group].sort((a, b) => a.timestamp - b.timestamp);
+                const representative = sorted[0];
+                let inputTokens = 0;
+                let outputTokens = 0;
+                let cacheReadTokens = 0;
+                let costUsd = 0;
+                for (const log of group) {
+                    inputTokens += log.inputTokens ?? 0;
+                    outputTokens += log.outputTokens ?? 0;
+                    cacheReadTokens += log.cacheReadTokens ?? 0;
+                    costUsd += log.costUsd ?? 0;
+                }
+                merged.push({ representative, inputTokens, outputTokens, cacheReadTokens, costUsd });
+            }
+            // Sort merged entries chronologically by representative timestamp
+            merged.sort((a, b) => a.representative.timestamp - b.representative.timestamp);
+            // First pass: build turns with context accumulation metrics
+            let runningContext = 0;
+            const turns = merged.map(({ representative: log, inputTokens, outputTokens, cacheReadTokens, costUsd }, idx) => {
+                const prevContext = runningContext;
+                // contextSize tracks total input (fresh + cached) to reflect actual context window usage
+                runningContext += inputTokens + cacheReadTokens;
+                // Claude API input_tokens IS the fresh (non-cached) count, so freshTokens = inputTokens
+                const freshTokens = inputTokens;
+                // cacheHitRate = fraction of total input that came from cache (0-1).
+                // Claude API reports input_tokens as fresh (non-cached) only, so
+                // total input = inputTokens + cacheReadTokens.
+                const totalInput = inputTokens + cacheReadTokens;
+                const cacheHitRate = totalInput > 0 ? cacheReadTokens / totalInput : 0;
+                return {
+                    spanId: log.spanId ?? log.logId,
+                    turnNumber: idx + 1,
+                    name: log.eventName ?? 'log_turn',
+                    timestamp: log.timestamp,
+                    source: 'claude-code',
+                    model: log.model,
+                    inputTokens,
+                    outputTokens,
+                    cacheReadTokens,
+                    freshTokens,
+                    cacheHitRate,
+                    costUsd,
+                    durationMs: 0,
+                    contextSize: runningContext,
+                    contextDelta: runningContext - prevContext,
+                    toolName: log.toolName,
+                    isContextSpike: false, // will be set in second pass
+                    childSpans: [],
+                    ...(log.taskType !== undefined && { taskType: log.taskType }),
+                    ...(log.phase !== undefined && { phase: log.phase }),
+                    ...(log.dispatchId !== undefined && { dispatchId: log.dispatchId }),
+                };
+            });
+            // Second pass: spike detection (inputTokens > 2 × average)
+            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 }, 'LogTurnAnalyzer.analyze complete');
+            return turns;
+        }
+        catch (err) {
+            this._logger.warn({ err }, 'LogTurnAnalyzer.analyze failed — returning empty array');
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=log-turn-analyzer.js.map

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

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

package/dist/telemetry/normalizer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 type { ILogger } from '../dispatch/types.js';
+import type { NormalizedSpan, NormalizedLog, DispatchContext } from './types.js';
+/**
+ * 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 declare class TelemetryNormalizer {
+    private readonly _logger;
+    constructor(logger: ILogger);
+    /**
+     * 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: unknown): NormalizedSpan[];
+    private _normalizeSpanInternal;
+    private _normalizeOneSpan;
+    /**
+     * 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: unknown, dispatchContext?: DispatchContext): NormalizedLog[];
+    private _normalizeLogInternal;
+    private _normalizeOneLog;
+}
+//# sourceMappingURL=normalizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../src/telemetry/normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA+JhF;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,OAAO;IAQ3B;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE;IAS7C,OAAO,CAAC,sBAAsB;IAmC9B,OAAO,CAAC,iBAAiB;IA6EzB;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,eAAe,GAAG,aAAa,EAAE;IAS9E,OAAO,CAAC,qBAAqB;IAkC7B,OAAO,CAAC,gBAAgB;CAqEzB"}