@akira-tl/forgerelay 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [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,8 @@ 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.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.
 
-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. 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.
 
 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

@@ -116,7 +116,7 @@ export class CapabilityRegistry {
 export function createCapabilityRegistry(dependencies) {
     const hooksCheckInput = z.object({}).strict();
     const codeIntelligenceInput = z.object({
-        operation: z.literal("definition"),
+        operation: z.enum(["definition", "hover"]),
         path: z.string().min(1),
         line: z.number().int(),
         column: z.number().int(),

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

@@ -0,0 +1 @@
+export {};

package/dist/lsp/code-intelligence.js

@@ -3,10 +3,11 @@ import { readFile, realpath } from "node:fs/promises";
 import { basename, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath, 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 { 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 { terminateProcessTree } from "../process-platform.js";
 import { CodeIntelligenceError } from "./code-intelligence-error.js";
+import { normalizeHoverContents } from "./normalization/hover.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;
@@ -75,6 +76,44 @@ 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 shutdown() {
         if (this.closed)
             return;
@@ -189,6 +228,10 @@ class LanguageService {
                         dynamicRegistration: false,
                         linkSupport: true,
                     },
+                    hover: {
+                        dynamicRegistration: false,
+                        contentFormat: [MarkupKind.Markdown, MarkupKind.PlainText],
+                    },
                 },
             },
         };
@@ -300,7 +343,7 @@ export class CodeIntelligenceManager {
         }, this.policy.cleanupIntervalMs);
         this.cleanupTimer.unref();
     }
-    async definition(workspaceRoot, input) {
+    async run(workspaceRoot, input) {
         let project;
         let canonicalWorkspaceRoot;
         try {
@@ -319,7 +362,9 @@ export class CodeIntelligenceManager {
         }
         const service = await this.acquireService(canonicalWorkspaceRoot, project);
         try {
-            return await service.definition(input);
+            return input.operation === "definition"
+                ? await service.definition(input)
+                : await service.hover(input);
         }
         finally {
             service.release();

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/server.js

@@ -757,7 +757,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,13 @@ 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.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.
 
 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.1",
   "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/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

@@ -333,9 +333,9 @@ 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",
+  assert.deepEqual(
+    describedCodeIntelligence.structuredContent.capability.inputSchema.properties.operation.enum,
+    ["definition", "hover"],
   );
   if (process.platform === "linux") {
     const describedArtifact = callTool(oauth.accessToken, sessionId, 82, "capability", {