@compilr-dev/sdk 0.10.31 → 0.10.33

package/dist/episodes/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Episodes Module
+ *
+ * Work history tracking — file-based persistence + automatic
+ * recording via an AfterToolHook. Both CLI and Desktop consume these
+ * exports; the global episode store helpers (setGlobalEpisodeStore /
+ * getGlobalEpisodeStore) intentionally remain CLI-side because the
+ * "global singleton" pattern is CLI-specific. Desktop wires the store
+ * via direct dependency injection through the IEpisodeService.
+ */
+export { FileEpisodeStore } from './store.js';
+export type { FileEpisodeStoreOptions } from './store.js';
+export { EpisodeRecorder } from './recorder.js';
+export type { EpisodeRecorderConfig } from './recorder.js';
+export { isSignificantWork, extractAffectedFiles, extractLinesChanged, } from './significant-work.js';
+export { queryWorkAtRisk } from './work-at-risk.js';
+export { buildWorkSummaryContent, updateWorkSummaryAnchor } from './work-summary-anchor.js';
+export type { WorkSummaryAnchorConfig } from './work-summary-anchor.js';
+export type { PendingToolSignal, EpisodeFile } from './types.js';

package/dist/episodes/index.js

@@ -0,0 +1,20 @@
+/**
+ * Episodes Module
+ *
+ * Work history tracking — file-based persistence + automatic
+ * recording via an AfterToolHook. Both CLI and Desktop consume these
+ * exports; the global episode store helpers (setGlobalEpisodeStore /
+ * getGlobalEpisodeStore) intentionally remain CLI-side because the
+ * "global singleton" pattern is CLI-specific. Desktop wires the store
+ * via direct dependency injection through the IEpisodeService.
+ */
+// Store
+export { FileEpisodeStore } from './store.js';
+// Recorder
+export { EpisodeRecorder } from './recorder.js';
+// Significant work detection
+export { isSignificantWork, extractAffectedFiles, extractLinesChanged, } from './significant-work.js';
+// Work-at-risk query (used by guardrails / rehearsal)
+export { queryWorkAtRisk } from './work-at-risk.js';
+// Work summary anchor (auto-updates a session anchor with cumulative work)
+export { buildWorkSummaryContent, updateWorkSummaryAnchor } from './work-summary-anchor.js';

