@akira-tl/forgerelay 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-08-11
+
+### Added
+
+- Added bounded `code.intelligence` `references` support through the shared Language-service path, using the same normalized location contract as definition results.
+
+### Changed
+
+- References default to 100 returned locations, accept an explicit limit up to 1000, and report `returned`, `truncated`, and the real `total` when the complete Language-server response is known.
+- Shared semantic-location normalization now preserves External code location metadata for both definition and references without expanding ForgeRelay file authority.
+- Split Language-service management from the protocol runtime so later code-intelligence operations can grow without concentrating lifecycle and request logic in one module.
+
+## [0.4.1] - 2026-08-11
+
+### Added
+
+- Added `code.intelligence` `hover` support through the same shared Language-service and filesystem synchronization path as definition lookup.
+
+### Changed
+
+- Hover responses now normalize Markdown/plaintext `MarkupContent` and supported legacy `MarkedString` payloads into a stable Agent-facing `contents` value with optional language and normalized range metadata.
+- Language Servers that do not advertise hover return `code.operation_unsupported` without invalidating the shared Language service.
+
 ## [0.4.0] - 2026-08-11
 
 ### Added

package/capabilities/code-intelligence/GUIDE.md

@@ -4,8 +4,10 @@ Use the `code.intelligence` Capability for read-only semantic code navigation ba
 
 ForgeRelay does not install Language servers. It discovers supported executables when available and accepts explicit definitions from the global ForgeRelay config or `<workspace>/.forgerelay/language-servers.json`. Project definitions override global definitions, and global definitions override built-in discovery. An explicit definition may disable discovery with `enabled: false`.
 
-For 0.4.0, the supported operation is `definition`. Pass a workspace-relative source `path` plus 1-based `line` and `column` values. Columns are Unicode code-point positions; ForgeRelay converts them to the position encoding negotiated with the Language server.
+ForgeRelay 0.4.2 supports `definition`, `hover`, and `references`. Position-based operations accept a workspace-relative source `path` plus 1-based `line` and `column` values. Columns are Unicode code-point positions; ForgeRelay converts them to the position encoding negotiated with the Language server.
 
-Code-intelligence results use ForgeRelay-normalized locations rather than raw LSP wire types. A result may identify an External code location outside the Workspace, but that does not expand ForgeRelay's allowed roots or grant the file tools permission to read that path.
+Code-intelligence results use ForgeRelay-owned shapes rather than raw LSP wire types. Definition returns normalized locations. Hover returns one `contents` string, an optional legacy `language`, and an optional ForgeRelay-normalized `range`; plaintext, Markdown `MarkupContent`, and supported legacy `MarkedString` payloads are normalized before reaching the Agent. References uses the same normalized location shape, defaults to `limit: 100`, and accepts limits up to 1000. Its result reports `returned`, `truncated`, and `total` when the complete Language-server response makes the total known.
+
+Semantic locations may identify External code locations outside the Workspace, but that does not expand ForgeRelay's allowed roots or grant the file tools permission to read those paths.
 
 Language-server definitions use structured process configuration rather than shell command strings. A project configuration entry may contain `command`, `args`, `env`, `languages`, `extensions`, `languageIdByExtension`, `projectMarkers`, and `enabled` fields. Use `languageIdByExtension` when one server definition covers multiple language IDs whose extensions do not map one-to-one by array position. The server command is launched directly without a shell.

