@akira-tl/forgerelay 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.4.3] - 2026-08-11
+
+### Added
+
+- Added `documentSymbols` code intelligence with hierarchy-preserving normalization for LSP `DocumentSymbol` trees and flat handling for legacy `SymbolInformation` responses.
+- Added bounded `workspaceSymbols` semantic search over one selected Language service, with normalized flat symbol metadata and External location handling.
+
+### Changed
+
+- Symbol collection limits reuse the 100 default / 1000 hard maximum budget. Document-symbol limits count tree nodes while preserving required ancestors; workspace-symbol results expose `returned`, `truncated`, and known `total` like references.
+- Workspace-symbol requests use a workspace-relative `path` to select and synchronize the Language project/service before applying the project-wide `query`; ForgeRelay does not silently merge nested Language services.
+
+## [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

package/capabilities/code-intelligence/GUIDE.md

@@ -4,8 +4,12 @@ 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`.
 
-ForgeRelay 0.4.1 supports `definition` and `hover`. Both 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.
+ForgeRelay 0.4.3 supports `definition`, `hover`, `references`, `documentSymbols`, and `workspaceSymbols`. Position-based operations accept a workspace-relative source `path` plus 1-based `line` and `column` values. `documentSymbols` needs only `path` and an optional bounded `limit`. `workspaceSymbols` uses `path` to select the Language project/service and accepts a `query` plus optional `limit`; it does not merge multiple nested Language services. Columns are Unicode code-point positions; ForgeRelay converts them to the position encoding negotiated with the Language server.
 
-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. A definition 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.
+
+Document symbols preserve hierarchical server responses as a tree and keep flat `SymbolInformation` responses flat. Names, stable symbol-kind names, ranges, selection ranges, details, container names, and children are normalized without exposing LSP union types. Workspace symbols are always returned as a flat list with stable symbol metadata and normalized locations. Symbol limits use the same default 100 / hard maximum 1000 collection budget; document-symbol limits count total tree nodes, while workspace-symbol results report the server response total directly when 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,31 @@ export class CapabilityRegistry {
 }
 export function createCapabilityRegistry(dependencies) {
     const hooksCheckInput = z.object({}).strict();
-    const codeIntelligenceInput = z.object({
-        operation: z.enum(["definition", "hover"]),
+    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(),
+        z.object({
+            operation: z.literal("documentSymbols"),
+            path: z.string().min(1),
+            limit: z.number().int().min(1).max(MAX_CODE_INTELLIGENCE_RESULT_LIMIT).optional(),
+        }).strict(),
+        z.object({
+            operation: z.literal("workspaceSymbols"),
+            path: z.string().min(1),
+            query: z.string(),
+            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

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

package/dist/lsp/code-intelligence.js

@@ -1,23 +1,20 @@
 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, HoverRequest, InitializeRequest, InitializedNotification, MarkupKind, PositionEncodingKind, ShutdownRequest, TextDocumentSyncKind, } from "vscode-languageserver-protocol";
-import { LanguageServerConfigurationError, resolveLanguageProject, } from "./language-server-config.js";
+import { DefinitionRequest, DocumentSymbolRequest, DidChangeTextDocumentNotification, DidCloseTextDocumentNotification, DidOpenTextDocumentNotification, ExitNotification, HoverRequest, InitializeRequest, ReferencesRequest, InitializedNotification, MarkupKind, PositionEncodingKind, ShutdownRequest, TextDocumentSyncKind, WorkspaceSymbolRequest, } 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 { normalizeDocumentSymbols, normalizeWorkspaceSymbols, } from "./normalization/symbols.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;
@@ -59,7 +56,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,
@@ -114,6 +111,91 @@ class LanguageService {
             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 documentSymbols(input) {
+        try {
+            await this.ensureStarted();
+            if (!this.capabilities?.documentSymbolProvider) {
+                throw new CodeIntelligenceError("code.operation_unsupported", `Language server ${this.project.definition.id} does not advertise document-symbol support.`);
+            }
+            const sourcePath = await workspaceSourcePath(this.workspaceRoot, input.path);
+            const document = await this.syncDocument(sourcePath);
+            const response = await withTimeout(this.connection.sendRequest(DocumentSymbolRequest.type, {
+                textDocument: { uri: document.uri },
+            }), this.policy.requestTimeoutMs, () => new CodeIntelligenceError("code.request_timeout", `Document-symbol request timed out for ${input.path}.`));
+            const normalized = normalizeDocumentSymbols(response, document.text, this.positionEncoding, input.limit ?? DEFAULT_CODE_INTELLIGENCE_RESULT_LIMIT);
+            return {
+                operation: "documentSymbols",
+                selectedServer: this.project.definition.id,
+                projectRoot: workspaceDisplayPath(this.workspaceRoot, this.project.projectRoot),
+                ...normalized,
+            };
+        }
+        catch (error) {
+            if (error instanceof CodeIntelligenceError)
+                throw error;
+            throw new CodeIntelligenceError("code.server_crashed", `Language server ${this.project.definition.id} failed: ${errorMessage(error)}${this.stderrSuffix()}`);
+        }
+    }
+    async workspaceSymbols(input) {
+        try {
+            await this.ensureStarted();
+            if (!this.capabilities?.workspaceSymbolProvider) {
+                throw new CodeIntelligenceError("code.operation_unsupported", `Language server ${this.project.definition.id} does not advertise workspace-symbol support.`);
+            }
+            const sourcePath = await workspaceSourcePath(this.workspaceRoot, input.path);
+            await this.syncDocument(sourcePath);
+            const response = await withTimeout(this.connection.sendRequest(WorkspaceSymbolRequest.type, { query: input.query }), this.policy.requestTimeoutMs, () => new CodeIntelligenceError("code.request_timeout", `Workspace-symbol request timed out for ${JSON.stringify(input.query)}.`));
+            const normalized = await normalizeWorkspaceSymbols(response, this.workspaceRoot, this.positionEncoding, input.limit ?? DEFAULT_CODE_INTELLIGENCE_RESULT_LIMIT);
+            return {
+                operation: "workspaceSymbols",
+                selectedServer: this.project.definition.id,
+                projectRoot: workspaceDisplayPath(this.workspaceRoot, this.project.projectRoot),
+                ...normalized,
+            };
+        }
+        catch (error) {
+            if (error instanceof CodeIntelligenceError)
+                throw error;
+            throw new CodeIntelligenceError("code.server_crashed", `Language server ${this.project.definition.id} failed: ${errorMessage(error)}${this.stderrSuffix()}`);
+        }
+    }
     async shutdown() {
         if (this.closed)
             return;
@@ -218,6 +300,9 @@ class LanguageService {
                 workspace: {
                     workspaceFolders: true,
                     configuration: true,
+                    symbol: {
+                        dynamicRegistration: false,
+                    },
                 },
                 textDocument: {
                     synchronization: {
@@ -232,6 +317,13 @@ class LanguageService {
                         dynamicRegistration: false,
                         contentFormat: [MarkupKind.Markdown, MarkupKind.PlainText],
                     },
+                    references: {
+                        dynamicRegistration: false,
+                    },
+                    documentSymbol: {
+                        dynamicRegistration: false,
+                        hierarchicalDocumentSymbolSupport: true,
+                    },
                 },
             },
         };
@@ -321,137 +413,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 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 {
-            return input.operation === "definition"
-                ? await service.definition(input)
-                : await service.hover(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,
@@ -494,48 +456,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 {
@@ -583,13 +503,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/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/normalization/symbols.js

@@ -0,0 +1,90 @@
+import { SymbolKind, } from "vscode-languageserver-protocol";
+import { CodeIntelligenceError } from "../code-intelligence-error.js";
+import { normalizeLocations } from "./locations.js";
+import { rangeFromLsp } from "../position-encoding.js";
+export function normalizeDocumentSymbols(response, text, encoding, limit) {
+    if (!response || response.length === 0) {
+        return { hierarchical: true, symbols: [], returned: 0, truncated: false, total: 0 };
+    }
+    if (isFlatSymbolInformation(response[0])) {
+        const flat = response;
+        const selected = flat.slice(0, limit).map((symbol) => ({
+            name: symbol.name,
+            kind: symbolKindName(symbol.kind),
+            ...(symbol.containerName ? { containerName: symbol.containerName } : {}),
+            range: rangeFromLsp(text, symbol.location.range, encoding),
+        }));
+        return {
+            hierarchical: false,
+            symbols: selected,
+            returned: selected.length,
+            truncated: flat.length > selected.length,
+            total: flat.length,
+        };
+    }
+    const hierarchical = response;
+    const total = countDocumentSymbols(hierarchical);
+    const budget = { remaining: limit, returned: 0 };
+    const symbols = takeDocumentSymbols(hierarchical, text, encoding, budget);
+    return {
+        hierarchical: true,
+        symbols,
+        returned: budget.returned,
+        truncated: total > budget.returned,
+        total,
+    };
+}
+function takeDocumentSymbols(symbols, text, encoding, budget) {
+    const normalized = [];
+    for (const symbol of symbols) {
+        if (budget.remaining <= 0)
+            break;
+        budget.remaining -= 1;
+        budget.returned += 1;
+        const children = symbol.children?.length
+            ? takeDocumentSymbols(symbol.children, text, encoding, budget)
+            : [];
+        normalized.push({
+            name: symbol.name,
+            kind: symbolKindName(symbol.kind),
+            ...(symbol.detail ? { detail: symbol.detail } : {}),
+            range: rangeFromLsp(text, symbol.range, encoding),
+            selectionRange: rangeFromLsp(text, symbol.selectionRange, encoding),
+            ...(children.length ? { children } : {}),
+        });
+    }
+    return normalized;
+}
+function countDocumentSymbols(symbols) {
+    return symbols.reduce((total, symbol) => total + 1 + (symbol.children ? countDocumentSymbols(symbol.children) : 0), 0);
+}
+function isFlatSymbolInformation(symbol) {
+    return "location" in symbol;
+}
+export async function normalizeWorkspaceSymbols(response, workspaceRoot, encoding, limit) {
+    const all = response ?? [];
+    const selected = all.slice(0, limit);
+    const locationEntries = selected.map((symbol) => {
+        if (!("range" in symbol.location)) {
+            throw new CodeIntelligenceError("code.result_outside_policy", `Language server returned unresolved workspace symbol ${symbol.name} without a range.`);
+        }
+        return { uri: symbol.location.uri, range: symbol.location.range };
+    });
+    const locations = await normalizeLocations(locationEntries, workspaceRoot, encoding);
+    const symbols = selected.map((symbol, index) => ({
+        name: symbol.name,
+        kind: symbolKindName(symbol.kind),
+        ...(symbol.containerName ? { containerName: symbol.containerName } : {}),
+        location: locations[index],
+    }));
+    return {
+        symbols,
+        returned: symbols.length,
+        truncated: all.length > symbols.length,
+        total: all.length,
+    };
+}
+export function symbolKindName(kind) {
+    const entry = Object.entries(SymbolKind).find(([, value]) => value === kind);
+    return entry ? entry[0].toLowerCase() : `unknown:${kind}`;
+}

package/dist/lsp/runtime/manager.js

@@ -0,0 +1,156 @@
+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);
+                case "documentSymbols":
+                    return await service.documentSymbols(input);
+                case "workspaceSymbols":
+                    return await service.workspaceSymbols(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";

package/docs/configuration.md

@@ -154,13 +154,21 @@ 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.1 supports
-`definition` and `hover`. Both 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. 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.3 supports
+`definition`, `hover`, `references`, `documentSymbols`, and `workspaceSymbols`.
+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. Document symbols use
+`path` plus optional `limit`, preserve server hierarchy when present, and keep flat
+legacy symbol responses flat. Workspace symbols use `path` to select the Language
+project/service, then apply a `query` with an optional bounded `limit`; ForgeRelay
+does not silently merge results from multiple nested Language services. Bounded
+collection 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.1",
+  "version": "0.4.3",
   "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/lsp/normalization/hover.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/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.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,23 @@ try {
   });
   assert.equal(describedCodeIntelligence.isError, undefined);
   assert.equal(describedCodeIntelligence.structuredContent.capability.guide.name, "code-intelligence");
-  assert.equal(describedCodeIntelligence.structuredContent.capability.inputSchema.type, "object");
+  const codeIntelligenceSchema = describedCodeIntelligence.structuredContent.capability.inputSchema;
+  assert.ok(Array.isArray(codeIntelligenceSchema.oneOf));
   assert.deepEqual(
-    describedCodeIntelligence.structuredContent.capability.inputSchema.properties.operation.enum,
-    ["definition", "hover"],
+    codeIntelligenceSchema.oneOf.map((variant) => variant.properties.operation.const),
+    ["definition", "hover", "references", "documentSymbols", "workspaceSymbols"],
   );
+  for (const operation of ["references", "documentSymbols", "workspaceSymbols"]) {
+    const boundedSchema = codeIntelligenceSchema.oneOf.find(
+      (variant) => variant.properties.operation.const === operation,
+    );
+    assert.equal(boundedSchema.properties.limit.minimum, 1);
+    assert.equal(boundedSchema.properties.limit.maximum, 1000);
+  }
+  const workspaceSymbolsSchema = codeIntelligenceSchema.oneOf.find(
+    (variant) => variant.properties.operation.const === "workspaceSymbols",
+  );
+  assert.ok(workspaceSymbolsSchema.required.includes("query"));
   if (process.platform === "linux") {
     const describedArtifact = callTool(oauth.accessToken, sessionId, 82, "capability", {
       workspaceId,