From 70b07aa14ca4fd34a272da981f8c1ef038e7b710 Mon Sep 17 00:00:00 2001
From: SweetRetry <zimin.zhang2000@gmail.com>
Date: Wed, 19 Aug 2026 20:22:47 +0800
Subject: [PATCH 1/2] Add production source location plugins

Add opt-in Next.js and Vite build integrations backed by a compact source manifest. Resolve instrumented DOM elements in the Agentation runtime and cover workspace, binding, and loader-order behavior.
---
 package.json                                  |   1 +
 .../source-location.instrumentation.test.ts   |  44 ++++
 package/src/utils/source-location.ts          |  58 +++++
 plugins/source-locations/README.md            |  83 +++++++
 plugins/source-locations/core.cjs             | 230 ++++++++++++++++++
 plugins/source-locations/core.test.cjs        |  70 ++++++
 plugins/source-locations/next.cjs             |  80 ++++++
 plugins/source-locations/package.json         |  26 ++
 plugins/source-locations/plugin.test.cjs      |  62 +++++
 plugins/source-locations/turbopack-loader.cjs |  25 ++
 plugins/source-locations/vite.cjs             | 102 ++++++++
 pnpm-lock.yaml                                |   6 +
 pnpm-workspace.yaml                           |   1 +
 13 files changed, 788 insertions(+)
 create mode 100644 package/src/utils/source-location.instrumentation.test.ts
 create mode 100644 plugins/source-locations/README.md
 create mode 100644 plugins/source-locations/core.cjs
 create mode 100644 plugins/source-locations/core.test.cjs
 create mode 100644 plugins/source-locations/next.cjs
 create mode 100644 plugins/source-locations/package.json
 create mode 100644 plugins/source-locations/plugin.test.cjs
 create mode 100644 plugins/source-locations/turbopack-loader.cjs
 create mode 100644 plugins/source-locations/vite.cjs

