@akira-tl/forgerelay 1.1.1 → 1.2.0-rc.1

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [1.2.0-rc.1] - 2026-09-13
+
+### Added
+
+- Added Config System v2 with generated v1 schemas, one definition/resolver model, explicit provenance, Project identity, machine-private Project Local configuration, and operator-facing `config check`, `config sources`, and `config explain` diagnostics.
+- Added explicit `forgerelay config migrate` with dry-run, backups, atomic writes, and ForgeRelay-owned legacy normalization for External MCP, Language Servers, Lifecycle Hooks, and Subagent Profiles.
+- Added packaged Config v2 product acceptance covering fresh setup, direct 1.1-style upgrade, explicit migration equivalence, reload/LKG, Project Local behavior, the project-execution trust seam, and isolated packaged server startup.
+
+### Changed
+
+- Unified precedence as `runtime > project-local > project > user > built-in`; External MCP, Language Servers, Hooks, and Subagent Profiles now use canonical Config v2 sources with content-fingerprint demand refresh, last-known-good fallback, and deletion semantics.
+- Rebuilt setup so basic `init` asks only required roots and connection mode, while `init --advanced` owns common advanced options. Runtime Shell Instructions remain opt-in, and `init --force` no longer acts as an implicit migration path.
+- Canonicalized Subagent Profile configuration under `subagents/`, kept ForgeRelay-owned Skills private to the ForgeRelay config directory, and routed legacy inputs through the same resolver instead of maintaining parallel old/new configuration architectures.
+- Added configured-versus-applied reporting for restart-required General Config and generation retirement for long-lived runtime resources whose effective configuration changes.
+
+### Compatibility
+
+- Existing ForgeRelay-owned legacy configuration remains directly readable with deprecation diagnostics in v1.2.x, receives stronger removal warnings in v1.3.x, and is scheduled for parser/path removal in v1.4.0. Startup never rewrites legacy files automatically.
+- Canonical configuration can coexist with legacy sources during migration; canonical same-scope sources shadow the corresponding legacy adapter so explicit migration preserves effective behavior.
+
+### Security
+
+- Separated allowed-root filesystem authority from Project Trust. Project Hooks, stdio External MCP, Project Language Servers, and Project Subagent Profiles now pass through one project-execution trust seam; v1.2.0 intentionally uses a compatibility-allow policy and does not claim a full interactive Project Trust approval UI.
+- Kept credentials outside the ordinary Config Resolver, limited environment interpolation to definition-approved fields, and kept resolved sensitive values out of normal provenance and diagnostic output.
+
+### Fixed
+
+- Made generated Config schema freshness checks line-ending independent so Windows CRLF checkouts do not falsely report generated schemas as stale while real schema drift still fails the gate.
+- Made Project-root regression and packaged-acceptance assertions use the same canonical realpath semantics as the runtime, covering macOS `/var` aliases and Windows short-path aliases such as `RUNNER~1` without changing Project identity behavior.
+- Hardened cross-process `auth.json` updates on Windows by retrying only transient atomic-replace failures while the existing file lock remains held, preserving concurrent remote-auth records without weakening serialization.
+- Updated optional LSP interoperability coverage to construct Code Intelligence through the Config v2 runtime seam, so installed servers such as `clangd` exercise the same resolver path as production.
+
+## [1.1.2] - 2026-09-11
+
+### Fixed
+
+- Clarified Capability discovery so Agents use only `open_workspace.capabilityCatalog` names with the `capability` gateway; semantic `capabilityFingerprint.capabilities` entries and Capability Guide descriptors are no longer presented as callable capability names.
+- Changed Agent Skill collision precedence so a Project's `.agents/skills` definition wins over the same-named global `~/.agents/skills` definition, keeping Project-local workflow customizations authoritative.
+
 ## [1.1.1] - 2026-09-10
 
 ### Added

package/README.md

@@ -59,8 +59,13 @@ http://127.0.0.1:7676/mcp
 
 ```bash
 forgerelay doctor
+forgerelay config check
+forgerelay config sources
+forgerelay config explain <logical-path>
 ```
 