package/dist/episodes/recorder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Episode Recorder
+ *
+ * Collects tool call signals via an AfterToolHook, batches them within
+ * a time window, and persists as WorkEpisode records.
+ */
+import type { AfterToolHook, Effort, EpisodeStore } from '@compilr-dev/agents';
+export interface EpisodeRecorderConfig {
+    /** Episode store for persistence */
+    store: EpisodeStore;
+    /** Agent ID (e.g., 'default', 'backend') */
+    agentId: string;
+    /** Terminal/window session prefix (first 8 chars). Hosts that don't
+     *  have a terminal can pass any short stable identifier (e.g. window id). */
+    terminalPrefix: string;
+    /** Session ID for grouping */
+    sessionId: string;
+    /** Enable automatic recording via hook (default: true) */
+    autoRecord?: boolean;
+    /** Minimum effort level to record (default: 'low') */
+    minEffortToRecord?: Effort;
+    /** Batch window in milliseconds (default: 5000) */
+    batchWindowMs?: number;
+    /** Called after each batch is flushed as a WorkEpisode */
+    onBatchFlushed?: () => void;
+}
+export declare class EpisodeRecorder {
+    private readonly store;
+    private readonly agentId;
+    private readonly terminalPrefix;
+    private readonly sessionId;
+    private readonly autoRecord;
+    private readonly minEffortToRecord;
+    private readonly batchWindowMs;
+    private readonly onBatchFlushed?;
+    private pendingSignals;
+    private batchTimer;
+    private batchStartTime;
+    constructor(config: EpisodeRecorderConfig);
+    /**
+     * Create an AfterToolHook for observing tool calls.
+     * Always returns undefined (observation only — never modifies results).
+     */
+    createHook(): AfterToolHook;
+    /**
+     * Force-flush all pending signals as a WorkEpisode.
+     * Called on shutdown to avoid losing data.
+     */
+    flush(): void;
+    private scheduleBatch;
+    private buildAndSaveEpisode;
+}

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,26 @@
+/**
+ * Significant Work Detection
+ *
+ * Determines which tool calls represent meaningful work (writes, edits,
+ * commits, runs) versus read-only exploration (reads, greps, globs).
+ *
+ * Uses hardcoded tool-name strings rather than a TOOL_NAMES constant so
+ * this module has zero dependency on any host's tool registry. Both
+ * agents-coding tools and platform tools use stable canonical names.
+ */
+/**
+ * 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,59 @@
+/**
+ * Significant Work Detection
+ *
+ * Determines which tool calls represent meaningful work (writes, edits,
+ * commits, runs) versus read-only exploration (reads, greps, globs).
+ *
+ * Uses hardcoded tool-name strings rather than a TOOL_NAMES constant so
+ * this module has zero dependency on any host's tool registry. Both
+ * agents-coding tools and platform tools use stable canonical names.
+ */
+const SIGNIFICANT_TOOLS = new Set([
+    'write_file',
+    'edit',
+    'git_commit',
+    'git_stash',
+    'run_tests',
+    'run_lint',
+    '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 === 'write_file' && typeof input.path === 'string') {
+        return [input.path];
+    }
+    if (toolName === '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,203 @@
+/**
+ * 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 host
+            }
+            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,36 @@
+/**
+ * Episode Module Internal Types
+ *
+ * Re-exports core types from `@compilr-dev/agents` and adds the
+ * internal types needed by the file-based store and the recorder.
+ */
+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,7 @@
+/**
+ * Episode Module Internal Types
+ *
+ * Re-exports core types from `@compilr-dev/agents` and adds the
+ * internal types needed by the file-based store and the recorder.
+ */
+export {};

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

@@ -0,0 +1,13 @@
+/**
+ * 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,39 @@
+/**
+ * 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 (wire via `EpisodeRecorderConfig.onBatchFlushed`).
+ */
+import type { EpisodeStore, ProjectWorkSummary, AnchorManager } from '@compilr-dev/agents';
+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;

package/dist/episodes/work-summary-anchor.js

@@ -0,0 +1,77 @@
+/**
+ * Work Summary Anchor
+ *
+ * Manages an auto-generated anchor that summarizes work done in the
+ * current session. Updated automatically after each episode batch is
+ * flushed (wire via `EpisodeRecorderConfig.onBatchFlushed`).
+ */
+const ANCHOR_TAG = 'episode-work-summary';
+/**
+ * Build the anchor content string from the store's work summary.
+ * Returns null when there are no episodes to summarize.
+ */
+export function buildWorkSummaryContent(summary) {
+    if (summary.episodeCount === 0)
+        return null;
+    const lines = ['[Session Work Summary]'];
+    lines.push(`Episodes: ${String(summary.episodeCount)}, Effort: ${summary.totalEffort}, Time: ${formatMs(summary.timeSpentMs)}`);
+    if (summary.agentBreakdown.length > 0) {
+        const agents = summary.agentBreakdown
+            .map((a) => `${a.agentId}(${String(a.episodeCount)})`)
+            .join(', ');
+        lines.push(`Agents: ${agents}`);
+    }
+    if (summary.topFiles.length > 0) {
+        const files = summary.topFiles
+            .slice(0, 5)
+            .map((f) => f.path.split('/').pop() ?? f.path)
+            .join(', ');
+        lines.push(`Top files: ${files}`);
+    }
+    if (summary.uncommittedWork.length > 0) {
+        lines.push(`Uncommitted: ${String(summary.uncommittedWork.length)} episode(s)`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Update the work summary anchor for a project.
+ * Removes existing anchor (if any) and adds updated one.
+ */
+export function updateWorkSummaryAnchor(config) {
+    const { store, projectId, getAnchorManager: getManager } = config;
+    const manager = getManager(projectId);
+    const summary = store.getWorkSummary();
+    const content = buildWorkSummaryContent(summary);
+    // Remove existing work summary anchor
+    const existing = manager.getAll().find((a) => a.tags?.includes(ANCHOR_TAG));
+    if (existing)
+        manager.remove(existing.id);
+    // Add new anchor if there's content
+    if (content) {
+        manager.add({
+            content,
+            priority: 'info',
+            scope: 'persistent',
+            tags: [ANCHOR_TAG],
+            projectId,
+        });
+    }
+}
+/**
+ * Format milliseconds to a human-readable string (e.g., "2h 15m", "45s").
+ */
+function formatMs(ms) {
+    if (ms < 1000)
+        return `${String(ms)}ms`;
+    const totalSeconds = Math.floor(ms / 1000);
+    if (totalSeconds < 60)
+        return `${String(totalSeconds)}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    if (minutes < 60)
+        return `${String(minutes)}m`;
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return remainingMinutes > 0
+        ? `${String(hours)}h ${String(remainingMinutes)}m`
+        : `${String(hours)}h`;
+}

package/dist/flow-runner/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Flow Runner — Public API.
+ *
+ * Pure state-machine helpers for the `build_interactive_flow` DSL.
+ * Hosts hold the runtime state and call these helpers for transitions
+ * (next-resolution, branch evaluation, backtrack). The helpers are
+ * pure functions with no framework dependencies.
+ *
+ * See `runner.ts` for the implementation rationale and spec link.
+ */
+export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, applyBacktrack, } from './runner.js';
+export type { BacktrackResult } from './runner.js';

package/dist/flow-runner/index.js

@@ -0,0 +1,11 @@
+/**
+ * Flow Runner — Public API.
+ *
+ * Pure state-machine helpers for the `build_interactive_flow` DSL.
+ * Hosts hold the runtime state and call these helpers for transitions
+ * (next-resolution, branch evaluation, backtrack). The helpers are
+ * pure functions with no framework dependencies.
+ *
+ * See `runner.ts` for the implementation rationale and spec link.
+ */
+export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, applyBacktrack, } from './runner.js';

package/dist/flow-runner/runner.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Flow Runner — Pure state-machine helpers for `build_interactive_flow`.
+ *
+ * Hosts (Desktop, CLI) hold the runtime state in whatever container fits
+ * their UI framework (React useState, BaseOverlayV2 state object, etc.)
+ * and call these helpers to compute transitions. The helpers are
+ * intentionally pure — no React, no DOM, no I/O — so they're trivially
+ * testable and reusable across renderers.
+ *
+ * Code lifted verbatim from `compilr-dev-desktop/src/renderer/src/
+ * components/flow/state/useFlowState.ts:297-409` (lines 240-272 also
+ * inform `applyBacktrack`). Desktop's `useFlowState` should re-export
+ * these in a follow-up commit; until then it keeps its local copies
+ * and these definitions are the canonical SDK ones.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-cli/interactive-flow-cli-spec.md
+ */
+import type { AnswerValue, BranchCondition, Flow, NextRef, NodeId, QuestionNode } from '../tools/interactive-flow-tool.js';
+/**
+ * Result of an `applyBacktrack` call: the new path + the answer maps
+ * with everything-after-the-restored-node wiped (per spec §4).
+ */
+export interface BacktrackResult {
+    path: NodeId[];
+    answers: Record<NodeId, AnswerValue>;
+    answerLabels: Record<NodeId, AnswerValue>;
+}
+/**
+ * Resolve a `NextRef` (+ optional answer that was just collected) to the
+ * single target nodeId. Returns `undefined` when the ref can't resolve —
+ * caller treats that as malformed-flow.
+ *
+ * Behaviour:
+ *   - String ref: returned verbatim.
+ *   - `{ byAnswer: { ... }, default }`:
+ *     - For a scalar answer, look it up in `byAnswer`.
+ *     - For a multi-select array, the first matching key wins.
+ *     - Fall back to `default` if nothing matched.
+ */
+export declare function resolveNext(next: NextRef, answer?: AnswerValue): NodeId | undefined;
+/**
+ * Evaluate a single branch condition against the collected answer map.
+ * Returns true iff the condition matches.
+ *
+ *   - `equals`: scalar string equality
+ *   - `includes`:
+ *       - scalar string: equality (treat the answer as a 1-element list)
+ *       - array (multi): true if the array contains the value
+ *   - `notEquals`: scalar string inequality
+ */
+export declare function evaluateBranchCondition(condition: BranchCondition, answers: Record<NodeId, AnswerValue>): boolean;
+/**
+ * Walk past any leading branch nodes from the tip of `path`, appending
+ * each branch visited and finally appending the next non-branch node
+ * we land on. Returns the new path.
+ *
+ * The branch nodes ARE recorded in path (so the agent sees the routing
+ * trail), but they're never the current node when this function returns
+ * — the caller can safely render `path[path.length - 1]`.
+ *
+ * Safety: bounded by `Object.keys(flow.nodes).length + 1` to prevent
+ * infinite loops on malformed cyclic branches (SDK `validateFlow`
+ * should prevent this, but defensive).
+ */
+export declare function walkPastBranches(flow: Flow, path: NodeId[], answers: Record<NodeId, AnswerValue>): NodeId[];
+/**
+ * Given a question node and the chosen answer, return the human-readable
+ * label(s). For `text` mode the label IS the answer. For `single` and
+ * `proposal`, look up the choice/option with the matching id. For
+ * `multi`, return an array of labels.
+ *
+ * Falls back to the answer id itself if no matching choice is found —
+ * keeps `answerLabels` populated even when validation didn't catch a
+ * mismatch.
+ */
+export declare function lookupLabel(node: QuestionNode, answer: AnswerValue): AnswerValue;
+/**
+ * Compute the result of a backtrack ("go back one user-visible step").
+ *
+ * Pops path entries until the previous question/info node is exposed,
+ * then wipes every answer (and label) recorded at or after that node
+ * — per spec §4: "answers wiped downstream of any backtrack point".
+ *
+ * Returns `null` when there's no prior user-visible node (i.e. the
+ * user is already on `startNode`); the caller should treat that as a
+ * no-op (or, depending on UI, as a cancel signal).
+ */
+export declare function applyBacktrack(flow: Flow, path: NodeId[], answers: Record<NodeId, AnswerValue>, answerLabels: Record<NodeId, AnswerValue>): BacktrackResult | null;

package/dist/flow-runner/runner.js

@@ -0,0 +1,212 @@
+/**
+ * Flow Runner — Pure state-machine helpers for `build_interactive_flow`.
+ *
+ * Hosts (Desktop, CLI) hold the runtime state in whatever container fits
+ * their UI framework (React useState, BaseOverlayV2 state object, etc.)
+ * and call these helpers to compute transitions. The helpers are
+ * intentionally pure — no React, no DOM, no I/O — so they're trivially
+ * testable and reusable across renderers.
+ *
+ * Code lifted verbatim from `compilr-dev-desktop/src/renderer/src/
+ * components/flow/state/useFlowState.ts:297-409` (lines 240-272 also
+ * inform `applyBacktrack`). Desktop's `useFlowState` should re-export
+ * these in a follow-up commit; until then it keeps its local copies
+ * and these definitions are the canonical SDK ones.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-cli/interactive-flow-cli-spec.md
+ */
+// =============================================================================
+// Pure helpers
+// =============================================================================
+/**
+ * Resolve a `NextRef` (+ optional answer that was just collected) to the
+ * single target nodeId. Returns `undefined` when the ref can't resolve —
+ * caller treats that as malformed-flow.
+ *
+ * Behaviour:
+ *   - String ref: returned verbatim.
+ *   - `{ byAnswer: { ... }, default }`:
+ *     - For a scalar answer, look it up in `byAnswer`.
+ *     - For a multi-select array, the first matching key wins.
+ *     - Fall back to `default` if nothing matched.
+ */
+export function resolveNext(next, answer) {
+    if (typeof next === 'string')
+        return next;
+    // Defensive against malformed runtime input (the test fixture passes
+    // null/undefined). TS proves this can't happen if you respect the
+    // declared type, but consumers may not.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!next || typeof next !== 'object')
+        return undefined;
+    // byAnswer map
+    const answerKey = typeof answer === 'string' ? answer : undefined;
+    if (answerKey !== undefined && answerKey in next.byAnswer) {
+        return next.byAnswer[answerKey];
+    }
+    // multi-select answer — first matching key wins
+    if (Array.isArray(answer)) {
+        for (const a of answer) {
+            if (a in next.byAnswer)
+                return next.byAnswer[a];
+        }
+    }
+    return next.default;
+}
+/**
+ * Evaluate a single branch condition against the collected answer map.
+ * Returns true iff the condition matches.
+ *
+ *   - `equals`: scalar string equality
+ *   - `includes`:
+ *       - scalar string: equality (treat the answer as a 1-element list)
+ *       - array (multi): true if the array contains the value
+ *   - `notEquals`: scalar string inequality
+ */
+export function evaluateBranchCondition(condition, answers) {
+    const value = answers[condition.questionId];
+    // Defensive — Record<K,V>[K] is `V` (not `V|undefined`) in non-strict-
+    // index mode, but the question may simply not have been answered yet.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (value === undefined)
+        return false;
+    if ('equals' in condition) {
+        return typeof value === 'string' && value === condition.equals;
+    }
+    if ('includes' in condition) {
+        if (typeof value === 'string')
+            return value === condition.includes;
+        return value.includes(condition.includes);
+    }
+    if ('notEquals' in condition) {
+        return typeof value === 'string' && value !== condition.notEquals;
+    }
+    return false;
+}
+/**
+ * Walk past any leading branch nodes from the tip of `path`, appending
+ * each branch visited and finally appending the next non-branch node
+ * we land on. Returns the new path.
+ *
+ * The branch nodes ARE recorded in path (so the agent sees the routing
+ * trail), but they're never the current node when this function returns
+ * — the caller can safely render `path[path.length - 1]`.
+ *
+ * Safety: bounded by `Object.keys(flow.nodes).length + 1` to prevent
+ * infinite loops on malformed cyclic branches (SDK `validateFlow`
+ * should prevent this, but defensive).
+ */
+export function walkPastBranches(flow, path, answers) {
+    const result = [...path];
+    let guard = Object.keys(flow.nodes).length + 1;
+    while (guard-- > 0) {
+        const tip = result[result.length - 1];
+        const node = flow.nodes[tip];
+        // Defensive — `flow.nodes[tip]` is typed as `Node` but the runtime
+        // value may be undefined if a NextRef pointed to a non-existent id.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!node || node.type !== 'branch')
+            return result;
+        // Evaluate routes in order; first match wins
+        let target = node.default;
+        for (const route of node.routes) {
+            if (evaluateBranchCondition(route.when, answers)) {
+                target = route.goto;
+                break;
+            }
+        }
+        if (!target || !(target in flow.nodes))
+            return result; // malformed; stop walking
+        result.push(target);
+    }
+    return result;
+}
+/**
+ * Given a question node and the chosen answer, return the human-readable
+ * label(s). For `text` mode the label IS the answer. For `single` and
+ * `proposal`, look up the choice/option with the matching id. For
+ * `multi`, return an array of labels.
+ *
+ * Falls back to the answer id itself if no matching choice is found —
+ * keeps `answerLabels` populated even when validation didn't catch a
+ * mismatch.
+ */
+export function lookupLabel(node, answer) {
+    const mode = node.input.mode;
+    if (mode === 'text') {
+        return answer;
+    }
+    if (mode === 'single') {
+        const id = typeof answer === 'string' ? answer : answer[0];
+        // Defensive — empty array answer
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (id === undefined)
+            return answer;
+        const found = node.input.choices.find((c) => c.id === id);
+        return found?.label ?? id;
+    }
+    if (mode === 'multi') {
+        const ids = Array.isArray(answer) ? answer : [answer];
+        return ids.map((id) => {
+            if (node.input.mode !== 'multi')
+                return id;
+            const found = node.input.choices.find((c) => c.id === id);
+            return found?.label ?? id;
+        });
+    }
+    // mode === 'proposal' — narrowed by the if-chain above
+    const id = typeof answer === 'string' ? answer : answer[0];
+    // Defensive — empty array answer
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (id === undefined)
+        return answer;
+    const found = node.input.options.find((o) => o.id === id);
+    return found?.label ?? id;
+}
+/**
+ * Compute the result of a backtrack ("go back one user-visible step").
+ *
+ * Pops path entries until the previous question/info node is exposed,
+ * then wipes every answer (and label) recorded at or after that node
+ * — per spec §4: "answers wiped downstream of any backtrack point".
+ *
+ * Returns `null` when there's no prior user-visible node (i.e. the
+ * user is already on `startNode`); the caller should treat that as a
+ * no-op (or, depending on UI, as a cancel signal).
+ */
+export function applyBacktrack(flow, path, answers, answerLabels) {
+    let targetIdx = path.length - 1;
+    for (let i = path.length - 2; i >= 0; i--) {
+        const id = path[i];
+        const node = flow.nodes[id];
+        // Defensive against missing-node entries in path (shouldn't happen but
+        // path entries originate from runtime, not the type system)
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (node && node.type !== 'branch') {
+            targetIdx = i;
+            break;
+        }
+    }
+    if (targetIdx === path.length - 1)
+        return null; // no prior visible node
+    const newPath = path.slice(0, targetIdx + 1);
+    // Wipe answers (and labels) for nodes from targetIdx onward (inclusive —
+    // the user is re-entering that node). Build fresh maps rather than
+    // `delete` keys (lint forbids dynamic delete).
+    const wipedIds = new Set(path.slice(targetIdx));
+    const wipedAnswers = {};
+    for (const [id, val] of Object.entries(answers)) {
+        if (!wipedIds.has(id))
+            wipedAnswers[id] = val;
+    }
+    const wipedLabels = {};
+    for (const [id, val] of Object.entries(answerLabels)) {
+        if (!wipedIds.has(id))
+            wipedLabels[id] = val;
+    }
+    return {
+        path: newPath,
+        answers: wipedAnswers,
+        answerLabels: wipedLabels,
+    };
+}

package/dist/index.d.ts

@@ -82,6 +82,10 @@ export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput,
 export { DEFAULT_PERMISSION_RULES, findMatchingRule, permissionModeLabel, permissionLevelLabel, } from './permissions.js';
 export type { PermissionRule, PermissionMode, PermissionLevel } from './permissions.js';
 export { DEFAULT_DELEGATION_CONFIG } from './delegation.js';
+export { FileEpisodeStore, EpisodeRecorder, isSignificantWork, extractAffectedFiles, extractLinesChanged, queryWorkAtRisk, buildWorkSummaryContent, updateWorkSummaryAnchor, } from './episodes/index.js';
+export type { FileEpisodeStoreOptions, EpisodeRecorderConfig, WorkSummaryAnchorConfig, PendingToolSignal, EpisodeFile, } from './episodes/index.js';
+export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, applyBacktrack, } from './flow-runner/index.js';
+export type { BacktrackResult } from './flow-runner/index.js';
 export { readMCPConfigFile, writeMCPConfigFile, resolveServerEntry, loadMCPServers, saveMCPServerEntry, deleteMCPServerEntry, getServerNames, } from './mcp-config.js';
 export type { MCPServerEntry, MCPConfigFile, ResolvedMCPServer } from './mcp-config.js';
 export { generateProject, isGitConfigured, generateCompilrMd, generateConfigJson, generateReadmeMd, generateCodingStandardsMd, generatePackageJson, generateTsconfig, generateGitignore, generateCompilrMdForImport, detectProjectInfo, detectGitInfo, prettifyName, getLanguageLabel, getFrameworkLabel, validateImportPath, isValidProjectName, projectExists, TECH_STACK_LABELS, CODING_STANDARDS_LABELS, REPO_PATTERN_LABELS, WORKFLOW_VERSION, } from './project-generator/index.js';

package/dist/index.js

@@ -202,6 +202,14 @@ export { DEFAULT_PERMISSION_RULES, findMatchingRule, permissionModeLabel, permis
 // =============================================================================
 export { DEFAULT_DELEGATION_CONFIG } from './delegation.js';
 // =============================================================================
+// Episodes — Work History Tracking
+// =============================================================================
+export { FileEpisodeStore, EpisodeRecorder, isSignificantWork, extractAffectedFiles, extractLinesChanged, queryWorkAtRisk, buildWorkSummaryContent, updateWorkSummaryAnchor, } from './episodes/index.js';
+// =============================================================================
+// Flow Runner — `build_interactive_flow` State Machine Helpers
+// =============================================================================
+export { resolveNext, evaluateBranchCondition, walkPastBranches, lookupLabel, applyBacktrack, } from './flow-runner/index.js';
+// =============================================================================
 // Shared MCP Configuration
 // =============================================================================
 export { readMCPConfigFile, writeMCPConfigFile, resolveServerEntry, loadMCPServers, saveMCPServerEntry, deleteMCPServerEntry, getServerNames, } from './mcp-config.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.10.31",
+  "version": "0.10.33",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",