diff --git a/package.json b/package.json
index 397c027f..f281d8ea 100644
--- a/package.json
+++ b/package.json
@@ -5,6 +5,7 @@
   "scripts": {
     "dev": "pnpm --filter agentation watch & pnpm --filter feedback-tool-example dev",
     "build": "pnpm --filter agentation build",
+    "test": "pnpm --filter agentation test && pnpm --filter @agentation/source-locations test",
     "example": "pnpm --filter feedback-tool-example dev",
     "pack": "cd package && pnpm pack",
     "mcp": "pnpm --filter agentation-mcp start",
diff --git a/package/src/utils/source-location.instrumentation.test.ts b/package/src/utils/source-location.instrumentation.test.ts
new file mode 100644
index 00000000..3de7588a
--- /dev/null
+++ b/package/src/utils/source-location.instrumentation.test.ts
@@ -0,0 +1,44 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { getSourceLocation } from "./source-location";
+
+describe("build-time source location instrumentation", () => {
+  afterEach(() => {
+    delete globalThis.__AGENTATION_SOURCE_MANIFEST__;
+  });
+
+  it("resolves an exact source location without a React fiber", () => {
+    const element = document.createElement("button");
+    element.setAttribute("data-agentation-id", "source-id");
+    globalThis.__AGENTATION_SOURCE_MANIFEST__ = {
+      version: 1,
+      files: ["src/app/Inspector.tsx"],
+      locations: { "source-id": [0, 24, 6] },
+    };
+
+    expect(getSourceLocation(element)).toEqual({
+      found: true,
+      source: {
+        fileName: "src/app/Inspector.tsx",
+        lineNumber: 24,
+        columnNumber: 6,
+      },
+      isReactApp: true,
+      isProduction: false,
+    });
+  });
+
+  it("falls back when the manifest does not contain the injected id", () => {
+    const element = document.createElement("button");
+    element.setAttribute("data-agentation-id", "missing-id");
+    globalThis.__AGENTATION_SOURCE_MANIFEST__ = {
+      version: 1,
+      files: [],
+      locations: {},
+    };
+
+    expect(getSourceLocation(element)).toMatchObject({
+      found: false,
+      reason: "no-fiber",
+    });
+  });
+});
diff --git a/package/src/utils/source-location.ts b/package/src/utils/source-location.ts
index d23b3309..b5578f9a 100644
--- a/package/src/utils/source-location.ts
+++ b/package/src/utils/source-location.ts
@@ -36,6 +36,20 @@ export interface SourceLocation {
   reactVersion?: string;
 }
 
+/** Compact build-time source location tuple: file index, line, column. */
+export type SourceLocationTuple = [number, number, number];
+
+/** Build-time instrumentation manifest used by `data-agentation-id`. */
+export interface SourceLocationManifest {
+  version: 1;
+  files: string[];
+  locations: Record<string, SourceLocationTuple>;
+}
+
+declare global {
+  var __AGENTATION_SOURCE_MANIFEST__: SourceLocationManifest | undefined;
+}
+
 /**
  * Result of source location detection
  */
@@ -114,6 +128,40 @@ interface ReactDOMElement extends HTMLElement {
   _reactRootContainer?: unknown;
 }
 
+const SOURCE_LOCATION_ATTRIBUTE = "data-agentation-id";
+
+/**
+ * Resolve source metadata injected by an Agentation build integration.
+ * This is intentionally checked before React internals because it remains
+ * stable in production builds and identifies the exact JSX host element.
+ */
+function findInstrumentedSource(element: HTMLElement): SourceLocation | null {
+  const sourceId = element.getAttribute(SOURCE_LOCATION_ATTRIBUTE);
+  if (!sourceId) return null;
+
+  const manifest = globalThis.__AGENTATION_SOURCE_MANIFEST__;
+  if (manifest?.version !== 1) return null;
+
+  const source = manifest.locations[sourceId];
+  if (
+    !source ||
+    typeof source[0] !== "number" ||
+    typeof source[1] !== "number" ||
+    typeof source[2] !== "number"
+  ) {
+    return null;
+  }
+
+  const fileName = manifest.files[source[0]];
+  if (typeof fileName !== "string") return null;
+
+  return {
+    fileName,
+    lineNumber: source[1],
+    columnNumber: source[2],
+  };
+}
+
 // React fiber tag constants (for reference)
 const FIBER_TAGS = {
   FunctionComponent: 0,
@@ -671,6 +719,16 @@ function probeSourceWalk(
  * ```
  */
 export function getSourceLocation(element: HTMLElement): SourceLocationResult {
+  const instrumentedSource = findInstrumentedSource(element);
+  if (instrumentedSource) {
+    return {
+      found: true,
+      source: instrumentedSource,
+      isReactApp: true,
+      isProduction: false,
+    };
+  }
+
   // Try to get fiber directly from the element (same approach as getReactComponentName)
   // This avoids detectReactApp() whose production heuristic can give false positives
   const fiber = getFiberFromElement(element);
diff --git a/plugins/source-locations/README.md b/plugins/source-locations/README.md
new file mode 100644
index 00000000..d114e772
--- /dev/null
+++ b/plugins/source-locations/README.md
@@ -0,0 +1,83 @@
+# Agentation source locations
+
+This first-party plugin lives in the Agentation monorepo because its manifest
+format is consumed directly by the Agentation runtime and must evolve atomically
+with that lookup contract.
+
+Build-time JSX instrumentation for exact production source locations. It adds a
+short `data-agentation-id` to rendered DOM and generates a manifest that maps the
+ID back to `file:line:column` without shipping source code.
+
+The manifest stores file paths once and represents each location as a compact
+`[fileIndex, line, column]` tuple.
+
+Instrumentation is enabled for production builds only by default. Development
+servers stay unchanged. Pass `enabled: true` only when development instrumentation
+is intentional.
+
+## Next.js 16 (Turbopack)
+
+Single-project repositories use `src` and `public` by default:
+
+```js
+const { withAgentationSourceLocations } = require("@agentation/source-locations/next");
+
+module.exports = withAgentationSourceLocations({});
+```
+
+For a monorepo, distinguish the application directory that owns `public` from the
+repository root used in reported source paths:
+
+```js
+const path = require("node:path");
+const { withAgentationSourceLocations } = require("@agentation/source-locations/next");
+
+module.exports = withAgentationSourceLocations(nextConfig, {
+  projectDir: __dirname,
+  rootDir: path.resolve(__dirname, "../.."),
+  sourceDirs: ["apps/web/src", "packages/ui/src"],
+});
+```
+
+Load the generated manifest before Agentation in the production document:
+
+```tsx
+import Script from "next/script";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <Script
+          src="/_agentation/source-manifest.js"
+          strategy="beforeInteractive"
+        />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+The Next plugin instruments intrinsic JSX plus components imported directly from
+`next/image` and `next/link`. It intentionally does not instrument arbitrary custom
+components or wrappers, because forwarding an unknown DOM attribute is not part of
+their contract. Existing Turbopack `.tsx` and `.jsx` rules are preserved.
+
+## Vite 7 + React
+
+```js
+import { defineConfig } from "vite";
+import { agentationSourceLocations } from "@agentation/source-locations/vite";
+
+export default defineConfig({
+  plugins: [agentationSourceLocations()],
+});
+```
+
+Vite injects the manifest script into built HTML. A monorepo can use the same
+`rootDir` and `sourceDirs` options shown above. Vite instruments intrinsic JSX; it
+does not need Next-specific component handling.
+
+Add `public/_agentation/` to `.gitignore` in Next projects. The file is generated
+during each build.
diff --git a/plugins/source-locations/core.cjs b/plugins/source-locations/core.cjs
new file mode 100644
index 00000000..49b7c809
--- /dev/null
+++ b/plugins/source-locations/core.cjs
@@ -0,0 +1,230 @@
+const fs = require("node:fs");
+const { createHash } = require("node:crypto");
+const path = require("node:path");
+const { transformSync } = require("@babel/core");
+
+const SOURCE_ATTRIBUTE = "data-agentation-id";
+const SOURCE_EXTENSION = /\.(?:js|jsx|tsx)$/;
+const MANIFEST_VERSION = 1;
+
+function normalizeSourceDirs(sourceDirs) {
+  return Array.isArray(sourceDirs) ? sourceDirs : [sourceDirs];
+}
+
+function normalizePath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+function isFileInside(directory, filename) {
+  const relative = path.relative(directory, filename);
+  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function createLocation(filename, rootDir, start) {
+  const fileName = normalizePath(path.relative(rootDir, filename));
+  const location = {
+    fileName,
+    lineNumber: start.line,
+    columnNumber: start.column,
+  };
+  const key = `${fileName}:${start.line}:${start.column}`;
+  const id = createHash("sha256").update(key).digest("base64url").slice(0, 11);
+
+  return { id, location };
+}
+
+function isIntrinsicElement(node) {
+  return node.type === "JSXIdentifier" && /^[a-z]/.test(node.name);
+}
+
+function collectInstrumentedBindings(programPath, instrumentedImports) {
+  const bindings = new Set();
+
+  for (const statementPath of programPath.get("body")) {
+    const statement = statementPath.node;
+    if (statement.type !== "ImportDeclaration") continue;
+
+    const allowedImports = instrumentedImports.filter(
+      (item) => item.source === statement.source.value,
+    );
+    if (allowedImports.length === 0) continue;
+
+    for (const specifier of statement.specifiers) {
+      for (const allowedImport of allowedImports) {
+        // Only an explicitly allowlisted import binding is safe to instrument.
+        // A same-named local component may consume or reject unknown props.
+        if (allowedImport.imported === "default" && specifier.type === "ImportDefaultSpecifier") {
+          const binding = programPath.scope.getBinding(specifier.local.name);
+          if (binding) bindings.add(binding);
+        }
+      }
+    }
+  }
+
+  return bindings;
+}
+
+function shouldInstrumentElement(elementPath, bindings) {
+  const node = elementPath.node.name;
+  return (
+    isIntrinsicElement(node) ||
+    (node.type === "JSXIdentifier" &&
+      bindings.has(elementPath.scope.getBinding(node.name)))
+  );
+}
+
+function hasSourceAttribute(attributes) {
+  return attributes.some(
+    (attribute) =>
+      attribute.type === "JSXAttribute" &&
+      attribute.name.type === "JSXIdentifier" &&
+      attribute.name.name === SOURCE_ATTRIBUTE,
+  );
+}
+
+function instrumentationPlugin({ types }, options) {
+  const { rootDir, inject, onLocation, instrumentedImports = [] } = options;
+  let instrumentedBindings = new Set();
+
+  return {
+    name: "agentation-source-location",
+    visitor: {
+      Program(programPath) {
+        instrumentedBindings = collectInstrumentedBindings(
+          programPath,
+          instrumentedImports,
+        );
+      },
+      JSXOpeningElement(babelPath, state) {
+        const node = babelPath.node;
+        if (!shouldInstrumentElement(babelPath, instrumentedBindings) || !node.loc) {
+          return;
+        }
+
+        const filename = state.file.opts.filename;
+        if (!filename) return;
+
+        const entry = createLocation(filename, rootDir, node.loc.start);
+        onLocation?.(entry.id, entry.location);
+
+        if (!inject || hasSourceAttribute(node.attributes)) return;
+
+        node.attributes.push(
+          types.jsxAttribute(
+            types.jsxIdentifier(SOURCE_ATTRIBUTE),
+            types.stringLiteral(entry.id),
+          ),
+        );
+      },
+    },
+  };
+}
+
+function transformSource({
+  source,
+  filename,
+  rootDir,
+  inject,
+  onLocation,
+  instrumentedImports,
+}) {
+  const result = transformSync(source, {
+    filename,
+    babelrc: false,
+    configFile: false,
+    sourceMaps: inject,
+    sourceFileName: normalizePath(path.relative(rootDir, filename)),
+    parserOpts: {
+      sourceType: "unambiguous",
+      plugins: ["jsx", "typescript"],
+    },
+    generatorOpts: {
+      retainLines: true,
+    },
+    plugins: [
+      [
+        instrumentationPlugin,
+        { rootDir, inject, onLocation, instrumentedImports },
+      ],
+    ],
+  });
+
+  return {
+    code: result?.code ?? source,
+    map: result?.map ?? undefined,
+  };
+}
+
+function collectSourceFiles(directory) {
+  const files = [];
+
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectSourceFiles(entryPath));
+    } else if (SOURCE_EXTENSION.test(entry.name)) {
+      files.push(entryPath);
+    }
+  }
+
+  return files.sort();
+}
+
+function createManifest(rootDir, sourceDirs, instrumentedImports) {
+  const files = [];
+  const fileIndexes = new Map();
+  const locations = {};
+  const filenames = normalizeSourceDirs(sourceDirs)
+    .filter((sourceDir) => fs.existsSync(sourceDir))
+    .flatMap(collectSourceFiles);
+
+  for (const filename of [...new Set(filenames)].sort()) {
+    const source = fs.readFileSync(filename, "utf8");
+    transformSource({
+      source,
+      filename,
+      rootDir,
+      inject: false,
+      instrumentedImports,
+      onLocation(id, location) {
+        let fileIndex = fileIndexes.get(location.fileName);
+        if (fileIndex === undefined) {
+          fileIndex = files.length;
+          files.push(location.fileName);
+          fileIndexes.set(location.fileName, fileIndex);
+        }
+
+        const tuple = [fileIndex, location.lineNumber, location.columnNumber ?? 0];
+        const previous = locations[id];
+        if (
+          previous &&
+          (previous[0] !== tuple[0] ||
+            previous[1] !== tuple[1] ||
+            previous[2] !== tuple[2])
+        ) {
+          throw new Error(`Agentation source id collision: ${id}`);
+        }
+        locations[id] = tuple;
+      },
+    });
+  }
+
+  return { version: MANIFEST_VERSION, files, locations };
+}
+
+function createManifestScript(rootDir, sourceDirs, instrumentedImports) {
+  return (
+    "globalThis.__AGENTATION_SOURCE_MANIFEST__=" +
+    JSON.stringify(createManifest(rootDir, sourceDirs, instrumentedImports)) +
+    ";\n"
+  );
+}
+
+module.exports = {
+  MANIFEST_VERSION,
+  SOURCE_EXTENSION,
+  createManifest,
+  createManifestScript,
+  isFileInside,
+  transformSource,
+};
diff --git a/plugins/source-locations/core.test.cjs b/plugins/source-locations/core.test.cjs
new file mode 100644
index 00000000..3ac24da2
--- /dev/null
+++ b/plugins/source-locations/core.test.cjs
@@ -0,0 +1,70 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const test = require("node:test");
+const { createManifest, createManifestScript, transformSource } = require("./core.cjs");
+
+const NEXT_COMPONENT_IMPORTS = [
+  { source: "next/image", imported: "default" },
+  { source: "next/link", imported: "default" },
+];
+
+test("instruments intrinsic elements and direct Next built-ins only", () => {
+  const rootDir = "/repo";
+  const filename = "/repo/src/example.tsx";
+  const source = `
+    import NextImage from "next/image";
+    import NextLink from "next/link";
+    import { Image, Link } from "./components";
+
+    export function Example() {
+      return <main><NextImage src="/a.png" alt="A" /><NextLink href="/a">A</NextLink><Image /><Link /></main>;
+    }
+
+    export function Shadowed(NextLink) {
+      return <NextLink href="/shadowed">Shadowed custom component</NextLink>;
+    }
+  `;
+  const result = transformSource({
+    source,
+    filename,
+    rootDir,
+    inject: true,
+    instrumentedImports: NEXT_COMPONENT_IMPORTS,
+  });
+
+  assert.match(result.code, /<main data-agentation-id=/);
+  assert.match(result.code, /<NextImage[^>]+data-agentation-id=/);
+  assert.match(result.code, /<NextLink[^>]+data-agentation-id=/);
+  assert.doesNotMatch(result.code, /<Image[^>]+data-agentation-id=/);
+  assert.doesNotMatch(result.code, /<Link[^>]+data-agentation-id=/);
+  assert.doesNotMatch(result.code, /<NextLink href="\/shadowed"[^>]+data-agentation-id=/);
+});
+
+test("builds one manifest from multiple source directories", (context) => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "agentation-source-"));
+  context.after(() => fs.rmSync(rootDir, { recursive: true, force: true }));
+
+  const appDir = path.join(rootDir, "apps/web/src");
+  const uiDir = path.join(rootDir, "packages/ui/src");
+  fs.mkdirSync(appDir, { recursive: true });
+  fs.mkdirSync(uiDir, { recursive: true });
+  fs.writeFileSync(path.join(appDir, "page.tsx"), "export const Page = () => <main />;");
+  fs.writeFileSync(path.join(appDir, "layout.js"), "export const Layout = () => <section />;");
+  fs.writeFileSync(path.join(uiDir, "card.tsx"), "export const Card = () => <article />;");
+
+  const manifest = createManifest(rootDir, [appDir, uiDir]);
+  assert.equal(manifest.version, 1);
+  assert.deepEqual(
+    Object.values(manifest.locations)
+      .map(([fileIndex]) => manifest.files[fileIndex])
+      .sort(),
+    [
+      "apps/web/src/layout.js",
+      "apps/web/src/page.tsx",
+      "packages/ui/src/card.tsx",
+    ],
+  );
+  assert.doesNotMatch(createManifestScript(rootDir, [appDir, uiDir]), /fileName/);
+});
diff --git a/plugins/source-locations/next.cjs b/plugins/source-locations/next.cjs
new file mode 100644
index 00000000..67631a41
--- /dev/null
+++ b/plugins/source-locations/next.cjs
@@ -0,0 +1,80 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  createManifestScript,
+  isFileInside,
+} = require("./core.cjs");
+
+const DEFAULT_MANIFEST_PATH = "_agentation/source-manifest.js";
+const NEXT_COMPONENT_IMPORTS = [
+  { source: "next/image", imported: "default" },
+  { source: "next/link", imported: "default" },
+];
+
+function prependRule(existingRule, agentationRule) {
+  if (!existingRule) return agentationRule;
+  return Array.isArray(existingRule)
+    ? [agentationRule, ...existingRule]
+    : [agentationRule, existingRule];
+}
+
+function writeManifest({ rootDir, sourceDirs, manifestFile }) {
+  const source = createManifestScript(
+    rootDir,
+    sourceDirs,
+    NEXT_COMPONENT_IMPORTS,
+  );
+  fs.mkdirSync(path.dirname(manifestFile), { recursive: true });
+  fs.writeFileSync(manifestFile, source);
+}
+
+function withAgentationSourceLocations(nextConfig = {}, options = {}) {
+  // Source instrumentation changes rendered DOM, so development stays untouched
+  // unless a caller explicitly opts in. `next build` sets NODE_ENV=production.
+  const enabled = options.enabled ?? process.env.NODE_ENV === "production";
+  if (!enabled) return nextConfig;
+
+  const projectDir = path.resolve(options.projectDir ?? process.cwd());
+  const rootDir = path.resolve(options.rootDir ?? projectDir);
+  const sourceDirs = (options.sourceDirs ?? [options.sourceDir ?? "src"]).map(
+    (sourceDir) => path.resolve(rootDir, sourceDir),
+  );
+  const manifestPath = options.manifestPath ?? DEFAULT_MANIFEST_PATH;
+  const publicDir = path.resolve(projectDir, "public");
+  const manifestFile = path.resolve(publicDir, manifestPath);
+
+  if (!isFileInside(publicDir, manifestFile)) {
+    throw new Error("Agentation manifestPath must stay inside the public directory");
+  }
+
+  const loader = {
+    loader: path.join(__dirname, "turbopack-loader.cjs"),
+    options: {
+      rootDir,
+      sourceDirs,
+      instrumentedImports: NEXT_COMPONENT_IMPORTS,
+    },
+  };
+
+  // Next 16 loads its config before starting the Turbopack build. The manifest
+  // must exist before Next copies public assets into the production output.
+  writeManifest({ rootDir, sourceDirs, manifestFile });
+
+  const rule = { loaders: [loader] };
+  const existingRules = nextConfig.turbopack?.rules ?? {};
+
+  return {
+    ...nextConfig,
+    turbopack: {
+      ...nextConfig.turbopack,
+      rules: {
+        ...existingRules,
+        "*.js": prependRule(existingRules["*.js"], rule),
+        "*.jsx": prependRule(existingRules["*.jsx"], rule),
+        "*.tsx": prependRule(existingRules["*.tsx"], rule),
+      },
+    },
+  };
+}
+
+module.exports = { withAgentationSourceLocations };
diff --git a/plugins/source-locations/package.json b/plugins/source-locations/package.json
new file mode 100644
index 00000000..126ed496
--- /dev/null
+++ b/plugins/source-locations/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "@agentation/source-locations",
+  "version": "0.1.0",
+  "description": "Build-time JSX instrumentation for Agentation source locations",
+  "license": "PolyForm-Shield-1.0.0",
+  "type": "commonjs",
+  "files": [
+    "core.cjs",
+    "next.cjs",
+    "turbopack-loader.cjs",
+    "vite.cjs"
+  ],
+  "exports": {
+    "./next": "./next.cjs",
+    "./vite": "./vite.cjs"
+  },
+  "scripts": {
+    "test": "node --test *.test.cjs"
+  },
+  "dependencies": {
+    "@babel/core": "^7.29.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
diff --git a/plugins/source-locations/plugin.test.cjs b/plugins/source-locations/plugin.test.cjs
new file mode 100644
index 00000000..0a6c1d19
--- /dev/null
+++ b/plugins/source-locations/plugin.test.cjs
@@ -0,0 +1,62 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const test = require("node:test");
+const { withAgentationSourceLocations } = require("./next.cjs");
+const { agentationSourceLocations } = require("./vite.cjs");
+
+test("Next stays disabled outside production unless explicitly enabled", () => {
+  const nextConfig = { reactStrictMode: true };
+  const previousNodeEnv = process.env.NODE_ENV;
+  process.env.NODE_ENV = "development";
+
+  try {
+    assert.equal(withAgentationSourceLocations(nextConfig), nextConfig);
+  } finally {
+    if (previousNodeEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = previousNodeEnv;
+  }
+});
+
+test("Next supports monorepo roots and runs before existing Turbopack rules", (context) => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "agentation-next-"));
+  context.after(() => fs.rmSync(rootDir, { recursive: true, force: true }));
+
+  const projectDir = path.join(rootDir, "apps/web");
+  const sourceDir = path.join(projectDir, "src");
+  fs.mkdirSync(path.join(projectDir, "public"), { recursive: true });
+  fs.mkdirSync(sourceDir, { recursive: true });
+  fs.writeFileSync(path.join(sourceDir, "page.tsx"), "export const Page = () => <main />;");
+
+  const existingRule = { loaders: ["existing-loader"] };
+  const result = withAgentationSourceLocations(
+    { turbopack: { rules: { "*.tsx": existingRule } } },
+    {
+      enabled: true,
+      projectDir,
+      rootDir,
+      sourceDirs: ["apps/web/src"],
+    },
+  );
+
+  assert.match(
+    result.turbopack.rules["*.tsx"][0].loaders[0].loader,
+    /turbopack-loader\.cjs$/,
+  );
+  assert.equal(result.turbopack.rules["*.tsx"][1], existingRule);
+  assert.equal(result.turbopack.rules["*.tsx"].length, 2);
+  assert.ok(result.turbopack.rules["*.js"]);
+  assert.ok(result.turbopack.rules["*.jsx"]);
+  assert.ok(fs.existsSync(path.join(projectDir, "public/_agentation/source-manifest.js")));
+});
+
+test("Vite is build-only by default and supports an explicit override", () => {
+  const plugin = agentationSourceLocations();
+  assert.equal(plugin.apply({}, { command: "build" }), true);
+  assert.equal(plugin.apply({}, { command: "serve" }), false);
+  assert.equal(
+    agentationSourceLocations({ enabled: true }).apply({}, { command: "serve" }),
+    true,
+  );
+});
diff --git a/plugins/source-locations/turbopack-loader.cjs b/plugins/source-locations/turbopack-loader.cjs
new file mode 100644
index 00000000..bbd44034
--- /dev/null
+++ b/plugins/source-locations/turbopack-loader.cjs
@@ -0,0 +1,25 @@
+const { isFileInside, transformSource } = require("./core.cjs");
+
+module.exports = function agentationSourceLocationLoader(source) {
+  this.cacheable(true);
+  const callback = this.async();
+  const { rootDir, sourceDirs, instrumentedImports } = this.getOptions();
+
+  if (!sourceDirs.some((sourceDir) => isFileInside(sourceDir, this.resourcePath))) {
+    callback(null, source);
+    return;
+  }
+
+  try {
+    const result = transformSource({
+      source: source.toString(),
+      filename: this.resourcePath,
+      rootDir,
+      inject: true,
+      instrumentedImports,
+    });
+    callback(null, result.code, result.map);
+  } catch (error) {
+    callback(error);
+  }
+};
diff --git a/plugins/source-locations/vite.cjs b/plugins/source-locations/vite.cjs
new file mode 100644
index 00000000..250c785c
--- /dev/null
+++ b/plugins/source-locations/vite.cjs
@@ -0,0 +1,102 @@
+const path = require("node:path");
+const {
+  SOURCE_EXTENSION,
+  createManifestScript,
+  isFileInside,
+  transformSource,
+} = require("./core.cjs");
+
+const DEFAULT_MANIFEST_PATH = "_agentation/source-manifest.js";
+
+function joinBase(base, manifestPath) {
+  return `${base.endsWith("/") ? base : `${base}/`}${manifestPath}`;
+}
+
+function agentationSourceLocations(options = {}) {
+  let rootDir;
+  let sourceDirs;
+  let base;
+  let command;
+  const manifestPath = options.manifestPath ?? DEFAULT_MANIFEST_PATH;
+
+  return {
+    name: "agentation-source-locations",
+    enforce: "pre",
+    // Vite build is the default scope. Set enabled:true to opt into dev/HMR.
+    apply(_config, environment) {
+      return options.enabled ?? environment.command === "build";
+    },
+
+    configResolved(config) {
+      rootDir = path.resolve(options.rootDir ?? config.root);
+      sourceDirs = (options.sourceDirs ?? [options.sourceDir ?? "src"]).map(
+        (sourceDir) => path.resolve(rootDir, sourceDir),
+      );
+      base = config.base;
+      command = config.command;
+    },
+
+    buildStart() {
+      if (command !== "build") return;
+      this.emitFile({
+        type: "asset",
+        fileName: manifestPath,
+        source: createManifestScript(rootDir, sourceDirs),
+      });
+    },
+
+    transform(source, id) {
+      const filename = id.split("?", 1)[0];
+      if (
+        !SOURCE_EXTENSION.test(filename) ||
+        !sourceDirs.some((sourceDir) => isFileInside(sourceDir, filename))
+      ) {
+        return null;
+      }
+
+      return transformSource({
+        source,
+        filename,
+        rootDir,
+        inject: true,
+      });
+    },
+
+    transformIndexHtml() {
+      return [
+        {
+          tag: "script",
+          attrs: { src: joinBase(base, manifestPath) },
+          injectTo: "head-prepend",
+        },
+      ];
+    },
+
+    configureServer(server) {
+      const manifestUrl = joinBase(base, manifestPath);
+      server.middlewares.use((request, response, next) => {
+        const pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+        if (pathname !== manifestUrl) {
+          next();
+          return;
+        }
+
+        response.statusCode = 200;
+        response.setHeader("Content-Type", "text/javascript; charset=utf-8");
+        response.setHeader("Cache-Control", "no-store");
+        response.end(createManifestScript(rootDir, sourceDirs));
+      });
+    },
+
+    handleHotUpdate(context) {
+      if (
+        SOURCE_EXTENSION.test(context.file) &&
+        sourceDirs.some((sourceDir) => isFileInside(sourceDir, context.file))
+      ) {
+        context.server.ws.send({ type: "full-reload" });
+      }
+    },
+  };
+}
+
+module.exports = { agentationSourceLocations };
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 72fe188e..cf4ba212 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -121,6 +121,12 @@ importers:
         specifier: ^5.0.0
         version: 5.9.3
 
