@akira-tl/forgerelay 0.4.2 → 0.4.3

package/CHANGELOG.md

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

package/capabilities/code-intelligence/GUIDE.md

@@ -4,10 +4,12 @@ Use the `code.intelligence` Capability for read-only semantic code navigation ba
 
 ForgeRelay does not install Language servers. It discovers supported executables when available and accepts explicit definitions from the global ForgeRelay config or `<workspace>/.forgerelay/language-servers.json`. Project definitions override global definitions, and global definitions override built-in discovery. An explicit definition may disable discovery with `enabled: false`.
 
-ForgeRelay 0.4.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.3 supports `definition`, `hover`, `references`, `documentSymbols`, and `workspaceSymbols`. Position-based operations accept a workspace-relative source `path` plus 1-based `line` and `column` values. `documentSymbols` needs only `path` and an optional bounded `limit`. `workspaceSymbols` uses `path` to select the Language project/service and accepts a `query` plus optional `limit`; it does not merge multiple nested Language services. Columns are Unicode code-point positions; ForgeRelay converts them to the position encoding negotiated with the Language server.
 
 Code-intelligence results use ForgeRelay-owned shapes rather than raw LSP wire types. Definition returns normalized locations. Hover returns one `contents` string, an optional legacy `language`, and an optional ForgeRelay-normalized `range`; plaintext, Markdown `MarkupContent`, and supported legacy `MarkedString` payloads are normalized before reaching the Agent. References uses the same normalized location shape, defaults to `limit: 100`, and accepts limits up to 1000. Its result reports `returned`, `truncated`, and `total` when the complete Language-server response makes the total known.
 
+Document symbols preserve hierarchical server responses as a tree and keep flat `SymbolInformation` responses flat. Names, stable symbol-kind names, ranges, selection ranges, details, container names, and children are normalized without exposing LSP union types. Workspace symbols are always returned as a flat list with stable symbol metadata and normalized locations. Symbol limits use the same default 100 / hard maximum 1000 collection budget; document-symbol limits count total tree nodes, while workspace-symbol results report the server response total directly when known.
+
 Semantic locations may identify External code locations outside the Workspace, but that does not expand ForgeRelay's allowed roots or grant the file tools permission to read those paths.
 
 Language-server definitions use structured process configuration rather than shell command strings. A project configuration entry may contain `command`, `args`, `env`, `languages`, `extensions`, `languageIdByExtension`, `projectMarkers`, and `enabled` fields. Use `languageIdByExtension` when one server definition covers multiple language IDs whose extensions do not map one-to-one by array position. The server command is launched directly without a shell.

package/dist/capability-registry.js

@@ -129,6 +129,17 @@ 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(),
     ]);
     return new CapabilityRegistry([
         {

package/dist/lsp/code-intelligence.js

@@ -3,12 +3,13 @@ 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, DocumentSymbolRequest, DidChangeTextDocumentNotification, DidCloseTextDocumentNotification, DidOpenTextDocumentNotification, ExitNotification, HoverRequest, InitializeRequest, ReferencesRequest, InitializedNotification, MarkupKind, PositionEncodingKind, ShutdownRequest, TextDocumentSyncKind, WorkspaceSymbolRequest, } from "vscode-languageserver-protocol";
 import { LanguageServerConfigurationError, } from "./language-server-config.js";
 import { terminateProcessTree } from "../process-platform.js";
 import { CodeIntelligenceError } from "./code-intelligence-error.js";
 import { DEFAULT_CODE_INTELLIGENCE_RESULT_LIMIT } from "./code-intelligence-types.js";
 import { normalizeHoverContents } from "./normalization/hover.js";
+import { normalizeDocumentSymbols, normalizeWorkspaceSymbols, } from "./normalization/symbols.js";
 import { isWithin, locationEntries, normalizeLocations, workspaceDisplayPath, } from "./normalization/locations.js";
 import { lspPositionFromUser, rangeFromLsp, wholeDocumentRange } from "./position-encoding.js";
 export { CodeIntelligenceError } from "./code-intelligence-error.js";
@@ -147,6 +148,54 @@ 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 shutdown() {
         if (this.closed)
             return;
@@ -251,6 +300,9 @@ export class LanguageService {
                 workspace: {
                     workspaceFolders: true,
                     configuration: true,
+                    symbol: {
+                        dynamicRegistration: false,
+                    },
                 },
                 textDocument: {
                     synchronization: {
@@ -268,6 +320,10 @@ export class LanguageService {
                     references: {
                         dynamicRegistration: false,
                     },
+                    documentSymbol: {
+                        dynamicRegistration: false,
+                        hierarchicalDocumentSymbolSupport: true,
+                    },
                 },
             },
         };

package/dist/lsp/normalization/symbols.js

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

package/dist/lsp/runtime/manager.js

@@ -56,6 +56,10 @@ 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);
             }
         }
         finally {

package/docs/configuration.md

@@ -154,16 +154,21 @@ force a Host to invalidate its cached schema.
 ### LSP code intelligence
 
 ForgeRelay advertises `code.intelligence` through the Capability Gateway; it does
-not add language-specific top-level MCP tools. ForgeRelay 0.4.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.3 supports
+`definition`, `hover`, `references`, `documentSymbols`, and `workspaceSymbols`.
+Position-based operations accept the same workspace-relative source position. Hover
+results normalize plaintext, Markdown, and supported legacy LSP payloads into one
+`contents` string with optional `language` and normalized `range` metadata.
+References use the same normalized location shape as definition, default to 100
+returned locations, and accept a `limit` from 1 through 1000. Document symbols use
+`path` plus optional `limit`, preserve server hierarchy when present, and keep flat
+legacy symbol responses flat. Workspace symbols use `path` to select the Language
+project/service, then apply a `query` with an optional bounded `limit`; ForgeRelay
+does not silently merge results from multiple nested Language services. Bounded
+collection results report `returned`, `truncated`, and the real `total` when the
+complete Language-server response makes it known. Language Servers are external
+dependencies: ForgeRelay may discover an executable already installed on the
+machine, but it never downloads or installs one automatically.
 
 Effective Language-server definitions resolve in this order:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -42,7 +42,7 @@
     "debug:accept": "node scripts/debug/accept.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/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/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"],
   );
-  const referencesSchema = codeIntelligenceSchema.oneOf.find(
-    (variant) => variant.properties.operation.const === "references",
+  for (const operation of ["references", "documentSymbols", "workspaceSymbols"]) {
+    const boundedSchema = codeIntelligenceSchema.oneOf.find(
+      (variant) => variant.properties.operation.const === operation,
+    );
+    assert.equal(boundedSchema.properties.limit.minimum, 1);
+    assert.equal(boundedSchema.properties.limit.maximum, 1000);
+  }
+  const workspaceSymbolsSchema = codeIntelligenceSchema.oneOf.find(
+    (variant) => variant.properties.operation.const === "workspaceSymbols",
   );
-  assert.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,