@akira-tl/forgerelay 0.3.7 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [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`.
+
+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.
+
+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.
+
+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.literal("definition"),
+        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.js

@@ -0,0 +1,550 @@
+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 { 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 { terminateProcessTree } from "../process-platform.js";
+import { CodeIntelligenceError } from "./code-intelligence-error.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 {
+    workspaceRoot;
+    project;
+    policy;
+    key;
+    lastUsedAt = Date.now();
+    inFlight = 0;
+    child;
+    connection;
+    initializePromise;
+    positionEncoding = PositionEncodingKind.UTF16;
+    capabilities;
+    documents = new Map();
+    stderrTail = Buffer.alloc(0);
+    closed = false;
+    constructor(workspaceRoot, project, policy) {
+        this.workspaceRoot = workspaceRoot;
+        this.project = project;
+        this.policy = policy;
+        this.key = languageServiceKey(project);
+    }
+    acquire() {
+        this.inFlight += 1;
+        this.lastUsedAt = Date.now();
+    }
+    release() {
+        this.inFlight = Math.max(0, this.inFlight - 1);
+        this.lastUsedAt = Date.now();
+    }
+    async definition(input) {
+        try {
+            await this.ensureStarted();
+            if (!this.capabilities?.definitionProvider) {
+                throw new CodeIntelligenceError("code.operation_unsupported", `Language server ${this.project.definition.id} does not advertise definition 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(DefinitionRequest.type, {
+                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);
+            return {
+                operation: "definition",
+                selectedServer: this.project.definition.id,
+                projectRoot: workspaceDisplayPath(this.workspaceRoot, this.project.projectRoot),
+                locations,
+            };
+        }
+        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;
+        this.closed = true;
+        const connection = this.connection;
+        const child = this.child;
+        if (connection) {
+            for (const document of this.documents.values()) {
+                if (!document.openNotified)
+                    continue;
+                try {
+                    await connection.sendNotification(DidCloseTextDocumentNotification.type, {
+                        textDocument: { uri: document.uri },
+                    });
+                }
+                catch {
+                    // The server may already be gone.
+                }
+            }
+            try {
+                await withTimeout(connection.sendRequest(ShutdownRequest.type), this.policy.shutdownTimeoutMs, () => new Error("Language-server shutdown timed out."));
+                await connection.sendNotification(ExitNotification.type);
+                if (child) {
+                    await waitForChildExit(child, this.policy.shutdownTimeoutMs);
+                }
+            }
+            catch {
+                // Fall through to process-tree termination below.
+            }
+            connection.dispose();
+        }
+        this.documents.clear();
+        if (child && child.exitCode === null && child.signalCode === null) {
+            terminateProcessTree(child, "SIGTERM", process.platform !== "win32");
+        }
+        this.child = undefined;
+        this.connection = undefined;
+        this.initializePromise = undefined;
+    }
+    async ensureStarted() {
+        if (this.closed) {
+            throw new CodeIntelligenceError("code.server_crashed", `Language service ${this.project.definition.id} is already closed.`);
+        }
+        if (!this.initializePromise)
+            this.initializePromise = this.start();
+        try {
+            const result = await this.initializePromise;
+            this.capabilities = result.capabilities;
+            this.positionEncoding = result.capabilities.positionEncoding ?? PositionEncodingKind.UTF16;
+        }
+        catch (error) {
+            this.initializePromise = undefined;
+            this.cleanupFailedStart();
+            if (error instanceof CodeIntelligenceError)
+                throw error;
+            throw new CodeIntelligenceError("code.language_service_start_failed", `Unable to initialize Language server ${this.project.definition.id}: ${errorMessage(error)}${this.stderrSuffix()}`);
+        }
+    }
+    async start() {
+        const definition = this.project.definition;
+        const detached = process.platform !== "win32";
+        let child;
+        try {
+            child = spawn(definition.command, definition.args, {
+                cwd: this.project.projectRoot,
+                env: { ...process.env, ...definition.env },
+                stdio: "pipe",
+                windowsHide: true,
+                detached,
+                shell: false,
+            });
+        }
+        catch (error) {
+            throw new CodeIntelligenceError("code.language_service_start_failed", `Unable to start Language server ${definition.id}: ${errorMessage(error)}.`);
+        }
+        this.child = child;
+        child.stderr.on("data", (chunk) => this.appendStderr(chunk));
+        await waitForChildSpawn(child, definition.id);
+        const connection = createMessageConnection(child.stdout, child.stdin);
+        this.connection = connection;
+        this.registerClientHandlers(connection);
+        connection.listen();
+        let onExitDuringInitialization;
+        const startupFailure = new Promise((_resolve, reject) => {
+            onExitDuringInitialization = (code, signal) => reject(new CodeIntelligenceError("code.language_service_start_failed", `Language server ${definition.id} exited during initialization (${signal ?? code ?? "unknown"}).${this.stderrSuffix()}`));
+            child.once("exit", onExitDuringInitialization);
+        });
+        const rootUri = pathToFileURL(this.project.projectRoot).href;
+        const initializeParams = {
+            processId: process.pid,
+            clientInfo: { name: "forgerelay" },
+            rootUri,
+            workspaceFolders: [{ uri: rootUri, name: basename(this.project.projectRoot) }],
+            capabilities: {
+                general: {
+                    positionEncodings: [
+                        PositionEncodingKind.UTF8,
+                        PositionEncodingKind.UTF16,
+                        PositionEncodingKind.UTF32,
+                    ],
+                },
+                workspace: {
+                    workspaceFolders: true,
+                    configuration: true,
+                },
+                textDocument: {
+                    synchronization: {
+                        dynamicRegistration: false,
+                        didSave: false,
+                    },
+                    definition: {
+                        dynamicRegistration: false,
+                        linkSupport: true,
+                    },
+                },
+            },
+        };
+        const initialize = connection.sendRequest(InitializeRequest.type, initializeParams);
+        try {
+            const result = await withTimeout(Promise.race([initialize, startupFailure]), this.policy.startTimeoutMs, () => new CodeIntelligenceError("code.language_service_start_timeout", `Language server ${definition.id} did not initialize within ${this.policy.startTimeoutMs}ms.`));
+            await connection.sendNotification(InitializedNotification.type, {});
+            return result;
+        }
+        finally {
+            if (onExitDuringInitialization)
+                child.off("exit", onExitDuringInitialization);
+        }
+    }
+    cleanupFailedStart() {
+        this.connection?.dispose();
+        const child = this.child;
+        if (child && child.exitCode === null && child.signalCode === null) {
+            terminateProcessTree(child, "SIGTERM", process.platform !== "win32");
+        }
+        this.connection = undefined;
+        this.child = undefined;
+        this.documents.clear();
+    }
+    registerClientHandlers(connection) {
+        connection.onRequest("workspace/configuration", (params) => Array.isArray(params?.items) ? params.items.map(() => null) : []);
+        connection.onRequest("workspace/workspaceFolders", () => [{
+                uri: pathToFileURL(this.project.projectRoot).href,
+                name: basename(this.project.projectRoot),
+            }]);
+        connection.onRequest("window/showMessageRequest", () => null);
+        connection.onNotification("window/logMessage", () => undefined);
+        connection.onNotification("window/showMessage", () => undefined);
+    }
+    async syncDocument(sourcePath) {
+        const uri = pathToFileURL(sourcePath).href;
+        const text = await readFile(sourcePath, "utf8");
+        const existing = this.documents.get(uri);
+        const languageId = languageIdForPath(this.project.definition, sourcePath);
+        const synchronization = textDocumentSynchronization(this.capabilities?.textDocumentSync);
+        if (!existing) {
+            const document = { uri, languageId, version: 1, text, openNotified: false };
+            this.documents.set(uri, document);
+            if (synchronization.openClose) {
+                await this.connection.sendNotification(DidOpenTextDocumentNotification.type, {
+                    textDocument: {
+                        uri: document.uri,
+                        languageId: document.languageId,
+                        version: document.version,
+                        text: document.text,
+                    },
+                });
+                document.openNotified = true;
+            }
+            return document;
+        }
+        if (existing.text !== text) {
+            const previousText = existing.text;
+            existing.version += 1;
+            existing.text = text;
+            if (synchronization.change === TextDocumentSyncKind.Full) {
+                await this.connection.sendNotification(DidChangeTextDocumentNotification.type, {
+                    textDocument: { uri, version: existing.version },
+                    contentChanges: [{ text }],
+                });
+            }
+            else if (synchronization.change === TextDocumentSyncKind.Incremental) {
+                await this.connection.sendNotification(DidChangeTextDocumentNotification.type, {
+                    textDocument: { uri, version: existing.version },
+                    contentChanges: [{
+                            range: wholeDocumentRange(previousText, this.positionEncoding),
+                            text,
+                        }],
+                });
+            }
+        }
+        return existing;
+    }
+    appendStderr(chunk) {
+        this.stderrTail = Buffer.concat([this.stderrTail, chunk]);
+        if (this.stderrTail.length > STDERR_TAIL_BYTES) {
+            this.stderrTail = this.stderrTail.subarray(this.stderrTail.length - STDERR_TAIL_BYTES);
+        }
+    }
+    stderrSuffix() {
+        const text = this.stderrTail.toString("utf8").trim();
+        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) {
+    return JSON.stringify([
+        resolve(project.projectRoot),
+        project.definition.id,
+        project.definition.fingerprint,
+    ]);
+}
+function languageIdForPath(definition, path) {
+    const extension = path.slice(path.lastIndexOf(".")).toLowerCase();
+    return definition.languageIdByExtension[extension] ?? definition.languages[0];
+}
+function textDocumentSynchronization(value) {
+    if (typeof value === "number") {
+        return {
+            openClose: value !== TextDocumentSyncKind.None,
+            change: value,
+        };
+    }
+    return {
+        openClose: value?.openClose === true,
+        change: value?.change ?? TextDocumentSyncKind.None,
+    };
+}
+async function workspaceSourcePath(workspaceRoot, inputPath) {
+    const root = resolve(workspaceRoot);
+    const path = resolve(root, inputPath);
+    if (!isWithin(root, path)) {
+        throw new CodeIntelligenceError("code.language_service_unavailable", `Code-intelligence source path must remain inside the Workspace: ${inputPath}`);
+    }
+    try {
+        const [canonicalRoot, canonicalPath] = await Promise.all([realpath(root), realpath(path)]);
+        if (!isWithin(canonicalRoot, canonicalPath)) {
+            throw new CodeIntelligenceError("code.language_service_unavailable", `Code-intelligence source path resolves outside the Workspace: ${inputPath}`);
+        }
+        await readFile(canonicalPath, "utf8");
+        return canonicalPath;
+    }
+    catch (error) {
+        if (error instanceof CodeIntelligenceError)
+            throw error;
+        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 {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(timeoutError()), timeoutMs);
+                timer.unref();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function waitForChildSpawn(child, serverId) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        const onSpawn = () => {
+            child.off("error", onError);
+            resolvePromise();
+        };
+        const onError = (error) => {
+            child.off("spawn", onSpawn);
+            rejectPromise(new CodeIntelligenceError("code.language_service_start_failed", `Unable to start Language server ${serverId}: ${error.message}.`));
+        };
+        child.once("spawn", onSpawn);
+        child.once("error", onError);
+    });
+}
+async function waitForChildExit(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return true;
+    return new Promise((resolvePromise) => {
+        let timer;
+        const finish = (exited) => {
+            child.off("exit", onExit);
+            if (timer)
+                clearTimeout(timer);
+            resolvePromise(exited);
+        };
+        const onExit = () => finish(true);
+        child.once("exit", onExit);
+        timer = setTimeout(() => finish(false), 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/language-server-config.js

@@ -0,0 +1,313 @@
+import { access, readFile, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+export class LanguageServerConfigurationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "LanguageServerConfigurationError";
+    }
+}
+const definitionSchema = z.object({
+    enabled: z.boolean().optional(),
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    languages: z.array(z.string().min(1)).min(1).optional(),
+    extensions: z.array(z.string().regex(/^\./)).min(1).optional(),
+    languageIdByExtension: z.record(z.string().regex(/^\./), z.string().min(1)).optional(),
+    projectMarkers: z.array(z.string().min(1)).optional(),
+}).strict();
+const configSchema = z.record(z.string().min(1), definitionSchema);
+const BUILTIN_DEFINITIONS = {
+    typescript: {
+        executableCandidates: ["typescript-language-server"],
+        args: ["--stdio"],
+        languages: ["typescript", "typescriptreact", "javascript", "javascriptreact"],
+        extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+        languageIdByExtension: {
+            ".ts": "typescript",
+            ".tsx": "typescriptreact",
+            ".js": "javascript",
+            ".jsx": "javascriptreact",
+            ".mjs": "javascript",
+            ".cjs": "javascript",
+        },
+        projectMarkers: ["tsconfig.json", "jsconfig.json", "package.json"],
+    },
+    pyright: {
+        executableCandidates: ["pyright-langserver"],
+        args: ["--stdio"],
+        languages: ["python"],
+        extensions: [".py", ".pyi"],
+        languageIdByExtension: { ".py": "python", ".pyi": "python" },
+        projectMarkers: ["pyrightconfig.json", "pyproject.toml", "setup.cfg", "setup.py"],
+    },
+    "rust-analyzer": {
+        executableCandidates: ["rust-analyzer"],
+        languages: ["rust"],
+        extensions: [".rs"],
+        languageIdByExtension: { ".rs": "rust" },
+        projectMarkers: ["Cargo.toml"],
+    },
+    gopls: {
+        executableCandidates: ["gopls"],
+        languages: ["go"],
+        extensions: [".go"],
+        languageIdByExtension: { ".go": "go" },
+        projectMarkers: ["go.work", "go.mod"],
+    },
+    clangd: {
+        executableCandidates: ["clangd"],
+        languages: ["c", "cpp", "objective-c", "objective-cpp"],
+        extensions: [".c", ".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".hxx", ".m", ".mm"],
+        languageIdByExtension: {
+            ".c": "c",
+            ".cc": "cpp",
+            ".cpp": "cpp",
+            ".cxx": "cpp",
+            ".h": "cpp",
+            ".hh": "cpp",
+            ".hpp": "cpp",
+            ".hxx": "cpp",
+            ".m": "objective-c",
+            ".mm": "objective-cpp",
+        },
+        projectMarkers: ["compile_commands.json", "compile_flags.txt", ".clangd"],
+    },
+};
+export async function resolveLanguageProject(input) {
+    const workspaceRoot = await canonicalWorkspaceRoot(input.workspaceRoot);
+    const sourcePath = await resolveWorkspaceSourcePath(workspaceRoot, input.sourcePath);
+    const projectConfig = await loadProjectLanguageServerConfig(workspaceRoot);
+    const globalConfig = parseLanguageServerConfig(input.globalConfig ?? {}, "global ForgeRelay config");
+    const definitions = await effectiveDefinitions(globalConfig, projectConfig, input.env ?? process.env);
+    const extension = extname(sourcePath).toLowerCase();
+    const candidates = [];
+    for (const definition of definitions) {
+        if (!definition.extensions.includes(extension))
+            continue;
+        const projectRoot = await findLanguageProjectRoot(workspaceRoot, dirname(sourcePath), definition.projectMarkers);
+        if (!projectRoot)
+            continue;
+        candidates.push({ definition, projectRoot });
+    }
+    if (candidates.length === 0) {
+        throw new LanguageServerConfigurationError("code.language_service_unavailable", `No available Language-server definition matches ${relative(workspaceRoot, sourcePath) || "."}.`);
+    }
+    const sourceRank = { builtin: 0, global: 1, project: 2 };
+    const highestRank = Math.max(...candidates.map((candidate) => sourceRank[candidate.definition.source]));
+    const highest = candidates.filter((candidate) => sourceRank[candidate.definition.source] === highestRank);
+    const deepestLength = Math.max(...highest.map((candidate) => candidate.projectRoot.length));
+    const nearest = highest.filter((candidate) => candidate.projectRoot.length === deepestLength);
+    if (nearest.length !== 1) {
+        throw new LanguageServerConfigurationError("code.configuration_ambiguous", `Multiple Language-server definitions match ${relative(workspaceRoot, sourcePath)} at the same priority: ${nearest.map((candidate) => candidate.definition.id).join(", ")}.`);
+    }
+    return nearest[0];
+}
+export async function loadProjectLanguageServerConfig(workspaceRoot) {
+    const path = join(workspaceRoot, ".forgerelay", "language-servers.json");
+    try {
+        return parseLanguageServerConfig(JSON.parse(await readFile(path, "utf8")), path);
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return {};
+        if (error instanceof LanguageServerConfigurationError)
+            throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new LanguageServerConfigurationError("code.configuration_invalid", `Unable to load Language-server configuration at ${path}: ${reason}`);
+    }
+}
+export function parseLanguageServerConfig(value, label) {
+    const parsed = configSchema.safeParse(value ?? {});
+    if (!parsed.success) {
+        const details = parsed.error.issues
+            .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+            .join("; ");
+        throw new LanguageServerConfigurationError("code.configuration_invalid", `Invalid Language-server configuration in ${label}: ${details}`);
+    }
+    return parsed.data;
+}
+async function effectiveDefinitions(globalConfig, projectConfig, env) {
+    const ids = new Set([
+        ...Object.keys(BUILTIN_DEFINITIONS),
+        ...Object.keys(globalConfig),
+        ...Object.keys(projectConfig),
+    ]);
+    const definitions = [];
+    for (const id of ids) {
+        const builtin = BUILTIN_DEFINITIONS[id];
+        const global = globalConfig[id];
+        const project = projectConfig[id];
+        const source = project
+            ? "project"
+            : global
+                ? "global"
+                : "builtin";
+        const merged = {
+            id,
+            source,
+            ...(builtin ?? {}),
+            ...(global ?? {}),
+            ...(project ?? {}),
+            env: {
+                ...(builtin?.env ?? {}),
+                ...(global?.env ?? {}),
+                ...(project?.env ?? {}),
+            },
+            languageIdByExtension: {
+                ...(builtin?.languageIdByExtension ?? {}),
+                ...(global?.languageIdByExtension ?? {}),
+                ...(project?.languageIdByExtension ?? {}),
+            },
+        };
+        if (merged.enabled === false)
+            continue;
+        const languages = merged.languages ?? [];
+        const extensions = merged.extensions?.map((entry) => entry.toLowerCase()) ?? [];
+        if (languages.length === 0 || extensions.length === 0)
+            continue;
+        const languageIdByExtension = normalizeLanguageIds(id, merged, languages, extensions);
+        let command = merged.command;
+        if (!command && builtin?.executableCandidates) {
+            command = await findExecutable(builtin.executableCandidates, env);
+            if (!command)
+                continue;
+        }
+        if (!command) {
+            throw new LanguageServerConfigurationError("code.configuration_invalid", `Language-server definition ${id} requires a command.`);
+        }
+        const normalized = {
+            id,
+            command,
+            args: merged.args ?? [],
+            env: merged.env ?? {},
+            languages,
+            extensions,
+            languageIdByExtension,
+            projectMarkers: merged.projectMarkers ?? [],
+            source,
+        };
+        definitions.push({
+            ...normalized,
+            fingerprint: createHash("sha256").update(JSON.stringify(normalized)).digest("hex"),
+        });
+    }
+    return definitions;
+}
+function normalizeLanguageIds(id, definition, languages, extensions) {
+    const mapping = Object.fromEntries(Object.entries(definition.languageIdByExtension ?? {})
+        .map(([extension, languageId]) => [extension.toLowerCase(), languageId]));
+    for (let index = 0; index < extensions.length; index += 1) {
+        const extension = extensions[index];
+        if (mapping[extension])
+            continue;
+        if (languages.length === 1) {
+            mapping[extension] = languages[0];
+            continue;
+        }
+        if (languages.length === extensions.length) {
+            mapping[extension] = languages[index];
+            continue;
+        }
+        throw new LanguageServerConfigurationError("code.configuration_invalid", `Language-server definition ${id} must map extension ${extension} to a languageId when multiple language IDs do not align one-to-one with extensions.`);
+    }
+    for (const [extension, languageId] of Object.entries(mapping)) {
+        if (!extensions.includes(extension))
+            continue;
+        if (!languages.includes(languageId)) {
+            throw new LanguageServerConfigurationError("code.configuration_invalid", `Language-server definition ${id} maps ${extension} to unknown languageId ${languageId}.`);
+        }
+    }
+    return mapping;
+}
+async function findLanguageProjectRoot(workspaceRoot, startDirectory, markers) {
+    if (markers.length === 0)
+        return workspaceRoot;
+    let current = startDirectory;
+    while (isWithin(workspaceRoot, current)) {
+        for (const marker of markers) {
+            try {
+                await access(join(current, marker));
+                return current;
+            }
+            catch {
+                // Try the next marker or parent directory.
+            }
+        }
+        if (current === workspaceRoot)
+            break;
+        current = dirname(current);
+    }
+    return undefined;
+}
+async function canonicalWorkspaceRoot(inputPath) {
+    try {
+        return await realpath(resolve(inputPath));
+    }
+    catch {
+        throw new LanguageServerConfigurationError("code.language_service_unavailable", `Code-intelligence Workspace root does not exist: ${inputPath}`);
+    }
+}
+async function resolveWorkspaceSourcePath(workspaceRoot, inputPath) {
+    const candidate = resolve(workspaceRoot, inputPath);
+    if (!isWithin(workspaceRoot, candidate)) {
+        throw new LanguageServerConfigurationError("code.language_service_unavailable", `Code-intelligence source path must remain inside the Workspace: ${inputPath}`);
+    }
+    try {
+        const [canonicalRoot, canonicalCandidate] = await Promise.all([
+            realpath(workspaceRoot),
+            realpath(candidate),
+        ]);
+        if (!isWithin(canonicalRoot, canonicalCandidate)) {
+            throw new LanguageServerConfigurationError("code.language_service_unavailable", `Code-intelligence source path resolves outside the Workspace: ${inputPath}`);
+        }
+        return canonicalCandidate;
+    }
+    catch (error) {
+        if (error instanceof LanguageServerConfigurationError)
+            throw error;
+        throw new LanguageServerConfigurationError("code.language_service_unavailable", `Code-intelligence source path does not exist: ${inputPath}`);
+    }
+}
+async function findExecutable(candidates, env) {
+    for (const candidate of candidates) {
+        if (isAbsolute(candidate)) {
+            if (await executable(candidate))
+                return candidate;
+            continue;
+        }
+        const pathEntries = (env.PATH ?? "").split(delimiter).filter(Boolean);
+        const extensions = process.platform === "win32"
+            ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+            : [""];
+        for (const directory of pathEntries) {
+            for (const extension of extensions) {
+                const path = join(directory, process.platform === "win32" ? `${candidate}${extension}` : candidate);
+                if (await executable(path))
+                    return path;
+            }
+        }
+    }
+    return undefined;
+}
+async function executable(path) {
+    try {
+        await access(path, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/dist/lsp/position-encoding.js

@@ -0,0 +1,88 @@
+import { PositionEncodingKind } from "vscode-languageserver-protocol";
+import { CodeIntelligenceError } from "./code-intelligence-error.js";
+export function lspPositionFromUser(text, line, column, encoding) {
+    if (!Number.isInteger(line) || line < 1 || !Number.isInteger(column) || column < 1) {
+        throw new CodeIntelligenceError("code.invalid_position", `Code-intelligence positions are 1-based positive integers; received line=${line}, column=${column}.`);
+    }
+    const lines = text.split(/\r?\n/);
+    const sourceLine = lines[line - 1];
+    if (sourceLine === undefined) {
+        throw new CodeIntelligenceError("code.invalid_position", `Line ${line} is outside the document (${lines.length} lines).`);
+    }
+    const codePoints = Array.from(sourceLine);
+    const codePointIndex = column - 1;
+    if (codePointIndex > codePoints.length) {
+        throw new CodeIntelligenceError("code.invalid_position", `Column ${column} is outside line ${line} (${codePoints.length + 1} valid insertion positions).`);
+    }
+    const prefix = codePoints.slice(0, codePointIndex).join("");
+    return {
+        line: line - 1,
+        character: encodedLength(prefix, encoding),
+    };
+}
+export function wholeDocumentRange(text, encoding) {
+    const lines = text.split(/\r?\n/);
+    const lastLine = Math.max(0, lines.length - 1);
+    return {
+        start: { line: 0, character: 0 },
+        end: {
+            line: lastLine,
+            character: encodedLength(lines[lastLine] ?? "", encoding),
+        },
+    };
+}
+export function rangeFromLsp(text, range, encoding) {
+    return {
+        start: positionFromLsp(text, range.start, encoding),
+        end: positionFromLsp(text, range.end, encoding),
+    };
+}
+function positionFromLsp(text, position, encoding) {
+    const lines = text.split(/\r?\n/);
+    const sourceLine = lines[position.line];
+    if (sourceLine === undefined) {
+        throw new CodeIntelligenceError("code.invalid_position", `Language server returned line ${position.line} outside a ${lines.length}-line document.`);
+    }
+    return {
+        line: position.line + 1,
+        column: decodedCodePointOffset(sourceLine, position.character, encoding) + 1,
+    };
+}
+function encodedLength(text, encoding) {
+    if (encoding === PositionEncodingKind.UTF8)
+        return Buffer.byteLength(text, "utf8");
+    if (encoding === PositionEncodingKind.UTF32)
+        return Array.from(text).length;
+    return text.length;
+}
+function decodedCodePointOffset(text, encodedOffset, encoding) {
+    if (!Number.isInteger(encodedOffset) || encodedOffset < 0) {
+        throw new CodeIntelligenceError("code.invalid_position", `Language server returned invalid character offset ${encodedOffset}.`);
+    }
+    if (encoding === PositionEncodingKind.UTF32) {
+        if (encodedOffset > Array.from(text).length) {
+            throw new CodeIntelligenceError("code.invalid_position", `Language server returned character offset ${encodedOffset} outside its line.`);
+        }
+        return encodedOffset;
+    }
+    if (encoding === PositionEncodingKind.UTF16) {
+        if (encodedOffset > text.length) {
+            throw new CodeIntelligenceError("code.invalid_position", `Language server returned character offset ${encodedOffset} outside its line.`);
+        }
+        return Array.from(text.slice(0, encodedOffset)).length;
+    }
+    let bytes = 0;
+    let codePoints = 0;
+    for (const character of text) {
+        if (bytes === encodedOffset)
+            return codePoints;
+        bytes += Buffer.byteLength(character, "utf8");
+        codePoints += 1;
+        if (bytes > encodedOffset) {
+            throw new CodeIntelligenceError("code.invalid_position", `Language server returned UTF-8 offset ${encodedOffset} inside a code point.`);
+        }
+    }
+    if (bytes === encodedOffset)
+        return codePoints;
+    throw new CodeIntelligenceError("code.invalid_position", `Language server returned character offset ${encodedOffset} outside its line.`);
+}

package/dist/server.js

@@ -21,6 +21,7 @@ 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 { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
 import { checkHookConfiguration } from "./hook-cli.js";
 import { buildServerInstructions, buildShellMutationPolicy, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
@@ -743,7 +744,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
         });
     });
 }
-export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters) {
+export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters, codeIntelligence) {
     const toolDescriptions = buildToolDescriptions(config);
     const hooks = new HookRunner(config.hooks, config.logging, process.env, (workspaceId, result) => attachCompletedProcessNotices(processSessions, workspaceId, result));
     const incomingArtifactRegistry = new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
@@ -751,6 +752,22 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     const reviewChangesAvailable = config.widgets === "changes";
     const capabilityRegistry = createCapabilityRegistry({
         inspectHooks: (workspaceRoot) => checkHookConfiguration(workspaceRoot, config.hooks),
+        codeIntelligence: {
+            available: true,
+            run: async (input, context) => {
+                try {
+                    return {
+                        value: await codeIntelligence.definition(context.workspaceRoot, input),
+                    };
+                }
+                catch (error) {
+                    if (error instanceof CodeIntelligenceError) {
+                        throw new CapabilityError(error.code, error.message);
+                    }
+                    throw error;
+                }
+            },
+        },
         reviewChanges: {
             available: reviewChangesAvailable,
             unavailableReason: reviewChangesAvailable
@@ -2108,6 +2125,7 @@ export function createServer(config = loadConfig(), options = {}) {
     const workspaces = new WorkspaceRegistry(config, workspaceStore);
     const reviewCheckpoints = createReviewCheckpointManager();
     const processSessions = new ProcessManager();
+    const codeIntelligence = new CodeIntelligenceManager(config);
     const localAgentProviders = config.subagents
         ? getLocalAgentProviderAvailabilitySnapshot()
         : [];
@@ -2154,6 +2172,7 @@ export function createServer(config = loadConfig(), options = {}) {
             processesCompleted: processStats.completed,
             cachedWorkspaces: workspaces.cachedWorkspaceCount,
             reviewStates: reviewCheckpoints.stateCount,
+            languageServices: codeIntelligence.size,
         });
     };
     const transportCleanupTimer = setInterval(() => {
@@ -2276,7 +2295,7 @@ export function createServer(config = loadConfig(), options = {}) {
                         });
                     }
                 };
-                const server = createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters);
+                const server = createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters, codeIntelligence);
                 await server.connect(transport);
             }
             else {
@@ -2306,6 +2325,7 @@ export function createServer(config = loadConfig(), options = {}) {
                 const results = await transports.closeAll();
                 logTransportCloseResults("server_shutdown", results);
                 processSessions.shutdown();
+                await codeIntelligence.shutdown();
                 oauthProvider.close();
                 workspaceStore.close?.();
             })();

package/docs/configuration.md

@@ -151,6 +151,68 @@ snapshot, treat that as stale Host MCP metadata: reconnect/refresh the integrati
 or use a Host context that reloads `tools/list`. The ForgeRelay process cannot
 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.
+
+Effective Language-server definitions resolve in this order:
+
+1. project configuration in `.forgerelay/language-servers.json`;
+2. global definitions from the `languageServers` object in
+   `~/.forgerelay/config.json`;
+3. built-in discovery for known executables.
+
+A project configuration file is an object keyed by definition name. Definitions
+use structured process launch and never go through a shell:
+
+```json
+{
+  "typescript": {
+    "command": "typescript-language-server",
+    "args": ["--stdio"],
+    "env": {},
+    "languages": ["typescript", "typescriptreact", "javascript", "javascriptreact"],
+    "extensions": [".ts", ".tsx", ".js", ".jsx"],
+    "languageIdByExtension": {
+      ".ts": "typescript",
+      ".tsx": "typescriptreact",
+      ".js": "javascript",
+      ".jsx": "javascriptreact"
+    },
+    "projectMarkers": ["tsconfig.json", "jsconfig.json"]
+  }
+}
+```
+
+Global configuration uses the same definition shape under `languageServers`:
+
+```json
+{
+  "languageServers": {
+    "typescript": {
+      "command": "/absolute/path/to/typescript-language-server",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+Explicit configuration can set `"enabled": false` to suppress the matching
+built-in definition. Project values override global values, and both override
+built-in defaults. ForgeRelay resolves a Language project by walking ancestors of
+the requested source file according to that definition's `projectMarkers`; it does
+not recursively scan the Workspace.
+
+Code-intelligence input positions are 1-based line and 1-based Unicode code-point
+column values. The Workspace filesystem is the only v1 document source of truth.
+Definition results may point outside the Workspace and are then marked
+`external: true`; this is informational only and does not expand allowed roots or
+file-tool authority.
+
 `rename` is the canonical move/rename primitive for files and directories; there
 is no separate `move` MCP tool.
 

package/docs/roadmap.md

@@ -225,6 +225,21 @@ Candidate servers include `typescript-language-server`/tsserver, Pyright,
 `rust-analyzer`, `gopls`, and `clangd`, but ForgeRelay should treat server
 commands/configuration as external dependencies.
 
+0.4 is delivered as independently published patch releases rather than one large
+0.4.0 batch. Every boundary must complete local acceptance, update release metadata,
+create and push its matching tag, pass cloud CI, publish npm and the GitHub Release,
+and verify publication before work begins on the next boundary:
+
+- **0.4.0** — Language-service foundation plus the complete `definition` tracer bullet;
+- **0.4.1** — hover/type information;
+- **0.4.2** — references and bounded semantic-location results;
+- **0.4.3** — hierarchical document symbols and bounded workspace symbols;
+- **0.4.4** — push/pull diagnostics and Diagnostic snapshots;
+- **0.4.5** — cancellation, deadlines, crash recovery/config invalidation, concurrency,
+  and full Language-service resource/lifecycle hardening;
+- **0.4.6** — optional real-server interoperability, cross-platform checks, fresh Host
+  acceptance, documentation, and final LSP v1 closure.
+
 ## 0.5 — First-class subagent MCP
 
 ForgeRelay already owns provider adapters and resumable local agent sessions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "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/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/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/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",
@@ -79,6 +79,8 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "semver": "^7.8.4",
+    "vscode-jsonrpc": "^9.0.1",
+    "vscode-languageserver-protocol": "^3.18.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },

package/scripts/debug/accept.mjs

@@ -244,6 +244,7 @@ try {
       "process.lifecycle",
       "hooks.lifecycle",
       "capability-guides.read",
+      "code.intelligence",
       ...(process.platform === "linux" ? ["artifact.native-download"] : []),
       "ui.mcp-app",
       "review.changes",
@@ -253,6 +254,7 @@ try {
   assert.deepEqual(capabilityCatalog.map((entry) => entry.name), [
     "hooks.check",
     "review.changes",
+    "code.intelligence",
     ...(process.platform === "linux" ? ["artifact.download"] : []),
   ]);
   assert.equal(capabilityCatalog[0].available, true);
@@ -323,6 +325,18 @@ try {
   assert.equal(describedCapability.isError, undefined);
   assert.equal(describedCapability.structuredContent.capability.guide.name, "lifecycle-hooks");
   assert.equal(describedCapability.structuredContent.capability.inputSchema.type, "object");
+  const describedCodeIntelligence = callTool(oauth.accessToken, sessionId, 88, "capability", {
+    workspaceId,
+    name: "code.intelligence",
+    action: "describe",
+  });
+  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",
+  );
   if (process.platform === "linux") {
     const describedArtifact = callTool(oauth.accessToken, sessionId, 82, "capability", {
       workspaceId,
@@ -350,6 +364,7 @@ try {
     "artifacts-review",
     "host-integration",
     "shell-processes",
+    "code-intelligence",
   ]);
   const hooksGuide = callTool(oauth.accessToken, sessionId, 78, "read", {
     workspaceId,