@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/episodes/recorder.js

@@ -0,0 +1,195 @@
+/**
+ * Episode Recorder
+ *
+ * Collects tool call signals via an AfterToolHook, batches them within
+ * a time window, and persists as WorkEpisode records.
+ */
+import { randomUUID } from 'crypto';
+import { estimateEffort, EFFORT_ORDER } from '@compilr-dev/agents';
+import { isSignificantWork, extractAffectedFiles, extractLinesChanged } from './significant-work.js';
+// =============================================================================
+// Constants
+// =============================================================================
+const DEFAULT_BATCH_WINDOW_MS = 5000;
+const DEFAULT_MIN_EFFORT = 'low';
+// =============================================================================
+// Implementation
+// =============================================================================
+export class EpisodeRecorder {
+    store;
+    agentId;
+    terminalPrefix;
+    sessionId;
+    autoRecord;
+    minEffortToRecord;
+    batchWindowMs;
+    onBatchFlushed;
+    pendingSignals = [];
+    batchTimer = null;
+    batchStartTime = null;
+    constructor(config) {
+        this.store = config.store;
+        this.agentId = config.agentId;
+        this.terminalPrefix = config.terminalPrefix;
+        this.sessionId = config.sessionId;
+        this.autoRecord = config.autoRecord ?? true;
+        this.minEffortToRecord = config.minEffortToRecord ?? DEFAULT_MIN_EFFORT;
+        this.batchWindowMs = config.batchWindowMs ?? DEFAULT_BATCH_WINDOW_MS;
+        this.onBatchFlushed = config.onBatchFlushed;
+    }
+    /**
+     * Create an AfterToolHook for observing tool calls.
+     * Always returns undefined (observation only — never modifies results).
+     */
+    createHook() {
+        return (context) => {
+            if (!this.autoRecord)
+                return undefined;
+            const success = context.result.success;
+            if (!isSignificantWork(context.toolName, context.input, success)) {
+                return undefined;
+            }
+            const signal = {
+                toolName: context.toolName,
+                files: extractAffectedFiles(context.toolName, context.input),
+                linesChanged: extractLinesChanged(context.result),
+                durationMs: context.durationMs,
+                success,
+                timestamp: new Date().toISOString(),
+            };
+            this.pendingSignals.push(signal);
+            this.scheduleBatch();
+            return undefined;
+        };
+    }
+    /**
+     * Force-flush all pending signals as a WorkEpisode.
+     * Called on shutdown to avoid losing data.
+     */
+    flush() {
+        if (this.batchTimer) {
+            clearTimeout(this.batchTimer);
+            this.batchTimer = null;
+        }
+        this.buildAndSaveEpisode();
+    }
+    // ---------------------------------------------------------------------------
+    // Internal
+    // ---------------------------------------------------------------------------
+    scheduleBatch() {
+        if (!this.batchStartTime) {
+            this.batchStartTime = Date.now();
+        }
+        // Clear existing timer and set a new one
+        if (this.batchTimer) {
+            clearTimeout(this.batchTimer);
+        }
+        this.batchTimer = setTimeout(() => {
+            this.batchTimer = null;
+            this.buildAndSaveEpisode();
+        }, this.batchWindowMs);
+    }
+    buildAndSaveEpisode() {
+        if (this.pendingSignals.length === 0) {
+            this.batchStartTime = null;
+            return;
+        }
+        const signals = [...this.pendingSignals];
+        this.pendingSignals = [];
+        const startTime = this.batchStartTime;
+        this.batchStartTime = null;
+        // Collect unique files, tool names, total lines
+        const allFiles = new Set();
+        const toolNames = new Set();
+        let totalLines = 0;
+        let totalDurationMs = 0;
+        for (const s of signals) {
+            for (const f of s.files)
+                allFiles.add(f);
+            toolNames.add(s.toolName);
+            totalLines += s.linesChanged;
+            totalDurationMs += s.durationMs;
+        }
+        const files = [...allFiles];
+        // Build effort signals
+        const effortSignals = {
+            fileCount: files.length,
+            linesChanged: totalLines,
+            toolCallCount: signals.length,
+            durationMs: totalDurationMs,
+            iterationCount: signals.length,
+            complexityIndicators: {
+                newFiles: toolNames.has('write_file'),
+                multiLanguage: hasMultipleLanguages(files),
+                tests: files.some(isTestFile),
+                configChanges: files.some(isConfigFile),
+            },
+        };
+        const effort = estimateEffort(effortSignals);
+        // Skip if below minimum effort threshold
+        if (EFFORT_ORDER.indexOf(effort) < EFFORT_ORDER.indexOf(this.minEffortToRecord)) {
+            return;
+        }
+        const episode = {
+            id: randomUUID(),
+            agentId: this.agentId,
+            terminalPrefix: this.terminalPrefix,
+            action: inferAction([...toolNames]),
+            summary: buildSummary([...toolNames], files, totalLines),
+            files,
+            linesChanged: totalLines > 0 ? totalLines : undefined,
+            timestamp: signals[0].timestamp,
+            sessionId: this.sessionId,
+            effort,
+            durationMs: startTime ? Date.now() - startTime : totalDurationMs,
+            toolCalls: signals.length,
+        };
+        void this.store.save(episode);
+        this.onBatchFlushed?.();
+    }
+}
+// =============================================================================
+// Helpers (module-private)
+// =============================================================================
+function inferAction(toolNames) {
+    if (toolNames.includes('git_commit'))
+        return 'commit';
+    if (toolNames.includes('run_tests'))
+        return 'test';
+    if (toolNames.includes('run_lint'))
+        return 'lint';
+    if (toolNames.includes('run_build'))
+        return 'build';
+    if (toolNames.includes('write_file') && !toolNames.includes('edit'))
+        return 'create';
+    if (toolNames.includes('edit'))
+        return 'edit';
+    return 'modify';
+}
+function buildSummary(toolNames, files, totalLines) {
+    const action = inferAction(toolNames);
+    const fileStr = files.length === 1 ? files[0] : `${String(files.length)} files`;
+    const lineStr = totalLines > 0 ? ` (${String(totalLines)} lines)` : '';
+    return `${action}: ${fileStr}${lineStr}`;
+}
+function hasMultipleLanguages(files) {
+    const extensions = new Set();
+    for (const f of files) {
+        const ext = f.split('.').pop();
+        if (ext)
+            extensions.add(ext);
+    }
+    return extensions.size > 1;
+}
+function isTestFile(file) {
+    return /\.(test|spec)\.[a-z]+$/i.test(file) || file.includes('__tests__');
+}
+function isConfigFile(file) {
+    const base = file.split('/').pop() ?? '';
+    return (base.startsWith('.') ||
+        base === 'package.json' ||
+        base === 'tsconfig.json' ||
+        base.endsWith('.config.ts') ||
+        base.endsWith('.config.js') ||
+        base.endsWith('.config.mjs'));
+}

