@akira-tl/forgerelay 0.3.6 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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
+
+- Added debug-only runtime resource telemetry for RSS/V8 heap, MCP transport count, running/completed process counts, cached workspaces, and review checkpoint state so long-running deployments can identify which resource class is growing.
+
+### Changed
+
+- Background `bash` completion state is now retained for at most five minutes, completed process handles are released immediately, completed notices are globally bounded, active processes have a global concurrency budget, and per-process retained output is smaller. High-output head/tail truncation no longer materializes whole strings as Unicode code-point arrays, sharply reducing transient heap growth and GC pressure.
+- Abandoned MCP transport sessions and in-memory review checkpoint states now have hard capacity limits. Review state is also released when its logical workspace closes, while persisted Git checkpoint refs remain available for reconstruction.
+- Workspace instruction discovery is now bounded and demand-driven: `open_workspace` scans only the workspace root and direct child directories, while deeper `AGENTS.md` / `CLAUDE.md` files are discovered along paths as the Agent first accesses them. Reads surface newly discovered instructions inline; mutation and shell calls stop before side effects and require a retry after newly discovered local instructions are applied.
+- Workspace/session activity timestamps now use a small in-process write-behind cache. Hot `lastUsedAt` touches are coalesced and flushed to SQLite in one transaction at most every five minutes, with an explicit final flush during normal shutdown; semantic create/close/status writes remain immediate.
+
+### Fixed
+
+- Expired, never-redeemed OAuth authorization codes are opportunistically evicted and cleared on provider shutdown instead of remaining in memory for the lifetime of the server.
+
 ## [0.3.6] - 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/capabilities/shell-processes/GUIDE.md

@@ -28,9 +28,9 @@ processId: <number>
 
 `action="run"` 与 `action="process"` 的参数不要混用。Process ownership 始终绑定原 `workspaceId`；未知或跨 workspace 的 `processId` 会被拒绝。
 
-等待超时不会隐式 kill process。若没有必要立即等待，可以继续其他工作；进程完成后，ForgeRelay 会把 completion notice 一次性附加到同一 logical workspace 的后续 tool result。
+等待超时不会隐式 kill process。若没有必要立即等待，可以继续其他工作；进程完成后，ForgeRelay 会把 completion notice 一次性附加到同一 logical workspace 的后续 tool result。未消费的 completed process notice 最多保留 5 分钟；进程退出时底层 ChildProcess/PTY handle 会立即释放。ForgeRelay 同时对 active process 与 completed notice 数量设置全局资源预算，达到 active process 上限时会拒绝启动新的命令，而不会擅自终止已有长任务。
 
-不要因为暂时没有输出就重复启动相同长进程；先用返回的 `processId` poll。
+不要因为暂时没有输出就重复启动相同长进程；先用返回的 `processId` poll。高输出命令会使用有界 head/tail buffer，不能把 ForgeRelay 当作无限历史日志存储。
 
 ## PTY / interactive commands
 

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

@@ -113,6 +113,8 @@ function formatPrettyMessage(entry, options) {
         case "mcp_transport_session_close_failed":
         case "mcp_session_close_failed":
             return `transport session ${transportSessionPrefix(entry) ?? "unknown"} close -> ${style("red", "error", options)}`;
+        case "runtime_resources":
+            return formatRuntimeResources(entry);
         case "auth_denied":
             return `auth denied${entry.reason ? `: ${String(entry.reason)}` : ""}`;
         case "mcp_request_error":
@@ -212,6 +214,20 @@ function stableColorIndex(value) {
     }
     return (hash >>> 0) % WORKSPACE_PROJECT_COLORS.length;
 }
+function formatRuntimeResources(entry) {
+    const rssMb = bytesToMegabytes(numberField(entry.rssBytes));
+    const heapUsedMb = bytesToMegabytes(numberField(entry.heapUsedBytes));
+    const heapTotalMb = bytesToMegabytes(numberField(entry.heapTotalBytes));
+    const transports = numberField(entry.mcpTransports) ?? 0;
+    const running = numberField(entry.processesRunning) ?? 0;
+    const completed = numberField(entry.processesCompleted) ?? 0;
+    const workspaces = numberField(entry.cachedWorkspaces) ?? 0;
+    const reviewStates = numberField(entry.reviewStates) ?? 0;
+    return `runtime rss=${rssMb}MB heap=${heapUsedMb}/${heapTotalMb}MB transports=${transports} processes=${running} running/${completed} completed workspaces=${workspaces} review=${reviewStates}`;
+}
+function bytesToMegabytes(value) {
+    return value === undefined ? 0 : Math.round(value / (1024 * 1024));
+}
 function formatGenericMessage(entry) {
     const event = String(entry.event ?? "log");
     const detail = [entry.reason, entry.error]

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";
+    }
+}