@4da/mcp-server 4.0.0 → 4.1.1

package/dist/db.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: FSL-1.1-Apache-2.0
 /**
  * Database module for 4DA MCP Server
  *
@@ -73,12 +74,21 @@ function getDefaultDbPath() {
  */
 export class FourDADatabase {
     db;
+    _isStandalone = false;
     constructor(dbPath) {
         const resolvedPath = dbPath || getDefaultDbPath();
         // Resolve path - if relative, resolve from cwd
         const absolutePath = path.isAbsolute(resolvedPath)
             ? resolvedPath
             : path.resolve(process.cwd(), resolvedPath);
+        const isNew = !fs.existsSync(absolutePath);
+        // Ensure parent directory exists (standalone mode may need to create it)
+        if (isNew) {
+            const dir = path.dirname(absolutePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+        }
         try {
             this.db = new Database(absolutePath, { readonly: false }); // Need write for feedback
             this.db.pragma("journal_mode = WAL");
@@ -86,6 +96,18 @@ export class FourDADatabase {
         catch (error) {
             throw new Error(`Failed to open 4DA database at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
+        // Standalone mode: create schema for a brand-new database
+        if (isNew) {
+            this.createMinimalSchema();
+            this._isStandalone = true;
+        }
+    }
+    /**
+     * Whether this database was freshly created in standalone mode
+     * (no pre-existing 4DA desktop app database found).
+     */
+    get isStandalone() {
+        return this._isStandalone;
     }
     /**
      * Validate that a database file exists, is readable, and passes integrity checks.
@@ -100,13 +122,12 @@ export class FourDADatabase {
         const absolutePath = path.isAbsolute(resolvedPath)
             ? resolvedPath
             : path.resolve(process.cwd(), resolvedPath);
-        // Check if file exists and is readable
+        // Check if file exists — if not, standalone mode will create it
         if (!fs.existsSync(absolutePath)) {
             return {
                 valid: false,
-                error: `Database file not found at ${absolutePath}. `
-                    + "Run 4DA at least once to create the database, or set FOURDA_DB_PATH "
-                    + "to the correct location.",
+                standalone: true,
+                error: `No existing database at ${absolutePath}. Standalone mode will create one on startup.`,
             };
         }
         // Try to open and run integrity check
@@ -160,6 +181,405 @@ export class FourDADatabase {
     close() {
         this.db.close();
     }
+    // ===========================================================================
+    // Standalone Mode — Schema & Population
+    // ===========================================================================
+    /**
+     * Create the minimal schema required for MCP tools to function.
+     * Mirrors the desktop app's tables but only the subset that MCP tools query.
+     * Called once when creating a brand-new standalone database.
+     */
+    createMinimalSchema() {
+        this.db.exec(`
+      -- Schema version tracking
+      CREATE TABLE IF NOT EXISTS schema_version (
+        version INTEGER PRIMARY KEY
+      );
+      INSERT INTO schema_version (version) VALUES (1);
+
+      -- Source items (content feed) — queried by get_relevant_content, source_health, daily_briefing, etc.
+      CREATE TABLE IF NOT EXISTS source_items (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_type TEXT NOT NULL,
+        source_id TEXT NOT NULL,
+        url TEXT,
+        title TEXT NOT NULL,
+        content TEXT NOT NULL DEFAULT '',
+        content_hash TEXT NOT NULL DEFAULT '',
+        embedding BLOB NOT NULL DEFAULT x'00',
+        signal_type TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        last_seen TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(source_type, source_id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_source_type ON source_items(source_type);
+      CREATE INDEX IF NOT EXISTS idx_source_type_created ON source_items(source_type, created_at);
+
+      -- User identity — queried by get_context
+      CREATE TABLE IF NOT EXISTS user_identity (
+        id INTEGER PRIMARY KEY CHECK (id = 1),
+        role TEXT,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      );
+
+      -- Tech stack (user-declared) — queried by get_context, tech_radar, developer_dna
+      CREATE TABLE IF NOT EXISTS tech_stack (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        technology TEXT NOT NULL UNIQUE,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+
+      -- Domains of interest — queried by get_context
+      CREATE TABLE IF NOT EXISTS domains (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        domain TEXT NOT NULL UNIQUE,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+
+      -- Explicit interests — queried by get_context, developer_dna
+      CREATE TABLE IF NOT EXISTS explicit_interests (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        topic TEXT NOT NULL UNIQUE,
+        weight REAL DEFAULT 1.0,
+        embedding BLOB,
+        source TEXT DEFAULT 'explicit',
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_interests_topic ON explicit_interests(topic);
+
+      -- Exclusions — queried by get_context
+      CREATE TABLE IF NOT EXISTS exclusions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        topic TEXT NOT NULL UNIQUE,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+
+      -- ACE detected tech — queried by get_context, tech_radar, developer_dna
+      CREATE TABLE IF NOT EXISTS detected_tech (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL UNIQUE,
+        category TEXT NOT NULL,
+        confidence REAL DEFAULT 0.5,
+        source TEXT NOT NULL DEFAULT 'project_scan',
+        evidence TEXT,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_detected_tech_name ON detected_tech(name);
+      CREATE INDEX IF NOT EXISTS idx_detected_tech_confidence ON detected_tech(confidence);
+
+      -- Active topics — queried by get_context
+      CREATE TABLE IF NOT EXISTS active_topics (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        topic TEXT NOT NULL UNIQUE,
+        weight REAL DEFAULT 0.5,
+        confidence REAL DEFAULT 0.5,
+        embedding BLOB,
+        source TEXT NOT NULL DEFAULT 'project_scan',
+        last_seen TEXT DEFAULT (datetime('now')),
+        decay_applied INTEGER DEFAULT 0,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_active_topics_topic ON active_topics(topic);
+
+      -- Topic affinities (learned) — queried by get_context, developer_dna, attention_report
+      CREATE TABLE IF NOT EXISTS topic_affinities (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        topic TEXT NOT NULL UNIQUE,
+        embedding BLOB,
+        positive_signals INTEGER DEFAULT 0,
+        negative_signals INTEGER DEFAULT 0,
+        total_exposures INTEGER DEFAULT 0,
+        affinity_score REAL DEFAULT 0.0,
+        confidence REAL DEFAULT 0.0,
+        last_interaction TEXT DEFAULT (datetime('now')),
+        decay_applied INTEGER DEFAULT 0,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      );
+
+      -- Anti-topics (learned exclusions) — queried by get_context
+      CREATE TABLE IF NOT EXISTS anti_topics (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        topic TEXT NOT NULL UNIQUE,
+        rejection_count INTEGER DEFAULT 0,
+        confidence REAL DEFAULT 0.0,
+        auto_detected INTEGER DEFAULT 1,
+        user_confirmed INTEGER DEFAULT 0,
+        first_rejection TEXT DEFAULT (datetime('now')),
+        last_rejection TEXT DEFAULT (datetime('now')),
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      );
+
+      -- Interactions — queried by record_feedback, developer_dna, knowledge_gaps
+      CREATE TABLE IF NOT EXISTS interactions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_item_id INTEGER,
+        item_id INTEGER,
+        action TEXT,
+        action_type TEXT,
+        action_data TEXT,
+        item_topics TEXT,
+        item_source TEXT,
+        signal_strength REAL DEFAULT 0.5,
+        timestamp TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_interactions_timestamp ON interactions(timestamp);
+      CREATE INDEX IF NOT EXISTS idx_interactions_item ON interactions(source_item_id);
+
+      -- Project dependencies — queried by project_health, tech_radar, developer_dna, knowledge_gaps
+      CREATE TABLE IF NOT EXISTS project_dependencies (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        project_path TEXT NOT NULL,
+        manifest_type TEXT NOT NULL,
+        package_name TEXT NOT NULL,
+        version TEXT,
+        is_dev INTEGER DEFAULT 0,
+        language TEXT NOT NULL,
+        last_scanned TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(project_path, package_name)
+      );
+      CREATE INDEX IF NOT EXISTS idx_deps_package ON project_dependencies(package_name);
+      CREATE INDEX IF NOT EXISTS idx_deps_project ON project_dependencies(project_path);
+
+      -- Developer decisions — queried by tech_radar, decision_memory
+      CREATE TABLE IF NOT EXISTS developer_decisions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        decision_type TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        decision TEXT NOT NULL,
+        rationale TEXT,
+        alternatives_rejected TEXT DEFAULT '[]',
+        context_tags TEXT DEFAULT '[]',
+        confidence REAL NOT NULL DEFAULT 0.8,
+        status TEXT NOT NULL DEFAULT 'active',
+        superseded_by INTEGER,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_decisions_type ON developer_decisions(decision_type);
+      CREATE INDEX IF NOT EXISTS idx_decisions_subject ON developer_decisions(subject);
+
+      -- Temporal events — queried by signal_chains, semantic_shifts, trend_analysis
+      CREATE TABLE IF NOT EXISTS temporal_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        event_type TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        data JSON NOT NULL,
+        embedding BLOB,
+        source_item_id INTEGER,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        expires_at TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_temporal_type_time ON temporal_events(event_type, created_at);
+
+      -- Item relationships — queried by reverse_mentions, topic_connections
+      CREATE TABLE IF NOT EXISTS item_relationships (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_item_id INTEGER NOT NULL,
+        related_item_id INTEGER NOT NULL,
+        relationship_type TEXT NOT NULL,
+        strength REAL DEFAULT 1.0,
+        metadata JSON,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(source_item_id, related_item_id, relationship_type)
+      );
+
+      -- Agent memory — queried by agent_memory, agent_session_brief
+      CREATE TABLE IF NOT EXISTS agent_memory (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        agent_type TEXT NOT NULL,
+        memory_type TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        content TEXT NOT NULL,
+        context_tags TEXT DEFAULT '[]',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        expires_at TEXT,
+        promoted_to_decision_id INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_agent_memory_type ON agent_memory(memory_type);
+      CREATE INDEX IF NOT EXISTS idx_agent_memory_session ON agent_memory(session_id);
+
+      -- Source health — queried by source_health diagnostic
+      CREATE TABLE IF NOT EXISTS source_health (
+        source_type TEXT PRIMARY KEY,
+        status TEXT NOT NULL DEFAULT 'unknown',
+        last_success TEXT,
+        last_error TEXT,
+        error_count INTEGER NOT NULL DEFAULT 0,
+        consecutive_failures INTEGER NOT NULL DEFAULT 0,
+        items_fetched INTEGER NOT NULL DEFAULT 0,
+        response_time_ms INTEGER NOT NULL DEFAULT 0,
+        checked_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      -- Sources registry
+      CREATE TABLE IF NOT EXISTS sources (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_type TEXT NOT NULL UNIQUE,
+        name TEXT NOT NULL,
+        enabled INTEGER NOT NULL DEFAULT 1,
+        config TEXT,
+        last_fetch TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      -- Briefings — queried by agent_session_brief, daily_briefing
+      CREATE TABLE IF NOT EXISTS briefings (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        content TEXT NOT NULL,
+        model TEXT,
+        item_count INTEGER NOT NULL DEFAULT 0,
+        tokens_used INTEGER,
+        latency_ms INTEGER,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      -- Autophagy cycles — queried by autophagy_status
+      CREATE TABLE IF NOT EXISTS autophagy_cycles (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        items_analyzed INTEGER NOT NULL DEFAULT 0,
+        items_pruned INTEGER NOT NULL DEFAULT 0,
+        calibrations_produced INTEGER NOT NULL DEFAULT 0,
+        topic_decay_rates_updated INTEGER NOT NULL DEFAULT 0,
+        source_autopsies_produced INTEGER NOT NULL DEFAULT 0,
+        anti_patterns_detected INTEGER NOT NULL DEFAULT 0,
+        db_size_before_bytes INTEGER NOT NULL DEFAULT 0,
+        db_size_after_bytes INTEGER NOT NULL DEFAULT 0,
+        duration_ms INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      -- Digested intelligence — queried by autophagy_status
+      CREATE TABLE IF NOT EXISTS digested_intelligence (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        digest_type TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        data TEXT NOT NULL,
+        confidence REAL NOT NULL DEFAULT 0.5,
+        sample_size INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        expires_at TEXT,
+        superseded_by INTEGER,
+        FOREIGN KEY (superseded_by) REFERENCES digested_intelligence(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_digest_type_subject ON digested_intelligence(digest_type, subject);
+
+      -- Decision windows — queried by decision_windows, compound_advantage
+      CREATE TABLE IF NOT EXISTS decision_windows (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        window_type TEXT NOT NULL,
+        title TEXT NOT NULL,
+        description TEXT NOT NULL DEFAULT '',
+        urgency REAL NOT NULL DEFAULT 0.5,
+        relevance REAL NOT NULL DEFAULT 0.5,
+        source_item_ids TEXT NOT NULL DEFAULT '[]',
+        signal_chain_id INTEGER,
+        dependency TEXT,
+        status TEXT NOT NULL DEFAULT 'open',
+        opened_at TEXT NOT NULL DEFAULT (datetime('now')),
+        expires_at TEXT,
+        acted_at TEXT,
+        closed_at TEXT,
+        outcome TEXT,
+        lead_time_hours REAL,
+        streets_engine TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_dw_status ON decision_windows(status);
+
+      -- Advantage score — queried by compound_advantage
+      CREATE TABLE IF NOT EXISTS advantage_score (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        period TEXT NOT NULL,
+        score REAL NOT NULL DEFAULT 0.0,
+        items_surfaced INTEGER NOT NULL DEFAULT 0,
+        avg_lead_time_hours REAL NOT NULL DEFAULT 0.0,
+        windows_opened INTEGER NOT NULL DEFAULT 0,
+        windows_acted INTEGER NOT NULL DEFAULT 0,
+        windows_expired INTEGER NOT NULL DEFAULT 0,
+        knowledge_gaps_closed INTEGER NOT NULL DEFAULT 0,
+        calibration_accuracy REAL NOT NULL DEFAULT 0.0,
+        response_rate REAL,
+        computed_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_advantage_period ON advantage_score(period, computed_at);
+
+      -- Agent feedback — queried by record_agent_feedback, get_agent_feedback_stats
+      CREATE TABLE IF NOT EXISTS agent_feedback (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        item_id TEXT NOT NULL,
+        outcome TEXT NOT NULL,
+        context TEXT,
+        session_task TEXT,
+        recorded_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_agent_feedback_item ON agent_feedback(item_id);
+      CREATE INDEX IF NOT EXISTS idx_agent_feedback_outcome ON agent_feedback(outcome);
+    `);
+    }
+    /**
+     * Populate the standalone database from a project scan result.
+     * Inserts detected tech, dependencies, and topics so MCP tools return useful data.
+     */
+    populateFromScan(scan) {
+        const insertTech = this.db.prepare("INSERT OR IGNORE INTO detected_tech (name, category, confidence, source) VALUES (?, ?, ?, ?)");
+        const insertTopic = this.db.prepare("INSERT OR IGNORE INTO active_topics (topic, weight, confidence, source) VALUES (?, ?, ?, ?)");
+        const insertDep = this.db.prepare("INSERT OR IGNORE INTO project_dependencies (project_path, manifest_type, package_name, version, is_dev, language) VALUES (?, ?, ?, ?, ?, ?)");
+        const insertInterest = this.db.prepare("INSERT OR IGNORE INTO explicit_interests (topic, weight, source) VALUES (?, ?, ?)");
+        const insertTechStack = this.db.prepare("INSERT OR IGNORE INTO tech_stack (technology) VALUES (?)");
+        // Run all inserts in a single transaction for speed
+        const populate = this.db.transaction(() => {
+            // Languages -> detected_tech + tech_stack + active_topics
+            for (const lang of scan.languages) {
+                insertTech.run(lang, "language", 0.95, "project_scan");
+                insertTechStack.run(lang);
+                insertTopic.run(lang, 0.8, 0.9, "project_scan");
+            }
+            // Frameworks -> detected_tech + tech_stack + active_topics
+            for (const fw of scan.frameworks) {
+                insertTech.run(fw, "framework", 0.85, "project_scan");
+                insertTechStack.run(fw);
+                insertTopic.run(fw, 0.7, 0.85, "project_scan");
+            }
+            // Determine primary ecosystem for dependency labeling.
+            // For multi-language projects, we use the primary ecosystem;
+            // this is a simplification — the desktop app's ACE engine handles
+            // per-manifest tracking more precisely.
+            const ecosystem = scan.languages.includes("typescript") || scan.languages.includes("javascript")
+                ? "npm"
+                : scan.languages.includes("rust")
+                    ? "rust"
+                    : scan.languages.includes("python")
+                        ? "python"
+                        : scan.languages.includes("go")
+                            ? "go"
+                            : "unknown";
+            const manifestType = ecosystem === "rust"
+                ? "Cargo.toml"
+                : ecosystem === "python"
+                    ? "pyproject.toml"
+                    : ecosystem === "go"
+                        ? "go.mod"
+                        : "package.json";
+            // Production dependencies
+            for (const dep of scan.dependencies) {
+                insertDep.run(scan.projectPath, manifestType, dep, null, 0, ecosystem);
+            }
+            // Dev dependencies
+            for (const dep of scan.devDependencies) {
+                insertDep.run(scan.projectPath, manifestType, dep, null, 1, ecosystem);
+            }
+            // Topics -> active_topics + explicit_interests (so get_context returns them)
+            for (const topic of scan.topics) {
+                insertTopic.run(topic, 0.7, 0.8, "project_scan");
+                insertInterest.run(topic, 0.8, "project_scan");
+            }
+        });
+        populate();
+    }
     /**
      * Execute a database operation with retry logic for SQLITE_BUSY / SQLITE_LOCKED.
      *
@@ -228,6 +648,8 @@ export class FourDADatabase {
                     : hoursAgo < 24
                         ? `${hoursAgo} hours ago`
                         : `${Math.round(hoursAgo / 24)} days ago`;
+                // Look up persisted necessity scores from Rust analysis pipeline
+                const necessity = this.getNecessityForItem(item.id);
                 scoredItems.push({
                     id: item.id,
                     source_type: item.source_type,
@@ -238,6 +660,10 @@ export class FourDADatabase {
                     relevance_score: Math.round(score * 100) / 100,
                     created_at: item.created_at,
                     discovered_ago: discoveredAgo,
+                    necessity_score: necessity.score,
+                    necessity_reason: necessity.reason,
+                    necessity_category: necessity.category,
+                    necessity_urgency: necessity.urgency,
                 });
             }
         }
@@ -257,6 +683,29 @@ export class FourDADatabase {
     `);
         return stmt.get(itemId, sourceType) || null;
     }
+    /**
+     * Look up persisted necessity scores for an item (written by Rust analysis pipeline).
+     * Returns defaults (0.0/null) if no necessity data exists yet.
+     */
+    getNecessityForItem(itemId) {
+        try {
+            const stmt = this.db.prepare(`SELECT necessity_score, necessity_reason, necessity_category, necessity_urgency
+         FROM item_necessity WHERE source_item_id = ?`);
+            const row = stmt.get(itemId);
+            if (row) {
+                return {
+                    score: row.necessity_score,
+                    reason: row.necessity_reason,
+                    category: row.necessity_category,
+                    urgency: row.necessity_urgency,
+                };
+            }
+        }
+        catch {
+            // Table may not exist yet (pre-migration) — graceful fallback
+        }
+        return { score: 0.0, reason: null, category: null, urgency: null };
+    }
     // ===========================================================================
     // User Context
     // ===========================================================================
@@ -495,6 +944,160 @@ export class FourDADatabase {
         }
     }
     // ===========================================================================
+    // Agent Feedback
+    // ===========================================================================
+    /**
+     * Ensure the agent_feedback table exists.
+     * Called on first use so existing databases (created before this feature)
+     * get the table added without requiring a migration.
+     */
+    ensureAgentFeedbackTable() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS agent_feedback (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        item_id TEXT NOT NULL,
+        outcome TEXT NOT NULL,
+        context TEXT,
+        session_task TEXT,
+        recorded_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_agent_feedback_item ON agent_feedback(item_id);
+      CREATE INDEX IF NOT EXISTS idx_agent_feedback_outcome ON agent_feedback(outcome);
+    `);
+    }
+    /**
+     * Record agent feedback on recommended content items
+     */
+    recordAgentFeedback(itemIds, outcome, context, sessionTask) {
+        this.ensureAgentFeedbackTable();
+        const validOutcomes = ["used", "rejected", "partially_used"];
+        if (!validOutcomes.includes(outcome)) {
+            return {
+                success: false,
+                message: `Invalid outcome: ${outcome}. Valid outcomes: ${validOutcomes.join(", ")}`,
+                recorded_count: 0,
+            };
+        }
+        if (!itemIds || itemIds.length === 0) {
+            return {
+                success: false,
+                message: "item_ids must contain at least one item ID",
+                recorded_count: 0,
+            };
+        }
+        try {
+            const stmt = this.db.prepare(`
+        INSERT INTO agent_feedback (item_id, outcome, context, session_task)
+        VALUES (?, ?, ?, ?)
+      `);
+            const insertMany = this.db.transaction((ids) => {
+                let count = 0;
+                for (const id of ids) {
+                    stmt.run(id, outcome, context || null, sessionTask || null);
+                    count++;
+                }
+                return count;
+            });
+            const count = insertMany(itemIds);
+            return {
+                success: true,
+                message: `Recorded ${outcome} feedback for ${count} item(s)`,
+                recorded_count: count,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to record agent feedback: ${error instanceof Error ? error.message : String(error)}`,
+                recorded_count: 0,
+            };
+        }
+    }
+    /**
+     * Get agent feedback statistics for the given period
+     */
+    getAgentFeedbackStats(days = 30) {
+        this.ensureAgentFeedbackTable();
+        const cutoff = `datetime('now', '-${Math.max(1, Math.min(365, days))} days')`;
+        // Outcome totals
+        const outcomeRows = this.db
+            .prepare(`SELECT outcome, COUNT(*) as cnt
+         FROM agent_feedback
+         WHERE recorded_at >= ${cutoff}
+         GROUP BY outcome`)
+            .all();
+        const outcomes = { used: 0, rejected: 0, partially_used: 0, total: 0 };
+        for (const row of outcomeRows) {
+            if (row.outcome === "used")
+                outcomes.used = row.cnt;
+            else if (row.outcome === "rejected")
+                outcomes.rejected = row.cnt;
+            else if (row.outcome === "partially_used")
+                outcomes.partially_used = row.cnt;
+            outcomes.total += row.cnt;
+        }
+        // By source type — join with source_items to get source_type
+        const sourceRows = this.db
+            .prepare(`SELECT COALESCE(si.source_type, 'unknown') as source_type, af.outcome, COUNT(*) as cnt
+         FROM agent_feedback af
+         LEFT JOIN source_items si ON CAST(af.item_id AS INTEGER) = si.id
+         WHERE af.recorded_at >= ${cutoff}
+         GROUP BY source_type, af.outcome
+         ORDER BY cnt DESC`)
+            .all();
+        // Aggregate source rows into per-source stats
+        const sourceMap = new Map();
+        for (const row of sourceRows) {
+            if (!sourceMap.has(row.source_type)) {
+                sourceMap.set(row.source_type, { used: 0, rejected: 0, partially_used: 0, total: 0 });
+            }
+            const entry = sourceMap.get(row.source_type);
+            if (row.outcome === "used")
+                entry.used += row.cnt;
+            else if (row.outcome === "rejected")
+                entry.rejected += row.cnt;
+            else if (row.outcome === "partially_used")
+                entry.partially_used += row.cnt;
+            entry.total += row.cnt;
+        }
+        const bySource = Array.from(sourceMap.entries()).map(([source_type, stats]) => ({
+            source_type,
+            ...stats,
+            usefulness_rate: stats.total > 0 ? (stats.used + stats.partially_used * 0.5) / stats.total : 0,
+        }));
+        // Top used items
+        const topItems = this.db
+            .prepare(`SELECT
+           af.item_id,
+           si.title,
+           si.source_type,
+           SUM(CASE WHEN af.outcome = 'used' THEN 1 ELSE 0 END) as used_count,
+           SUM(CASE WHEN af.outcome = 'rejected' THEN 1 ELSE 0 END) as rejected_count
+         FROM agent_feedback af
+         LEFT JOIN source_items si ON CAST(af.item_id AS INTEGER) = si.id
+         WHERE af.recorded_at >= ${cutoff}
+         GROUP BY af.item_id
+         HAVING used_count > 0
+         ORDER BY used_count DESC
+         LIMIT 10`)
+            .all();
+        // Recent feedback entries
+        const recentFeedback = this.db
+            .prepare(`SELECT item_id, outcome, context, session_task, recorded_at
+         FROM agent_feedback
+         WHERE recorded_at >= ${cutoff}
+         ORDER BY recorded_at DESC
+         LIMIT 20`)
+            .all();
+        return {
+            period_days: days,
+            outcomes,
+            by_source: bySource,
+            top_used_items: topItems,
+            recent_feedback: recentFeedback,
+        };
+    }
+    // ===========================================================================
     // Helper Methods
     // ===========================================================================
     /**