package/dist/episodes/significant-work.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Significant Work Detection
+ *
+ * Determines which tool calls represent meaningful work (writes, edits, commits)
+ * versus read-only exploration (reads, greps, globs).
+ */
+/**
+ * Check if a tool call represents significant work worth recording.
+ * Returns false for failed tool calls (fail-closed: don't record broken work).
+ */
+export declare function isSignificantWork(toolName: string, _input: Record<string, unknown>, success: boolean): boolean;
+/**
+ * Extract affected file paths from a tool call's input.
+ * Returns an empty array if no files can be extracted.
+ */
+export declare function extractAffectedFiles(toolName: string, input: Record<string, unknown>): string[];
+/**
+ * Extract lines changed from a tool result, best-effort.
+ * Returns 0 if the information is not available.
+ */
+export declare function extractLinesChanged(result: Record<string, unknown>): number;

package/dist/episodes/significant-work.js

@@ -0,0 +1,56 @@
+/**
+ * Significant Work Detection
+ *
+ * Determines which tool calls represent meaningful work (writes, edits, commits)
+ * versus read-only exploration (reads, greps, globs).
+ */
+import { TOOL_NAMES } from '../tool-names.js';
+/** Tool names that represent significant (mutating) work */
+const SIGNIFICANT_TOOLS = new Set([
+    TOOL_NAMES.WRITE_FILE,
+    TOOL_NAMES.EDIT,
+    TOOL_NAMES.GIT_COMMIT,
+    TOOL_NAMES.GIT_STASH,
+    TOOL_NAMES.RUN_TESTS,
+    TOOL_NAMES.RUN_LINT,
+    TOOL_NAMES.RUN_BUILD,
+]);
+/**
+ * Check if a tool call represents significant work worth recording.
+ * Returns false for failed tool calls (fail-closed: don't record broken work).
+ */
+export function isSignificantWork(toolName, _input, success) {
+    if (!success)
+        return false;
+    return SIGNIFICANT_TOOLS.has(toolName);
+}
+/**
+ * Extract affected file paths from a tool call's input.
+ * Returns an empty array if no files can be extracted.
+ */
+export function extractAffectedFiles(toolName, input) {
+    if (toolName === TOOL_NAMES.WRITE_FILE && typeof input.path === 'string') {
+        return [input.path];
+    }
+    if (toolName === TOOL_NAMES.EDIT && typeof input.filePath === 'string') {
+        return [input.filePath];
+    }
+    return [];
+}
+/**
+ * Extract lines changed from a tool result, best-effort.
+ * Returns 0 if the information is not available.
+ */
+export function extractLinesChanged(result) {
+    // Some tools report linesWritten directly
+    if (typeof result.linesWritten === 'number') {
+        return result.linesWritten;
+    }
+    // Edit results may have linesAdded + linesRemoved
+    const added = typeof result.linesAdded === 'number' ? result.linesAdded : 0;
+    const removed = typeof result.linesRemoved === 'number' ? result.linesRemoved : 0;
+    if (added > 0 || removed > 0) {
+        return added + removed;
+    }
+    return 0;
+}