+v1.2 的 Config System 统一解析 User、Project 和机器私有 Project Local 配置，统一优先级是 `runtime > project-local > project > user > built-in`。External MCP、Language Servers、Hooks 和 Subagent Profiles 支持按需热刷新与 last-known-good；需要重启的 General 配置会区分 configured / applied，不会自动重启 Server。Canonical JSON 可以引用 npm package 中的 `schemas/v1/*` `$schema`，受支持的敏感字段可用 `${ENV_NAME}`，诊断不会输出解析后的 secret。ForgeRelay 启动不会自动重写旧配置，需要迁移时使用 `forgerelay config migrate --dry-run ...` 先预览。
+
 ### ChatGPT 访问不到 localhost？
 
 如果 Host 运行在云端，需要给 ForgeRelay 一个公网 HTTPS 入口。Cloudflare Tunnel、ngrok、Tailscale Funnel 或普通反向代理都可以。
@@ -120,6 +125,8 @@ ForgeRelay 给 Agent 的是真实本机执行权限，不是模拟环境。
 
 文件工具受 Workspace 和 allowed roots 限制；Shell 命令使用启动 ForgeRelay 的本地用户权限执行，**Shell 不是 OS sandbox**。因此只连接你信任的 MCP Host，只开放确实需要的项目目录，并保护好 Owner password。
 
+Allowed roots 是文件系统 / Workspace authority，不等于 Project Trust approval。v1.2.0 已把项目中的可执行配置统一接入 Project execution trust seam，但首个稳定策略是 compatibility-allow；完整的交互式 Project Trust approval UI 不是 v1.2.0 已实现功能。
+
 ForgeRelay 默认拒绝 elevated / administrator 启动。只有你显式选择高权限运行时才会继续，并会提示系统级修改可能不可逆。
 
 完整边界见 [安全模型](https://github.com/Akira-TL/forgerelay/wiki/Security)。
@@ -173,8 +180,13 @@ To see the configuration and Command Shell Runtime ForgeRelay actually resolved:
 
 ```bash
 forgerelay doctor
+forgerelay config check
+forgerelay config sources
+forgerelay config explain <logical-path>
 ```
 
+Config System v2 in v1.2 resolves User, Project, and machine-private Project Local sources using `runtime > project-local > project > user > built-in`. External MCP, Language Servers, Hooks, and Subagent Profiles refresh on demand with last-known-good protection; restart-required General settings keep configured and applied values distinct and never auto-restart the server. Canonical JSON can point at the packaged `schemas/v1/*` `$schema` files, supported sensitive fields may use `${ENV_NAME}`, and diagnostics do not expose resolved secrets. Startup never rewrites legacy configuration automatically; preview an explicit migration with `forgerelay config migrate --dry-run ...` first.
+
 ### Host cannot reach localhost?
 
 Cloud-hosted MCP clients need a public HTTPS route to ForgeRelay. Cloudflare Tunnel, ngrok, Tailscale Funnel, or a normal reverse proxy all work.
@@ -234,6 +246,8 @@ ForgeRelay gives an Agent real local execution capability.
 
 Filesystem tools are constrained by the opened Workspace and configured allowed roots. Shell commands run with the authority of the local user running ForgeRelay; **the shell is not an OS sandbox**. Connect only MCP hosts you trust, expose only project roots you want an Agent to access, and keep the Owner password private.
 
+Allowed roots grant filesystem/Workspace authority; they are not a Project Trust approval. v1.2.0 routes executable project configuration through a shared Project execution trust seam, but its initial policy is compatibility-allow. A full interactive Project Trust approval UI is not claimed for v1.2.0.
+
 Elevated / administrator startup is rejected by default. It only proceeds after explicit opt-in, with a warning that system-level AI-driven changes may be irreversible.
 
 See the [Security model](https://github.com/Akira-TL/forgerelay/wiki/Security) for the full boundary.

package/dist/activity/runtime/mcp-query-tools.js

@@ -70,7 +70,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         },
     }, async ({ workspaceId }, extra) => {
         const requestContext = mcpHandlerRequestContext(extra);
-        const workspace = workspacePanelState?.(workspaceId);
+        const workspace = await workspacePanelState?.(workspaceId);
         if (!workspace) {
             throw new Error(`No Workspace presentation is available for ${workspaceId}. Call open_workspace for that workspace before activity_panel.`);
         }
@@ -82,7 +82,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
                 _meta: {
                     ...(relayed._meta ?? {}),
                     [ACTIVITY_PANEL_DEFAULT_EXPANDED_META_KEY]: panelDefaultExpanded,
-                    [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                    [ACTIVITY_PANEL_WORKSPACE_META_KEY]: mergeRelayedWorkspaceConfiguration(workspace, relayed),
                 },
             };
         }
