@4da/mcp-server 5.0.4 → 6.0.0

package/dist/tool-dispatch.js

@@ -2,11 +2,13 @@
 /**
  * Tool Dispatch Registry
  *
- * Map-based dispatch for the 14 active tools.
+ * Map-based dispatch for the 15 active tools.
  * Adding a new tool = add to this map + schema-registry + barrel export.
  */
 import { assertToolPermission } from "./auth-context.js";
-import { executeGetRelevantContent, executeGetContext, executeRecordFeedback, executeGetActionableSignals, executeKnowledgeGaps, executeDecisionMemory, executeCheckDecisionAlignment, executeAgentMemory, executeDeveloperDna, executeWhatShouldIKnow, executeVulnerabilityScan, executeEcosystemPulse, executeDependencyHealth, executeUpgradePlanner, } from "./tools/index.js";
+import { checkBuildStaleness } from "./build-staleness.js";
+import { cleanStrings } from "./tool-args.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";
 /**
  * Dispatch map — tool name → execute function
@@ -16,13 +18,15 @@ const DISPATCH_MAP = {
     vulnerability_scan: (db, params) => executeVulnerabilityScan(db, params, getLiveIntelligence()),
     dependency_health: (db, params) => executeDependencyHealth(db, params, getLiveIntelligence()),
     upgrade_planner: (db, params) => executeUpgradePlanner(db, params, getLiveIntelligence()),
+    dependency_check: (db, params) => executeDependencyCheck(db, params, getLiveIntelligence()),
+    upgrade_impact: (db, params) => executeUpgradeImpact(db, params, getLiveIntelligence()),
     // Intelligence
     what_should_i_know: executeWhatShouldIKnow,
     ecosystem_pulse: (db, params) => executeEcosystemPulse(db, params, getLiveIntelligence()),
     get_context: executeGetContext,
     get_relevant_content: executeGetRelevantContent,
     get_actionable_signals: executeGetActionableSignals,
-    knowledge_gaps: executeKnowledgeGaps,
+    knowledge_gaps: (db, params) => executeKnowledgeGaps(db, params, getLiveIntelligence()),
     record_feedback: executeRecordFeedback,
     // Decisions
     decision_memory: executeDecisionMemory,
@@ -79,9 +83,24 @@ export async function dispatchTool(name, db, args) {
             throw error;
         }
     }
-    const payload = FRESHNESS_TOOLS.has(name) ? attachFreshness(db, result) : result;
+    // 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);
+    // 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";
+    // The same payload as text AND as structuredContent: hosts disagree on which
+    // one reaches the model (Claude Code and VS Code read the structured form;
+    // Cursor, Zed and Gemini CLI read only the text), so neither may be partial.
+    // Compact JSON: indentation was ~20% of every response's tokens.
+    const structured = payload !== null && typeof payload === "object" && !Array.isArray(payload)
+        ? { structuredContent: payload }
+        : {};
     return {
-        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        ...structured,
+        ...(failed ? { isError: true } : {}),
     };
 }
 /**
@@ -98,13 +117,28 @@ function attachFreshness(db, result) {
     catch {
         return result;
     }
+    // Repo checkouts only (null in the published package): when the running
+    // dist/ predates src/, every DB-backed answer reflects code the repo has
+    // already replaced. Saying so on the payload is what would have caught the
+    // 2026-08-30 two-day-stale server before its bugs were re-diagnosed.
+    let server_build;
+    try {
+        const staleness = checkBuildStaleness();
+        if (staleness?.stale && staleness.note) {
+            server_build = { stale: true, note: staleness.note };
+        }
+    }
+    catch {
+        // Never let the self-check break a tool response.
+    }
+    const extras = server_build ? { server_build } : {};
     if (Array.isArray(result)) {
-        return { data_freshness, item_count: result.length, items: result };
+        return { data_freshness, ...extras, item_count: result.length, items: result };
     }
     if (result && typeof result === "object") {
-        return { data_freshness, ...result };
+        return { data_freshness, ...extras, ...result };
     }
-    return { data_freshness, result };
+    return { data_freshness, ...extras, result };
 }
 /** Check if a tool exists in the dispatch map */
 export function hasDispatchTool(name) {

package/dist/tools/app-plan.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The 4DA app's persisted Upgrade Plan, read for `upgrade_planner` (AD-049).
+ *
+ * The desktop app writes its ranked plan to `kv_store` under
+ * `upgrade_plan_snapshot` after every plan compute (the same envelope
+ * `4da plan --json` prints). From schema 4 the envelope carries `steps`: a
+ * machine-readable work order keyed by plan item id, built in Rust from the
+ * same per-line targets as the item titles. This module only READS it — no
+ * range matching, target walking or scope grading is reimplemented here, so
+ * the agent gets the app's answer, not a second opinion.
+ *
+ * Fail-closed like the Rust reader: any schema version other than
+ * APP_PLAN_SCHEMA_VERSION is treated as absent and the caller falls back to
+ * its standalone heuristic.
+ */
+import type { FourDADatabase } from "../db.js";
+/** The snapshot schema this reader understands (Rust `PLAN_SCHEMA_VERSION`). */
+export declare const APP_PLAN_SCHEMA_VERSION = 4;
+export interface AppPlanSite {
+    project: string;
+    direct: boolean;
+    dev: boolean;
+}
+export interface AppPlanLine {
+    installed: string;
+    target: string | null;
+    upgrade_type: "patch" | "minor" | "major" | null;
+    clears_all_known: boolean;
+    sites: AppPlanSite[];
+}
+export interface AppPlanStep {
+    item_id: string;
+    ecosystem: string;
+    package: string;
+    lines: AppPlanLine[];
+    mechanism: "manifest_bump" | "lockfile_or_parent_update" | "mixed" | "no_fix";
+    advisory_ids: string[];
+    verification: string;
+}
+/** A step with the title and urgency of the plan item it belongs to. */
+export interface AppPlanStepView extends AppPlanStep {
+    title: string | null;
+    urgency: string | null;
+}
+export interface AppPlanSnapshot {
+    schemaVersion: number;
+    generatedAt: string;
+    expiresAt: string;
+    generatorVersion: string | null;
+    sourceFreshness: string | null;
+    multiVersionCoverage: boolean | null;
+    validationDropCount: number | null;
+    itemCount: number;
+    steps: AppPlanStepView[];
+}
+export type AppPlanRead = {
+    kind: "plan";
+    snapshot: AppPlanSnapshot;
+    stale: boolean;
+} | {
+    kind: "absent";
+    reason: string;
+};
+/**
+ * Read the app's plan from the shared database. Never throws: a missing
+ * database, a standalone database without `kv_store`, no snapshot, bad JSON
+ * or another schema version all come back as `absent` with the reason.
+ */
+export declare function readAppPlan(db: FourDADatabase | null | undefined, now?: Date): AppPlanRead;
+export interface AppPlanResult {
+    generatedAt: string;
+    expiresAt: string;
+    /** True past `expiresAt`: the security data the plan read may have moved on. */
+    stale: boolean;
+    staleness: string | null;
+    totalSteps: number;
+    steps: AppPlanStepView[];
+    summary: string;
+    snapshot: Omit<AppPlanSnapshot, "steps" | "generatedAt" | "expiresAt">;
+    provenance: {
+        mode: "app_plan";
+        note: string;
+    };
+}
+/** Shape the app's plan as the tool result; `risk_threshold` / `max_recommendations` narrow it. */
+export declare function formatAppPlan(read: Extract<AppPlanRead, {
+    kind: "plan";
+}>, params: {
+    risk_threshold?: string;
+    max_recommendations?: number;
+    package?: string;
+}): AppPlanResult;

package/dist/tools/app-plan.js

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The 4DA app's persisted Upgrade Plan, read for `upgrade_planner` (AD-049).
+ *
+ * The desktop app writes its ranked plan to `kv_store` under
+ * `upgrade_plan_snapshot` after every plan compute (the same envelope
+ * `4da plan --json` prints). From schema 4 the envelope carries `steps`: a
+ * machine-readable work order keyed by plan item id, built in Rust from the
+ * same per-line targets as the item titles. This module only READS it — no
+ * range matching, target walking or scope grading is reimplemented here, so
+ * the agent gets the app's answer, not a second opinion.
+ *
+ * Fail-closed like the Rust reader: any schema version other than
+ * APP_PLAN_SCHEMA_VERSION is treated as absent and the caller falls back to
+ * its standalone heuristic.
+ */
+/** The snapshot schema this reader understands (Rust `PLAN_SCHEMA_VERSION`). */
+export const APP_PLAN_SCHEMA_VERSION = 4;
+const PLAN_KV_KEY = "upgrade_plan_snapshot";
+/**
+ * Read the app's plan from the shared database. Never throws: a missing
+ * database, a standalone database without `kv_store`, no snapshot, bad JSON
+ * or another schema version all come back as `absent` with the reason.
+ */
+export function readAppPlan(db, now = new Date()) {
+    if (!db)
+        return { kind: "absent", reason: "no 4DA database" };
+    let raw;
+    try {
+        const row = db
+            .getRawDb()
+            .prepare("SELECT value FROM kv_store WHERE key = ?")
+            .get(PLAN_KV_KEY);
+        raw = typeof row?.value === "string" ? row.value : undefined;
+    }
+    catch {
+        return { kind: "absent", reason: "the database has no plan store (the 4DA app has not run on it)" };
+    }
+    if (raw === undefined) {
+        return { kind: "absent", reason: "the 4DA app has not computed an upgrade plan yet" };
+    }
+    let env;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { kind: "absent", reason: "the app's plan snapshot is unreadable" };
+        }
+        env = parsed;
+    }
+    catch {
+        return { kind: "absent", reason: "the app's plan snapshot is unreadable" };
+    }
+    const version = env.schema_version;
+    if (version !== APP_PLAN_SCHEMA_VERSION) {
+        return {
+            kind: "absent",
+            reason: `the app's plan snapshot is schema ${String(version)}, this server reads schema ${APP_PLAN_SCHEMA_VERSION}`,
+        };
+    }
+    if (!Array.isArray(env.steps) || !Array.isArray(env.items)) {
+        return { kind: "absent", reason: "the app's plan snapshot has no work order" };
+    }
+    if (typeof env.generated_at !== "string" || typeof env.expires_at !== "string") {
+        return { kind: "absent", reason: "the app's plan snapshot has no freshness stamp" };
+    }
+    const items = new Map();
+    for (const item of env.items) {
+        if (item && typeof item.id === "string")
+            items.set(item.id, item);
+    }
+    const steps = env.steps.map((step) => {
+        const item = items.get(step.item_id);
+        return { ...step, title: item?.title ?? null, urgency: item?.urgency ?? null };
+    });
+    const expires = Date.parse(env.expires_at);
+    // An unparseable horizon cannot prove freshness: treat it as stale.
+    const stale = Number.isNaN(expires) || now.getTime() > expires;
+    return {
+        kind: "plan",
+        stale,
+        snapshot: {
+            schemaVersion: APP_PLAN_SCHEMA_VERSION,
+            generatedAt: env.generated_at,
+            expiresAt: env.expires_at,
+            generatorVersion: typeof env.generator_version === "string" ? env.generator_version : null,
+            sourceFreshness: typeof env.source_freshness === "string" ? env.source_freshness : null,
+            multiVersionCoverage: typeof env.multi_version_coverage === "boolean" ? env.multi_version_coverage : null,
+            validationDropCount: typeof env.validation_drop_count === "number" ? env.validation_drop_count : null,
+            itemCount: items.size,
+            steps,
+        },
+    };
+}
+const URGENCY_RISK = { critical: 3, high: 2, medium: 1, watch: 0 };
+const RISK_LEVELS = { low: 0, medium: 1, high: 2, critical: 3 };
+const APP_PROVENANCE_NOTE = "The 4DA desktop app's own cross-project, version-confirmed Upgrade Plan, read from its database " +
+    "(the same plan the app shows and `4da plan --json` prints). Each step is keyed by the app's item id.";
+/** Shape the app's plan as the tool result; `risk_threshold` / `max_recommendations` narrow it. */
+export function formatAppPlan(read, params) {
+    const { snapshot, stale } = read;
+    const threshold = params.risk_threshold ?? "all";
+    let steps = snapshot.steps;
+    // `package` narrows the app's plan the same way it narrows the standalone one.
+    const wanted = params.package?.trim().toLowerCase();
+    if (wanted)
+        steps = steps.filter((s) => s.package.toLowerCase() === wanted);
+    if (threshold !== "all" && threshold in RISK_LEVELS) {
+        steps = steps.filter((s) => (URGENCY_RISK[s.urgency ?? ""] ?? 1) >= RISK_LEVELS[threshold]);
+    }
+    // The same default as the standalone plan (20). All 53 steps of a real plan
+    // came to ~11k tokens, past the size Claude Code warns about (2026-10-03).
+    const selected = steps.slice(0, params.max_recommendations ?? 20);
+    const count = (m) => selected.filter((s) => s.mechanism === m).length;
+    const majors = selected.filter((s) => s.lines.some((l) => l.upgrade_type === "major")).length;
+    const parts = [
+        `${selected.length} step${selected.length !== 1 ? "s" : ""} from the 4DA app's plan (generated ${snapshot.generatedAt})`,
+    ];
+    if (count("manifest_bump") > 0)
+        parts.push(`${count("manifest_bump")} manifest bump(s)`);
+    if (count("lockfile_or_parent_update") > 0) {
+        parts.push(`${count("lockfile_or_parent_update")} lockfile or parent update(s) (transitive only)`);
+    }
+    if (count("mixed") > 0)
+        parts.push(`${count("mixed")} mixed (direct in some projects, transitive in others)`);
+    if (count("no_fix") > 0)
+        parts.push(`${count("no_fix")} with no fix published`);
+    if (majors > 0)
+        parts.push(`${majors} cross a major version`);
+    if (selected.length < snapshot.steps.length) {
+        parts.push(`${snapshot.steps.length} in the full plan (raise max_recommendations for the rest)`);
+    }
+    const staleness = stale
+        ? `STALE: past its freshness horizon (${snapshot.expiresAt}). The advisories or installs may have changed since; open the 4DA app to recompute.`
+        : null;
+    if (staleness)
+        parts.push(staleness);
+    return {
+        generatedAt: snapshot.generatedAt,
+        expiresAt: snapshot.expiresAt,
+        stale,
+        staleness,
+        totalSteps: snapshot.steps.length,
+        steps: selected,
+        summary: parts.join(". ") + ".",
+        snapshot: {
+            schemaVersion: snapshot.schemaVersion,
+            generatorVersion: snapshot.generatorVersion,
+            sourceFreshness: snapshot.sourceFreshness,
+            multiVersionCoverage: snapshot.multiVersionCoverage,
+            validationDropCount: snapshot.validationDropCount,
+            itemCount: snapshot.itemCount,
+        },
+        provenance: { mode: "app_plan", note: APP_PROVENANCE_NOTE },
+    };
+}