package/dist/episodes/store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * File-Based Episode Store
+ *
+ * Persists work episodes to a JSON file per project.
+ * Uses an in-memory cache — all reads are synchronous, writes are async (fire-and-forget).
+ */
+import type { WorkEpisode, ProjectWorkSummary, Effort, EpisodeStore } from '@compilr-dev/agents';
+export interface FileEpisodeStoreOptions {
+    /** Path to the episodes JSON file */
+    filePath: string;
+    /** Maximum episodes to keep (oldest pruned on flush). Default: 1000 */
+    maxEpisodes?: number;
+    /** Maximum age in milliseconds for cleanup. Default: 30 days */
+    maxAgeMs?: number;
+}
+export declare class FileEpisodeStore implements EpisodeStore {
+    private readonly filePath;
+    private readonly maxEpisodes;
+    private readonly maxAgeMs;
+    private _episodes;
+    private flushPromise;
+    constructor(options: FileEpisodeStoreOptions);
+    /** Lazy-load and return the in-memory episode cache */
+    private get episodes();
+    save(episode: WorkEpisode): void;
+    saveBatch(episodes: WorkEpisode[]): void;
+    getAll(): WorkEpisode[];
+    getByFiles(files: string[]): WorkEpisode[];
+    getByAgent(agentId: string): WorkEpisode[];
+    getBySession(sessionId: string): WorkEpisode[];
+    getByTimeRange(start: string, end: string): WorkEpisode[];
+    getRecent(count: number): WorkEpisode[];
+    getWorkSummary(): ProjectWorkSummary;
+    getTotalEffort(episodes?: WorkEpisode[]): Effort;
+    cleanup(maxAgeMs?: number): number;
+    private loadFromDisk;
+    private flush;
+}