@@ -124,7 +124,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         const conversationScopeId = hostConversationScopeId(requestContext, connectionScopeId);
         const relayed = await relay?.snapshot({ turnId, workspaceId, knownRevision }, conversationScopeId);
         if (relayed) {
-            const workspace = workspaceId ? workspacePanelState?.(workspaceId) : undefined;
+            const workspace = workspaceId ? await workspacePanelState?.(workspaceId) : undefined;
             if (workspaceId && !workspace) {
                 throw new Error(`No Workspace presentation is available for ${workspaceId}.`);
             }
@@ -134,7 +134,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
                     _meta: {
                         ...(relayed._meta ?? {}),
                         [ACTIVITY_PANEL_DEFAULT_EXPANDED_META_KEY]: panelDefaultExpanded,
-                        [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                        [ACTIVITY_PANEL_WORKSPACE_META_KEY]: mergeRelayedWorkspaceConfiguration(workspace, relayed),
                     },
                 }
                 : relayed;
@@ -155,7 +155,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
                 transportSessionIdPrefix: transportSessionIdPrefix(requestContext.transportSessionId),
             });
         }
-        const workspace = workspaceId ? workspacePanelState?.(workspaceId) : undefined;
+        const workspace = workspaceId ? await workspacePanelState?.(workspaceId) : undefined;
         if (workspaceId && !workspace) {
             throw new Error(`No Workspace presentation is available for ${workspaceId}.`);
         }
@@ -288,3 +288,13 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         };
     });
 }
+function mergeRelayedWorkspaceConfiguration(workspace, relayed) {
+    const meta = relayed._meta;
+    if (!meta || typeof meta !== "object")
+        return workspace;
+    const relayedWorkspace = meta[ACTIVITY_PANEL_WORKSPACE_META_KEY];
+    if (!relayedWorkspace || typeof relayedWorkspace !== "object" || Array.isArray(relayedWorkspace))
+        return workspace;
+    const configuration = relayedWorkspace.configuration;
+    return configuration === undefined ? workspace : { ...workspace, configuration };
+}

package/dist/cli/config/inspect.js