+  plugins/source-locations:
+    dependencies:
+      '@babel/core':
+        specifier: ^7.29.0
+        version: 7.29.0
+
 packages:
 
   '@asamuzakjp/css-color@3.2.0':
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 645858de..a42ccf2b 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -2,3 +2,4 @@ packages:
   - 'package'
   - 'package/example'
   - 'mcp'
+  - 'plugins/*'

From 93c7165ad18123340b5985115e19ad11aee48db5 Mon Sep 17 00:00:00 2001
From: SweetRetry <zimin.zhang2000@gmail.com>
Date: Wed, 19 Aug 2026 21:46:56 +0800
Subject: [PATCH 2/2] feat(mcp): expose annotation source locations

---
 .gitignore                        |   2 +
 mcp/package.json                  |   1 +
 mcp/src/server/http.ts            |  64 ++++++--------
 mcp/src/server/mcp.ts             | 135 +++++++++++++++++++++--------
 mcp/src/server/sqlite.ts          |   9 +-
 mcp/src/types.ts                  |   1 +
 mcp/test/source-file.e2e.test.cjs | 139 ++++++++++++++++++++++++++++++
 package.json                      |   2 +-
 package/src/types.ts              |   3 +-
 9 files changed, 278 insertions(+), 78 deletions(-)
 create mode 100644 mcp/test/source-file.e2e.test.cjs