package/dist/episodes/store.js

@@ -0,0 +1,199 @@
+/**
+ * File-Based Episode Store
+ *
+ * Persists work episodes to a JSON file per project.
+ * Uses an in-memory cache — all reads are synchronous, writes are async (fire-and-forget).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { EFFORT_ORDER } from '@compilr-dev/agents';
+// =============================================================================
+// Constants
+// =============================================================================
+const DEFAULT_MAX_EPISODES = 1000;
+const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+// =============================================================================
+// Implementation
+// =============================================================================
+export class FileEpisodeStore {
+    filePath;
+    maxEpisodes;
+    maxAgeMs;
+    _episodes = null; // lazy-loaded
+    flushPromise = null;
+    constructor(options) {
+        this.filePath = options.filePath;
+        this.maxEpisodes = options.maxEpisodes ?? DEFAULT_MAX_EPISODES;
+        this.maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    }
+    /** Lazy-load and return the in-memory episode cache */
+    get episodes() {
+        if (this._episodes === null) {
+            this._episodes = this.loadFromDisk();
+        }
+        return this._episodes;
+    }
+    // ---------------------------------------------------------------------------
+    // Write methods
+    // ---------------------------------------------------------------------------
+    save(episode) {
+        this.episodes.push(episode);
+        void this.flush();
+    }
+    saveBatch(episodes) {
+        if (episodes.length === 0)
+            return;
+        this.episodes.push(...episodes);
+        void this.flush();
+    }
+    // ---------------------------------------------------------------------------
+    // Read methods (synchronous — read from cache)
+    // ---------------------------------------------------------------------------
+    getAll() {
+        return [...this.episodes];
+    }
+    getByFiles(files) {
+        const fileSet = new Set(files);
+        return this.episodes.filter((ep) => ep.files.some((f) => fileSet.has(f)));
+    }
+    getByAgent(agentId) {
+        return this.episodes.filter((ep) => ep.agentId === agentId);
+    }
+    getBySession(sessionId) {
+        return this.episodes.filter((ep) => ep.sessionId === sessionId);
+    }
+    getByTimeRange(start, end) {
+        return this.episodes.filter((ep) => ep.timestamp >= start && ep.timestamp <= end);
+    }
+    getRecent(count) {
+        return this.episodes.slice(-count);
+    }
+    getWorkSummary() {
+        const eps = this.episodes;
+        // Agent breakdown
+        const agentMap = new Map();
+        for (const ep of eps) {
+            const entry = agentMap.get(ep.agentId) ?? { count: 0, maxEffort: 'trivial', timeMs: 0 };
+            entry.count++;
+            if (EFFORT_ORDER.indexOf(ep.effort) > EFFORT_ORDER.indexOf(entry.maxEffort)) {
+                entry.maxEffort = ep.effort;
+            }
+            entry.timeMs += ep.durationMs ?? 0;
+            agentMap.set(ep.agentId, entry);
+        }
+        // Top files
+        const fileCount = new Map();
+        for (const ep of eps) {
+            for (const f of ep.files) {
+                fileCount.set(f, (fileCount.get(f) ?? 0) + 1);
+            }
+        }
+        const topFiles = [...fileCount.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([p, touchCount]) => ({ path: p, touchCount }));
+        // Uncommitted work: episodes after last git_commit episode
+        let lastCommitIdx = -1;
+        for (let i = eps.length - 1; i >= 0; i--) {
+            if (eps[i].action === 'commit') {
+                lastCommitIdx = i;
+                break;
+            }
+        }
+        const uncommittedWork = lastCommitIdx >= 0 ? eps.slice(lastCommitIdx + 1) : [...eps];
+        return {
+            episodeCount: eps.length,
+            totalEffort: this.getTotalEffort(eps),
+            timeSpentMs: eps.reduce((sum, ep) => sum + (ep.durationMs ?? 0), 0),
+            agentBreakdown: [...agentMap.entries()].map(([agentId, entry]) => ({
+                agentId,
+                episodeCount: entry.count,
+                maxEffort: entry.maxEffort,
+                timeSpentMs: entry.timeMs,
+            })),
+            topFiles,
+            uncommittedWork,
+        };
+    }
+    getTotalEffort(episodes) {
+        const eps = episodes ?? this.episodes;
+        if (eps.length === 0)
+            return 'trivial';
+        return maxEffort(eps);
+    }
+    // ---------------------------------------------------------------------------
+    // Cleanup
+    // ---------------------------------------------------------------------------
+    cleanup(maxAgeMs) {
+        const cutoff = new Date(Date.now() - (maxAgeMs ?? this.maxAgeMs)).toISOString();
+        const before = this.episodes.length;
+        this._episodes = this.episodes.filter((ep) => ep.timestamp > cutoff);
+        const removed = before - this._episodes.length;
+        if (removed > 0) {
+            void this.flush();
+        }
+        return removed;
+    }
+    // ---------------------------------------------------------------------------
+    // Internal
+    // ---------------------------------------------------------------------------
+    loadFromDisk() {
+        try {
+            if (!fs.existsSync(this.filePath))
+                return [];
+            const raw = fs.readFileSync(this.filePath, 'utf-8');
+            const data = JSON.parse(raw);
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime data from disk, version may differ
+            if (data.version === 1 && Array.isArray(data.episodes)) {
+                return data.episodes;
+            }
+            return [];
+        }
+        catch {
+            // Corrupted file — start fresh
+            return [];
+        }
+    }
+    async flush() {
+        // Coalesce concurrent flushes
+        if (this.flushPromise)
+            return this.flushPromise;
+        this.flushPromise = (async () => {
+            try {
+                const dir = path.dirname(this.filePath);
+                await fs.promises.mkdir(dir, { recursive: true });
+                // Prune to max episodes (keep most recent)
+                const eps = this.episodes;
+                const prunedEpisodes = eps.length > this.maxEpisodes ? eps.slice(-this.maxEpisodes) : eps;
+                if (prunedEpisodes !== eps) {
+                    this._episodes = prunedEpisodes;
+                }
+                const data = {
+                    version: 1,
+                    episodes: prunedEpisodes,
+                    lastCleanup: new Date().toISOString(),
+                };
+                await fs.promises.writeFile(this.filePath, JSON.stringify(data, null, 2), 'utf-8');
+            }
+            catch {
+                // Silently fail — episodes are best-effort, never crash the CLI
+            }
+            finally {
+                this.flushPromise = null;
+            }
+        })();
+        return this.flushPromise;
+    }
+}
+// =============================================================================
+// Helpers (module-private)
+// =============================================================================
+function maxEffort(episodes) {
+    let max = 'trivial';
+    for (const ep of episodes) {
+        if (EFFORT_ORDER.indexOf(ep.effort) > EFFORT_ORDER.indexOf(max)) {
+            max = ep.effort;
+        }
+    }
+    return max;
+}

