@debugai/mcp 2.4.3 → 2.5.0

package/README.md

@@ -233,6 +233,13 @@ Recent server-side work, all of it live for agents already:
 - pytest, unittest, jest, vitest and mocha output yields real file paths, so a
   failing test gets cross-file context instead of none.
 
+**2.5.0** - The server now reads what your project declares and sends it with the
+error: dependency names and the versions your own manifests pin, including
+`.csproj` for .NET and nested manifests in a monorepo. The engine could never see
+your disk, so it used to guess at third-party APIs - it now knows when a version
+is pinned exactly, and says it does not know when nothing pins it. `.env` is
+never opened; only its existence is reported.
+
 **2.4.2**: the bundled server prints the memory it advertises. This package and
 the copy bundled in the VS Code extension are the same server, and only this one
 was rendering the recurrence count and confirmed fix that both of them promise an

package/dist/backend.d.ts

@@ -6,6 +6,17 @@ export interface DebugRequest {
     file_path?: string;
     project_id?: string;
     framework_hint?: string;
+    /**
+     * What this repository declares, read off disk by the local server.
+     * Optional on purpose: an older gateway ignores an unknown field, and a newer
+     * engine treats its absence as "we do not know" rather than "there is none".
+     * See ../gatherWorkspaceFacts.ts.
+     *
+     * Typed as an opaque object rather than a named shape: this module's job is
+     * to forward JSON, and importing the fact type here would couple the
+     * transport to a contract that gains fields independently of it.
+     */
+    workspace_facts?: object;
 }
 export interface DebugEdit {
     file: string;

package/dist/gatherWorkspaceFacts.d.ts

@@ -0,0 +1,64 @@
+import { type WorkspaceFacts } from './workspaceFacts.js';
+/**
+ * Opened by exact name only. `.env` is absent on purpose - see the header.
+ *
+ * Load bearing, and it took a mutation pass to make it so: the reads used to be
+ * driven by three hard-coded `joined('package.json')` calls, which meant adding
+ * `.env` to this Set changed no behaviour and turned no test red. A guard that
+ * cannot be broken by editing it is not a guard. Everything now iterates this
+ * list, and `drift.test.ts` pins its exact contents.
+ */
+export declare const MANIFEST_FILES: readonly ["package.json", "requirements.txt", "pyproject.toml"];
+/** A manifest larger than this is not a manifest we can use. */
+export declare const MAX_MANIFEST_BYTES: number;
+/** Directories visited. A monorepo must cost a bounded walk, not a full one. */
+export declare const MAX_DIRS = 400;
+/** How deep. Deep enough for `services/api/src`, shallow enough to stay cheap. */
+export declare const MAX_DEPTH = 6;
+/** Python files collected for `local_modules`. Matches the extension's cap. */
+export declare const MAX_PY_FILES = 600;
+/** .NET project files read. Six services is a normal solution; twelve is plenty. */
+export declare const MAX_CSPROJ = 12;
+/**
+ * Nested manifests read, beyond the root ones.
+ *
+ * A monorepo keeps its real dependencies in subdirectories - this repository's
+ * root `package.json` declares exactly one package while `apps/web` declares
+ * forty, and salman's react-dom error was about `web/package.json` in a tree
+ * whose root is a .NET solution. Reading only the root would have made the
+ * feature answer confidently about the wrong half of his project.
+ */
+export declare const MAX_NESTED_MANIFESTS = 8;
+/** Wall clock. A slow or network filesystem costs the facts, never the debug. */
+export declare const DEADLINE_MS = 1500;
+/**
+ * How long a gathered set stays good.
+ *
+ * The VS Code extension has cached these on the same TTL since 2026-09-10 (it
+ * shares the framework hint's window) and this copy shipped without one - an
+ * agent working through a failing build calls `debug_error` repeatedly, and
+ * every call was walking the tree again. Five minutes is also the CORRECTNESS
+ * bound, and it is the reason the TTL is short rather than long: install a
+ * package and the facts are stale, so the window has to be small enough that a
+ * wrong answer cannot outlive the mistake by much.
+ */
+export declare const CACHE_TTL_MS: number;
+/** Test seam. Never called in production. */
+export declare function __resetWorkspaceFactsCache(): void;
+/** What the gatherer adds on top of the shared pure contract. */
+export interface GatheredFacts extends WorkspaceFacts {
+    /**
+     * A `.env` (or `.env.*`) sits at the project root.
+     *
+     * Recorded because two of the 76 fixes in the 2026-09-13 corpus turned on it
+     * - one workspace had only `.env.example`, another had a deployed value that
+     * differed from the local file - and because "there is one" is the whole of
+     * what can be safely known. The contents are never read.
+     */
+    has_env_file: boolean;
+}
+/**
+ * Gather what this repository declares. Returns null when there is nothing
+ * worth sending, when the root is unusable, or on any failure at all.
+ */
+export declare function gatherWorkspaceFacts(root: string | null | undefined): GatheredFacts | null;

package/dist/gatherWorkspaceFacts.js

@@ -0,0 +1,369 @@
+/**
+ * Read this project's manifests off disk, so the engine stops guessing.
+ *
+ * ## The hole
+ *
+ * `workspaceFacts.ts` (pure, beside this file) has existed since 2026-09-10 and
+ * answers the question every wrong diagnosis needed: what is actually on this
+ * machine. It runs in the VS Code extension only. It has never run here.
+ *
+ * A read of 76 production `debug_feedback.actual_fix` rows on 2026-09-13 put
+ * numbers on that: the largest single class of wrong answer, 24%, needed a fact
+ * about the MACHINE rather than about the error - an interpreter, a declared
+ * dependency, an installed version. And 54 of the last 83 debugs arrived over
+ * MCP, where none of those facts are sent.
+ *
+ * The clearest case is one line of one file on 2026-09-12. Four consecutive
+ * answers guessed at `Elastic.Clients.Elasticsearch` constructor signatures and
+ * a fifth invented `.AddPassiveHealthCheckPolicies()` on YARP, at confidence 92,
+ * while the user's own `.csproj` said `Version="2.3.0"` the whole time - and
+ * this process was running inside that repository.
+ *
+ * ## Why the server reads them rather than asking the agent
+ *
+ * Same reason `sourceContext.ts` reads the files a trace names: this is a local
+ * process with the filesystem the engine lacks, and an agent that has to be
+ * asked for something will be asked differently by every client. Reading costs
+ * one bounded walk; asking costs a contract with every MCP host there is.
+ *
+ * ## What it refuses to do
+ *
+ * The security model here is an EXACT-NAME allowlist, and it has to be, because
+ * the extension allowlist that protects `sourceContext.ts` does not apply: a
+ * manifest has no source extension. Only the names in `MANIFEST_FILES` are ever
+ * opened, plus files matching `PROJECT_EXT` whose names vary by project.
+ *
+ * `.env` is deliberately NOT in that list, and never will be. It is the single
+ * most useful-looking file here and it holds secrets; two production rows had a
+ * live Stripe key and a Discord bot token pasted into an error box already, and
+ * we are not going to be the ones who send the next one. Its EXISTENCE is a
+ * fact worth having and costs nothing - `has_env_file` says so without reading
+ * a byte.
+ *
+ * Everything resolves inside the project root after symlinks, the walk is
+ * depth- and count-bounded, and every read is size-capped. A repository is
+ * untrusted input; it was cloned, not written.
+ *
+ * ## Never throws
+ *
+ * Returns `null` rather than raising, on every path. A debug that fails because
+ * the fact-gatherer tripped over a permissions error would be strictly worse
+ * than the guessing this replaces.
+ */
+import { readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve, extname, relative, sep } from 'node:path';
+import { buildWorkspaceFacts } from './workspaceFacts.js';
+/**
+ * Opened by exact name only. `.env` is absent on purpose - see the header.
+ *
+ * Load bearing, and it took a mutation pass to make it so: the reads used to be
+ * driven by three hard-coded `joined('package.json')` calls, which meant adding
+ * `.env` to this Set changed no behaviour and turned no test red. A guard that
+ * cannot be broken by editing it is not a guard. Everything now iterates this
+ * list, and `drift.test.ts` pins its exact contents.
+ */
+export const MANIFEST_FILES = [
+    'package.json',
+    'requirements.txt',
+    'pyproject.toml',
+];
+function isManifestName(name) {
+    return MANIFEST_FILES.includes(name);
+}
+/** .NET project files. Names vary per project, so these go by extension. */
+const PROJECT_EXT = new Set(['.csproj', '.fsproj', '.vbproj']);
+/** Never descended into. Same list the chunker and sourceContext use. */
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', '__pycache__', '.venv', 'venv', 'env', '.virtualenv',
+    'dist', 'build', 'out', '.next', '.nuxt', 'coverage', 'target', 'bin', 'obj',
+    '.idea', '.vscode', '.cache', 'vendor', 'site-packages',
+]);
+/** A manifest larger than this is not a manifest we can use. */
+export const MAX_MANIFEST_BYTES = 512 * 1024;
+/** Directories visited. A monorepo must cost a bounded walk, not a full one. */
+export const MAX_DIRS = 400;
+/** How deep. Deep enough for `services/api/src`, shallow enough to stay cheap. */
+export const MAX_DEPTH = 6;
+/** Python files collected for `local_modules`. Matches the extension's cap. */
+export const MAX_PY_FILES = 600;
+/** .NET project files read. Six services is a normal solution; twelve is plenty. */
+export const MAX_CSPROJ = 12;
+/**
+ * Nested manifests read, beyond the root ones.
+ *
+ * A monorepo keeps its real dependencies in subdirectories - this repository's
+ * root `package.json` declares exactly one package while `apps/web` declares
+ * forty, and salman's react-dom error was about `web/package.json` in a tree
+ * whose root is a .NET solution. Reading only the root would have made the
+ * feature answer confidently about the wrong half of his project.
+ */
+export const MAX_NESTED_MANIFESTS = 8;
+/** Wall clock. A slow or network filesystem costs the facts, never the debug. */
+export const DEADLINE_MS = 1500;
+/**
+ * How long a gathered set stays good.
+ *
+ * The VS Code extension has cached these on the same TTL since 2026-09-10 (it
+ * shares the framework hint's window) and this copy shipped without one - an
+ * agent working through a failing build calls `debug_error` repeatedly, and
+ * every call was walking the tree again. Five minutes is also the CORRECTNESS
+ * bound, and it is the reason the TTL is short rather than long: install a
+ * package and the facts are stale, so the window has to be small enough that a
+ * wrong answer cannot outlive the mistake by much.
+ */
+export const CACHE_TTL_MS = 5 * 60 * 1000;
+let cached = null;
+/** Test seam. Never called in production. */
+export function __resetWorkspaceFactsCache() {
+    cached = null;
+}
+function insideRoot(candidate, root) {
+    let realRoot;
+    let realCandidate;
+    try {
+        realRoot = realpathSync(root);
+    }
+    catch {
+        return false;
+    }
+    try {
+        realCandidate = realpathSync(candidate);
+    }
+    catch {
+        return false;
+    }
+    const rel = relative(realRoot, realCandidate);
+    return rel === '' || (!rel.startsWith('..') && !rel.startsWith(sep + '..'));
+}
+function readCapped(path, root) {
+    try {
+        if (!insideRoot(path, root)) {
+            return null;
+        }
+        const st = statSync(path);
+        if (!st.isFile() || st.size > MAX_MANIFEST_BYTES) {
+            return null;
+        }
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One bounded pass over the tree.
+ *
+ * Breadth-first so that a shallow, relevant directory is always visited before
+ * a deep one - when the caps bite, what survives is the top of the project
+ * rather than whichever branch the walk happened to enter first.
+ */
+function walk(root, deadline) {
+    const out = {
+        pythonFiles: [], pythonTruncated: false,
+        csprojPaths: [], csprojTruncated: false,
+        nested: [], nestedTruncated: false,
+        rootDirs: [], hasEnvFile: false,
+    };
+    const queue = [{ dir: root, depth: 0 }];
+    let visited = 0;
+    while (queue.length > 0) {
+        if (Date.now() > deadline) {
+            out.pythonTruncated = true;
+            out.csprojTruncated = true;
+            break;
+        }
+        if (visited >= MAX_DIRS) {
+            out.pythonTruncated = true;
+            out.csprojTruncated = true;
+            break;
+        }
+        const next = queue.shift();
+        if (!next) {
+            break;
+        }
+        const { dir, depth } = next;
+        visited += 1;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true })
+                .map(d => ({ name: d.name, isDir: d.isDirectory() }));
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            // A symlink reports `isDirectory() === false`, so a link to a directory
+            // is never descended into - which was accidental protection until a
+            // mutation pass showed the containment test passing for that reason
+            // rather than for the check it was written to exercise. A symlinked FILE
+            // does fall through to the file branch below, gets collected, and is
+            // stopped by `insideRoot` inside `readCapped`. Both halves are needed and
+            // both are now pinned by their own test.
+            if (e.isDir) {
+                if (depth === 0) {
+                    out.rootDirs.push(e.name);
+                }
+                if (SKIP_DIRS.has(e.name) || e.name.startsWith('.')) {
+                    continue;
+                }
+                if (depth + 1 <= MAX_DEPTH) {
+                    queue.push({ dir: join(dir, e.name), depth: depth + 1 });
+                }
+                continue;
+            }
+            if (depth === 0 && (e.name === '.env' || e.name.startsWith('.env.'))) {
+                // Recorded, never opened. See the header.
+                out.hasEnvFile = true;
+            }
+            if (depth > 0 && isManifestName(e.name)) {
+                if (out.nested.length < MAX_NESTED_MANIFESTS) {
+                    out.nested.push({ name: e.name, path: join(dir, e.name) });
+                }
+                else {
+                    out.nestedTruncated = true;
+                }
+            }
+            const ext = extname(e.name).toLowerCase();
+            if (ext === '.py') {
+                if (out.pythonFiles.length < MAX_PY_FILES) {
+                    out.pythonFiles.push(relative(root, join(dir, e.name)));
+                }
+                else {
+                    out.pythonTruncated = true;
+                }
+            }
+            else if (PROJECT_EXT.has(ext)) {
+                if (out.csprojPaths.length < MAX_CSPROJ) {
+                    out.csprojPaths.push(join(dir, e.name));
+                }
+                else {
+                    out.csprojTruncated = true;
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Gather what this repository declares. Returns null when there is nothing
+ * worth sending, when the root is unusable, or on any failure at all.
+ */
+export function gatherWorkspaceFacts(root) {
+    try {
+        if (!root || typeof root !== 'string') {
+            return null;
+        }
+        const abs = resolve(root);
+        // Keyed by root, not merely time: a single agent process can be pointed at
+        // more than one repository, and serving one project's manifests for another
+        // would be worse than sending nothing at all.
+        const now = Date.now();
+        if (cached && cached.root === abs && (now - cached.at) < CACHE_TTL_MS) {
+            return cached.facts;
+        }
+        try {
+            if (!statSync(abs).isDirectory()) {
+                return null;
+            }
+        }
+        catch {
+            // Deliberately NOT cached. A root that does not exist yet may exist on
+            // the next call (a clone finishing, a folder being opened), and caching
+            // the failure would hold the feature off for five minutes for no reason.
+            return null;
+        }
+        const deadline = Date.now() + DEADLINE_MS;
+        const walked = walk(abs, deadline);
+        const manifest = (name) => isManifestName(name) ? readCapped(join(abs, name), abs) : null;
+        // Nested manifests, concatenated per KIND into the same string the root one
+        // occupies. Concatenation is safe for every format here and keeps the pure
+        // builder's contract untouched: requirements.txt is line-oriented, and both
+        // JSON and TOML parsers in `workspaceFacts.ts` are regex-shaped rather than
+        // strict, by the design documented there. A package.json that fails to
+        // parse contributes nothing rather than breaking the set.
+        const extraByKind = {};
+        for (const n of walked.nested) {
+            if (Date.now() > deadline) {
+                walked.nestedTruncated = true;
+                break;
+            }
+            const text = readCapped(n.path, abs);
+            if (text === null) {
+                continue;
+            }
+            (extraByKind[n.name] ||= []).push(text);
+        }
+        const joined = (name) => {
+            const root = manifest(name);
+            const extra = extraByKind[name] || [];
+            if (root === null && extra.length === 0) {
+                return null;
+            }
+            if (name === 'package.json') {
+                // JSON cannot be concatenated. Merge the dependency blocks instead,
+                // which is the only part `depsFromPackageJson` and its version twin
+                // read. Anything unparseable is skipped, never thrown.
+                const merged = {};
+                for (const text of [root, ...extra]) {
+                    if (text === null) {
+                        continue;
+                    }
+                    let pkg;
+                    try {
+                        pkg = JSON.parse(text);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!pkg || typeof pkg !== 'object') {
+                        continue;
+                    }
+                    for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+                        const block = pkg[field];
+                        if (!block || typeof block !== 'object' || Array.isArray(block)) {
+                            continue;
+                        }
+                        merged[field] = { ...block, ...(merged[field] || {}) }; // first file wins
+                    }
+                }
+                return JSON.stringify(merged);
+            }
+            return [root, ...extra].filter((t) => t !== null).join('\n');
+        };
+        const csprojFiles = [];
+        for (const p of walked.csprojPaths) {
+            if (Date.now() > deadline) {
+                walked.csprojTruncated = true;
+                break;
+            }
+            const text = readCapped(p, abs);
+            if (text !== null) {
+                csprojFiles.push(text);
+            }
+        }
+        const facts = buildWorkspaceFacts({
+            packageJson: joined('package.json'),
+            requirementsTxt: joined('requirements.txt'),
+            pyprojectToml: joined('pyproject.toml'),
+            csprojFiles,
+            // A manifest list we stopped enumerating declares more than we can see,
+            // and a name missing from a short list must prove nothing.
+            csprojTruncated: walked.csprojTruncated || walked.nestedTruncated,
+            pythonFiles: walked.pythonFiles,
+            pythonFilesTruncated: walked.pythonTruncated,
+            rootDirs: walked.rootDirs,
+            // Deliberately absent: `python_interpreter`. VS Code's Python extension
+            // reports which interpreter is SELECTED; this process has no equivalent
+            // and could only report its own `process.execPath`, which is node. A
+            // wrong fact is worse than a missing one - the engine treats absence as
+            // "we do not know" and says so, which is true here.
+            pythonInterpreter: null,
+        });
+        const out = { ...facts, has_env_file: walked.hasEnvFile };
+        cached = { root: abs, at: now, facts: out };
+        return out;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/tools/debugError.js

@@ -5,6 +5,7 @@ import { resolveAuth } from './authGate.js';
 import { getProjectId, getProjectRoot } from '../project.js';
 import { memorySection } from '../memorySection.js';
 import { resolveSourceContext } from '../sourceContext.js';
+import { gatherWorkspaceFacts } from '../gatherWorkspaceFacts.js';
 // Tri-state verification labeling (docs/plan-v2-contract-phase1.md §1).
 // The null case is rendered ON PURPOSE: a confidence number nothing checked
 // must never look the same as one that was mechanically verified.
@@ -96,6 +97,16 @@ export function registerDebugError(server, config) {
         }
         const snippet = codeSnippet ?? resolved?.snippet;
         const effectiveFilePath = filePath ?? resolved?.files[0]?.label;
+        // What this repository declares - dependency names and the versions its
+        // own manifests pin. The engine cannot read a disk and this process is
+        // sitting on the one that matters.
+        //
+        // Unconditional, unlike the source resolution above: an agent's snippet
+        // can replace what WE would have read, but no agent sends a .csproj, and
+        // 24% of the wrong answers in the 2026-09-13 corpus needed exactly this.
+        // Bounded and total - see ../gatherWorkspaceFacts.ts - so the worst case
+        // is null and a prompt identical to today's.
+        const workspaceFacts = gatherWorkspaceFacts(getProjectRoot());
         try {
             const result = await callDebugBackend({
                 error_message: errorText,
@@ -108,6 +119,7 @@ export function registerDebugError(server, config) {
                 // from the git repo root so it agrees with the VS Code extension's
                 // md5(workspaceFolder) for the same checkout. See ../project.ts.
                 project_id: getProjectId() ?? undefined,
+                workspace_facts: workspaceFacts ?? undefined,
                 // framework_hint deliberately omitted: a language ('python') is not a
                 // framework ('fastapi'), and sending it bypasses the engine's
                 // framework detection — FastAPI/React errors lose their expert hints.