diff --git a/.gitignore b/.gitignore
index 8024e99d..8683f711 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,5 @@ mcp/dist
 .env.*
 !.env.example
 .claude/settings.local.json
+
+examples
diff --git a/mcp/package.json b/mcp/package.json
index 74891d28..ba55801e 100644
--- a/mcp/package.json
+++ b/mcp/package.json
@@ -27,6 +27,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "test": "pnpm build && node --test test/*.test.cjs",
     "watch": "tsup --watch",
     "dev": "pnpm build && pnpm watch",
     "start": "pnpm build && node dist/cli.js server",
diff --git a/mcp/src/server/http.ts b/mcp/src/server/http.ts
index 734f3e13..8c2bb7da 100644
--- a/mcp/src/server/http.ts
+++ b/mcp/src/server/http.ts
@@ -4,13 +4,9 @@
  */
 
 import { createServer, type IncomingMessage, type ServerResponse } from "http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-import { TOOLS, handleTool, error as toolError } from "./mcp.js";
+import { createAgentationMcpServer } from "./mcp.js";
 import {
   createSession,
   getSession,
@@ -66,33 +62,25 @@ const agentConnections = new Set<ServerResponse>();
 // MCP HTTP Transport
 // -----------------------------------------------------------------------------
 
-// Store transports by session ID for stateful sessions
-const mcpTransports = new Map<string, StreamableHTTPServerTransport>();
+type McpSession = {
+  server: McpServer;
+  transport: StreamableHTTPServerTransport;
+};
+
+// Keep both objects alive for the lifetime of each stateful MCP session.
+const mcpSessions = new Map<string, McpSession>();
 
 /**
  * Initialize a new MCP server with HTTP transport for a session.
  */
-function createMcpSession(): { server: Server; transport: StreamableHTTPServerTransport } {
+async function createMcpSession(): Promise<McpSession> {
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: () => crypto.randomUUID(),
   });
 
-  const server = new Server(
-    { name: "agentation", version: "0.0.1" },
-    { capabilities: { tools: {} } }
-  );
-
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-  server.setRequestHandler(CallToolRequestSchema, async (req) => {
-    try {
-      return await handleTool(req.params.name, req.params.arguments);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : "Unknown error";
-      return toolError(message);
-    }
-  });
+  const server = createAgentationMcpServer();
 
-  server.connect(transport);
+  await server.connect(transport);
   return { server, transport };
 }
 
