@akira-tl/forgerelay 0.3.7 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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
+
+- Added `code.intelligence` as a Capability Gateway-only LSP code-intelligence surface. ForgeRelay 0.4.0 ships the first complete `definition` tracer bullet without changing the canonical nine Core MCP tools.
+- Added Language-server definitions with project (`.forgerelay/language-servers.json`), global (`~/.forgerelay/config.json`), and built-in discovery precedence. Common built-ins cover TypeScript/JavaScript, Pyright, rust-analyzer, gopls, and clangd when those executables are already installed.
+- Added a deterministic child-process fake LSP server and MCP-level regression seam covering initialize/shutdown, document synchronization, definition normalization, shared Language-service identity, capacity limits, and server-initiated edit rejection.
+
+### Changed
+
+- Code-intelligence positions use ForgeRelay's 1-based line and Unicode code-point column contract and are converted internally to the position encoding negotiated with the Language Server.
+- Language services are shared by canonical Language project root plus effective server-definition fingerprint rather than logical workspace ID, remain capacity/idle bounded, and use structured no-shell process launch over Microsoft's `vscode-jsonrpc` / `vscode-languageserver-protocol` substrate.
+- Language-server configuration can explicitly disable built-in discovery; nested Language projects resolve by walking ancestors of the requested source path instead of recursively scanning the Workspace.
+
+### Fixed
+
+- External LSP definition targets are marked as informational external locations without expanding ForgeRelay file-read authority, including symlink-escape protection and canonical Workspace-root handling.
+- Language-server startup failure/timeout, unsupported operations, invalid positions, configuration ambiguity, capacity exhaustion, and other policy failures now use stable ForgeRelay `code.*` errors instead of leaking raw JSON-RPC failures.
+
 ## [0.3.7] - 2026-08-10
 
 ### Added

package/capabilities/code-intelligence/GUIDE.md

@@ -0,0 +1,11 @@
+# Code Intelligence
+
+Use the `code.intelligence` Capability for read-only semantic code navigation backed by Language servers that are already installed on the user's machine or explicitly configured for the project.
+
+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.
+
+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/capabilities.js

@@ -34,6 +34,11 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
         description: "Long-running bash processes, processId interaction, PTY, and platform edges.",
         whenToRead: "Read for running or interactive command issues.",
     },
+    {
+        name: "code-intelligence",
+        description: "Read-only semantic code navigation backed by external Language servers.",
+        whenToRead: "Read before using code.intelligence or configuring Language servers.",
+    },
 ];
 function capabilityGuidesDir() {
     return fileURLToPath(new URL("../capabilities", import.meta.url));
@@ -75,6 +80,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "process.lifecycle",
         "hooks.lifecycle",
         "capability-guides.read",
+        "code.intelligence",
     ];
     if (config.subagents) {
         capabilities.push("subagent.profiles");

package/dist/capability-registry.js

@@ -115,6 +115,12 @@ export class CapabilityRegistry {
 }
 export function createCapabilityRegistry(dependencies) {
     const hooksCheckInput = z.object({}).strict();
+    const codeIntelligenceInput = z.object({
+        operation: z.enum(["definition", "hover"]),
+        path: z.string().min(1),
+        line: z.number().int(),
+        column: z.number().int(),
+    }).strict();
     return new CapabilityRegistry([
         {
             name: "hooks.check",
@@ -144,6 +150,20 @@ export function createCapabilityRegistry(dependencies) {
                     run: async (_input, context) => dependencies.reviewChanges.run(context),
                 }]
             : []),
+        ...(dependencies.codeIntelligence
+            ? [{
+                    name: "code.intelligence",
+                    description: "Read semantic code information through an available Language server without changing the Workspace.",
+                    guideName: "code-intelligence",
+                    readGuideBeforeFirstUse: true,
+                    inputSchema: codeIntelligenceInput,
+                    availability: () => ({
+                        available: dependencies.codeIntelligence?.available ?? false,
+                        reason: dependencies.codeIntelligence?.unavailableReason,
+                    }),
+                    run: async (input, context) => dependencies.codeIntelligence.run(input, context),
+                }]
+            : []),
         ...(dependencies.downloadArtifact
             ? [{
                     name: "artifact.download",

package/dist/config.js

@@ -223,6 +223,7 @@ export function loadConfig(env = process.env) {
         subagents: productEnv(env, "SUBAGENTS") === undefined
             ? files.config.subagents === true
             : parseBoolean(productEnv(env, "SUBAGENTS")),
+        languageServers: files.config.languageServers ?? {},
         agentDir: resolve(expandHomePath(productEnv(env, "AGENT_DIR") ?? files.config.agentDir ?? defaultAgentDir())),
         systemInstructionsPath: parseSystemInstructionsPath(productEnv(env, "SYSTEM_INSTRUCTIONS_PATH") ?? files.config.systemInstructionsPath),
         hooks: mergeHookConfigs(parseHookConfig(files.config.hooks), parseHookConfig(files.hooks), files.hookFiles),

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

@@ -0,0 +1,8 @@
+export class CodeIntelligenceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CodeIntelligenceError";
+    }
+}

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

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