package/dist/episodes/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Episodic Memory Types (CLI)
+ *
+ * Re-exports core types from @compilr-dev/agents and adds CLI-internal types.
+ */
+export type { Effort, WorkEpisode, EffortSignals, EffortWeights, EffortSummary, ProjectWorkSummary, WorkAtRisk, EpisodeStore, } from '@compilr-dev/agents';
+/**
+ * Pending tool signal — accumulated during a batch window before
+ * being rolled into a WorkEpisode.
+ */
+export interface PendingToolSignal {
+    /** Tool name that was invoked */
+    toolName: string;
+    /** Files affected by this tool call */
+    files: string[];
+    /** Lines changed, if known */
+    linesChanged: number;
+    /** Duration of the tool call in milliseconds */
+    durationMs: number;
+    /** Whether the tool call succeeded */
+    success: boolean;
+    /** ISO timestamp of the tool call */
+    timestamp: string;
+}
+/**
+ * On-disk format for the episodes JSON file.
+ */
+export interface EpisodeFile {
+    /** File format version */
+    version: 1;
+    /** All stored episodes */
+    episodes: import('@compilr-dev/agents').WorkEpisode[];
+    /** ISO timestamp of last cleanup */
+    lastCleanup: string;
+}

package/dist/episodes/types.js

