agents-reverse-engineer 0.3.5 → 0.4.0

package/dist/ai/service.js

@@ -0,0 +1,239 @@
+/**
+ * AI service orchestrator.
+ *
+ * The {@link AIService} class is the main entry point for making AI calls.
+ * It ties together the subprocess wrapper, retry logic, backend selection,
+ * and telemetry logging into a clean `call()` method.
+ *
+ * @module
+ */
+import { AIServiceError } from './types.js';
+import { runSubprocess } from './subprocess.js';
+import { withRetry, DEFAULT_RETRY_OPTIONS } from './retry.js';
+import { TelemetryLogger } from './telemetry/logger.js';
+import { writeRunLog } from './telemetry/run-log.js';
+import { cleanupOldLogs } from './telemetry/cleanup.js';
+import { estimateCost } from './pricing.js';
+// ---------------------------------------------------------------------------
+// Rate-limit detection patterns
+// ---------------------------------------------------------------------------
+/** Patterns in stderr that indicate a transient rate-limit error */
+const RATE_LIMIT_PATTERNS = [
+    'rate limit',
+    '429',
+    'too many requests',
+    'overloaded',
+];
+/**
+ * Check whether stderr text contains rate-limit indicators.
+ *
+ * @param stderr - Standard error output from the subprocess
+ * @returns `true` if any rate-limit pattern matches (case-insensitive)
+ */
+function isRateLimitStderr(stderr) {
+    const lower = stderr.toLowerCase();
+    return RATE_LIMIT_PATTERNS.some((pattern) => lower.includes(pattern));
+}
+// ---------------------------------------------------------------------------
+// AIService
+// ---------------------------------------------------------------------------
+/**
+ * Orchestrates AI CLI calls with retry, timeout, and telemetry.
+ *
+ * Create one instance per CLI run. Call {@link call} for each AI invocation.
+ * Call {@link finalize} at the end to write the run log and clean up old files.
+ *
+ * @example
+ * ```typescript
+ * import { AIService } from './service.js';
+ * import { resolveBackend, createBackendRegistry } from './registry.js';
+ *
+ * const registry = createBackendRegistry();
+ * const backend = await resolveBackend(registry, 'auto');
+ * const service = new AIService(backend, {
+ *   timeoutMs: 120_000,
+ *   maxRetries: 3,
+ *   telemetry: { keepRuns: 10 },
+ * });
+ *
+ * const response = await service.call({ prompt: 'Summarize this codebase' });
+ * console.log(response.text);
+ *
+ * const { logPath, summary } = await service.finalize('/path/to/project');
+ * console.log(`Log written to ${logPath}, cost: $${summary.totalCostUsd}`);
+ * ```
+ */
+export class AIService {
+    /** The backend adapter used for CLI invocations */
+    backend;
+    /** Service configuration */
+    options;
+    /** In-memory telemetry logger for this run */
+    logger;
+    /** Running count of calls made (used for entry tracking) */
+    callCount = 0;
+    /** Set of model IDs for which an unknown-pricing warning has already been emitted */
+    warnedModels = new Set();
+    /**
+     * Create a new AI service instance.
+     *
+     * @param backend - The resolved backend adapter
+     * @param options - Service configuration (timeout, retries, telemetry)
+     */
+    constructor(backend, options) {
+        this.backend = backend;
+        this.options = options;
+        this.logger = new TelemetryLogger(new Date().toISOString());
+    }
+    /**
+     * Make an AI call with retry logic and telemetry recording.
+     *
+     * The call flow:
+     * 1. Build CLI args via the backend adapter
+     * 2. Wrap the subprocess invocation in retry logic
+     * 3. On success: parse response via backend, record telemetry entry
+     * 4. On failure: record error telemetry entry, throw the error
+     *
+     * Retries are attempted for `RATE_LIMIT` and `TIMEOUT` errors only.
+     * All other errors are treated as permanent failures.
+     *
+     * @param options - The call options (prompt, model, timeout, etc.)
+     * @returns The normalized AI response
+     * @throws {AIServiceError} On timeout, rate limit exhaustion, parse error, or subprocess failure
+     */
+    async call(options) {
+        this.callCount++;
+        const callStart = Date.now();
+        const timestamp = new Date().toISOString();
+        const args = this.backend.buildArgs(options);
+        const timeoutMs = options.timeoutMs ?? this.options.timeoutMs;
+        let retryCount = 0;
+        try {
+            const response = await withRetry(async () => {
+                const result = await runSubprocess(this.backend.cliCommand, args, {
+                    timeoutMs,
+                    input: options.prompt,
+                });
+                if (result.timedOut) {
+                    throw new AIServiceError('TIMEOUT', 'Subprocess timed out');
+                }
+                if (result.exitCode !== 0) {
+                    if (isRateLimitStderr(result.stderr)) {
+                        throw new AIServiceError('RATE_LIMIT', `Rate limited by ${this.backend.name}: ${result.stderr.slice(0, 200)}`);
+                    }
+                    throw new AIServiceError('SUBPROCESS_ERROR', `${this.backend.name} CLI exited with code ${result.exitCode}: ${result.stderr.slice(0, 500)}`);
+                }
+                // Parse the response -- wrap in try/catch for parse errors
+                try {
+                    return this.backend.parseResponse(result.stdout, result.durationMs, result.exitCode);
+                }
+                catch (error) {
+                    if (error instanceof AIServiceError) {
+                        throw error;
+                    }
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new AIServiceError('PARSE_ERROR', `Failed to parse response: ${message}`);
+                }
+            }, {
+                ...DEFAULT_RETRY_OPTIONS,
+                maxRetries: this.options.maxRetries,
+                isRetryable: (error) => {
+                    return (error instanceof AIServiceError &&
+                        (error.code === 'RATE_LIMIT' || error.code === 'TIMEOUT'));
+                },
+                onRetry: (_attempt, _error) => {
+                    retryCount++;
+                },
+            });
+            // Compute cost via pricing engine
+            const costResult = estimateCost(response.model, response.inputTokens, response.outputTokens, response.costUsd > 0 ? response.costUsd : undefined, this.options.pricingOverrides);
+            // Warn once per unknown model (stderr to preserve JSON stdout)
+            if (costResult.source === 'unavailable' && !this.warnedModels.has(response.model)) {
+                this.warnedModels.add(response.model);
+                console.error(`Warning: No pricing data for model "${response.model}". Cost shown as N/A. Add pricing in config under ai.pricing.`);
+            }
+            // Record successful call
+            this.logger.addEntry({
+                timestamp,
+                prompt: options.prompt,
+                systemPrompt: options.systemPrompt,
+                response: response.text,
+                model: response.model,
+                inputTokens: response.inputTokens,
+                outputTokens: response.outputTokens,
+                cacheReadTokens: response.cacheReadTokens,
+                cacheCreationTokens: response.cacheCreationTokens,
+                costUsd: costResult.costUsd,
+                latencyMs: response.durationMs,
+                exitCode: response.exitCode,
+                retryCount,
+                thinking: 'not supported',
+                filesRead: [],
+                costSource: costResult.source,
+            });
+            return response;
+        }
+        catch (error) {
+            // Record failed call
+            const latencyMs = Date.now() - callStart;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.addEntry({
+                timestamp,
+                prompt: options.prompt,
+                systemPrompt: options.systemPrompt,
+                response: '',
+                model: options.model ?? 'unknown',
+                inputTokens: 0,
+                outputTokens: 0,
+                cacheReadTokens: 0,
+                cacheCreationTokens: 0,
+                costUsd: 0,
+                latencyMs,
+                exitCode: 1,
+                error: errorMessage,
+                retryCount,
+                thinking: 'not supported',
+                filesRead: [],
+                costSource: 'unavailable',
+            });
+            throw error;
+        }
+    }
+    /**
+     * Finalize the run: write the run log to disk and clean up old files.
+     *
+     * Call this once at the end of a CLI invocation, after all `call()`
+     * invocations have completed (or failed).
+     *
+     * @param projectRoot - Absolute path to the project root directory
+     * @returns The log file path and the run summary
+     */
+    async finalize(projectRoot) {
+        const runLog = this.logger.toRunLog();
+        const logPath = await writeRunLog(projectRoot, runLog);
+        await cleanupOldLogs(projectRoot, this.options.telemetry.keepRuns);
+        return { logPath, summary: runLog.summary };
+    }
+    /**
+     * Attach file-read metadata to the most recent telemetry entry.
+     *
+     * Called by the command runner after an AI call completes, to record
+     * which source files were sent as context for that call.
+     *
+     * @param filesRead - Array of file-read records (path + size)
+     */
+    addFilesReadToLastEntry(filesRead) {
+        this.logger.setFilesReadOnLastEntry(filesRead);
+    }
+    /**
+     * Get the current run summary without finalizing.
+     *
+     * Useful for displaying progress during a run.
+     *
+     * @returns Current summary statistics
+     */
+    getSummary() {
+        return this.logger.getSummary();
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/ai/service.js.map

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

package/dist/ai/subprocess.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Low-level subprocess wrapper for AI CLI invocations.
+ *
+ * This is the ONLY place in the codebase that spawns AI CLI processes.
+ * Centralizes timeout enforcement, stdin piping, zombie prevention,
+ * and exit code extraction.
+ *
+ * @module
+ */
+import type { SubprocessResult } from './types.js';
+/**
+ * Spawn a CLI subprocess with timeout enforcement and stdin piping.
+ *
+ * Always resolves -- never rejects. Errors are captured in the returned
+ * {@link SubprocessResult} fields (`exitCode`, `timedOut`, `stderr`) so
+ * that callers can decide how to handle failures.
+ *
+ * @param command - The CLI executable to run (e.g., "claude", "gemini")
+ * @param args - Argument array passed to the executable
+ * @param options - Timeout and optional stdin input
+ * @returns Resolved result with stdout, stderr, exit code, timing, and timeout flag
+ *
+ * @example
+ * ```typescript
+ * import { runSubprocess } from './subprocess.js';
+ *
+ * const result = await runSubprocess('claude', ['-p', '--output-format', 'json'], {
+ *   timeoutMs: 120_000,
+ *   input: 'Summarize this codebase',
+ * });
+ *
+ * if (result.timedOut) {
+ *   console.error('CLI timed out after 120s');
+ * } else if (result.exitCode !== 0) {
+ *   console.error('CLI failed:', result.stderr);
+ * } else {
+ *   const response = JSON.parse(result.stdout);
+ * }
+ * ```
+ */
+export declare function runSubprocess(command: string, args: string[], options: {
+    timeoutMs: number;
+    input?: string;
+}): Promise<SubprocessResult>;
+//# sourceMappingURL=subprocess.d.ts.map

package/dist/ai/subprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../src/ai/subprocess.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,gBAAgB,CAAC,CAuD3B"}

package/dist/ai/subprocess.js

@@ -0,0 +1,90 @@
+/**
+ * Low-level subprocess wrapper for AI CLI invocations.
+ *
+ * This is the ONLY place in the codebase that spawns AI CLI processes.
+ * Centralizes timeout enforcement, stdin piping, zombie prevention,
+ * and exit code extraction.
+ *
+ * @module
+ */
+import { execFile } from 'node:child_process';
+/**
+ * Spawn a CLI subprocess with timeout enforcement and stdin piping.
+ *
+ * Always resolves -- never rejects. Errors are captured in the returned
+ * {@link SubprocessResult} fields (`exitCode`, `timedOut`, `stderr`) so
+ * that callers can decide how to handle failures.
+ *
+ * @param command - The CLI executable to run (e.g., "claude", "gemini")
+ * @param args - Argument array passed to the executable
+ * @param options - Timeout and optional stdin input
+ * @returns Resolved result with stdout, stderr, exit code, timing, and timeout flag
+ *
+ * @example
+ * ```typescript
+ * import { runSubprocess } from './subprocess.js';
+ *
+ * const result = await runSubprocess('claude', ['-p', '--output-format', 'json'], {
+ *   timeoutMs: 120_000,
+ *   input: 'Summarize this codebase',
+ * });
+ *
+ * if (result.timedOut) {
+ *   console.error('CLI timed out after 120s');
+ * } else if (result.exitCode !== 0) {
+ *   console.error('CLI failed:', result.stderr);
+ * } else {
+ *   const response = JSON.parse(result.stdout);
+ * }
+ * ```
+ */
+export function runSubprocess(command, args, options) {
+    return new Promise((resolve) => {
+        const startTime = Date.now();
+        const child = execFile(command, args, {
+            timeout: options.timeoutMs,
+            killSignal: 'SIGTERM',
+            maxBuffer: 10 * 1024 * 1024, // 10MB for large AI responses
+            encoding: 'utf-8',
+        }, (error, stdout, stderr) => {
+            const durationMs = Date.now() - startTime;
+            // Detect timeout: execFile sets `killed = true` when the process
+            // is terminated due to exceeding the timeout option.
+            const timedOut = error !== null && 'killed' in error && error.killed === true;
+            // Extract exit code from the error or child process.
+            // execFile puts the exit code in error.code when the process exits
+            // with a non-zero code, but error.code can also be a string like
+            // 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'. Fall back to child.exitCode,
+            // then default to 1 for unknown failures and 0 for no error.
+            let exitCode;
+            if (error === null) {
+                exitCode = 0;
+            }
+            else if (typeof error.code === 'number') {
+                exitCode = error.code;
+            }
+            else if (child.exitCode !== null) {
+                exitCode = child.exitCode;
+            }
+            else {
+                exitCode = 1;
+            }
+            resolve({
+                stdout: stdout ?? '',
+                stderr: stderr ?? '',
+                exitCode,
+                signal: (error !== null && 'signal' in error ? error.signal : null) ?? null,
+                durationMs,
+                timedOut,
+            });
+        });
+        // Write prompt to stdin if provided, then close the stream.
+        // IMPORTANT: Always call .end() -- the child process blocks waiting
+        // for EOF on stdin otherwise (see RESEARCH.md Pitfall 1).
+        if (options.input !== undefined && child.stdin !== null) {
+            child.stdin.write(options.input);
+            child.stdin.end();
+        }
+    });
+}
+//# sourceMappingURL=subprocess.js.map

package/dist/ai/subprocess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess.js","sourceRoot":"","sources":["../../src/ai/subprocess.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAe,EACf,IAAc,EACd,OAA8C;IAE9C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,MAAM,KAAK,GAAG,QAAQ,CACpB,OAAO,EACP,IAAI,EACJ;YACE,OAAO,EAAE,OAAO,CAAC,SAAS;YAC1B,UAAU,EAAE,SAAS;YACrB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,8BAA8B;YAC3D,QAAQ,EAAE,OAAO;SAClB,EACD,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAE1C,iEAAiE;YACjE,qDAAqD;YACrD,MAAM,QAAQ,GAAG,KAAK,KAAK,IAAI,IAAI,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC;YAE9E,qDAAqD;YACrD,mEAAmE;YACnE,iEAAiE;YACjE,oEAAoE;YACpE,6DAA6D;YAC7D,IAAI,QAAgB,CAAC;YACrB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,QAAQ,GAAG,CAAC,CAAC;YACf,CAAC;iBAAM,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC1C,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC;YACxB,CAAC;iBAAM,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACnC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,QAAQ,GAAG,CAAC,CAAC;YACf,CAAC;YAED,OAAO,CAAC;gBACN,MAAM,EAAE,MAAM,IAAI,EAAE;gBACpB,MAAM,EAAE,MAAM,IAAI,EAAE;gBACpB,QAAQ;gBACR,MAAM,EAAE,CAAC,KAAK,KAAK,IAAI,IAAI,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI;gBACrF,UAAU;gBACV,QAAQ;aACT,CAAC,CAAC;QACL,CAAC,CACF,CAAC;QAEF,4DAA4D;QAC5D,oEAAoE;QACpE,0DAA0D;QAC1D,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACxD,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACjC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACpB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/ai/telemetry/cleanup.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Telemetry log cleanup utility.
+ *
+ * Removes old run log files from `.agents-reverse-engineer/logs/`,
+ * keeping only the N most recent. Files are sorted lexicographically
+ * by name, which works correctly because filenames contain ISO timestamps.
+ *
+ * @module
+ */
+/**
+ * Remove old telemetry log files, keeping only the most recent ones.
+ *
+ * Reads the logs directory, filters for files matching `run-*.json`,
+ * sorts newest-first (lexicographic sort on ISO timestamp filenames),
+ * and deletes everything beyond `keepCount`.
+ *
+ * If the logs directory does not exist, returns 0 without error.
+ *
+ * @param projectRoot - Absolute path to the project root directory
+ * @param keepCount - Number of most recent log files to retain
+ * @returns Number of files deleted
+ *
+ * @example
+ * ```typescript
+ * const deleted = await cleanupOldLogs('/home/user/project', 10);
+ * console.log(`Cleaned up ${deleted} old log files`);
+ * ```
+ */
+export declare function cleanupOldLogs(projectRoot: string, keepCount: number): Promise<number>;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/ai/telemetry/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../../src/ai/telemetry/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4B5F"}

package/dist/ai/telemetry/cleanup.js

@@ -0,0 +1,56 @@
+/**
+ * Telemetry log cleanup utility.
+ *
+ * Removes old run log files from `.agents-reverse-engineer/logs/`,
+ * keeping only the N most recent. Files are sorted lexicographically
+ * by name, which works correctly because filenames contain ISO timestamps.
+ *
+ * @module
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+/** Directory name for telemetry log files (relative to project root) */
+const LOGS_DIR = '.agents-reverse-engineer/logs';
+/**
+ * Remove old telemetry log files, keeping only the most recent ones.
+ *
+ * Reads the logs directory, filters for files matching `run-*.json`,
+ * sorts newest-first (lexicographic sort on ISO timestamp filenames),
+ * and deletes everything beyond `keepCount`.
+ *
+ * If the logs directory does not exist, returns 0 without error.
+ *
+ * @param projectRoot - Absolute path to the project root directory
+ * @param keepCount - Number of most recent log files to retain
+ * @returns Number of files deleted
+ *
+ * @example
+ * ```typescript
+ * const deleted = await cleanupOldLogs('/home/user/project', 10);
+ * console.log(`Cleaned up ${deleted} old log files`);
+ * ```
+ */
+export async function cleanupOldLogs(projectRoot, keepCount) {
+    const logsDir = path.join(projectRoot, LOGS_DIR);
+    let entries;
+    try {
+        const allEntries = await fs.readdir(logsDir);
+        entries = allEntries.filter((name) => name.startsWith('run-') && name.endsWith('.json'));
+    }
+    catch (error) {
+        // Directory doesn't exist -- nothing to clean up
+        if (error.code === 'ENOENT') {
+            return 0;
+        }
+        throw error;
+    }
+    // Sort lexicographically (newest first) and find files to delete
+    entries.sort();
+    entries.reverse();
+    const toDelete = entries.slice(keepCount);
+    for (const filename of toDelete) {
+        await fs.unlink(path.join(logsDir, filename));
+    }
+    return toDelete.length;
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/ai/telemetry/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../../src/ai/telemetry/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,wEAAwE;AACxE,MAAM,QAAQ,GAAG,+BAA+B,CAAC;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,WAAmB,EAAE,SAAiB;IACzE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAEjD,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC7C,OAAO,GAAG,UAAU,CAAC,MAAM,CACzB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC5D,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,iDAAiD;QACjD,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,iEAAiE;IACjE,OAAO,CAAC,IAAI,EAAE,CAAC;IACf,OAAO,CAAC,OAAO,EAAE,CAAC;IAElB,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAE1C,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAAE,CAAC;QAChC,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,QAAQ,CAAC,MAAM,CAAC;AACzB,CAAC"}

package/dist/ai/telemetry/logger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * In-memory telemetry logger for AI service calls.
+ *
+ * Accumulates {@link TelemetryEntry} instances during a run and computes
+ * aggregate summaries. The logger is created once per CLI invocation and
+ * finalized when the run completes.
+ *
+ * @module
+ */
+import type { TelemetryEntry, RunLog, FileRead } from '../types.js';
+/**
+ * Accumulates per-call telemetry entries in memory and produces a
+ * complete {@link RunLog} when the run finishes.
+ *
+ * @example
+ * ```typescript
+ * const logger = new TelemetryLogger('2026-02-07T12:00:00.000Z');
+ * logger.addEntry(entry);
+ * const summary = logger.getSummary();
+ * const runLog = logger.toRunLog();
+ * ```
+ */
+export declare class TelemetryLogger {
+    /** Unique identifier for this run (ISO timestamp-based) */
+    readonly runId: string;
+    /** ISO 8601 timestamp when the run started */
+    readonly startTime: string;
+    /** Accumulated telemetry entries */
+    private readonly entries;
+    /**
+     * Create a new telemetry logger for a run.
+     *
+     * @param runId - Unique run identifier (typically an ISO timestamp)
+     */
+    constructor(runId: string);
+    /**
+     * Record a telemetry entry for a completed AI call.
+     *
+     * @param entry - The telemetry entry to record
+     */
+    addEntry(entry: TelemetryEntry): void;
+    /**
+     * Get all recorded entries as a read-only array.
+     *
+     * @returns Immutable view of the accumulated entries
+     */
+    getEntries(): readonly TelemetryEntry[];
+    /**
+     * Update the most recent entry's filesRead array.
+     *
+     * Called by the AI service after the command runner attaches file
+     * metadata to the last call.
+     *
+     * @param filesRead - Array of file-read records to attach
+     */
+    setFilesReadOnLastEntry(filesRead: FileRead[]): void;
+    /**
+     * Compute aggregate summary statistics from all recorded entries.
+     *
+     * Totals are computed on every call (not cached) so the summary
+     * always reflects the current state of the entries array.
+     *
+     * @returns Summary with totals for calls, tokens, cost, duration, and errors
+     */
+    getSummary(): RunLog['summary'];
+    /**
+     * Assemble the complete {@link RunLog} for this run.
+     *
+     * Sets `endTime` to the current time, includes all entries, and
+     * computes the summary. Call this once when the run is finished.
+     *
+     * @returns Complete run log ready for serialization
+     */
+    toRunLog(): RunLog;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/ai/telemetry/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/ai/telemetry/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,oCAAoC;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAEhD;;;;OAIG;gBACS,KAAK,EAAE,MAAM;IAKzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAIrC;;;;OAIG;IACH,UAAU,IAAI,SAAS,cAAc,EAAE;IAIvC;;;;;;;OAOG;IACH,uBAAuB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI;IAKpD;;;;;;;OAOG;IACH,UAAU,IAAI,MAAM,CAAC,SAAS,CAAC;IAwC/B;;;;;;;OAOG;IACH,QAAQ,IAAI,MAAM;CASnB"}