@akira-tl/forgerelay 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.4.4] - 2026-08-11
+
+### Added
+
+- Added `code.intelligence` `diagnostics` with one normalized Agent-facing contract for traditional push diagnostics and LSP 3.17 pull diagnostics.
+- Added bounded latest Diagnostic snapshots with per-document freshness/version metadata, replacement/clear semantics, and no historical accumulation.
+
+### Changed
+
+- Pull diagnostics are preferred when a Language server advertises `diagnosticProvider`; ForgeRelay sends the previous `resultId`, handles `unchanged` reports, and keeps pull state independent from asynchronous push snapshots on mixed-capability servers.
+- Diagnostic collections reuse the 100 default / 1000 hard request limit while runtime caches independently bound document count and retained diagnostics per document. Filesystem synchronization makes stale push snapshots explicit and pull reports fresh against the synchronized document version.
+
+## [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

package/capabilities/code-intelligence/GUIDE.md

@@ -4,10 +4,14 @@ 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.2 supports `definition`, `hover`, and `references`. Position-based operations accept a workspace-relative source `path` plus 1-based `line` and `column` values. Columns are Unicode code-point positions; ForgeRelay converts them to the position encoding negotiated with the Language server.
+ForgeRelay 0.4.4 adds `diagnostics` alongside `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. `diagnostics` uses `path` plus an optional bounded `limit`. 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. 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.
+
+Diagnostics use the same normalized result contract for push and pull providers. When a Language server advertises LSP pull diagnostics, ForgeRelay prefers pull, supplies the previous `resultId` when available, and treats an `unchanged` report as a refresh of the same bounded snapshot for the newly synchronized filesystem version. Otherwise ForgeRelay uses traditional `publishDiagnostics` snapshots. Push diagnostics retain only the latest snapshot for each synchronized document: no diagnostic history is accumulated. A result reports `provider`, bounded normalized diagnostics, `returned`/`truncated`/`total`, and `freshness`. `freshness.state` distinguishes fresh, stale, missing, and unknown snapshots; filesystem changes advance ForgeRelay's synchronized document version, making an older push snapshot detectably stale until the Language server publishes a replacement. Pull and push state are bounded independently so a mixed-capability server cannot overwrite pull `resultId` state with an asynchronous push. All diagnostic state is released with the Language service.
+
 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

@@ -129,6 +129,22 @@ export function createCapabilityRegistry(dependencies) {
             ...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(),
+        z.object({
+            operation: z.literal("diagnostics"),
+            path: z.string().min(1),
+            limit: z.number().int().min(1).max(MAX_CODE_INTELLIGENCE_RESULT_LIMIT).optional(),
+        }).strict(),
     ]);
     return new CapabilityRegistry([
         {

package/dist/lsp/code-intelligence.js

@@ -3,14 +3,16 @@ import { readFile, realpath } from "node:fs/promises";
 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, ReferencesRequest, InitializedNotification, MarkupKind, PositionEncodingKind, ShutdownRequest, TextDocumentSyncKind, } from "vscode-languageserver-protocol";
+import { DefinitionRequest, DocumentDiagnosticReportKind, DocumentDiagnosticRequest, DocumentSymbolRequest, DidChangeTextDocumentNotification, DidCloseTextDocumentNotification, DidOpenTextDocumentNotification, ExitNotification, HoverRequest, InitializeRequest, ReferencesRequest, InitializedNotification, MarkupKind, PositionEncodingKind, PublishDiagnosticsNotification, 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";
+import { DiagnosticSnapshotStore } from "./runtime/diagnostic-snapshots.js";
 export { CodeIntelligenceError } from "./code-intelligence-error.js";
 const STDERR_TAIL_BYTES = 64 * 1024;
 export class LanguageService {
@@ -26,6 +28,7 @@ export class LanguageService {
     positionEncoding = PositionEncodingKind.UTF16;
     capabilities;
     documents = new Map();
+    diagnosticSnapshots;
     stderrTail = Buffer.alloc(0);
     closed = false;
     constructor(workspaceRoot, project, policy) {
@@ -33,6 +36,7 @@ export class LanguageService {
         this.project = project;
         this.policy = policy;
         this.key = languageServiceKey(project);
+        this.diagnosticSnapshots = new DiagnosticSnapshotStore(policy.maxDiagnosticDocuments, policy.maxDiagnosticsPerDocument);
     }
     acquire() {
         this.inFlight += 1;
@@ -147,6 +151,102 @@ export class LanguageService {
             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 diagnostics(input) {
+        try {
+            await this.ensureStarted();
+            const sourcePath = await workspaceSourcePath(this.workspaceRoot, input.path);
+            const document = await this.syncDocument(sourcePath);
+            const limit = input.limit ?? DEFAULT_CODE_INTELLIGENCE_RESULT_LIMIT;
+            const common = {
+                operation: "diagnostics",
+                selectedServer: this.project.definition.id,
+                projectRoot: workspaceDisplayPath(this.workspaceRoot, this.project.projectRoot),
+                path: workspaceDisplayPath(this.workspaceRoot, sourcePath),
+            };
+            const diagnosticProvider = this.capabilities?.diagnosticProvider;
+            if (diagnosticProvider) {
+                const previousResultId = this.diagnosticSnapshots.previousPullResultId(document.uri);
+                const response = await withTimeout(this.connection.sendRequest(DocumentDiagnosticRequest.type, {
+                    textDocument: { uri: document.uri },
+                    ...(diagnosticProvider.identifier === undefined ? {} : { identifier: diagnosticProvider.identifier }),
+                    ...(previousResultId === undefined ? {} : { previousResultId }),
+                }), this.policy.requestTimeoutMs, () => new CodeIntelligenceError("code.request_timeout", `Diagnostic request timed out for ${input.path}.`));
+                if (response.kind === DocumentDiagnosticReportKind.Full) {
+                    this.diagnosticSnapshots.capturePull(response.items, document, this.positionEncoding, response.resultId);
+                }
+                else if (!this.diagnosticSnapshots.markPullUnchanged(document, response.resultId)) {
+                    throw new CodeIntelligenceError("code.result_outside_policy", `Language server ${this.project.definition.id} returned unchanged diagnostics without a previous full report.`);
+                }
+                return {
+                    ...common,
+                    provider: "pull",
+                    ...this.diagnosticSnapshots.readPull(document, limit),
+                };
+            }
+            const snapshot = this.diagnosticSnapshots.readPush(document, limit);
+            if (snapshot.freshness.state === "missing" && !this.diagnosticSnapshots.hasObservedPushDiagnostics()) {
+                throw new CodeIntelligenceError("code.operation_unsupported", `Language server ${this.project.definition.id} does not provide pull diagnostics and has not published push diagnostics.`);
+            }
+            return {
+                ...common,
+                provider: "push",
+                ...snapshot,
+            };
+        }
+        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;
@@ -179,6 +279,7 @@ export class LanguageService {
             connection.dispose();
         }
         this.documents.clear();
+        this.diagnosticSnapshots.clear();
         if (child && child.exitCode === null && child.signalCode === null) {
             terminateProcessTree(child, "SIGTERM", process.platform !== "win32");
         }
@@ -251,6 +352,9 @@ export class LanguageService {
                 workspace: {
                     workspaceFolders: true,
                     configuration: true,
+                    symbol: {
+                        dynamicRegistration: false,
+                    },
                 },
                 textDocument: {
                     synchronization: {
@@ -268,6 +372,14 @@ export class LanguageService {
                     references: {
                         dynamicRegistration: false,
                     },
+                    documentSymbol: {
+                        dynamicRegistration: false,
+                        hierarchicalDocumentSymbolSupport: true,
+                    },
+                    diagnostic: {
+                        dynamicRegistration: false,
+                        relatedDocumentSupport: false,
+                    },
                 },
             },
         };
@@ -291,6 +403,7 @@ export class LanguageService {
         this.connection = undefined;
         this.child = undefined;
         this.documents.clear();
+        this.diagnosticSnapshots.clear();
     }
     registerClientHandlers(connection) {
         connection.onRequest("workspace/configuration", (params) => Array.isArray(params?.items) ? params.items.map(() => null) : []);
@@ -301,6 +414,9 @@ export class LanguageService {
         connection.onRequest("window/showMessageRequest", () => null);
         connection.onNotification("window/logMessage", () => undefined);
         connection.onNotification("window/showMessage", () => undefined);
+        connection.onNotification(PublishDiagnosticsNotification.type, (params) => {
+            this.diagnosticSnapshots.capturePush(params, this.documents.get(params.uri), this.positionEncoding);
+        });
     }
     async syncDocument(sourcePath) {
         const uri = pathToFileURL(sourcePath).href;

package/dist/lsp/normalization/diagnostics.js

@@ -0,0 +1,29 @@
+import { rangeFromLsp } from "../position-encoding.js";
+export function normalizeDiagnostic(diagnostic, documentText, encoding) {
+    return {
+        range: rangeFromLsp(documentText, diagnostic.range, encoding),
+        ...(diagnostic.severity === undefined ? {} : { severity: diagnosticSeverityName(diagnostic.severity) }),
+        ...(diagnostic.code === undefined ? {} : { code: diagnostic.code }),
+        ...(diagnostic.source === undefined ? {} : { source: diagnostic.source }),
+        message: typeof diagnostic.message === "string" ? diagnostic.message : diagnostic.message.value,
+        ...(diagnostic.tags?.length
+            ? { tags: diagnostic.tags.map(diagnosticTagName) }
+            : {}),
+    };
+}
+function diagnosticSeverityName(value) {
+    switch (value) {
+        case 1: return "error";
+        case 2: return "warning";
+        case 3: return "information";
+        case 4: return "hint";
+        default: return `unknown:${value}`;
+    }
+}
+function diagnosticTagName(value) {
+    switch (value) {
+        case 1: return "unnecessary";
+        case 2: return "deprecated";
+        default: return `unknown:${value}`;
+    }
+}

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/diagnostic-snapshots.js

@@ -0,0 +1,105 @@
+import { normalizeDiagnostic } from "../normalization/diagnostics.js";
+export class DiagnosticSnapshotStore {
+    maxDocuments;
+    maxDiagnosticsPerDocument;
+    pushSnapshots = new Map();
+    pullSnapshots = new Map();
+    pushObserved = false;
+    constructor(maxDocuments, maxDiagnosticsPerDocument) {
+        this.maxDocuments = maxDocuments;
+        this.maxDiagnosticsPerDocument = maxDiagnosticsPerDocument;
+    }
+    capturePush(params, document, encoding) {
+        this.pushObserved = true;
+        if (!document)
+            return;
+        const snapshot = this.normalizeSnapshot(params.diagnostics, document, encoding, params.version === undefined ? {} : { publishedVersion: params.version });
+        this.setBounded(this.pushSnapshots, params.uri, snapshot);
+    }
+    capturePull(diagnostics, document, encoding, resultId) {
+        const snapshot = this.normalizeSnapshot(diagnostics, document, encoding, resultId === undefined ? {} : { resultId });
+        this.setBounded(this.pullSnapshots, document.uri, snapshot);
+    }
+    markPullUnchanged(document, resultId) {
+        const previous = this.pullSnapshots.get(document.uri);
+        if (!previous)
+            return false;
+        const snapshot = {
+            ...previous,
+            snapshotDocumentVersion: document.version,
+            resultId,
+        };
+        this.setBounded(this.pullSnapshots, document.uri, snapshot);
+        return true;
+    }
+    previousPullResultId(uri) {
+        return this.pullSnapshots.get(uri)?.resultId;
+    }
+    readPush(document, limit) {
+        return this.read(this.pushSnapshots, document, limit, true);
+    }
+    readPull(document, limit) {
+        return this.read(this.pullSnapshots, document, limit, false);
+    }
+    hasObservedPushDiagnostics() {
+        return this.pushObserved;
+    }
+    clear() {
+        this.pushSnapshots.clear();
+        this.pullSnapshots.clear();
+        this.pushObserved = false;
+    }
+    get size() {
+        return this.pushSnapshots.size + this.pullSnapshots.size;
+    }
+    normalizeSnapshot(diagnostics, document, encoding, metadata) {
+        return {
+            diagnostics: diagnostics
+                .slice(0, this.maxDiagnosticsPerDocument)
+                .map((diagnostic) => normalizeDiagnostic(diagnostic, document.text, encoding)),
+            total: diagnostics.length,
+            snapshotDocumentVersion: document.version,
+            ...metadata,
+        };
+    }
+    setBounded(snapshots, uri, snapshot) {
+        snapshots.delete(uri);
+        snapshots.set(uri, snapshot);
+        while (snapshots.size > this.maxDocuments) {
+            const oldestUri = snapshots.keys().next().value;
+            if (!oldestUri)
+                break;
+            snapshots.delete(oldestUri);
+        }
+    }
+    read(snapshots, document, limit, usePublishedVersion) {
+        const snapshot = snapshots.get(document.uri);
+        if (!snapshot) {
+            return {
+                diagnostics: [],
+                returned: 0,
+                truncated: false,
+                freshness: {
+                    state: "missing",
+                    documentVersion: document.version,
+                },
+            };
+        }
+        const diagnostics = snapshot.diagnostics.slice(0, limit);
+        const freshness = usePublishedVersion && snapshot.publishedVersion !== undefined
+            ? (snapshot.publishedVersion === document.version ? "fresh" : "stale")
+            : (snapshot.snapshotDocumentVersion === document.version ? "fresh" : "stale");
+        return {
+            diagnostics,
+            returned: diagnostics.length,
+            truncated: snapshot.total > diagnostics.length,
+            total: snapshot.total,
+            freshness: {
+                state: freshness,
+                documentVersion: document.version,
+                snapshotDocumentVersion: snapshot.snapshotDocumentVersion,
+                ...(snapshot.publishedVersion === undefined ? {} : { publishedVersion: snapshot.publishedVersion }),
+            },
+        };
+    }
+}

package/dist/lsp/runtime/manager.js

@@ -8,6 +8,8 @@ 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 MAX_DIAGNOSTIC_DOCUMENTS = 128;
+const MAX_DIAGNOSTICS_PER_DOCUMENT = 1000;
 export class CodeIntelligenceManager {
     config;
     services = new Map();
@@ -24,6 +26,8 @@ export class CodeIntelligenceManager {
             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"),
+            maxDiagnosticDocuments: positiveInteger(options.maxDiagnosticDocuments, MAX_DIAGNOSTIC_DOCUMENTS, "maxDiagnosticDocuments"),
+            maxDiagnosticsPerDocument: positiveInteger(options.maxDiagnosticsPerDocument, MAX_DIAGNOSTICS_PER_DOCUMENT, "maxDiagnosticsPerDocument"),
         };
         this.cleanupTimer = setInterval(() => {
             void this.closeIdle();
@@ -56,6 +60,12 @@ export class CodeIntelligenceManager {
                     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);
+                case "diagnostics":
+                    return await service.diagnostics(input);
             }
         }
         finally {

package/docs/configuration.md

@@ -154,16 +154,26 @@ 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.2 supports
-`definition`, `hover`, and `references`. Position-based operations accept the same
-workspace-relative source position. Hover results normalize plaintext, Markdown,
-and supported legacy LSP payloads into one `contents` string with optional
-`language` and normalized `range` metadata. References use the same normalized
-location shape as definition, default to 100 returned locations, and accept a
-`limit` from 1 through 1000; results report `returned`, `truncated`, and the real
-`total` when the complete Language-server response makes it known. Language Servers
-are external dependencies: ForgeRelay may discover an executable already installed
-on the machine, but it never downloads or installs one automatically.
+not add language-specific top-level MCP tools. ForgeRelay 0.4.4 supports
+`definition`, `hover`, `references`, `documentSymbols`, `workspaceSymbols`, and
+`diagnostics`.
+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. Diagnostics
+use `path` plus optional `limit`, prefer LSP pull diagnostics when the selected server
+advertises them, and otherwise consume the latest bounded `publishDiagnostics`
+snapshot. Push and pull use one normalized result shape with `provider`,
+`returned`/`truncated`/`total`, and freshness metadata tied to ForgeRelay's synchronized
+filesystem document version. 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.2",
+  "version": "0.4.4",
   "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/lsp/references.server.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspace-store.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "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/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.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

@@ -336,13 +336,19 @@ try {
   assert.ok(Array.isArray(codeIntelligenceSchema.oneOf));
   assert.deepEqual(
     codeIntelligenceSchema.oneOf.map((variant) => variant.properties.operation.const),
-    ["definition", "hover", "references"],
+    ["definition", "hover", "references", "documentSymbols", "workspaceSymbols", "diagnostics"],
   );
-  const referencesSchema = codeIntelligenceSchema.oneOf.find(
-    (variant) => variant.properties.operation.const === "references",
+  for (const operation of ["references", "documentSymbols", "workspaceSymbols", "diagnostics"]) {
+    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.equal(referencesSchema.properties.limit.minimum, 1);
-  assert.equal(referencesSchema.properties.limit.maximum, 1000);
+  assert.ok(workspaceSymbolsSchema.required.includes("query"));
   if (process.platform === "linux") {
     const describedArtifact = callTool(oauth.accessToken, sessionId, 82, "capability", {
       workspaceId,