package/dist/capability-registry.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { MAX_CODE_INTELLIGENCE_RESULT_LIMIT, } from "./lsp/code-intelligence-types.js";
 export class CapabilityError extends Error {
     code;
     constructor(code, message) {
@@ -115,12 +116,20 @@ export class CapabilityRegistry {
 }
 export function createCapabilityRegistry(dependencies) {
     const hooksCheckInput = z.object({}).strict();
-    const codeIntelligenceInput = z.object({
-        operation: z.literal("definition"),
+    const positionInput = {
         path: z.string().min(1),
         line: z.number().int(),
         column: z.number().int(),
-    }).strict();
+    };
+    const codeIntelligenceInput = z.discriminatedUnion("operation", [
+        z.object({ operation: z.literal("definition"), ...positionInput }).strict(),
+        z.object({ operation: z.literal("hover"), ...positionInput }).strict(),
+        z.object({
+            operation: z.literal("references"),
+            ...positionInput,
+            limit: z.number().int().min(1).max(MAX_CODE_INTELLIGENCE_RESULT_LIMIT).optional(),
+        }).strict(),
+    ]);
     return new CapabilityRegistry([
         {
             name: "hooks.check",

package/dist/lsp/code-intelligence-types.js

@@ -0,0 +1,2 @@
+export const DEFAULT_CODE_INTELLIGENCE_RESULT_LIMIT = 100;
+export const MAX_CODE_INTELLIGENCE_RESULT_LIMIT = 1000;

package/dist/lsp/code-intelligence.js

@@ -1,22 +1,19 @@
 import { spawn } from "node:child_process";
 import { readFile, realpath } from "node:fs/promises";
-import { basename, isAbsolute, relative, resolve, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { basename, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { createMessageConnection } from "vscode-jsonrpc/node";
-import { DefinitionRequest, DidChangeTextDocumentNotification, DidCloseTextDocumentNotification, DidOpenTextDocumentNotification, ExitNotification, InitializeRequest, InitializedNotification, PositionEncodingKind, ShutdownRequest, TextDocumentSyncKind, } from "vscode-languageserver-protocol";
-import { LanguageServerConfigurationError, resolveLanguageProject, } from "./language-server-config.js";
+import { DefinitionRequest, DidChangeTextDocumentNotification, DidCloseTextDocumentNotification, DidOpenTextDocumentNotification, ExitNotification, HoverRequest, InitializeRequest, ReferencesRequest, InitializedNotification, MarkupKind, PositionEncodingKind, ShutdownRequest, TextDocumentSyncKind, } from "vscode-languageserver-protocol";
+import { LanguageServerConfigurationError, } from "./language-server-config.js";
 import { terminateProcessTree } from "../process-platform.js";
 import { CodeIntelligenceError } from "./code-intelligence-error.js";
+import { DEFAULT_CODE_INTELLIGENCE_RESULT_LIMIT } from "./code-intelligence-types.js";
+import { normalizeHoverContents } from "./normalization/hover.js";
+import { isWithin, locationEntries, normalizeLocations, workspaceDisplayPath, } from "./normalization/locations.js";
 import { lspPositionFromUser, rangeFromLsp, wholeDocumentRange } from "./position-encoding.js";
 export { CodeIntelligenceError } from "./code-intelligence-error.js";
-const LANGUAGE_SERVICE_IDLE_MS = 10 * 60 * 1_000;
-const LANGUAGE_SERVICE_CLEANUP_INTERVAL_MS = 60 * 1_000;
-const MAX_LANGUAGE_SERVICES = 16;
-const LANGUAGE_SERVICE_START_TIMEOUT_MS = 15_000;
-const LANGUAGE_REQUEST_TIMEOUT_MS = 10_000;
-const LANGUAGE_SERVICE_SHUTDOWN_TIMEOUT_MS = 2_000;
 const STDERR_TAIL_BYTES = 64 * 1024;
-class LanguageService {
+export class LanguageService {
     workspaceRoot;
     project;
     policy;
@@ -58,7 +55,7 @@ class LanguageService {
                 textDocument: { uri: document.uri },
                 position,
             }), this.policy.requestTimeoutMs, () => new CodeIntelligenceError("code.request_timeout", `Definition request timed out for ${input.path}.`));
-            const locations = await normalizeDefinitionResponse(response, this.workspaceRoot, this.positionEncoding);
+            const locations = await normalizeLocations(locationEntries(response), this.workspaceRoot, this.positionEncoding);
             return {
                 operation: "definition",
                 selectedServer: this.project.definition.id,
@@ -75,6 +72,81 @@ class LanguageService {
             throw new CodeIntelligenceError("code.server_crashed", `Language server ${this.project.definition.id} failed: ${errorMessage(error)}${this.stderrSuffix()}`);
         }
     }
+    async hover(input) {
+        try {
+            await this.ensureStarted();
+            if (!this.capabilities?.hoverProvider) {
+                throw new CodeIntelligenceError("code.operation_unsupported", `Language server ${this.project.definition.id} does not advertise hover support.`);
+            }
+            const sourcePath = await workspaceSourcePath(this.workspaceRoot, input.path);
+            const document = await this.syncDocument(sourcePath);
+            const position = lspPositionFromUser(document.text, input.line, input.column, this.positionEncoding);
+            const response = await withTimeout(this.connection.sendRequest(HoverRequest.type, {
+                textDocument: { uri: document.uri },
+                position,
+            }), this.policy.requestTimeoutMs, () => new CodeIntelligenceError("code.request_timeout", `Hover request timed out for ${input.path}.`));
+            const common = {
+                operation: "hover",
+                selectedServer: this.project.definition.id,
+                projectRoot: workspaceDisplayPath(this.workspaceRoot, this.project.projectRoot),
+            };
+            if (!response)
+                return { ...common, contents: null };
+            const normalized = normalizeHoverContents(response.contents);
+            return {
+                ...common,
+                ...normalized,
+                ...(response.range
+                    ? { range: rangeFromLsp(document.text, response.range, this.positionEncoding) }
+                    : {}),
+            };
+        }
+        catch (error) {
+            if (error instanceof CodeIntelligenceError)
+                throw error;
+            if (error instanceof LanguageServerConfigurationError) {
+                throw new CodeIntelligenceError(error.code, error.message);
+            }
+            throw new CodeIntelligenceError("code.server_crashed", `Language server ${this.project.definition.id} failed: ${errorMessage(error)}${this.stderrSuffix()}`);
+        }
+    }
+    async references(input) {
+        try {
+            await this.ensureStarted();
+            if (!this.capabilities?.referencesProvider) {
+                throw new CodeIntelligenceError("code.operation_unsupported", `Language server ${this.project.definition.id} does not advertise references support.`);
+            }
+            const sourcePath = await workspaceSourcePath(this.workspaceRoot, input.path);
+            const document = await this.syncDocument(sourcePath);
+            const position = lspPositionFromUser(document.text, input.line, input.column, this.positionEncoding);
+            const response = await withTimeout(this.connection.sendRequest(ReferencesRequest.type, {
+                textDocument: { uri: document.uri },
+                position,
+                context: { includeDeclaration: true },
+            }), this.policy.requestTimeoutMs, () => new CodeIntelligenceError("code.request_timeout", `References request timed out for ${input.path}.`));
+            const entries = locationEntries(response ?? []);
+            const limit = input.limit ?? DEFAULT_CODE_INTELLIGENCE_RESULT_LIMIT;
+            const selected = entries.slice(0, limit);
+            const locations = await normalizeLocations(selected, this.workspaceRoot, this.positionEncoding);
+            return {
+                operation: "references",
+                selectedServer: this.project.definition.id,
+                projectRoot: workspaceDisplayPath(this.workspaceRoot, this.project.projectRoot),
+                locations,
+                returned: locations.length,
+                truncated: entries.length > locations.length,
+                total: entries.length,
+            };
+        }
+        catch (error) {
+            if (error instanceof CodeIntelligenceError)
+                throw error;
+            if (error instanceof LanguageServerConfigurationError) {
+                throw new CodeIntelligenceError(error.code, error.message);
+            }
+            throw new CodeIntelligenceError("code.server_crashed", `Language server ${this.project.definition.id} failed: ${errorMessage(error)}${this.stderrSuffix()}`);
+        }
+    }
     async shutdown() {
         if (this.closed)
             return;
@@ -189,6 +261,13 @@ class LanguageService {
                         dynamicRegistration: false,
                         linkSupport: true,
                     },
+                    hover: {
+                        dynamicRegistration: false,
+                        contentFormat: [MarkupKind.Markdown, MarkupKind.PlainText],
+                    },
+                    references: {
+                        dynamicRegistration: false,
+                    },
                 },
             },
         };
@@ -278,135 +357,7 @@ class LanguageService {
         return text ? ` Server stderr: ${text}` : "";
     }
 }
-export class CodeIntelligenceManager {
-    config;
-    services = new Map();
-    serviceCreations = new Map();
-    serviceCreationQueue = Promise.resolve();
-    cleanupTimer;
-    policy;
-    constructor(config, options = {}) {
-        this.config = config;
-        this.policy = {
-            idleMs: positiveInteger(options.idleMs, LANGUAGE_SERVICE_IDLE_MS, "idleMs"),
-            cleanupIntervalMs: positiveInteger(options.cleanupIntervalMs, LANGUAGE_SERVICE_CLEANUP_INTERVAL_MS, "cleanupIntervalMs"),
-            maxServices: positiveInteger(options.maxServices, MAX_LANGUAGE_SERVICES, "maxServices"),
-            startTimeoutMs: positiveInteger(options.startTimeoutMs, LANGUAGE_SERVICE_START_TIMEOUT_MS, "startTimeoutMs"),
-            requestTimeoutMs: positiveInteger(options.requestTimeoutMs, LANGUAGE_REQUEST_TIMEOUT_MS, "requestTimeoutMs"),
-            shutdownTimeoutMs: positiveInteger(options.shutdownTimeoutMs, LANGUAGE_SERVICE_SHUTDOWN_TIMEOUT_MS, "shutdownTimeoutMs"),
-        };
-        this.cleanupTimer = setInterval(() => {
-            void this.closeIdle();
-        }, this.policy.cleanupIntervalMs);
-        this.cleanupTimer.unref();
-    }
-    async definition(workspaceRoot, input) {
-        let project;
-        let canonicalWorkspaceRoot;
-        try {
-            canonicalWorkspaceRoot = await realpath(resolve(workspaceRoot));
-            project = await resolveLanguageProject({
-                workspaceRoot: canonicalWorkspaceRoot,
-                sourcePath: input.path,
-                globalConfig: this.config.languageServers,
-            });
-        }
-        catch (error) {
-            if (error instanceof LanguageServerConfigurationError) {
-                throw new CodeIntelligenceError(error.code, error.message);
-            }
-            throw error;
-        }
-        const service = await this.acquireService(canonicalWorkspaceRoot, project);
-        try {
-            return await service.definition(input);
-        }
-        finally {
-            service.release();
-        }
-    }
-    async shutdown() {
-        clearInterval(this.cleanupTimer);
-        await Promise.allSettled(this.serviceCreations.values());
-        this.serviceCreations.clear();
-        const services = [...this.services.values()];
-        this.services.clear();
-        await Promise.allSettled(services.map((service) => service.shutdown()));
-    }
-    get size() {
-        return this.services.size;
-    }
-    async acquireService(workspaceRoot, project) {
-        const key = languageServiceKey(project);
-        const existing = this.services.get(key);
-        if (existing) {
-            existing.acquire();
-            return existing;
-        }
-        const pending = this.serviceCreations.get(key);
-        if (pending) {
-            const service = await pending;
-            service.acquire();
-            return service;
-        }
-        const creation = this.withServiceCreationLock(async () => {
-            const current = this.services.get(key);
-            if (current) {
-                current.acquire();
-                return current;
-            }
-            await this.ensureCapacity();
-            const service = new LanguageService(workspaceRoot, project, this.policy);
-            service.acquire();
-            this.services.set(key, service);
-            return service;
-        });
-        this.serviceCreations.set(key, creation);
-        try {
-            return await creation;
-        }
-        finally {
-            if (this.serviceCreations.get(key) === creation) {
-                this.serviceCreations.delete(key);
-            }
-        }
-    }
-    async withServiceCreationLock(operation) {
-        const previous = this.serviceCreationQueue;
-        let release = () => undefined;
-        this.serviceCreationQueue = new Promise((resolvePromise) => {
-            release = resolvePromise;
-        });
-        await previous;
-        try {
-            return await operation();
-        }
-        finally {
-            release();
-        }
-    }
-    async closeIdle(now = Date.now()) {
-        const stale = [...this.services.entries()].filter(([, service]) => service.inFlight === 0 && now - service.lastUsedAt >= this.policy.idleMs);
-        for (const [key, service] of stale) {
-            this.services.delete(key);
-            await service.shutdown();
-        }
-    }
-    async ensureCapacity() {
-        if (this.services.size < this.policy.maxServices)
-            return;
-        const idle = [...this.services.entries()]
-            .filter(([, service]) => service.inFlight === 0)
-            .sort((left, right) => left[1].lastUsedAt - right[1].lastUsedAt);
-        const candidate = idle[0];
-        if (!candidate) {
-            throw new CodeIntelligenceError("code.language_service_capacity", `Language service capacity reached (${this.policy.maxServices}) with no idle service available for eviction.`);
-        }
-        this.services.delete(candidate[0]);
-        await candidate[1].shutdown();
-    }
-}
-function languageServiceKey(project) {
+export function languageServiceKey(project) {
     return JSON.stringify([
         resolve(project.projectRoot),
         project.definition.id,
@@ -449,48 +400,6 @@ async function workspaceSourcePath(workspaceRoot, inputPath) {
         throw new CodeIntelligenceError("code.language_service_unavailable", `Unable to read code-intelligence source ${inputPath}: ${errorMessage(error)}`);
     }
 }
-async function normalizeDefinitionResponse(response, workspaceRoot, encoding) {
-    if (!response)
-        return [];
-    const entries = Array.isArray(response) ? response : [response];
-    return Promise.all(entries.map(async (entry) => {
-        const uri = isLocationLink(entry) ? entry.targetUri : entry.uri;
-        const range = isLocationLink(entry) ? entry.targetRange : entry.range;
-        if (!uri.startsWith("file:")) {
-            throw new CodeIntelligenceError("code.result_outside_policy", `Language server returned a non-file definition URI: ${uri}`);
-        }
-        const targetPath = fileURLToPath(uri);
-        const root = resolve(workspaceRoot);
-        let resolvedTarget;
-        let text;
-        try {
-            resolvedTarget = await realpath(targetPath);
-            text = await readFile(resolvedTarget, "utf8");
-        }
-        catch (error) {
-            throw new CodeIntelligenceError("code.result_outside_policy", `Unable to normalize definition location ${targetPath}: ${errorMessage(error)}`);
-        }
-        const external = !isWithin(root, resolvedTarget);
-        return {
-            path: external ? resolvedTarget : workspaceDisplayPath(root, resolvedTarget),
-            external,
-            range: rangeFromLsp(text, range, encoding),
-        };
-    }));
-}
-function isLocationLink(value) {
-    return "targetUri" in value;
-}
-function workspaceDisplayPath(workspaceRoot, path) {
-    const rel = relative(resolve(workspaceRoot), resolve(path));
-    if (!rel)
-        return ".";
-    return rel.split(sep).join("/");
-}
-function isWithin(root, candidate) {
-    const rel = relative(root, candidate);
-    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
-}
 async function withTimeout(promise, timeoutMs, timeoutError) {
     let timer;
     try {
@@ -538,13 +447,6 @@ async function waitForChildExit(child, timeoutMs) {
         timer.unref();
     });
 }
-function positiveInteger(value, fallback, label) {
-    const resolvedValue = value ?? fallback;
-    if (!Number.isInteger(resolvedValue) || resolvedValue < 1) {
-        throw new Error(`Code-intelligence ${label} must be a positive integer.`);
-    }
-    return resolvedValue;
-}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/lsp/normalization/hover.js

@@ -0,0 +1,29 @@
+export function normalizeHoverContents(contents) {
+    if (Array.isArray(contents)) {
+        if (contents.length === 1)
+            return normalizeMarkedString(contents[0]);
+        return {
+            contents: contents.map(renderMarkedString).join("\n\n"),
+        };
+    }
+    if (isMarkupContent(contents)) {
+        return { contents: contents.value };
+    }
+    return normalizeMarkedString(contents);
+}
+function isMarkupContent(value) {
+    return typeof value === "object" && value !== null && "kind" in value;
+}
+function normalizeMarkedString(value) {
+    if (typeof value === "string")
+        return { contents: value };
+    return {
+        contents: value.value,
+        language: value.language,
+    };
+}
+function renderMarkedString(value) {
+    if (typeof value === "string")
+        return value;
+    return `\`\`\`${value.language}\n${value.value}\n\`\`\``;
+}

package/dist/lsp/normalization/locations.js

@@ -0,0 +1,53 @@
+import { readFile, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CodeIntelligenceError } from "../code-intelligence-error.js";
+import { rangeFromLsp } from "../position-encoding.js";
+export function locationEntries(response) {
+    if (!response)
+        return [];
+    const entries = Array.isArray(response) ? response : [response];
+    return entries.map((entry) => isLocationLink(entry)
+        ? { uri: entry.targetUri, range: entry.targetRange }
+        : { uri: entry.uri, range: entry.range });
+}
+export async function normalizeLocations(entries, workspaceRoot, encoding) {
+    return Promise.all(entries.map(async ({ uri, range }) => {
+        if (!uri.startsWith("file:")) {
+            throw new CodeIntelligenceError("code.result_outside_policy", `Language server returned a non-file code location: ${uri}`);
+        }
+        const targetPath = fileURLToPath(uri);
+        const root = resolve(workspaceRoot);
+        let resolvedTarget;
+        let text;
+        try {
+            resolvedTarget = await realpath(targetPath);
+            text = await readFile(resolvedTarget, "utf8");
+        }
+        catch (error) {
+            throw new CodeIntelligenceError("code.result_outside_policy", `Unable to normalize code location ${targetPath}: ${errorMessage(error)}`);
+        }
+        const external = !isWithin(root, resolvedTarget);
+        return {
+            path: external ? resolvedTarget : workspaceDisplayPath(root, resolvedTarget),
+            external,
+            range: rangeFromLsp(text, range, encoding),
+        };
+    }));
+}
+export function workspaceDisplayPath(workspaceRoot, path) {
+    const rel = relative(resolve(workspaceRoot), resolve(path));
+    if (!rel)
+        return ".";
+    return rel.split(sep).join("/");
+}
+export function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function isLocationLink(value) {
+    return "targetUri" in value;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lsp/runtime/manager.js

@@ -0,0 +1,152 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { CodeIntelligenceError, LanguageService, languageServiceKey, } from "../code-intelligence.js";
+import { LanguageServerConfigurationError, resolveLanguageProject, } from "../language-server-config.js";
+const LANGUAGE_SERVICE_IDLE_MS = 10 * 60 * 1_000;
+const LANGUAGE_SERVICE_CLEANUP_INTERVAL_MS = 60 * 1_000;
+const MAX_LANGUAGE_SERVICES = 16;
+const LANGUAGE_SERVICE_START_TIMEOUT_MS = 15_000;
+const LANGUAGE_REQUEST_TIMEOUT_MS = 10_000;
+const LANGUAGE_SERVICE_SHUTDOWN_TIMEOUT_MS = 2_000;
+export class CodeIntelligenceManager {
+    config;
+    services = new Map();
+    serviceCreations = new Map();
+    serviceCreationQueue = Promise.resolve();
+    cleanupTimer;
+    policy;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.policy = {
+            idleMs: positiveInteger(options.idleMs, LANGUAGE_SERVICE_IDLE_MS, "idleMs"),
+            cleanupIntervalMs: positiveInteger(options.cleanupIntervalMs, LANGUAGE_SERVICE_CLEANUP_INTERVAL_MS, "cleanupIntervalMs"),
+            maxServices: positiveInteger(options.maxServices, MAX_LANGUAGE_SERVICES, "maxServices"),
+            startTimeoutMs: positiveInteger(options.startTimeoutMs, LANGUAGE_SERVICE_START_TIMEOUT_MS, "startTimeoutMs"),
+            requestTimeoutMs: positiveInteger(options.requestTimeoutMs, LANGUAGE_REQUEST_TIMEOUT_MS, "requestTimeoutMs"),
+            shutdownTimeoutMs: positiveInteger(options.shutdownTimeoutMs, LANGUAGE_SERVICE_SHUTDOWN_TIMEOUT_MS, "shutdownTimeoutMs"),
+        };
+        this.cleanupTimer = setInterval(() => {
+            void this.closeIdle();
+        }, this.policy.cleanupIntervalMs);
+        this.cleanupTimer.unref();
+    }
+    async run(workspaceRoot, input) {
+        let project;
+        let canonicalWorkspaceRoot;
+        try {
+            canonicalWorkspaceRoot = await realpath(resolve(workspaceRoot));
+            project = await resolveLanguageProject({
+                workspaceRoot: canonicalWorkspaceRoot,
+                sourcePath: input.path,
+                globalConfig: this.config.languageServers,
+            });
+        }
+        catch (error) {
+            if (error instanceof LanguageServerConfigurationError) {
+                throw new CodeIntelligenceError(error.code, error.message);
+            }
+            throw error;
+        }
+        const service = await this.acquireService(canonicalWorkspaceRoot, project);
+        try {
+            switch (input.operation) {
+                case "definition":
+                    return await service.definition(input);
+                case "hover":
+                    return await service.hover(input);
+                case "references":
+                    return await service.references(input);
+            }
+        }
+        finally {
+            service.release();
+        }
+    }
+    async shutdown() {
+        clearInterval(this.cleanupTimer);
+        await Promise.allSettled(this.serviceCreations.values());
+        this.serviceCreations.clear();
+        const services = [...this.services.values()];
+        this.services.clear();
+        await Promise.allSettled(services.map((service) => service.shutdown()));
+    }
+    get size() {
+        return this.services.size;
+    }
+    async acquireService(workspaceRoot, project) {
+        const key = languageServiceKey(project);
+        const existing = this.services.get(key);
+        if (existing) {
+            existing.acquire();
+            return existing;
+        }
+        const pending = this.serviceCreations.get(key);
+        if (pending) {
+            const service = await pending;
+            service.acquire();
+            return service;
+        }
+        const creation = this.withServiceCreationLock(async () => {
+            const current = this.services.get(key);
+            if (current) {
+                current.acquire();
+                return current;
+            }
+            await this.ensureCapacity();
+            const service = new LanguageService(workspaceRoot, project, this.policy);
+            service.acquire();
+            this.services.set(key, service);
+            return service;
+        });
+        this.serviceCreations.set(key, creation);
+        try {
+            return await creation;
+        }
+        finally {
+            if (this.serviceCreations.get(key) === creation) {
+                this.serviceCreations.delete(key);
+            }
+        }
+    }
+    async withServiceCreationLock(operation) {
+        const previous = this.serviceCreationQueue;
+        let release = () => undefined;
+        this.serviceCreationQueue = new Promise((resolvePromise) => {
+            release = resolvePromise;
+        });
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    async closeIdle(now = Date.now()) {
+        const stale = [...this.services.entries()].filter(([, service]) => service.inFlight === 0 && now - service.lastUsedAt >= this.policy.idleMs);
+        for (const [key, service] of stale) {
+            this.services.delete(key);
+            await service.shutdown();
+        }
+    }
+    async ensureCapacity() {
+        if (this.services.size < this.policy.maxServices)
+            return;
+        const idle = [...this.services.entries()]
+            .filter(([, service]) => service.inFlight === 0)
+            .sort((left, right) => left[1].lastUsedAt - right[1].lastUsedAt);
+        const candidate = idle[0];
+        if (!candidate) {
+            throw new CodeIntelligenceError("code.language_service_capacity", `Language service capacity reached (${this.policy.maxServices}) with no idle service available for eviction.`);
+        }
+        this.services.delete(candidate[0]);
+        await candidate[1].shutdown();
+    }
+}
+function positiveInteger(value, fallback, label) {
+    const resolvedValue = value ?? fallback;
+    if (!Number.isInteger(resolvedValue) || resolvedValue < 1) {
+        throw new Error(`Code-intelligence ${label} must be a positive integer.`);
+    }
+    return resolvedValue;
+}

package/dist/lsp/test-support/server-fixture.js

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { loadConfig } from "../../config.js";
+import { createReviewCheckpointManager } from "../../review-checkpoints.js";
+import { ProcessManager } from "../../process-sessions.js";
+import { createMcpServer } from "../../server.js";
+import { SqliteWorkspaceStore } from "../../workspace-store.js";
+import { WorkspaceRegistry } from "../../workspaces.js";
+import { CodeIntelligenceManager } from "../runtime/manager.js";
+export async function createCodeIntelligenceServerFixture(t, options = {}) {
+    const root = await mkdtemp(join(tmpdir(), "forgerelay-code-intelligence-server-test-"));
+    const project = join(root, "project");
+    const agentDir = join(root, "agent");
+    const stateDir = join(root, ".state");
+    await mkdir(project, { recursive: true });
+    await mkdir(agentDir, { recursive: true });
+    await writeFile(join(agentDir, "AGENTS.md"), "global instructions\n");
+    await writeFile(join(project, "AGENTS.md"), "project instructions\n");
+    const config = loadConfig({
+        DEVSPACE_CONFIG_DIR: join(root, ".config"),
+        DEVSPACE_ALLOWED_ROOTS: root,
+        DEVSPACE_WORKTREE_ROOT: join(root, ".worktrees"),
+        DEVSPACE_AGENT_DIR: agentDir,
+        DEVSPACE_WIDGETS: "full",
+        DEVSPACE_TOOL_MODE: "full",
+        DEVSPACE_OAUTH_OWNER_TOKEN: "test-owner-token-that-is-long-enough",
+        PORT: "1",
+    });
+    const store = new SqliteWorkspaceStore(stateDir);
+    const workspaces = new WorkspaceRegistry(config, store);
+    const processSessions = new ProcessManager();
+    const codeIntelligence = new CodeIntelligenceManager(config, options.codeIntelligenceOptions);
+    const server = createMcpServer(config, workspaces, createReviewCheckpointManager(), processSessions, [], [], codeIntelligence);
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "forgerelay-code-intelligence-test-client", version: "1.0.0" });
+    await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await client.close();
+        await server.close();
+        await codeIntelligence.shutdown();
+        processSessions.shutdown();
+        store.close();
+    };
+    t.after(async () => {
+        await close();
+        await rm(root, { recursive: true, force: true });
+    });
+    return { client, project, close };
+}
+export async function callOpen(client, path, conversationScopeId) {
+    return client.callTool({
+        name: "open_workspace",
+        arguments: { path },
+        _meta: { "openai/session": conversationScopeId },
+    });
+}
+export function structuredContent(result) {
+    assert.ok(result.structuredContent);
+    return result.structuredContent;
+}

package/dist/server.js

@@ -21,7 +21,8 @@ import { deletePath, renamePath } from "./file-mutations.js";
 import { downloadIncomingArtifact, isArtifactDownloadSupportedPlatform, } from "./artifact-tools.js";
 import { ArtifactError } from "./artifact-error.js";
 import { loadConfig } from "./config.js";
-import { CodeIntelligenceError, CodeIntelligenceManager } from "./lsp/code-intelligence.js";
+import { CodeIntelligenceError } from "./lsp/code-intelligence.js";
+import { CodeIntelligenceManager } from "./lsp/runtime/manager.js";
 import { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
 import { checkHookConfiguration } from "./hook-cli.js";
 import { buildServerInstructions, buildShellMutationPolicy, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
@@ -757,7 +758,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             run: async (input, context) => {
                 try {
                     return {
-                        value: await codeIntelligence.definition(context.workspaceRoot, input),
+                        value: await codeIntelligence.run(context.workspaceRoot, input),
                     };
                 }
                 catch (error) {

package/docs/configuration.md

@@ -154,10 +154,16 @@ force a Host to invalidate its cached schema.
 ### LSP code intelligence
 
 ForgeRelay advertises `code.intelligence` through the Capability Gateway; it does
-not add language-specific top-level MCP tools. ForgeRelay 0.4.0 supports the
-`definition` operation. Language Servers are external dependencies: ForgeRelay may
-discover an executable already installed on the machine, but it never downloads or
-installs one automatically.
+not add language-specific top-level MCP tools. ForgeRelay 0.4.2 supports
+`definition`, `hover`, and `references`. Position-based operations accept the same
+workspace-relative source position. Hover results normalize plaintext, Markdown,
+and supported legacy LSP payloads into one `contents` string with optional
+`language` and normalized `range` metadata. References use the same normalized
+location shape as definition, default to 100 returned locations, and accept a
+`limit` from 1 through 1000; results report `returned`, `truncated`, and the real
+`total` when the complete Language-server response makes it known. Language Servers
+are external dependencies: ForgeRelay may discover an executable already installed
+on the machine, but it never downloads or installs one automatically.
 
 Effective Language-server definitions resolve in this order:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -42,7 +42,7 @@
     "debug:accept": "node scripts/debug/accept.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspace-store.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspace-store.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/debug/accept.mjs

@@ -332,11 +332,17 @@ try {
   });
   assert.equal(describedCodeIntelligence.isError, undefined);
   assert.equal(describedCodeIntelligence.structuredContent.capability.guide.name, "code-intelligence");
-  assert.equal(describedCodeIntelligence.structuredContent.capability.inputSchema.type, "object");
-  assert.equal(
-    describedCodeIntelligence.structuredContent.capability.inputSchema.properties.operation.const,
-    "definition",
+  const codeIntelligenceSchema = describedCodeIntelligence.structuredContent.capability.inputSchema;
+  assert.ok(Array.isArray(codeIntelligenceSchema.oneOf));
+  assert.deepEqual(
+    codeIntelligenceSchema.oneOf.map((variant) => variant.properties.operation.const),
+    ["definition", "hover", "references"],
+  );
+  const referencesSchema = codeIntelligenceSchema.oneOf.find(
+    (variant) => variant.properties.operation.const === "references",
   );
+  assert.equal(referencesSchema.properties.limit.minimum, 1);
+  assert.equal(referencesSchema.properties.limit.maximum, 1000);
   if (process.platform === "linux") {
     const describedArtifact = callTool(oauth.accessToken, sessionId, 82, "capability", {
       workspaceId,