@@ -0,0 +1,331 @@
+import { join, resolve } from "node:path";
+import { forgerelayConfigDir } from "../../runtime/config/user-config.js";
+import { ExternalMcpConfigRegistry } from "../../runtime/config/external-mcp-registry.js";
+import { resolveGeneralConfig } from "../../runtime/config/resolution/general.js";
+import { resolveHooksConfig } from "../../runtime/config/resolution/hooks.js";
+import { resolveLanguageServersConfig } from "../../runtime/config/resolution/language-servers.js";
+import { readJsonConfigSource } from "../../runtime/config/resolution/project-sources.js";
+import { ConfigSourceRuntime } from "../../runtime/config/runtime/source-refresh.js";
+import { resolveSubagentProfilesConfigSources } from "../../subagents/profiles.js";
+import { ProjectContextResolver } from "../../workspaces/state/project-context.js";
+const OFFLINE_LIVE_STATE = {
+    mode: "offline",
+    lastKnownGood: "unknown",
+    appliedValues: "unknown",
+};
+export async function runConfigInspection(args) {
+    let options;
+    try {
+        options = parseInspectionArgs(args);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    let domains;
+    try {
+        domains = await resolveInspectionDomains(options);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    const diagnostics = domains.flatMap((domain) => [
+        ...domain.diagnostics.map((diagnostic) => inspectionDiagnostic(domain.domain, diagnostic)),
+        ...shadowDiagnostics(domain),
+    ]);
+    const summary = summarizeDiagnostics(diagnostics);
+    if (options.command === "explain") {
+        const match = findEntry(domains, options.logicalPath);
+        if (!match) {
+            console.error(`Unknown configuration logical path: ${options.logicalPath}.`);
+            return 2;
+        }
+        const relatedSourceIds = new Set([
+            match.entry.effective.source.id,
+            ...match.entry.shadowed.map((shadowed) => shadowed.source.id),
+        ]);
+        const relatedDiagnostics = diagnostics.filter((diagnostic) => diagnostic.logicalPath === options.logicalPath || relatedSourceIds.has(diagnostic.source.id));
+        const output = {
+            version: 1,
+            command: "explain",
+            scope: options.scope,
+            liveState: OFFLINE_LIVE_STATE,
+            logicalPath: options.logicalPath,
+            domain: match.domain.domain,
+            effective: match.entry.effective,
+            shadowed: match.entry.shadowed,
+            tombstone: match.entry.tombstone === true,
+            diagnostics: relatedDiagnostics,
+        };
+        if (options.json)
+            console.log(JSON.stringify(output, null, 2));
+        else
+            printExplain(output);
+        return relatedDiagnostics.some((diagnostic) => diagnostic.severity === "error") ? 1 : 0;
+    }
+    if (options.command === "sources") {
+        const output = {
+            version: 1,
+            command: "sources",
+            scope: options.scope,
+            liveState: OFFLINE_LIVE_STATE,
+            summary,
+            diagnostics,
+            sources: inspectSources(domains),
+        };
+        if (options.json)
+            console.log(JSON.stringify(output, null, 2));
+        else
+            printSources(output);
+        return summary.errors > 0 ? 1 : 0;
+    }
+    const output = {
+        version: 1,
+        command: "check",
+        scope: options.scope,
+        liveState: OFFLINE_LIVE_STATE,
+        summary,
+        diagnostics,
+    };
+    if (options.json)
+        console.log(JSON.stringify(output, null, 2));
+    else
+        printCheck(output);
+    return summary.errors > 0 ? 1 : 0;
+}
+function parseInspectionArgs(args) {
+    const [command, ...rest] = args;
+    if (command !== "check" && command !== "sources" && command !== "explain") {
+        throw new Error("Expected config check, config sources, or config explain <logical-path>.");
+    }
+    let json = false;
+    let global = false;
+    let projectRoot;
+    let logicalPath;
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === "--json") {
+            if (json)
+                throw new Error("--json may only be supplied once.");
+            json = true;
+            continue;
+        }
+        if (arg === "--global") {
+            if (global || projectRoot)
+                throw new Error("--global and --project cannot be used together or repeated.");
+            global = true;
+            continue;
+        }
+        if (arg === "--project") {
+            if (global || projectRoot)
+                throw new Error("--global and --project cannot be used together or repeated.");
+            const value = rest[index + 1];
+            if (!value || value.startsWith("--"))
+                throw new Error("--project requires a project path.");
+            projectRoot = resolve(value);
+            index += 1;
+            continue;
+        }
+        if (command === "explain" && logicalPath === undefined && !arg.startsWith("--")) {
+            logicalPath = arg;
+            continue;
+        }
+        throw new Error(`Unknown config ${command} option: ${arg}`);
+    }
+    if (command === "explain" && !logicalPath)
+        throw new Error("config explain requires a logical path.");
+    return {
+        command,
+        json,
+        scope: global
+            ? { mode: "global" }
+            : { mode: "project", projectRoot: projectRoot ?? resolve(process.env.FORGERELAY_WORKSPACE_ROOT ?? process.cwd()) },
+        ...(logicalPath ? { logicalPath } : {}),
+    };
+}
+async function resolveInspectionDomains(options) {
+    const configDir = forgerelayConfigDir();
+    const sourceRuntime = new ConfigSourceRuntime();
+    const userSource = await readJsonConfigSource({
+        id: "user:config",
+        scope: "user",
+        location: join(configDir, "config.json"),
+    });
+    const project = options.scope.mode === "project"
+        ? await new ProjectContextResolver(configDir).inspect(options.scope.projectRoot)
+        : undefined;
+    const projectSource = project
+        ? await readJsonConfigSource({
+            id: "project:config",
+            scope: "project",
+            location: join(project.sharedConfigDir, "config.json"),
+        })
+        : undefined;
+    const projectLocalSource = project?.localConfigDir
+        ? await readJsonConfigSource({
+            id: "project-local:config",
+            scope: "project-local",
+            location: join(project.localConfigDir, "config.json"),
+        })
+        : undefined;
+    const general = resolveGeneralConfig({
+        env: process.env,
+        ...(userSource ? { userSource } : {}),
+        ...(projectSource ? { projectSource } : {}),
+        ...(projectLocalSource ? { projectLocalSource } : {}),
+    });
+    const mcp = new ExternalMcpConfigRegistry({
+        configDir,
+        environment: process.env,
+        sourceRuntime,
+    }).resolveConfiguration({
+        ...(project ? { projectSharedConfigDir: project.sharedConfigDir } : {}),
+        ...(project?.localConfigDir ? { projectLocalConfigDir: project.localConfigDir } : {}),
+    });
+    const languageServers = await resolveLanguageServersConfig({
+        configDir,
+        environment: process.env,
+        sourceRuntime,
+        ...(project?.localConfigDir
+            ? { project: { sharedConfigDir: project.sharedConfigDir, localConfigDir: project.localConfigDir } }
+            : project
+                ? { projectSharedConfigDir: project.sharedConfigDir }
+                : {}),
+    });
+    const hooks = await resolveHooksConfig({
+        configDir,
+        sourceRuntime,
+        ...(project?.localConfigDir
+            ? { project: { sharedConfigDir: project.sharedConfigDir, localConfigDir: project.localConfigDir } }
+            : project
+                ? { projectSharedConfigDir: project.sharedConfigDir }
+                : {}),
+    });
+    const subagents = resolveSubagentProfilesConfigSources({
+        configDir,
+        sourceRuntime,
+        ...(project ? { projectSharedConfigDir: project.sharedConfigDir } : {}),
+        ...(project?.localConfigDir ? { projectLocalConfigDir: project.localConfigDir } : {}),
+    });
+    return [general, mcp, languageServers, hooks, subagents];
+}
+function shadowDiagnostics(domain) {
+    return Object.values(domain.entries).flatMap((entry) => entry.shadowed.map((shadowed) => ({
+        severity: shadowed.reason === "source-shadowed" ? "warning" : "info",
+        code: shadowed.reason === "source-shadowed" ? "source_shadowed" : "shadowed_value",
+        domain: domain.domain,
+        logicalPath: entry.logicalPath,
+        source: shadowed.source,
+        message: shadowed.reason === "source-shadowed"
+            ? `${entry.logicalPath} from ${shadowed.source.id} is suppressed by a canonical compatibility source.`
+            : `${entry.logicalPath} from ${shadowed.source.id} is shadowed by ${entry.effective.source.id} (${shadowed.reason}).`,
+    })));
+}
+function inspectionDiagnostic(domain, diagnostic) {
+    return {
+        severity: diagnostic.severity,
+        code: diagnostic.code,
+        domain,
+        ...(diagnostic.logicalPath ? { logicalPath: diagnostic.logicalPath } : {}),
+        source: diagnostic.source,
+        message: diagnostic.message,
+    };
+}
+function summarizeDiagnostics(diagnostics) {
+    return {
+        errors: diagnostics.filter((diagnostic) => diagnostic.severity === "error").length,
+        warnings: diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length,
+        info: diagnostics.filter((diagnostic) => diagnostic.severity === "info").length,
+    };
+}
+function findEntry(domains, logicalPath) {
+    for (const domain of domains) {
+        const entry = Object.values(domain.entries).find((candidate) => candidate.logicalPath === logicalPath);
+        if (entry)
+            return { domain, entry };
+    }
+    return undefined;
+}
+function inspectSources(domains) {
+    return domains.flatMap((domain) => {
+        const roles = new Map();
+        const roleSet = (id) => {
+            const existing = roles.get(id);
+            if (existing)
+                return existing;
+            const created = new Set();
+            roles.set(id, created);
+            return created;
+        };
+        for (const entry of Object.values(domain.entries)) {
+            roleSet(entry.effective.source.id).add("effective");
+            for (const shadowed of entry.shadowed)
+                roleSet(shadowed.source.id).add("shadowed");
+        }
+        for (const diagnostic of domain.diagnostics)
+            roleSet(diagnostic.source.id).add("diagnostic");
+        return domain.sources.flatMap((source) => {
+            const sourceRoles = roleSet(source.id);
+            if (source.id.startsWith("legacy:"))
+                sourceRoles.add("legacy");
+            if (source.kind === "environment" || source.kind === "cli")
+                sourceRoles.add("runtime");
+            if (source.kind === "built-in")
+                sourceRoles.add("built-in");
+            const meaningful = source.kind === "file" || sourceRoles.has("effective") || sourceRoles.has("shadowed") || sourceRoles.has("diagnostic");
+            if (!meaningful)
+                return [];
+            const invalid = domain.diagnostics.some((diagnostic) => diagnostic.source.id === source.id && diagnostic.severity === "error");
+            return [{
+                    domain: domain.domain,
+                    id: source.id,
+                    scope: source.scope,
+                    kind: source.kind,
+                    ...(source.location ? { location: source.location } : {}),
+                    priority: source.priority,
+                    state: invalid ? "invalid" : "valid",
+                    roles: [...sourceRoles].sort(),
+                }];
+        });
+    }).sort((left, right) => left.domain.localeCompare(right.domain) || left.id.localeCompare(right.id));
+}
+function printExplain(output) {
+    console.log(`Config explain ${output.logicalPath}`);
+    console.log(`Effective source: ${output.effective.source.id}`);
+    console.log(`Configured value: ${formatValue(output.effective.configuredValue)}`);
+    console.log(`Effective value: ${formatValue(output.effective.effectiveValue)}`);
+    console.log(`Reload: ${output.effective.reload}`);
+    console.log(`Execution effect: ${output.effective.executionEffect}`);
+    for (const shadowed of output.shadowed) {
+        console.log(`Shadowed: ${shadowed.source.id} (${shadowed.reason})`);
+    }
+    if (output.diagnostics.length > 0) {
+        console.log("Diagnostics:");
+        for (const diagnostic of output.diagnostics) {
+            const location = diagnostic.source.location ?? diagnostic.source.id;
+            console.log(`  ${diagnostic.severity.toUpperCase()} ${diagnostic.code} ${location}: ${diagnostic.message}`);
+        }
+    }
+    console.log("Live runtime state: unknown (offline inspection; in-memory last-known-good and running applied values are unavailable).");
+}
+function formatValue(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function printSources(output) {
+    console.log(`Config sources (${output.scope.mode})`);
+    for (const source of output.sources) {
+        console.log(`${source.domain} ${source.id} · ${source.state} · ${source.roles.join(", ")}` +
+            (source.location ? ` · ${source.location}` : ""));
+    }
+    console.log("Live runtime state: unknown (offline inspection; in-memory last-known-good and running applied values are unavailable).");
+}
+function printCheck(output) {
+    console.log(`Config check (${output.scope.mode})`);
+    for (const diagnostic of output.diagnostics) {
+        const location = diagnostic.source.location ?? diagnostic.source.id;
+        console.log(`${diagnostic.severity.toUpperCase()} ${diagnostic.domain} ${location}: ${diagnostic.message}`);
+    }
+    console.log(`Summary: ${output.summary.errors} error(s), ${output.summary.warnings} warning(s), ${output.summary.info} info`);
+    console.log("Live runtime state: unknown (offline inspection; in-memory last-known-good and running applied values are unavailable).");
+}