@compilr-dev/sdk 0.10.30 → 0.10.32

package/dist/delegation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared delegation defaults for tool result auto-summarization.
+ *
+ * `DelegationConfig` controls when large tool results get summarized
+ * by a delegate agent (instead of being inlined into the conversation
+ * context) — a per-turn token economy win that the agents library wires
+ * via the AfterToolHook.
+ *
+ * Each host (CLI, Desktop) used to keep its own copy of this config.
+ * The two had drifted: identical baselines (8000 default threshold etc.)
+ * but diverged tool overrides — Desktop had 6 extra tools tuned
+ * (run_tests, run_lint, run_build, web_fetch, artifact_get,
+ * find_references, propose_alternatives) plus a tighter `git_diff`
+ * threshold (4000 vs CLI's 6000). The baseline below converges to
+ * Desktop's set since it's the more recently tuned version, and hosts
+ * spread + override per-tool as needed.
+ *
+ * Audit ref: TODO-13.
+ */
+import type { DelegationConfig } from '@compilr-dev/agents';
+export declare const DEFAULT_DELEGATION_CONFIG: DelegationConfig;

package/dist/delegation.js

@@ -0,0 +1,49 @@
+/**
+ * Shared delegation defaults for tool result auto-summarization.
+ *
+ * `DelegationConfig` controls when large tool results get summarized
+ * by a delegate agent (instead of being inlined into the conversation
+ * context) — a per-turn token economy win that the agents library wires
+ * via the AfterToolHook.
+ *
+ * Each host (CLI, Desktop) used to keep its own copy of this config.
+ * The two had drifted: identical baselines (8000 default threshold etc.)
+ * but diverged tool overrides — Desktop had 6 extra tools tuned
+ * (run_tests, run_lint, run_build, web_fetch, artifact_get,
+ * find_references, propose_alternatives) plus a tighter `git_diff`
+ * threshold (4000 vs CLI's 6000). The baseline below converges to
+ * Desktop's set since it's the more recently tuned version, and hosts
+ * spread + override per-tool as needed.
+ *
+ * Audit ref: TODO-13.
+ */
+export const DEFAULT_DELEGATION_CONFIG = {
+    enabled: true,
+    delegationThreshold: 8000,
+    summaryMaxTokens: 800,
+    resultTTL: 600_000,
+    maxStoredResults: 50,
+    strategy: 'auto',
+    toolOverrides: {
+        // Bash often produces large output; allow a higher inline budget
+        // before summarising.
+        bash: { threshold: 12000 },
+        grep: { threshold: 4000 },
+        // Large-output tools — tighter thresholds for earlier summarisation
+        git_diff: { threshold: 4000 },
+        run_tests: { threshold: 6000 },
+        run_lint: { threshold: 4000 },
+        run_build: { threshold: 6000 },
+        web_fetch: { threshold: 6000 },
+        artifact_get: { threshold: 6000 },
+        find_references: { threshold: 4000 },
+        // Disable delegation on small / interactive / read-only tools where
+        // the round-trip cost would exceed the saving.
+        get_tool_info: { enabled: false },
+        list_tools: { enabled: false },
+        ask_user: { enabled: false },
+        ask_user_simple: { enabled: false },
+        propose_alternatives: { enabled: false },
+        todo_read: { enabled: false },
+    },
+};

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/index.d.ts

@@ -81,6 +81,9 @@ export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createL
 export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, PermissionHandlerResponse, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
 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 { 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

@@ -198,6 +198,14 @@ AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, Abor
 // =============================================================================
 export { DEFAULT_PERMISSION_RULES, findMatchingRule, permissionModeLabel, permissionLevelLabel, } from './permissions.js';
 // =============================================================================
+// Shared Delegation Config Defaults
+// =============================================================================
+export { DEFAULT_DELEGATION_CONFIG } from './delegation.js';
+// =============================================================================
+// Episodes — Work History Tracking
+// =============================================================================
+export { FileEpisodeStore, EpisodeRecorder, isSignificantWork, extractAffectedFiles, extractLinesChanged, queryWorkAtRisk, buildWorkSummaryContent, updateWorkSummaryAnchor, } from './episodes/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.30",
+  "version": "0.10.32",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",