package/dist/tools/briefing-stored-advisories.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Advisory-database rows in the 4DA feed that name a package a task touches.
+ *
+ * Only the feed's advisory sources count (`cve`, `osv`): their titles name the
+ * affected package. A headline that happens to contain a package name is not
+ * an advisory — that is how OpenAI-the-company news became "Critical: Security
+ * issue affects openai" (2026-10-01). Rows the relevance judge rejected
+ * (`feed_relevant = 0`) are left out. These rows are NOT matched to installed
+ * versions; the briefing says so, and with a ready scan keeps them only for
+ * packages the scan confirms vulnerable.
+ */
+import type { FourDADatabase } from "../db.js";
+import type { TaskPackage } from "./briefing-task-scope.js";
+export interface StoredAdvisory {
+    package: string;
+    title: string;
+    url: string | null;
+    priority: string;
+}
+export declare function storedAdvisoriesFor(db: FourDADatabase, packages: TaskPackage[], limit?: number): StoredAdvisory[];

package/dist/tools/briefing-stored-advisories.js

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Advisory-database rows in the 4DA feed that name a package a task touches.
+ *
+ * Only the feed's advisory sources count (`cve`, `osv`): their titles name the
+ * affected package. A headline that happens to contain a package name is not
+ * an advisory — that is how OpenAI-the-company news became "Critical: Security
+ * issue affects openai" (2026-10-01). Rows the relevance judge rejected
+ * (`feed_relevant = 0`) are left out. These rows are NOT matched to installed
+ * versions; the briefing says so, and with a ready scan keeps them only for
+ * packages the scan confirms vulnerable.
+ */
+import { normalizeStoredPriority } from "./signal-classifier.js";
+const ADVISORY_SOURCES = ["cve", "osv"];
+export function storedAdvisoriesFor(db, packages, limit = 5) {
+    if (packages.length === 0)
+        return [];
+    const raw = db.getRawDb();
+    const hasFeedRelevant = (() => {
+        try {
+            return raw.prepare("PRAGMA table_info(source_items)").all().some((c) => c.name === "feed_relevant");
+        }
+        catch {
+            return false;
+        }
+    })();
+    const out = [];
+    for (const pkg of packages) {
+        let rows;
+        try {
+            rows = raw
+                .prepare(`SELECT title, url, signal_priority FROM source_items
+           WHERE source_type IN (${ADVISORY_SOURCES.map(() => "?").join(", ")})
+             AND created_at > datetime('now', '-90 days')
+             AND LOWER(title) LIKE ?
+             ${hasFeedRelevant ? "AND (feed_relevant IS NULL OR feed_relevant = 1)" : ""}
+           ORDER BY created_at DESC LIMIT 20`)
+                .all(...ADVISORY_SOURCES, `%${pkg.name.toLowerCase()}%`);
+        }
+        catch {
+            continue;
+        }
+        const word = new RegExp(`(^|[^\\w@/-])${pkg.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w-])`, "i");
+        for (const row of rows) {
+            if (!word.test(row.title))
+                continue;
+            out.push({
+                package: pkg.name,
+                title: row.title,
+                url: row.url,
+                priority: row.signal_priority ? normalizeStoredPriority(row.signal_priority) : "medium",
+            });
+            if (out.length >= limit)
+                return out;
+        }
+    }
+    return out;
+}