@@ -710,11 +698,11 @@ async function handleMcp(req: IncomingMessage, res: ServerResponse): Promise<voi
 
   // POST: Handle JSON-RPC requests
   if (method === "POST") {
-    let transport: StreamableHTTPServerTransport;
+    let mcpSession: McpSession;
 
     if (sessionId) {
       // Session ID provided - must exist in our map
-      if (!mcpTransports.has(sessionId)) {
+      if (!mcpSessions.has(sessionId)) {
         res.writeHead(404, { "Content-Type": "application/json" });
         res.end(JSON.stringify({
           jsonrpc: "2.0",
@@ -723,14 +711,14 @@ async function handleMcp(req: IncomingMessage, res: ServerResponse): Promise<voi
         }));
         return;
       }
-      transport = mcpTransports.get(sessionId)!;
+      mcpSession = mcpSessions.get(sessionId)!;
     } else {
       // No session ID - this should be an initialize request, create new session
-      const { transport: newTransport } = createMcpSession();
-      transport = newTransport;
+      mcpSession = await createMcpSession();
     }
 
     try {
+      const { transport } = mcpSession;
       // Read the request body
       const body = await new Promise<string>((resolve, reject) => {
         let data = "";
@@ -744,10 +732,10 @@ async function handleMcp(req: IncomingMessage, res: ServerResponse): Promise<voi
       // Handle the request through the transport (it writes directly to res)
       await transport.handleRequest(req, res, parsedBody);
 
-      // Store the transport with its session ID after the request is handled (for new sessions)
+      // Store the server and transport after initialization assigns a session ID.
       const newSessionId = transport.sessionId;
-      if (newSessionId && !mcpTransports.has(newSessionId)) {
-        mcpTransports.set(newSessionId, transport);
+      if (newSessionId && !mcpSessions.has(newSessionId)) {
+        mcpSessions.set(newSessionId, mcpSession);
         log(`[MCP HTTP] New session created: ${newSessionId}`);
       }
     } catch (err) {
@@ -762,13 +750,13 @@ async function handleMcp(req: IncomingMessage, res: ServerResponse): Promise<voi
 
   // GET: SSE stream for notifications
   if (method === "GET") {
-    if (!sessionId || !mcpTransports.has(sessionId)) {
+    if (!sessionId || !mcpSessions.has(sessionId)) {
       res.writeHead(400, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ error: "Missing or invalid Mcp-Session-Id" }));
       return;
     }
 
-    const transport = mcpTransports.get(sessionId)!;
+    const { transport } = mcpSessions.get(sessionId)!;
 
     try {
       // Handle the SSE request (transport writes directly to res)
@@ -785,10 +773,10 @@ async function handleMcp(req: IncomingMessage, res: ServerResponse): Promise<voi
 
   // DELETE: Session cleanup
   if (method === "DELETE") {
-    if (sessionId && mcpTransports.has(sessionId)) {
-      const transport = mcpTransports.get(sessionId)!;
-      await transport.close();
-      mcpTransports.delete(sessionId);
+    if (sessionId && mcpSessions.has(sessionId)) {
+      const { server } = mcpSessions.get(sessionId)!;
+      await server.close();
+      mcpSessions.delete(sessionId);
       res.writeHead(204);
       res.end();
     } else {
diff --git a/mcp/src/server/mcp.ts b/mcp/src/server/mcp.ts
index 4265a9cd..e8fada2f 100644
--- a/mcp/src/server/mcp.ts
+++ b/mcp/src/server/mcp.ts
@@ -6,12 +6,8 @@
  * rather than maintaining its own store.
  */
 
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import type { ActionRequest } from "../types.js";
 
@@ -155,7 +151,7 @@ export const TOOLS = [
   {
     name: "agentation_get_pending",
     description:
-      "Get all pending (unacknowledged) annotations for a session. Annotations have a `kind` field: \"feedback\" (default), \"placement\" (design component placements), or \"rearrange\" (section reorder/resize). Placement and rearrange annotations include structured data.",
+      "Get all pending (unacknowledged) annotations for a session. When available, `sourceFile` is the first code lookup target for the selected element. Annotations have a `kind` field: \"feedback\" (default), \"placement\" (design component placements), or \"rearrange\" (section reorder/resize). Placement and rearrange annotations include structured data.",
     inputSchema: {
       type: "object" as const,
       properties: {
@@ -170,7 +166,7 @@ export const TOOLS = [
   {
     name: "agentation_get_all_pending",
     description:
-      "Get all pending annotations across ALL sessions. Includes feedback, design placements, and rearrange annotations. Each annotation has a `kind` field.",
+      "Get all pending annotations across ALL sessions. When available, `sourceFile` is the first code lookup target for the selected element. Includes feedback, design placements, and rearrange annotations. Each annotation has a `kind` field.",
     inputSchema: {
       type: "object" as const,
       properties: {},
@@ -254,7 +250,8 @@ export const TOOLS = [
     description:
       "Block until new annotations appear, then collect a batch and return them. " +
       "Triggers automatically when annotations are created — the user just annotates in the browser " +
-      "and the agent picks them up. Includes all annotation kinds: feedback, placement (design components), " +
+      "and the agent picks them up. When available, `sourceFile` is the first code lookup target. " +
+      "Includes all annotation kinds: feedback, placement (design components), " +
       "and rearrange (section reorder/resize). After detecting the first new annotation, waits for a batch window " +
       "to collect more before returning. Use in a loop for hands-free processing. " +
       "After addressing each annotation, call agentation_resolve with the annotation ID and a summary " +
@@ -304,6 +301,7 @@ type Annotation = {
   timestamp?: number;
   nearbyText?: string;
   reactComponents?: string;
+  sourceFile?: string;
   status: string;
   kind?: "feedback" | "placement" | "rearrange";
   placement?: {
@@ -345,6 +343,7 @@ function mapAnnotationForMcp(a: Annotation) {
     timestamp: a.timestamp,
     nearbyText: a.nearbyText,
     reactComponents: a.reactComponents,
+    sourceFile: a.sourceFile,
     ...(a.kind === "placement" && a.placement ? { placement: a.placement } : {}),
     ...(a.kind === "rearrange" && a.rearrange ? { rearrange: a.rearrange } : {}),
   };
@@ -695,6 +694,98 @@ export async function handleTool(name: string, args: unknown): Promise<ToolResul
 // Server
 // -----------------------------------------------------------------------------
 
+async function executeTool(name: string, args: unknown): Promise<ToolResult> {
+  try {
+    return await handleTool(name, args);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown error";
+    return error(message);
+  }
+}
+
+function getToolDescription(name: string): string {
+  const tool = TOOLS.find((candidate) => candidate.name === name);
+  if (!tool) throw new Error(`Missing MCP tool definition: ${name}`);
+  return tool.description;
+}
+
+/** Create a high-level MCP server with all Agentation tools registered. */
+export function createAgentationMcpServer(): McpServer {
+  const server = new McpServer({
+    name: "agentation",
+    version: "0.0.1",
+  });
+
+  server.registerTool(
+    "agentation_list_sessions",
+    { description: getToolDescription("agentation_list_sessions") },
+    () => executeTool("agentation_list_sessions", undefined),
+  );
+  server.registerTool(
+    "agentation_get_session",
+    {
+      description: getToolDescription("agentation_get_session"),
+      inputSchema: GetSessionSchema.shape,
+    },
+    (args) => executeTool("agentation_get_session", args),
+  );
+  server.registerTool(
+    "agentation_get_pending",
+    {
+      description: getToolDescription("agentation_get_pending"),
+      inputSchema: GetPendingSchema.shape,
+    },
+    (args) => executeTool("agentation_get_pending", args),
+  );
+  server.registerTool(
+    "agentation_get_all_pending",
+    { description: getToolDescription("agentation_get_all_pending") },
+    () => executeTool("agentation_get_all_pending", undefined),
+  );
+  server.registerTool(
+    "agentation_acknowledge",
+    {
+      description: getToolDescription("agentation_acknowledge"),
+      inputSchema: AcknowledgeSchema.shape,
+    },
+    (args) => executeTool("agentation_acknowledge", args),
+  );
+  server.registerTool(
+    "agentation_resolve",
+    {
+      description: getToolDescription("agentation_resolve"),
+      inputSchema: ResolveSchema.shape,
+    },
+    (args) => executeTool("agentation_resolve", args),
+  );
+  server.registerTool(
+    "agentation_dismiss",
+    {
+      description: getToolDescription("agentation_dismiss"),
+      inputSchema: DismissSchema.shape,
+    },
+    (args) => executeTool("agentation_dismiss", args),
+  );
+  server.registerTool(
+    "agentation_reply",
+    {
+      description: getToolDescription("agentation_reply"),
+      inputSchema: ReplySchema.shape,
+    },
+    (args) => executeTool("agentation_reply", args),
+  );
+  server.registerTool(
+    "agentation_watch_annotations",
+    {
+      description: getToolDescription("agentation_watch_annotations"),
+      inputSchema: WatchAnnotationsSchema.shape,
+    },
+    (args) => executeTool("agentation_watch_annotations", args),
+  );
+
+  return server;
+}
+
 /**
  * Create and start the MCP server on stdio.
  * @param baseUrl - Optional HTTP server URL to fetch from (default: http://localhost:4747)
@@ -704,33 +795,7 @@ export async function startMcpServer(baseUrl?: string): Promise<void> {
     setHttpBaseUrl(baseUrl);
   }
 
-  const server = new Server(
-    {
-      name: "agentation",
-      version: "0.0.1",
-    },
-    {
-      capabilities: {
-        tools: {},
-      },
-    }
-  );
-
-  // List available tools
-  server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools: TOOLS };
-  });
-
-  // Handle tool calls
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    try {
-      return await handleTool(name, args);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : "Unknown error";
-      return error(message);
-    }
-  });
+  const server = createAgentationMcpServer();
 
   // Connect via stdio
   const transport = new StdioServerTransport();
diff --git a/mcp/src/server/sqlite.ts b/mcp/src/server/sqlite.ts
index 007c386a..8a3704f3 100644
--- a/mcp/src/server/sqlite.ts
+++ b/mcp/src/server/sqlite.ts
@@ -102,6 +102,7 @@ function initDatabase(db: Database.Database): void {
       is_multi_select INTEGER DEFAULT 0,
       is_fixed INTEGER DEFAULT 0,
       react_components TEXT,
+      source_file TEXT,
       url TEXT,
       intent TEXT,
       severity TEXT,
@@ -215,6 +216,7 @@ function rowToAnnotation(row: Record<string, unknown>): Annotation {
     isMultiSelect: Boolean(row.is_multi_select),
     isFixed: Boolean(row.is_fixed),
     reactComponents: row.react_components as string | undefined,
+    sourceFile: row.source_file as string | undefined,
     kind,
     ...(kind === "placement" && extra?.placement ? { placement: extra.placement } : {}),
     ...(kind === "rearrange" && extra?.rearrange ? { rearrange: extra.rearrange } : {}),
@@ -243,6 +245,7 @@ export function createSQLiteStore(dbPath?: string): AFSStore {
   // Safe migrations for new columns (no-ops if already exist)
   try { db.exec("ALTER TABLE annotations ADD COLUMN kind TEXT DEFAULT 'feedback'"); } catch {}
   try { db.exec("ALTER TABLE annotations ADD COLUMN extra TEXT"); } catch {}
+  try { db.exec("ALTER TABLE annotations ADD COLUMN source_file TEXT"); } catch {}
 
   // Restore event sequence from last event
   const lastEvent = db.prepare("SELECT MAX(sequence) as seq FROM events").get() as { seq: number | null };
@@ -269,13 +272,13 @@ export function createSQLiteStore(dbPath?: string): AFSStore {
         id, session_id, x, y, comment, element, element_path, timestamp,
         selected_text, bounding_box, nearby_text, css_classes, nearby_elements,
         computed_styles, full_path, accessibility, is_multi_select, is_fixed,
-        react_components, url, intent, severity, status, thread, created_at,
+        react_components, source_file, url, intent, severity, status, thread, created_at,
         updated_at, resolved_at, resolved_by, author_id, kind, extra
       ) VALUES (
         @id, @sessionId, @x, @y, @comment, @element, @elementPath, @timestamp,
         @selectedText, @boundingBox, @nearbyText, @cssClasses, @nearbyElements,
         @computedStyles, @fullPath, @accessibility, @isMultiSelect, @isFixed,
-        @reactComponents, @url, @intent, @severity, @status, @thread, @createdAt,
+        @reactComponents, @sourceFile, @url, @intent, @severity, @status, @thread, @createdAt,
         @updatedAt, @resolvedAt, @resolvedBy, @authorId, @kind, @extra
       )
     `),
@@ -430,6 +433,7 @@ export function createSQLiteStore(dbPath?: string): AFSStore {
         isMultiSelect: annotation.isMultiSelect ? 1 : 0,
         isFixed: annotation.isFixed ? 1 : 0,
         reactComponents: annotation.reactComponents ?? null,
+        sourceFile: annotation.sourceFile ?? null,
         url: annotation.url ?? null,
         intent: annotation.intent ?? null,
         severity: annotation.severity ?? null,
@@ -612,6 +616,7 @@ export function createTenantStore(dbPath?: string): TenantStore {
   // Safe migrations for new columns (no-ops if already exist)
   try { db.exec("ALTER TABLE annotations ADD COLUMN kind TEXT DEFAULT 'feedback'"); } catch {}
   try { db.exec("ALTER TABLE annotations ADD COLUMN extra TEXT"); } catch {}
+  try { db.exec("ALTER TABLE annotations ADD COLUMN source_file TEXT"); } catch {}
 
   // Restore event sequence from last event
   const lastEvent = db.prepare("SELECT MAX(sequence) as seq FROM events").get() as { seq: number | null };
diff --git a/mcp/src/types.ts b/mcp/src/types.ts
index b6ba3ac7..d50585eb 100644
--- a/mcp/src/types.ts
+++ b/mcp/src/types.ts
@@ -21,6 +21,7 @@ export type Annotation = {
   isMultiSelect?: boolean; // true if created via drag selection
   isFixed?: boolean; // true if element has fixed/sticky positioning (marker stays fixed)
   reactComponents?: string; // React component hierarchy (e.g. "<App> <Dashboard> <Button>")
+  sourceFile?: string; // Detected source path and position (e.g. "src/Button.tsx:42:6")
 
   // Annotation kind (defaults to "feedback" when undefined — backward compat)
   kind?: "feedback" | "placement" | "rearrange";
diff --git a/mcp/test/source-file.e2e.test.cjs b/mcp/test/source-file.e2e.test.cjs
new file mode 100644
index 00000000..59610752
--- /dev/null
+++ b/mcp/test/source-file.e2e.test.cjs
@@ -0,0 +1,139 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const http = require("node:http");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const { once } = require("node:events");
+const test = require("node:test");
+const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
+const {
+  StreamableHTTPClientTransport,
+} = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+
+function getAvailablePort() {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : null;
+      server.close((error) => {
+        if (error) reject(error);
+        else if (port === null) reject(new Error("Could not allocate a test port"));
+        else resolve(port);
+      });
+    });
+  });
+}
+
+async function waitForServer(baseUrl, child, getStderr) {
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(`Agentation server exited early:\n${getStderr()}`);
+    }
+
+    try {
+      const response = await fetch(`${baseUrl}/health`);
+      if (response.ok) return;
+    } catch {
+      // The server has not started listening yet.
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+
+  throw new Error(`Timed out waiting for Agentation server:\n${getStderr()}`);
+}
+
+async function stopChild(child) {
+  if (child.exitCode !== null) return;
+  child.kill("SIGTERM");
+  await Promise.race([
+    once(child, "exit"),
+    new Promise((resolve) => setTimeout(resolve, 2000)),
+  ]);
+}
+
+test("sourceFile survives HTTP, SQLite, and MCP retrieval", async (context) => {
+  const dataHome = fs.mkdtempSync(path.join(os.tmpdir(), "agentation-mcp-e2e-"));
+  const port = await getAvailablePort();
+  const baseUrl = `http://127.0.0.1:${port}`;
+  const cliPath = path.resolve(__dirname, "../dist/cli.js");
+  let stderr = "";
+
+  const child = spawn(
+    process.execPath,
+    [cliPath, "server", "--port", String(port)],
+    {
+      env: { ...process.env, HOME: dataHome },
+      stdio: ["pipe", "pipe", "pipe"],
+    },
+  );
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString();
+  });
+
+  let client;
+  context.after(async () => {
+    if (client) await client.close();
+    await stopChild(child);
+    fs.rmSync(dataHome, { recursive: true, force: true });
+  });
+
+  await waitForServer(baseUrl, child, () => stderr);
+
+  const sessionResponse = await fetch(`${baseUrl}/sessions`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ url: "http://preview.example.test" }),
+  });
+  assert.equal(sessionResponse.status, 201);
+  const session = await sessionResponse.json();
+
+  const sourceFile = "src/components/Banner.tsx:16:6";
+  const annotationResponse = await fetch(
+    `${baseUrl}/sessions/${session.id}/annotations`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        x: 25,
+        y: 120,
+        comment: "Align this heading",
+        element: "Banner heading",
+        elementPath: "main > section > h1",
+        timestamp: Date.now(),
+        sourceFile,
+      }),
+    },
+  );
+  assert.equal(annotationResponse.status, 201);
+
+  client = new Client({ name: "source-file-e2e", version: "1.0.0" });
+  const transport = new StreamableHTTPClientTransport(
+    new URL(`${baseUrl}/mcp`),
+  );
+  await client.connect(transport);
+
+  const tools = await client.listTools();
+  assert.equal(tools.tools.length, 9);
+  const getPendingTool = tools.tools.find(
+    (tool) => tool.name === "agentation_get_pending",
+  );
+  assert.ok(getPendingTool);
+  assert.deepEqual(getPendingTool.inputSchema.required, ["sessionId"]);
+  assert.match(getPendingTool.description, /sourceFile/);
+
+  const result = await client.callTool({
+    name: "agentation_get_pending",
+    arguments: { sessionId: session.id },
+  });
+  const text = result.content.find((item) => item.type === "text");
+  assert.ok(text && "text" in text);
+
+  const payload = JSON.parse(text.text);
+  assert.equal(payload.count, 1);
+  assert.equal(payload.annotations[0].sourceFile, sourceFile);
+});
diff --git a/package.json b/package.json
index f281d8ea..ba203225 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "pnpm --filter agentation watch & pnpm --filter feedback-tool-example dev",
     "build": "pnpm --filter agentation build",
-    "test": "pnpm --filter agentation test && pnpm --filter @agentation/source-locations test",
+    "test": "pnpm --filter agentation test && pnpm --filter @agentation/source-locations test && pnpm --filter agentation-mcp test",
     "example": "pnpm --filter feedback-tool-example dev",
     "pack": "cd package && pnpm pack",
     "mcp": "pnpm --filter agentation-mcp start",
diff --git a/package/src/types.ts b/package/src/types.ts
index bf1102ed..21537d88 100644
--- a/package/src/types.ts
+++ b/package/src/types.ts
@@ -21,7 +21,7 @@ export type Annotation = {
   isMultiSelect?: boolean; // true if created via drag selection
   isFixed?: boolean; // true if element has fixed/sticky positioning (marker stays fixed)
   reactComponents?: string; // React component hierarchy (e.g. "<App> <Dashboard> <Button>")
-  sourceFile?: string; // Source file path from React _debugSource (dev mode only, e.g. "src/Button.tsx:42")
+  sourceFile?: string; // Detected source path and position (e.g. "src/Button.tsx:42:6")
   drawingIndex?: number; // Index of linked draw stroke (if any)
   elementBoundingBoxes?: Array<{
     x: number;
@@ -106,4 +106,3 @@ export type ThreadMessage = {
   content: string;
   timestamp: number;
 };
-