@@ -0,0 +1,6 @@
+/**
+ * Episodic Memory Types (CLI)
+ *
+ * Re-exports core types from @compilr-dev/agents and adds CLI-internal types.
+ */
+export {};

package/dist/episodes/work-at-risk.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Work At Risk Query
+ *
+ * Pure function to query episodes by affected files and build a WorkAtRisk summary.
+ * Used by guardrails and rehearsal to warn about destructive operations.
+ */
+import type { EpisodeStore, WorkAtRisk } from '@compilr-dev/agents';
+/**
+ * Query episodes that touch any of the given files and build a WorkAtRisk summary.
+ * Returns null if no episodes are at risk.
+ */
+export declare function queryWorkAtRisk(store: EpisodeStore, files: string[]): WorkAtRisk | null;

package/dist/episodes/work-at-risk.js

@@ -0,0 +1,38 @@
+/**
+ * Work At Risk Query
+ *
+ * Pure function to query episodes by affected files and build a WorkAtRisk summary.
+ * Used by guardrails and rehearsal to warn about destructive operations.
+ */
+import { EFFORT_ORDER } from '@compilr-dev/agents';
+/**
+ * Query episodes that touch any of the given files and build a WorkAtRisk summary.
+ * Returns null if no episodes are at risk.
+ */
+export function queryWorkAtRisk(store, files) {
+    const episodes = store.getByFiles(files);
+    if (episodes.length === 0)
+        return null;
+    // Max effort
+    let totalEffort = 'trivial';
+    for (const ep of episodes) {
+        if (EFFORT_ORDER.indexOf(ep.effort) > EFFORT_ORDER.indexOf(totalEffort)) {
+            totalEffort = ep.effort;
+        }
+    }
+    // Agent attribution: "agentId (terminalPrefix)"
+    const seen = new Set();
+    const agentAttribution = [];
+    for (const ep of episodes) {
+        const key = `${ep.agentId} (${ep.terminalPrefix})`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            agentAttribution.push(key);
+        }
+    }
+    // Warning message
+    const fileCount = new Set(episodes.flatMap(ep => ep.files)).size;
+    const warningMessage = `⚠️ ${String(episodes.length)} episode(s) of work (effort: ${totalEffort}) ` +
+        `on ${String(fileCount)} file(s) by ${agentAttribution.join(', ')} would be affected.`;
+    return { episodes, totalEffort, agentAttribution, warningMessage };
+}

package/dist/episodes/work-summary-anchor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Work Summary Anchor
+ *
+ * Manages an auto-generated anchor that summarizes work done in the current session.
+ * Updated automatically after each episode batch is flushed.
+ */
+import type { EpisodeStore, ProjectWorkSummary } from '@compilr-dev/agents';
+import type { AnchorManager } from '@compilr-dev/sdk';
+export interface WorkSummaryAnchorConfig {
+    store: EpisodeStore;
+    projectId: string;
+    getAnchorManager: (projectId: string) => AnchorManager;
+}
+/**
+ * Build the anchor content string from the store's work summary.
+ * Returns null when there are no episodes to summarize.
+ */
+export declare function buildWorkSummaryContent(summary: ProjectWorkSummary): string | null;
+/**
+ * Update the work summary anchor for a project.
+ * Removes existing anchor (if any) and adds updated one.
+ */
+export declare function updateWorkSummaryAnchor(config: WorkSummaryAnchorConfig): void;