@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/db/schema.d.ts

@@ -4,8 +4,8 @@
  * Based on: db-workflow-architecture.md
  * Database: SQLite via better-sqlite3
  */
-export declare const SCHEMA_VERSION = 1;
-export declare const SCHEMA_SQL = "\n-- Schema version tracking\nCREATE TABLE IF NOT EXISTS schema_version (\n  version INTEGER PRIMARY KEY,\n  applied_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n\n-- Projects table\nCREATE TABLE IF NOT EXISTS projects (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  name TEXT UNIQUE NOT NULL,\n  display_name TEXT NOT NULL,\n  description TEXT,\n\n  -- Project type and status\n  type TEXT DEFAULT 'general',\n  status TEXT DEFAULT 'active',\n\n  -- Paths\n  path TEXT NOT NULL,\n  docs_path TEXT,\n  repo_pattern TEXT DEFAULT 'single',\n\n  -- Tech stack (auto-detected)\n  language TEXT,\n  framework TEXT,\n  package_manager TEXT,\n  runtime_version TEXT,\n\n  -- Commands (JSON)\n  commands TEXT,\n\n  -- Git info\n  git_remote TEXT,\n  git_branch TEXT DEFAULT 'main',\n\n  -- Workflow\n  workflow_mode TEXT DEFAULT 'flexible',\n  lifecycle_state TEXT DEFAULT 'setup',\n  current_item_id TEXT,\n\n  -- Context & Metadata (JSON)\n  last_context TEXT,\n  metadata TEXT,\n\n  -- Timestamps\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  last_activity_at DATETIME\n);\n\n-- Work items (backlog items, tasks, bugs)\nCREATE TABLE IF NOT EXISTS work_items (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n\n  -- Identity\n  item_number INTEGER NOT NULL,\n  item_id TEXT NOT NULL,\n\n  -- Classification\n  type TEXT NOT NULL,\n  status TEXT DEFAULT 'backlog',\n  priority TEXT DEFAULT 'medium',\n\n  -- Guided mode: current step in work item cycle\n  guided_step TEXT,\n\n  -- Content\n  title TEXT NOT NULL,\n  description TEXT,\n\n  -- Effort tracking\n  estimated_effort TEXT,\n  actual_minutes INTEGER,\n\n  -- Completion\n  completed_at DATETIME,\n  completed_by TEXT,\n  commit_hash TEXT,\n\n  -- Timestamps\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  UNIQUE (project_id, item_id)\n);\n\n-- Project documents (PRD, architecture, etc.)\nCREATE TABLE IF NOT EXISTS project_documents (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n\n  doc_type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  content TEXT NOT NULL,\n\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\n\n-- Work item history (audit trail)\nCREATE TABLE IF NOT EXISTS work_item_history (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  work_item_id INTEGER NOT NULL,\n  project_id INTEGER NOT NULL,\n\n  action TEXT NOT NULL,\n  old_value TEXT,\n  new_value TEXT,\n  notes TEXT,\n\n  changed_by TEXT,\n  changed_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_projects_path ON projects(path);\nCREATE INDEX IF NOT EXISTS idx_projects_docs_path ON projects(docs_path);\nCREATE INDEX IF NOT EXISTS idx_projects_status ON projects(status);\n\nCREATE INDEX IF NOT EXISTS idx_work_items_project ON work_items(project_id);\nCREATE INDEX IF NOT EXISTS idx_work_items_status ON work_items(status);\nCREATE INDEX IF NOT EXISTS idx_work_items_priority ON work_items(priority);\n\nCREATE INDEX IF NOT EXISTS idx_project_documents_project ON project_documents(project_id);\nCREATE INDEX IF NOT EXISTS idx_project_documents_type ON project_documents(doc_type);\n\nCREATE INDEX IF NOT EXISTS idx_work_item_history_item ON work_item_history(work_item_id);\n";
+export declare const SCHEMA_VERSION = 6;
+export declare const SCHEMA_SQL = "\n-- Schema version tracking\nCREATE TABLE IF NOT EXISTS schema_version (\n  version INTEGER PRIMARY KEY,\n  applied_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n\n-- Projects table\nCREATE TABLE IF NOT EXISTS projects (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  name TEXT UNIQUE NOT NULL,\n  display_name TEXT NOT NULL,\n  description TEXT,\n\n  -- Project type and status\n  type TEXT DEFAULT 'general',\n  status TEXT DEFAULT 'active',\n\n  -- Paths\n  path TEXT NOT NULL,\n  docs_path TEXT,\n  repo_pattern TEXT DEFAULT 'single',\n\n  -- Tech stack (auto-detected)\n  language TEXT,\n  framework TEXT,\n  package_manager TEXT,\n  runtime_version TEXT,\n\n  -- Commands (JSON)\n  commands TEXT,\n\n  -- Git info\n  git_remote TEXT,\n  git_branch TEXT DEFAULT 'main',\n\n  -- Workflow\n  workflow_mode TEXT DEFAULT 'flexible',\n  lifecycle_state TEXT DEFAULT 'setup',\n  current_item_id TEXT,\n\n  -- Context & Metadata (JSON)\n  last_context TEXT,\n  metadata TEXT,\n\n  -- Timestamps\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  last_activity_at DATETIME\n);\n\n-- Work items (backlog items, tasks, bugs)\nCREATE TABLE IF NOT EXISTS work_items (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n\n  -- Identity\n  item_number INTEGER NOT NULL,\n  item_id TEXT NOT NULL,\n\n  -- Classification\n  type TEXT NOT NULL,\n  status TEXT DEFAULT 'backlog',\n  priority TEXT DEFAULT 'medium',\n\n  -- Guided mode: current step in work item cycle\n  guided_step TEXT,\n\n  -- Ownership (for multi-agent teams)\n  owner TEXT,\n\n  -- Content\n  title TEXT NOT NULL,\n  description TEXT,\n\n  -- Effort tracking\n  estimated_effort TEXT,\n  actual_minutes INTEGER,\n\n  -- Completion\n  completed_at DATETIME,\n  completed_by TEXT,\n  commit_hash TEXT,\n\n  -- Timestamps\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  UNIQUE (project_id, item_id)\n);\n\n-- Project documents (PRD, architecture, plans, etc.)\nCREATE TABLE IF NOT EXISTS project_documents (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  project_id INTEGER NOT NULL,\n\n  doc_type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  content TEXT NOT NULL,\n\n  -- Plan-specific fields (NULL for non-plan documents)\n  status TEXT,\n  work_item_id INTEGER,\n\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE SET NULL\n);\n\n-- Work item history (audit trail)\nCREATE TABLE IF NOT EXISTS work_item_history (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  work_item_id INTEGER NOT NULL,\n  project_id INTEGER NOT NULL,\n\n  action TEXT NOT NULL,\n  old_value TEXT,\n  new_value TEXT,\n  notes TEXT,\n\n  changed_by TEXT,\n  changed_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n\n  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\n\n-- Indexes for common queries\nCREATE INDEX IF NOT EXISTS idx_projects_path ON projects(path);\nCREATE INDEX IF NOT EXISTS idx_projects_docs_path ON projects(docs_path);\nCREATE INDEX IF NOT EXISTS idx_projects_status ON projects(status);\n\nCREATE INDEX IF NOT EXISTS idx_work_items_project ON work_items(project_id);\nCREATE INDEX IF NOT EXISTS idx_work_items_status ON work_items(status);\nCREATE INDEX IF NOT EXISTS idx_work_items_priority ON work_items(priority);\nCREATE INDEX IF NOT EXISTS idx_work_items_owner ON work_items(owner);\n\nCREATE INDEX IF NOT EXISTS idx_project_documents_project ON project_documents(project_id);\nCREATE INDEX IF NOT EXISTS idx_project_documents_type ON project_documents(doc_type);\nCREATE INDEX IF NOT EXISTS idx_project_documents_status ON project_documents(status);\nCREATE INDEX IF NOT EXISTS idx_project_documents_work_item ON project_documents(work_item_id);\n\nCREATE INDEX IF NOT EXISTS idx_work_item_history_item ON work_item_history(work_item_id);\n\n-- Terminal sessions (multi-terminal awareness)\nCREATE TABLE IF NOT EXISTS terminal_sessions (\n  id TEXT PRIMARY KEY,\n  project_id INTEGER,\n  pid INTEGER NOT NULL,\n  tty_path TEXT,\n  label TEXT,\n  started_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  last_heartbeat DATETIME DEFAULT CURRENT_TIMESTAMP,\n  active_agent TEXT DEFAULT 'default',\n  agents_json TEXT DEFAULT '[]',\n  status TEXT DEFAULT 'active',\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE SET NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_project ON terminal_sessions(project_id);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_status ON terminal_sessions(status);\n\n-- File locks (multi-terminal file lock awareness)\nCREATE TABLE IF NOT EXISTS file_locks (\n  path TEXT NOT NULL,\n  project_id INTEGER NOT NULL,\n  session_id TEXT NOT NULL,\n  agent_id TEXT NOT NULL,\n  locked_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  PRIMARY KEY (path, project_id),\n  FOREIGN KEY (session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE\n);\n\nCREATE INDEX IF NOT EXISTS idx_file_locks_session ON file_locks(session_id);\n\n-- Session notifications (cross-session notifications)\nCREATE TABLE IF NOT EXISTS session_notifications (\n  id TEXT PRIMARY KEY,\n  project_id INTEGER NOT NULL,\n  from_session_id TEXT NOT NULL,\n  to_session_id TEXT,\n  type TEXT NOT NULL,\n  title TEXT NOT NULL,\n  message TEXT,\n  payload_json TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  read_at DATETIME,\n  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,\n  FOREIGN KEY (from_session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE\n);\n\nCREATE INDEX IF NOT EXISTS idx_session_notifications_project ON session_notifications(project_id);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_to_session ON session_notifications(to_session_id);\nCREATE INDEX IF NOT EXISTS idx_session_notifications_unread ON session_notifications(read_at);\n";
 export interface ProjectRecord {
     id: number;
     name: string;
@@ -41,6 +41,7 @@ export interface WorkItemRecord {
     status: string;
     priority: string;
     guided_step: string | null;
+    owner: string | null;
     title: string;
     description: string | null;
     estimated_effort: string | null;
@@ -57,6 +58,8 @@ export interface ProjectDocumentRecord {
     doc_type: string;
     title: string;
     content: string;
+    status: string | null;
+    work_item_id: number | null;
     created_at: string;
     updated_at: string;
 }
@@ -80,4 +83,38 @@ export type WorkItemType = 'feature' | 'bug' | 'tech-debt' | 'chore';
 export type WorkItemStatus = 'backlog' | 'in_progress' | 'completed' | 'skipped';
 export type WorkItemPriority = 'critical' | 'high' | 'medium' | 'low';
 export type GuidedStep = 'plan' | 'implement' | 'test' | 'commit' | 'review';
-export type DocumentType = 'prd' | 'architecture' | 'design' | 'notes';
+export type DocumentType = 'prd' | 'architecture' | 'design' | 'notes' | 'plan';
+export type PlanStatus = 'draft' | 'approved' | 'in_progress' | 'completed' | 'abandoned';
+export type TerminalSessionStatus = 'active' | 'stale' | 'dead';
+export interface TerminalSessionRecord {
+    id: string;
+    project_id: number | null;
+    pid: number;
+    tty_path: string | null;
+    label: string | null;
+    started_at: string;
+    last_heartbeat: string;
+    active_agent: string;
+    agents_json: string;
+    status: TerminalSessionStatus;
+}
+export interface FileLockRecord {
+    path: string;
+    project_id: number;
+    session_id: string;
+    agent_id: string;
+    locked_at: string;
+}
+export type SessionNotificationType = 'pending_request' | 'agent_finished';
+export interface SessionNotificationRecord {
+    id: string;
+    project_id: number;
+    from_session_id: string;
+    to_session_id: string | null;
+    type: SessionNotificationType;
+    title: string;
+    message: string | null;
+    payload_json: string | null;
+    created_at: string;
+    read_at: string | null;
+}

package/dist/db/schema.js

@@ -4,7 +4,7 @@
  * Based on: db-workflow-architecture.md
  * Database: SQLite via better-sqlite3
  */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 6;
 export const SCHEMA_SQL = `
 -- Schema version tracking
 CREATE TABLE IF NOT EXISTS schema_version (
@@ -73,6 +73,9 @@ CREATE TABLE IF NOT EXISTS work_items (
   -- Guided mode: current step in work item cycle
   guided_step TEXT,
 
+  -- Ownership (for multi-agent teams)
+  owner TEXT,
+
   -- Content
   title TEXT NOT NULL,
   description TEXT,
@@ -94,7 +97,7 @@ CREATE TABLE IF NOT EXISTS work_items (
   UNIQUE (project_id, item_id)
 );
 
--- Project documents (PRD, architecture, etc.)
+-- Project documents (PRD, architecture, plans, etc.)
 CREATE TABLE IF NOT EXISTS project_documents (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   project_id INTEGER NOT NULL,
@@ -103,10 +106,15 @@ CREATE TABLE IF NOT EXISTS project_documents (
   title TEXT NOT NULL,
   content TEXT NOT NULL,
 
+  -- Plan-specific fields (NULL for non-plan documents)
+  status TEXT,
+  work_item_id INTEGER,
+
   created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
   updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 
-  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+  FOREIGN KEY (work_item_id) REFERENCES work_items(id) ON DELETE SET NULL
 );
 
 -- Work item history (audit trail)
@@ -135,9 +143,64 @@ CREATE INDEX IF NOT EXISTS idx_projects_status ON projects(status);
 CREATE INDEX IF NOT EXISTS idx_work_items_project ON work_items(project_id);
 CREATE INDEX IF NOT EXISTS idx_work_items_status ON work_items(status);
 CREATE INDEX IF NOT EXISTS idx_work_items_priority ON work_items(priority);
+CREATE INDEX IF NOT EXISTS idx_work_items_owner ON work_items(owner);
 
 CREATE INDEX IF NOT EXISTS idx_project_documents_project ON project_documents(project_id);
 CREATE INDEX IF NOT EXISTS idx_project_documents_type ON project_documents(doc_type);
+CREATE INDEX IF NOT EXISTS idx_project_documents_status ON project_documents(status);
+CREATE INDEX IF NOT EXISTS idx_project_documents_work_item ON project_documents(work_item_id);
 
 CREATE INDEX IF NOT EXISTS idx_work_item_history_item ON work_item_history(work_item_id);
+
+-- Terminal sessions (multi-terminal awareness)
+CREATE TABLE IF NOT EXISTS terminal_sessions (
+  id TEXT PRIMARY KEY,
+  project_id INTEGER,
+  pid INTEGER NOT NULL,
+  tty_path TEXT,
+  label TEXT,
+  started_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  last_heartbeat DATETIME DEFAULT CURRENT_TIMESTAMP,
+  active_agent TEXT DEFAULT 'default',
+  agents_json TEXT DEFAULT '[]',
+  status TEXT DEFAULT 'active',
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_terminal_sessions_project ON terminal_sessions(project_id);
+CREATE INDEX IF NOT EXISTS idx_terminal_sessions_status ON terminal_sessions(status);
+
+-- File locks (multi-terminal file lock awareness)
+CREATE TABLE IF NOT EXISTS file_locks (
+  path TEXT NOT NULL,
+  project_id INTEGER NOT NULL,
+  session_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  locked_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (path, project_id),
+  FOREIGN KEY (session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE,
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_file_locks_session ON file_locks(session_id);
+
+-- Session notifications (cross-session notifications)
+CREATE TABLE IF NOT EXISTS session_notifications (
+  id TEXT PRIMARY KEY,
+  project_id INTEGER NOT NULL,
+  from_session_id TEXT NOT NULL,
+  to_session_id TEXT,
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  message TEXT,
+  payload_json TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  read_at DATETIME,
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+  FOREIGN KEY (from_session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_session_notifications_project ON session_notifications(project_id);
+CREATE INDEX IF NOT EXISTS idx_session_notifications_to_session ON session_notifications(to_session_id);
+CREATE INDEX IF NOT EXISTS idx_session_notifications_unread ON session_notifications(read_at);
 `;

package/dist/episodes/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Episodes Module (CLI)
+ *
+ * Work history tracking with file-based persistence and automatic recording.
+ */
+import type { EpisodeStore } from '@compilr-dev/agents';
+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';
+export type { Effort, WorkEpisode, EffortSignals, EffortWeights, EffortSummary, ProjectWorkSummary, WorkAtRisk, EpisodeStore, } from './types.js';
+/** Set the global episode store (called during startup) */
+export declare function setGlobalEpisodeStore(store: EpisodeStore): void;
+/** Get the global episode store (used by recall_work tool) */
+export declare function getGlobalEpisodeStore(): EpisodeStore | null;

package/dist/episodes/index.js

@@ -0,0 +1,27 @@
+/**
+ * Episodes Module (CLI)
+ *
+ * Work history tracking with file-based persistence and automatic recording.
+ */
+// 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
+export { queryWorkAtRisk } from './work-at-risk.js';
+// Work summary anchor
+export { buildWorkSummaryContent, updateWorkSummaryAnchor } from './work-summary-anchor.js';
+// =============================================================================
+// Global Episode Store
+// =============================================================================
+let _globalStore = null;
+/** Set the global episode store (called during startup) */
+export function setGlobalEpisodeStore(store) {
+    _globalStore = store;
+}
+/** Get the global episode store (used by recall_work tool) */
+export function getGlobalEpisodeStore() {
+    return _globalStore;
+}

package/dist/episodes/recorder.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 session prefix (first 8 chars) */
+    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,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;
+}