@4da/mcp-server 6.0.0 → 6.0.2

package/dist/setup.js

@@ -7,160 +7,343 @@
  * the user can start using 4DA tools immediately after install.
  *
  * Usage:
- *   npx @4da/mcp-server --setup
- *   4da-mcp-setup
+ *   npx @4da/mcp-server --setup [--dry-run]
+ *   4da-mcp-setup [--dry-run]
  *   pnpm run setup
+ *
+ * Audited 2026-10-05: three of the four editors were configured in files the
+ * editor never reads (`~/.vscode/mcp.json`, `~/.windsurf/mcp.json`, and
+ * `mcpServers` in a project's `.claude/settings.json`), and any config file
+ * that failed `JSON.parse` (VS Code's `mcp.json` is JSONC: comments and
+ * trailing commas are legal) was replaced by `{}` plus our entry, deleting
+ * every other server the user had. Each path below cites the doc it was
+ * checked against, and a file that cannot be parsed is never written.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import path from "node:path";
 import { homedir } from "node:os";
+import jsonc from "jsonc-parser";
+/** The command every editor runs. */
+const SERVER_COMMAND = { command: "npx", args: ["@4da/mcp-server"] };
 /** MCP config snippet for editors that use the standard mcpServers format */
 const MCP_CONFIG = {
-    "4da": {
-        command: "npx",
-        args: ["@4da/mcp-server"],
-    },
+    "4da": SERVER_COMMAND,
 };
+/** The Claude Code command printed instead of editing `~/.claude.json`. */
+export const CLAUDE_CODE_COMMAND = "claude mcp add --scope user 4da -- npx @4da/mcp-server";
+export function currentContext() {
+    return { platform: process.platform, env: process.env, home: homedir() };
+}
+function pathFor(ctx) {
+    return ctx.platform === "win32" ? path.win32 : path.posix;
+}
+/** `%APPDATA%` on Windows, the Electron-style config base elsewhere. */
+function roamingDir(ctx) {
+    const p = pathFor(ctx);
+    return ctx.env.APPDATA?.trim() || p.join(ctx.home, "AppData", "Roaming");
+}
+function xdgConfigDir(ctx) {
+    return ctx.env.XDG_CONFIG_HOME?.trim() || pathFor(ctx).join(ctx.home, ".config");
+}
 /**
- * Safely read and parse a JSON file, returning empty object on failure.
+ * The per-platform user-data dir of a desktop app (Electron `appData`):
+ * `%APPDATA%\<name>`, `~/Library/Application Support/<name>`,
+ * `$XDG_CONFIG_HOME/<name>` (default `~/.config/<name>`).
  */
-function readJsonSafe(filePath) {
-    if (!existsSync(filePath))
-        return {};
-    try {
-        return JSON.parse(readFileSync(filePath, "utf-8"));
-    }
-    catch {
-        return {};
-    }
+function appDataDir(ctx, name) {
+    const p = pathFor(ctx);
+    if (ctx.platform === "win32")
+        return p.join(roamingDir(ctx), name);
+    if (ctx.platform === "darwin")
+        return p.join(ctx.home, "Library", "Application Support", name);
+    return p.join(xdgConfigDir(ctx), name);
 }
 /**
- * Ensure directory exists and write JSON to file.
+ * Every editor this setup can write, with its config path on `ctx.platform`.
+ * Pure: nothing is read from disk here.
  */
-function writeJsonFile(filePath, data) {
-    const dir = dirname(filePath);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
-}
-const editors = [
-    {
-        name: "Claude Code",
-        detect: () => {
-            // Project-level config takes priority
-            const projectClaudeDir = join(process.cwd(), ".claude");
-            if (existsSync(projectClaudeDir)) {
-                return join(projectClaudeDir, "settings.json");
-            }
-            // Fall back to global config
-            return join(homedir(), ".claude.json");
-        },
-        write: (configPath) => {
-            const config = readJsonSafe(configPath);
-            const mcpServers = (config.mcpServers || {});
-            mcpServers["4da"] = MCP_CONFIG["4da"];
-            config.mcpServers = mcpServers;
-            writeJsonFile(configPath, config);
-            console.log(`  Written: ${configPath}`);
-        },
-    },
-    {
-        name: "Cursor",
-        detect: () => {
-            const cursorDir = join(homedir(), ".cursor");
-            if (existsSync(cursorDir)) {
-                return join(cursorDir, "mcp.json");
-            }
-            return null;
-        },
-        write: (configPath) => {
-            const config = readJsonSafe(configPath);
-            const mcpServers = (config.mcpServers || {});
-            mcpServers["4da"] = MCP_CONFIG["4da"];
-            config.mcpServers = mcpServers;
-            writeJsonFile(configPath, config);
-            console.log(`  Written: ${configPath}`);
-        },
-    },
-    {
-        name: "VS Code (Copilot)",
-        detect: () => {
-            const vscodePath = join(homedir(), ".vscode");
-            if (existsSync(vscodePath)) {
-                return join(vscodePath, "mcp.json");
-            }
-            return null;
+export function editorTargets(ctx = currentContext()) {
+    const p = pathFor(ctx);
+    const vscodeEntry = { type: "stdio", ...SERVER_COMMAND };
+    const vscode = (name, product) => {
+        const userDir = p.join(appDataDir(ctx, product), "User");
+        return {
+            name,
+            // The default profile's user-level file; it sits beside settings.json.
+            // A non-default profile keeps its own under User/profiles/<id>/, which
+            // VS Code does not name anywhere setup could find it.
+            configPath: p.join(userDir, "mcp.json"),
+            detectDir: userDir,
+            key: "servers",
+            entry: vscodeEntry,
+            docs: "https://code.visualstudio.com/docs/copilot/reference/mcp-configuration",
+        };
+    };
+    const devinDir = ctx.platform === "win32" ? p.join(roamingDir(ctx), "devin") : p.join(xdgConfigDir(ctx), "devin");
+    const windsurfDir = p.join(ctx.home, ".codeium", "windsurf");
+    return [
+        {
+            name: "Cursor",
+            configPath: p.join(ctx.home, ".cursor", "mcp.json"),
+            detectDir: p.join(ctx.home, ".cursor"),
+            key: "mcpServers",
+            entry: SERVER_COMMAND,
+            docs: "https://cursor.com/docs/mcp",
         },
-        write: (configPath) => {
-            const config = readJsonSafe(configPath);
-            // VS Code uses "servers" key instead of "mcpServers"
-            const servers = (config.servers || {});
-            servers["4da"] = {
-                type: "stdio",
-                command: "npx",
-                args: ["@4da/mcp-server"],
-            };
-            config.servers = servers;
-            writeJsonFile(configPath, config);
-            console.log(`  Written: ${configPath}`);
+        vscode("VS Code (Copilot)", "Code"),
+        vscode("VS Code Insiders (Copilot)", "Code - Insiders"),
+        {
+            name: "Windsurf",
+            configPath: p.join(windsurfDir, "mcp_config.json"),
+            detectDir: windsurfDir,
+            key: "mcpServers",
+            entry: SERVER_COMMAND,
+            docs: "https://docs.devin.ai/cli/reference/configuration/read-config-from",
         },
-    },
-    {
-        name: "Windsurf",
-        detect: () => {
-            const windsurfDir = join(homedir(), ".windsurf");
-            if (existsSync(windsurfDir)) {
-                return join(windsurfDir, "mcp.json");
-            }
-            return null;
+        {
+            // Windsurf's successor. Its Cascade agent and the Devin CLI read the
+            // same user-level file.
+            name: "Devin Desktop / Devin CLI",
+            configPath: p.join(devinDir, "mcp_config.json"),
+            detectDir: devinDir,
+            key: "mcpServers",
+            entry: SERVER_COMMAND,
+            docs: "https://docs.devin.ai/desktop/cascade/mcp",
         },
-        write: (configPath) => {
-            const config = readJsonSafe(configPath);
-            const mcpServers = (config.mcpServers || {});
-            mcpServers["4da"] = MCP_CONFIG["4da"];
-            config.mcpServers = mcpServers;
-            writeJsonFile(configPath, config);
-            console.log(`  Written: ${configPath}`);
+        {
+            name: "Claude Desktop",
+            configPath: p.join(appDataDir(ctx, "Claude"), "claude_desktop_config.json"),
+            detectDir: appDataDir(ctx, "Claude"),
+            key: "mcpServers",
+            entry: SERVER_COMMAND,
+            docs: "https://modelcontextprotocol.io/docs/develop/connect-local-servers",
         },
-    },
-];
+    ];
+}
+/**
+ * Claude Code keeps user- and local-scope servers in `~/.claude.json`
+ * (`$CLAUDE_CONFIG_DIR/.claude.json` when set), a file it rewrites itself and
+ * that also holds the sign-in session and per-project state. Setup never
+ * edits it: it prints the `claude mcp add` command, which does.
+ * https://code.claude.com/docs/en/mcp
+ */
+export function claudeCodeConfigPath(ctx = currentContext()) {
+    const p = pathFor(ctx);
+    const configDir = ctx.env.CLAUDE_CONFIG_DIR?.trim();
+    return configDir ? p.join(configDir, ".claude.json") : p.join(ctx.home, ".claude.json");
+}
+function lineOf(text, offset) {
+    return text.slice(0, offset).split("\n").length;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function sameJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Decide what writing `entry` under `<key>["4da"]` does to a config file whose
+ * current text is `existing` (null when it does not exist).
+ *
+ * The file is parsed as JSONC (comments and trailing commas allowed) and
+ * edited in place with `jsonc-parser`'s `modify`, so other servers, other keys,
+ * comments and formatting all survive. A file that does not parse is refused,
+ * never replaced. An existing `4da` entry keeps its other fields (`env`, say);
+ * only the fields setup owns are set.
+ */
+export function planConfig(existing, key, entry) {
+    if (existing === null || existing.trim() === "") {
+        return {
+            action: existing === null ? "create" : "update",
+            content: JSON.stringify({ [key]: { "4da": entry } }, null, 2) + "\n",
+        };
+    }
+    const errors = [];
+    const root = jsonc.parse(existing, errors, { allowTrailingComma: true, disallowComments: false });
+    if (errors.length > 0) {
+        const first = errors[0];
+        return {
+            action: "refuse",
+            reason: `it does not parse (${jsonc.printParseErrorCode(first.error)} at line ${lineOf(existing, first.offset)})`,
+        };
+    }
+    if (!isPlainObject(root)) {
+        return { action: "refuse", reason: "its top level is not a JSON object" };
+    }
+    const servers = root[key];
+    if (servers !== undefined && !isPlainObject(servers)) {
+        return { action: "refuse", reason: `its "${key}" is not an object` };
+    }
+    const current = servers?.["4da"];
+    if (current !== undefined && !isPlainObject(current)) {
+        return { action: "refuse", reason: `its "${key}"."4da" is not an object` };
+    }
+    if (current && Object.entries(entry).every(([field, value]) => sameJson(current[field], value))) {
+        return { action: "unchanged" };
+    }
+    const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+    const indent = /^([ \t]+)\S/m.exec(existing)?.[1] ?? "  ";
+    const formattingOptions = {
+        insertSpaces: !indent.startsWith("\t"),
+        tabSize: indent.startsWith("\t") ? 1 : indent.length,
+        eol,
+    };
+    let content = existing;
+    // Field by field when the entry exists, so its other fields and any
+    // comments inside it stay; whole when it does not.
+    const edits = current
+        ? Object.entries(entry).map(([field, value]) => [[key, "4da", field], value])
+        : [[[key, "4da"], entry]];
+    for (const [jsonPath, value] of edits) {
+        content = jsonc.applyEdits(content, jsonc.modify(content, jsonPath, value, { formattingOptions }));
+    }
+    return { action: "update", content };
+}
+/** Read a config file's text; null when it does not exist. */
+function readConfig(filePath) {
+    return existsSync(filePath) ? readFileSync(filePath, "utf-8") : null;
+}
+/** `<file>.bak`, or a timestamped name when that is taken: an earlier backup is never overwritten. */
+function backupPath(filePath) {
+    const plain = `${filePath}.bak`;
+    if (!existsSync(plain))
+        return plain;
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..*$/, "");
+    for (let n = 0;; n++) {
+        const candidate = `${filePath}.${stamp}${n === 0 ? "" : `-${n}`}.bak`;
+        if (!existsSync(candidate))
+            return candidate;
+    }
+}
+/**
+ * Write `content` to `filePath`: back up an existing file first, then write a
+ * temp file beside it and rename it over the original, so an interrupted run
+ * leaves either the old file or the new one, never half of one. A symlinked
+ * config (a dotfiles repo) is written through to its target.
+ * @returns The backup path, when one was made.
+ */
+export function writeConfigAtomic(filePath, content) {
+    // Only a symlinked file is resolved: resolving the whole path would turn
+    // macOS's /var/... into /private/var/... in every path reported back.
+    const target = existsSync(filePath) && lstatSync(filePath).isSymbolicLink() ? realpathSync(filePath) : filePath;
+    mkdirSync(path.dirname(target), { recursive: true });
+    let backup = null;
+    if (existsSync(target)) {
+        backup = backupPath(target);
+        copyFileSync(target, backup);
+    }
+    const temp = `${target}.4da-${process.pid}.tmp`;
+    try {
+        writeFileSync(temp, content);
+        renameSync(temp, target);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    }
+    return backup;
+}
+/** The snippet an editor gets, as printed in a dry run and for manual setup. */
+function snippet(target) {
+    return JSON.stringify({ [target.key]: { "4da": target.entry } }, null, 2)
+        .split("\n")
+        .map((line) => `    ${line}`)
+        .join("\n");
+}
+/** Whether `~/.claude.json` already has a user-scope `4da` server. Read-only. */
+function claudeCodeHas4da(configPath) {
+    try {
+        const root = JSON.parse(readFileSync(configPath, "utf-8"));
+        return isPlainObject(root) && isPlainObject(root.mcpServers) && "4da" in root.mcpServers;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Run the setup wizard: detect editors and write MCP configurations.
  * @param dryRun If true, only report what would be written without modifying files.
  */
-export function runSetup(dryRun = false) {
-    console.log("\n  4DA MCP Server — Setup\n");
+export function runSetup(dryRun = false, ctx = currentContext(), log = console.log) {
+    log("\n  4DA MCP Server — Setup\n");
     if (dryRun)
-        console.log("  [DRY RUN] No files will be modified.\n");
-    console.log("  Detecting editors...\n");
-    let configured = 0;
-    for (const editor of editors) {
-        const configPath = editor.detect();
-        if (configPath) {
-            console.log(`  Found: ${editor.name}`);
-            if (dryRun) {
-                console.log(`  Would write: ${configPath}`);
+        log("  [DRY RUN] No files will be modified.\n");
+    log("  Detecting editors...\n");
+    let found = 0;
+    let refused = 0;
+    // Claude Code: print the command, never edit ~/.claude.json.
+    const claudeJson = claudeCodeConfigPath(ctx);
+    const claudeDir = pathFor(ctx).join(ctx.home, ".claude");
+    if (existsSync(claudeJson) || existsSync(claudeDir)) {
+        found++;
+        log("  Found: Claude Code");
+        if (claudeCodeHas4da(claudeJson)) {
+            log(`  Already configured (user scope, ${claudeJson}).`);
+        }
+        else {
+            log("  Claude Code keeps its MCP servers in ~/.claude.json, which it rewrites");
+            log("  itself; setup does not edit it. Add the server with:");
+            log(`    ${CLAUDE_CODE_COMMAND}`);
+        }
+        log("");
+    }
+    for (const target of editorTargets(ctx)) {
+        if (!existsSync(target.detectDir))
+            continue;
+        found++;
+        log(`  Found: ${target.name}`);
+        let plan;
+        try {
+            plan = planConfig(readConfig(target.configPath), target.key, target.entry);
+        }
+        catch (error) {
+            plan = { action: "refuse", reason: `it could not be read (${error instanceof Error ? error.message : String(error)})` };
+        }
+        if (plan.action === "unchanged") {
+            log(`  Already configured: ${target.configPath}`);
+        }
+        else if (plan.action === "refuse") {
+            refused++;
+            log(`  Not modified: ${target.configPath}`);
+            log(`  Setup left it untouched because ${plan.reason}. Add this by hand:`);
+            log(snippet(target));
+        }
+        else if (dryRun) {
+            log(`  Would ${plan.action === "create" ? "create" : "update"}: ${target.configPath}`);
+            log(`  Adding under "${target.key}":`);
+            log(snippet(target));
+        }
+        else {
+            try {
+                const backup = writeConfigAtomic(target.configPath, plan.content ?? "");
+                log(`  Written: ${target.configPath}`);
+                if (backup)
+                    log(`  Backup:  ${backup}`);
             }
-            else {
-                editor.write(configPath);
+            catch (error) {
+                refused++;
+                log(`  Could not write ${target.configPath}: ${error instanceof Error ? error.message : String(error)}`);
+                log("  Add this by hand:");
+                log(snippet(target));
             }
-            configured++;
-            console.log("");
         }
+        log("");
+    }
+    if (found === 0) {
+        log("  No supported editors detected.\n");
+        log("  Manual setup — add to your editor's MCP config:\n");
+        log(`  ${JSON.stringify({ mcpServers: MCP_CONFIG }, null, 2)}\n`);
+        log(`  Claude Code: ${CLAUDE_CODE_COMMAND}\n`);
     }
-    if (configured === 0) {
-        console.log("  No supported editors detected.\n");
-        console.log("  Manual setup — add to your editor's MCP config:\n");
-        console.log(`  ${JSON.stringify(MCP_CONFIG, null, 2)}\n`);
-    }
-    console.log("  Done. Restart your editor to activate 4DA.");
-    console.log("");
-    console.log("  Note: This server reads data from the 4DA desktop app.");
-    console.log("  If you haven't installed it yet:");
-    console.log("    https://github.com/4DA-Systems/4DA/releases/latest");
-    console.log("");
-    console.log("  Run: npx @4da/mcp-server --doctor  to verify everything works.\n");
+    if (refused > 0)
+        log(`  ${refused} config file${refused === 1 ? " needs" : "s need"} the entry added by hand (above).`);
+    log("  Done. Restart your editor to activate 4DA.");
+    log("");
+    log("  The server works on its own; with the 4DA desktop app installed it");
+    log("  also reads the app's scored feed:");
+    log("    https://github.com/4DA-Systems/4DA/releases/latest");
+    log("");
+    log("  Run: npx @4da/mcp-server --doctor  to verify everything works.\n");
 }
 // Run directly if invoked as a script (bin entry or pnpm run setup)
 const isDirectRun = process.argv[1]?.endsWith("setup.js") || process.argv[1]?.endsWith("setup.ts");

package/dist/tool-dispatch.d.ts

@@ -20,6 +20,8 @@ export type ToolExecutor = (db: FourDADatabase, params: any) => unknown | Promis
  * context; the host already owns the process).
  */
 export declare function dispatchTool(name: string, db: FourDADatabase, args: Record<string, unknown> | undefined): Promise<CallToolResult>;
+/** What a desktop-only tool says when no desktop app database was found. */
+export declare function desktopAppNote(name: string): string;
 /** Check if a tool exists in the dispatch map */
 export declare function hasDispatchTool(name: string): boolean;
 /** Get count of registered tool executors */

package/dist/tool-dispatch.js

@@ -8,6 +8,7 @@
 import { assertToolPermission } from "./auth-context.js";
 import { checkBuildStaleness } from "./build-staleness.js";
 import { cleanStrings } from "./tool-args.js";
+import { TOOL_REGISTRY } from "./schema-registry.js";
 import { executeGetRelevantContent, executeGetContext, executeRecordFeedback, executeGetActionableSignals, executeKnowledgeGaps, executeDecisionMemory, executeCheckDecisionAlignment, executeAgentMemory, executeDeveloperDna, executeWhatShouldIKnow, executeVulnerabilityScan, executeEcosystemPulse, executeDependencyHealth, executeUpgradePlanner, executeDependencyCheck, executeUpgradeImpact, } from "./tools/index.js";
 import { getLiveIntelligence } from "./live-singleton.js";
 /**
@@ -86,7 +87,11 @@ export async function dispatchTool(name, db, args) {
     // Feed freshness describes the desktop app's feed; a standalone install has
     // none, and telling it to "run fourda-engine" is noise.
     const withFreshness = FRESHNESS_TOOLS.has(name) && !db.isStandalone;
-    const payload = cleanStrings(withFreshness ? attachFreshness(db, result) : result);
+    // A desktop-only tool called without the desktop app's database (tools/list
+    // hides these in standalone mode, but a host can call one by name) used to
+    // answer `[]`, which reads as "nothing relevant" rather than "no app".
+    const desktopOnly = db.isStandalone && TOOL_REGISTRY[name]?.standalone === false;
+    const payload = cleanStrings(withFreshness ? attachFreshness(db, result) : desktopOnly ? attachDesktopAppNote(name, result) : result);
     // An executor that returns `{ error: "<message>" }` failed: say so in the
     // protocol, not only in the body, so the host and model treat it as an error.
     const failed = payload !== null && typeof payload === "object" && typeof payload.error === "string";
@@ -140,6 +145,21 @@ function attachFreshness(db, result) {
     }
     return { data_freshness, ...extras, result };
 }
+/** What a desktop-only tool says when no desktop app database was found. */
+export function desktopAppNote(name) {
+    return (`${name} reads the 4DA desktop app's database, and none was found (standalone mode), so this result is empty or partial. ` +
+        "Install the app (https://github.com/4DA-Systems/4DA/releases/latest) or set FOURDA_DB_PATH to its database. " +
+        "The dependency, vulnerability, upgrade and decision tools work without it.");
+}
+/** Same wrapping as attachFreshness: an array becomes { desktop_app_note, item_count, items }. */
+function attachDesktopAppNote(name, result) {
+    const desktop_app_note = desktopAppNote(name);
+    if (Array.isArray(result))
+        return { desktop_app_note, item_count: result.length, items: result };
+    if (result && typeof result === "object")
+        return { desktop_app_note, ...result };
+    return { desktop_app_note, result };
+}
 /** Check if a tool exists in the dispatch map */
 export function hasDispatchTool(name) {
     return name in DISPATCH_MAP;

package/dist/types.d.ts

@@ -119,37 +119,6 @@ export interface UserContext {
         anti_topics: AntiTopic[];
     };
 }
-/**
- * Score breakdown for explain_relevance
- */
-export interface ScoreBreakdown {
-    embedding_similarity: number | null;
-    static_match_score: number;
-    ace_match_score: number;
-    learned_affinity_score: number;
-    anti_penalty: number;
-    final_score: number;
-}
-/**
- * Matching context elements
- */
-export interface MatchingContext {
-    matching_interests: string[];
-    matching_tech: string[];
-    matching_topics: string[];
-    matching_affinities: string[];
-}
-/**
- * Full relevance explanation
- */
-export interface RelevanceExplanation {
-    item_id: number;
-    source_type: string;
-    title: string;
-    score_breakdown: ScoreBreakdown;
-    matching_context: MatchingContext;
-    explanation: string;
-}
 /**
  * Valid feedback action types
  */
@@ -293,107 +262,3 @@ export interface SignalEventRow {
     data: string;
     created_at: string;
 }
-/**
- * Valid agent feedback outcome types
- */
-export type AgentFeedbackOutcome = "used" | "rejected" | "partially_used";
-/**
- * Parameters for recording agent feedback
- */
-export interface RecordAgentFeedbackParams {
-    item_ids: string[];
-    outcome: AgentFeedbackOutcome;
-    context?: string;
-    session_task?: string;
-}
-/**
- * Result from recording agent feedback
- */
-export interface AgentFeedbackResult {
-    success: boolean;
-    message: string;
-    recorded_count: number;
-}
-/**
- * Parameters for getting agent feedback stats
- */
-export interface GetAgentFeedbackStatsParams {
-    days?: number;
-}
-/**
- * Outcome breakdown in agent feedback stats
- */
-export interface AgentFeedbackOutcomeStats {
-    used: number;
-    rejected: number;
-    partially_used: number;
-    total: number;
-}
-/**
- * Per-source feedback stats
- */
-export interface AgentFeedbackSourceStats {
-    source_type: string;
-    used: number;
-    rejected: number;
-    partially_used: number;
-    total: number;
-    usefulness_rate: number;
-}
-/**
- * A frequently used item
- */
-export interface AgentFeedbackTopItem {
-    item_id: string;
-    title: string | null;
-    source_type: string | null;
-    used_count: number;
-    rejected_count: number;
-}
-/**
- * A recent feedback entry
- */
-export interface AgentFeedbackRecentEntry {
-    item_id: string;
-    outcome: string;
-    context: string | null;
-    session_task: string | null;
-    recorded_at: string;
-}
-/**
- * Full agent feedback stats response
- */
-export interface AgentFeedbackStats {
-    period_days: number;
-    outcomes: AgentFeedbackOutcomeStats;
-    by_source: AgentFeedbackSourceStats[];
-    top_used_items: AgentFeedbackTopItem[];
-    recent_feedback: AgentFeedbackRecentEntry[];
-}
-/** Row from agent_feedback table */
-export interface AgentFeedbackRow {
-    item_id: string;
-    outcome: string;
-    context: string | null;
-    session_task: string | null;
-    recorded_at: string;
-}
-/** Row from agent_feedback stats query — outcome counts */
-export interface AgentFeedbackOutcomeRow {
-    outcome: string;
-    cnt: number;
-}
-/** Row from agent_feedback stats query — source breakdown */
-export interface AgentFeedbackSourceRow {
-    source_type: string;
-    outcome: string;
-    cnt: number;
-}
-/** Row from agent_feedback stats query — top items */
-export interface AgentFeedbackTopItemRow {
-    item_id: string;
-    title: string | null;
-    source_type: string | null;
-    used_count: number;
-    rejected_count: number;
-}