package/dist/tools/briefing-task-scope.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Which of this project's dependencies a task touches, and what is known
+ * about each — the core of the what_should_i_know briefing.
+ *
+ * Measured 2026-10-01: asked about "bump fastembed 5 -> 7", the briefing
+ * returned eleven advisories and none about fastembed. It never asked which
+ * packages the task names; it merged feed items by recency and keyword class,
+ * so a 7-day-old `fastembed v7.1.0` release row was outside its 72-hour window
+ * while an arXiv dataset paper and three OpenAI-company headlines were in.
+ * This module starts from the task instead: the dependencies it names (exact
+ * package names from the resolved dependency set), then facts about exactly
+ * those packages.
+ */
+import type { FourDADatabase } from "../db.js";
+import type { ResolvedDependency, VulnerabilityEntry } from "../live/types.js";
+/** A dependency the task names, with every installed copy. */
+export interface TaskPackage {
+    name: string;
+    ecosystem: string;
+    installed: string[];
+    direct: boolean;
+    dev: boolean;
+    /** Versions the task text names after the package ("5.x to 7.x" -> from 5.x, to 7.x). */
+    requested_from: string | null;
+    requested_to: string | null;
+}
+/**
+ * Package names that are also everyday words. One of these counts as named
+ * only with a qualifier beside it — "the next crate", "`next`", "upgrade
+ * next to 15" — so "the next step" does not drag the `next` package in.
+ */
+export declare const COMMON_WORDS: Set<string>;
+/**
+ * The dependencies a task (and its file list) names. Exact names only; a
+ * common-word name needs a qualifier within two tokens or code quoting.
+ * Direct dependencies first; at most `limit` packages.
+ */
+export declare function detectTaskPackages(task: string, files: string[], deps: ResolvedDependency[], limit?: number): TaskPackage[];
+/** Major version of a version or a `7.x` / `v7` request; null when unreadable. */
+export declare function majorOf(version: string | null): number | null;
+/** Actionable advisories on the installed copies of one package, highest presented severity first. */
+export declare function advisoriesFor(pkg: TaskPackage, vulns: VulnerabilityEntry[]): {
+    id: string;
+    installed: string;
+    severity: "critical" | "high" | "low" | "medium" | "unknown";
+    fixed_version: string | null;
+    summary: string;
+}[];
+/**
+ * Registry release rows the desktop app's feed holds for one package, newer
+ * than the installed version. Matched on the registry's own title format
+ * (`crates.io: fastembed v7.1.0`), never on a free-text mention. Empty in
+ * standalone mode (no feed) or for ecosystems the feed does not watch.
+ */
+export declare function releasesFor(db: FourDADatabase, pkg: TaskPackage): Array<{
+    version: string;
+    seen: string;
+    url: string | null;
+}>;
+/**
+ * Feed items about the task's packages that the app's relevance judge
+ * accepted (latest `llm_judgments` verdict >= 0.5) and that the feed kept
+ * (`feed_relevant` = 1). Exact package-name match on a word boundary in the
+ * title. Third-party text: reported as data. Empty without the desktop feed.
+ */
+export declare function judgedReadingFor(db: FourDADatabase, packages: TaskPackage[], limit?: number): {
+    id: number;
+    title: string;
+    url: string | null;
+    source: string;
+    judge_relevance: number;
+    package: string;
+}[];