evolcore 0.0.1 → 0.0.3

package/dist/config/config-manager.js

@@ -0,0 +1,1120 @@
+/**
+ * ConfigManager —— 所有配置文件读写/合并的统一归口（全项目唯一合并实现点）。
+ *
+ * 不允许散落的 fs.readFileSync 直接操作配置文件。
+ *
+ * v3 设计（2026-06-19）：
+ * - 覆盖链：defaults.json → agent/config.json → relation/config.json
+ * - 所有参数统一在 config.json，不再有 behavior.json
+ * - 进程级 daemon.json：独立，不参与覆盖链
+ *
+ * 详见 docs/config/01-overview.md
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolvePaths, agentConfig as agentConfigPath, agentContactConfig, agentRelationConfig, agentDir, agentRelationsDir, agentRolesIndex, agentRoleConfig, } from '../paths.js';
+import { atomicReadJson, atomicWriteJson } from '../utils/atomic-write.js';
+import { fileCache } from '../core/daemon-file-cache.js';
+import { isValidAid } from '../aun/aid/validation.js';
+import { isExplicitGroupId } from '../aun/group-identity.js';
+import { parseContactAlias } from './contact-alias.js';
+import { loadSchema, currentVersion, isSchemaName, } from './schema-registry.js';
+import { mergeLayers, expandVars, buildEnvResolver } from './merge.js';
+import { normalizeAgentLifecycle } from './lifecycle.js';
+import { isBehaviorConfigFieldPath } from './config-field-policy.js';
+import { clearRoleStoreCache, isRoleName } from './role-store.js';
+import { writeRoleDefinition, writeRoleRegistry } from './role-service.js';
+import { DAEMON_SCHEMA_NAME } from '../product.js';
+export var ConfigTarget;
+(function (ConfigTarget) {
+    ConfigTarget["Process"] = "process";
+    ConfigTarget["Defaults"] = "defaults";
+    ConfigTarget["Agent"] = "agent";
+    ConfigTarget["Relation"] = "relation";
+    ConfigTarget["Contact"] = "contact";
+    ConfigTarget["RoleRegistry"] = "role-registry";
+    ConfigTarget["Role"] = "role";
+})(ConfigTarget || (ConfigTarget = {}));
+const configWriteListeners = new Set();
+/** Observe successful in-process config writes after cache invalidation. */
+export function onConfigWrite(listener) {
+    configWriteListeners.add(listener);
+    return () => configWriteListeners.delete(listener);
+}
+const TARGET_SCHEMA = {
+    [ConfigTarget.Process]: DAEMON_SCHEMA_NAME,
+    [ConfigTarget.Defaults]: 'defaults',
+    [ConfigTarget.Agent]: 'agent-config',
+    [ConfigTarget.Relation]: 'relation-config',
+    [ConfigTarget.Contact]: 'contact-book',
+    [ConfigTarget.RoleRegistry]: 'role-registry',
+    [ConfigTarget.Role]: 'role-config',
+};
+export class ConfigError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'ConfigError';
+    }
+}
+let _initialized = false;
+/** ConfigManager 初始化（预留扩展点）。幂等。 */
+export function initConfigManager() {
+    if (_initialized)
+        return;
+    // 初始化逻辑（如需要）
+    _initialized = true;
+}
+/**
+ * Daemon startup gate for the one-off role config v4 migration.
+ * This intentionally does not mutate files or provide runtime compatibility.
+ */
+export function assertRoleConfigV4Ready() {
+    const root = resolvePaths().root;
+    const agentsRoot = resolvePaths().agentsDir;
+    if (!fs.existsSync(agentsRoot))
+        return;
+    const issues = [];
+    const inspect = (file, logicalName, minimumVersion) => {
+        let value;
+        try {
+            value = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch (error) {
+            issues.push({ file, detail: `invalid JSON: ${error instanceof Error ? error.message : String(error)}` });
+            return;
+        }
+        const actualVersion = value && typeof value === 'object'
+            ? value.$schema_version
+            : undefined;
+        if (typeof actualVersion !== 'number' || actualVersion < minimumVersion) {
+            issues.push({
+                file,
+                detail: `$schema_version must be at least ${minimumVersion}, got ${String(actualVersion)}`,
+            });
+            return;
+        }
+        let schema;
+        try {
+            schema = loadSchema(logicalName, actualVersion);
+        }
+        catch {
+            issues.push({ file, detail: `unsupported ${logicalName} schema version ${actualVersion}` });
+            return;
+        }
+        if (!schema.validate(value)) {
+            const detail = (schema.validate.errors ?? []).map(error => {
+                const extra = typeof error.params?.additionalProperty === 'string'
+                    ? ` (additionalProperty=${error.params.additionalProperty})`
+                    : '';
+                return `${error.instancePath || '/'} ${error.message}${extra}`;
+            }).join('; ');
+            issues.push({ file, detail });
+        }
+    };
+    const walkRelationConfigs = (dir) => {
+        if (!fs.existsSync(dir))
+            return [];
+        const files = [];
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                files.push(...walkRelationConfigs(full));
+            else if (entry.isFile() && entry.name === 'config.json')
+                files.push(full);
+        }
+        return files;
+    };
+    for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !isValidAid(entry.name))
+            continue;
+        const agentDirPath = path.join(agentsRoot, entry.name);
+        const agentFile = path.join(agentDirPath, 'config.json');
+        if (fs.existsSync(agentFile)) {
+            inspect(agentFile, 'agent-config', 4);
+        }
+        for (const relationFile of walkRelationConfigs(path.join(agentDirPath, 'relations'))) {
+            inspect(relationFile, 'relation-config', 4);
+        }
+    }
+    if (!issues.length)
+        return;
+    const shown = issues.slice(0, 20)
+        .map(issue => `- ${path.relative(root, issue.file)}: ${issue.detail}`)
+        .join('\n');
+    const omitted = issues.length > 20 ? `\n- ... ${issues.length - 20} more issue(s)` : '';
+    const quotedRoot = JSON.stringify(root);
+    throw new ConfigError('ROLE_CONFIG_MIGRATION_REQUIRED', `Role config v4 migration is required before daemon startup:\n${shown}${omitted}\n` +
+        `Stop the daemon, then run dry-run and review it:\n` +
+        `node kits/migrations/migrate-role-config-v4.mjs --home ${quotedRoot}\n` +
+        `Apply only after review:\n` +
+        `node kits/migrations/migrate-role-config-v4.mjs --apply --home ${quotedRoot}`, { issues });
+}
+/** Validate the standalone role domain after the v4 -> v5 migration. */
+export function assertRoleConfigV5Ready() {
+    const root = resolvePaths().root;
+    const agentsRoot = resolvePaths().agentsDir;
+    if (!fs.existsSync(agentsRoot))
+        return;
+    const issues = [];
+    const registrySchema = loadSchema('role-registry');
+    const readJson = (file) => {
+        try {
+            return JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch (error) {
+            issues.push({ file, detail: `invalid JSON: ${error instanceof Error ? error.message : String(error)}` });
+            return null;
+        }
+    };
+    const schemaErrors = (schema) => (schema.validate.errors ?? [])
+        .map(error => `${error.instancePath || '/'} ${error.message}`).join('; ');
+    for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !isValidAid(entry.name))
+            continue;
+        const aid = entry.name;
+        const agentFile = path.join(agentsRoot, aid, 'config.json');
+        if (!fs.existsSync(agentFile))
+            continue;
+        const agent = readJson(agentFile);
+        const agentVersion = agent?.$schema_version;
+        let agentSchema = null;
+        if (typeof agentVersion === 'number' && agentVersion >= 5) {
+            try {
+                agentSchema = loadSchema('agent-config', agentVersion);
+            }
+            catch { }
+        }
+        if (!agent || !agentSchema || !agentSchema.validate(agent)) {
+            if (agent)
+                issues.push({
+                    file: agentFile,
+                    detail: agentSchema
+                        ? schemaErrors(agentSchema)
+                        : `agent schema version must be supported and >= 5, got ${String(agentVersion)}`,
+                });
+            continue;
+        }
+        const registryFile = agentRolesIndex(aid);
+        if (!fs.existsSync(registryFile)) {
+            issues.push({ file: registryFile, detail: 'roles/index.json is required for Agent config v5' });
+            continue;
+        }
+        const registry = readJson(registryFile);
+        if (!registry || !registrySchema.validate(registry)) {
+            if (registry)
+                issues.push({ file: registryFile, detail: schemaErrors(registrySchema) });
+            continue;
+        }
+    }
+    if (!issues.length)
+        return;
+    const shown = issues.slice(0, 20).map(issue => `- ${path.relative(root, issue.file)}: ${issue.detail}`).join('\n');
+    throw new ConfigError('ROLE_CONFIG_V5_MIGRATION_REQUIRED', `Standalone role config migration is required before daemon startup:\n${shown}\n` +
+        `node kits/migrations/migrate-role-config-v5.mjs --home ${JSON.stringify(root)}\n` +
+        `node kits/migrations/migrate-role-config-v5.mjs --apply --home ${JSON.stringify(root)}`, { issues });
+}
+/** Final startup gate for the contact-book authorization migration. */
+export function assertContactBookV2Ready() {
+    const root = resolvePaths().root;
+    const agentsRoot = resolvePaths().agentsDir;
+    if (!fs.existsSync(agentsRoot))
+        return;
+    const issues = [];
+    const agentSchema = loadSchema('agent-config', 6);
+    const contactSchema = loadSchema('contact-book', 2);
+    const relationSchema = loadSchema('relation-config', 5);
+    const inspect = (file, schema) => {
+        let value;
+        try {
+            value = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch (error) {
+            issues.push({ file, detail: `invalid JSON: ${error instanceof Error ? error.message : String(error)}` });
+            return;
+        }
+        if (!schema.validate(value)) {
+            const detail = (schema.validate.errors ?? [])
+                .map(error => `${error.instancePath || '/'} ${error.message}`)
+                .join('; ');
+            issues.push({ file, detail });
+        }
+    };
+    const walkRelationConfigs = (dir) => {
+        if (!fs.existsSync(dir))
+            return [];
+        const files = [];
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                files.push(...walkRelationConfigs(full));
+            else if (entry.isFile() && entry.name === 'config.json')
+                files.push(full);
+        }
+        return files;
+    };
+    for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !isValidAid(entry.name))
+            continue;
+        const dir = path.join(agentsRoot, entry.name);
+        const agentFile = path.join(dir, 'config.json');
+        if (!fs.existsSync(agentFile))
+            continue;
+        inspect(agentFile, agentSchema);
+        const contactFile = path.join(dir, 'contact.json');
+        if (fs.existsSync(contactFile)) {
+            inspect(contactFile, contactSchema);
+            inspectContactBookDomain(contactFile, agentFile, issues);
+        }
+        for (const relationFile of walkRelationConfigs(path.join(dir, 'relations'))) {
+            inspect(relationFile, relationSchema);
+        }
+    }
+    const correctionReceipt = path.join(root, 'data', 'contact-book-v2-relation-role-authority.json');
+    if (!hasContactRoleAuthorityReceipt(correctionReceipt)) {
+        const recoverable = findRelationRoleRemovedByExperimentalMigration(root);
+        if (recoverable) {
+            issues.push({
+                file: recoverable,
+                detail: 'experimental contact-book migration backup must be reviewed and relation role authority correction recorded',
+            });
+        }
+    }
+    if (!issues.length)
+        return;
+    const shown = issues.slice(0, 20)
+        .map(issue => `- ${path.relative(root, issue.file)}: ${issue.detail}`)
+        .join('\n');
+    const omitted = issues.length > 20 ? `\n- ... ${issues.length - 20} more issue(s)` : '';
+    throw new ConfigError('CONTACT_BOOK_V2_MIGRATION_REQUIRED', `Contact book authorization migration is required before daemon startup:\n${shown}${omitted}\n` +
+        `node kits/migrations/migrate-contact-book-v2.mjs --home ${JSON.stringify(root)}\n` +
+        `node kits/migrations/migrate-contact-book-v2.mjs --apply --home ${JSON.stringify(root)}`, { issues });
+}
+function inspectContactBookDomain(contactFile, agentFile, issues) {
+    let contact;
+    let agent;
+    try {
+        contact = JSON.parse(fs.readFileSync(contactFile, 'utf8'));
+        agent = JSON.parse(fs.readFileSync(agentFile, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    const owners = new Set(Array.isArray(agent?.owners) ? agent.owners.map(String) : []);
+    const configuredChannelKeys = new Set((Array.isArray(agent?.channels) ? agent.channels : [])
+        .filter((channel) => channel && typeof channel === 'object' && channel.type !== 'aun')
+        .map((channel) => {
+        const type = String(channel.type || '').trim().toLowerCase();
+        const name = String(channel.name || '').trim();
+        return type && name ? `${type}#${String(agent?.aid || '').trim()}#${name}` : '';
+    })
+        .filter(Boolean));
+    const aliases = new Map();
+    for (const [primaryId, entry] of Object.entries(contact?.contacts ?? {})) {
+        if (isExplicitGroupId(primaryId)) {
+            issues.push({ file: contactFile, detail: `group contact ${primaryId} is not supported` });
+        }
+        if (entry?.status === 'blocked' && owners.has(primaryId)) {
+            issues.push({ file: contactFile, detail: `owner contact ${primaryId} cannot be blocked` });
+        }
+        for (const alias of Array.isArray(entry?.aliases) ? entry.aliases : []) {
+            const parsed = parseContactAlias(alias, agent?.aid);
+            if (!parsed) {
+                issues.push({ file: contactFile, detail: `invalid Contact alias ${String(alias)}; expected <channelKey>:<urlEncode(peerId)>` });
+                continue;
+            }
+            if (!configuredChannelKeys.has(parsed.channelKey)) {
+                issues.push({ file: contactFile, detail: `alias ${alias} references an unconfigured channel instance` });
+                continue;
+            }
+            const previous = aliases.get(parsed.alias);
+            if (previous && previous !== primaryId) {
+                issues.push({ file: contactFile, detail: `alias ${parsed.alias} is assigned to both ${previous} and ${primaryId}` });
+            }
+            else {
+                aliases.set(parsed.alias, primaryId);
+            }
+        }
+    }
+}
+function hasContactRoleAuthorityReceipt(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return value?.migration === 'contact-book-v2-relation-role-authority' && value?.designVersion === 2;
+    }
+    catch {
+        return false;
+    }
+}
+function findRelationRoleRemovedByExperimentalMigration(root) {
+    const backupsRoot = path.join(root, 'backups', 'contact-book-v2-migration');
+    if (!fs.existsSync(backupsRoot))
+        return null;
+    for (const stamp of fs.readdirSync(backupsRoot, { withFileTypes: true })) {
+        if (!stamp.isDirectory())
+            continue;
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(backupsRoot, stamp.name, 'manifest.json'), 'utf8'));
+            if (manifest?.designVersion >= 2)
+                continue;
+        }
+        catch { }
+        const agentsRoot = path.join(backupsRoot, stamp.name, 'files', 'agents');
+        if (!fs.existsSync(agentsRoot))
+            continue;
+        for (const agent of fs.readdirSync(agentsRoot, { withFileTypes: true })) {
+            if (!agent.isDirectory() || !isValidAid(agent.name))
+                continue;
+            const relationsRoot = path.join(agentsRoot, agent.name, 'relations');
+            if (!fs.existsSync(relationsRoot))
+                continue;
+            for (const relation of fs.readdirSync(relationsRoot, { withFileTypes: true })) {
+                if (!relation.isDirectory() || relation.name.startsWith('_'))
+                    continue;
+                const backupFile = path.join(relationsRoot, relation.name, 'config.json');
+                if (!fs.existsSync(backupFile))
+                    continue;
+                let backupValue;
+                try {
+                    backupValue = JSON.parse(fs.readFileSync(backupFile, 'utf8'));
+                }
+                catch {
+                    continue;
+                }
+                if (typeof backupValue?.role !== 'string' || backupValue.role === 'owner')
+                    continue;
+                const currentFile = path.join(root, 'agents', agent.name, 'relations', relation.name, 'config.json');
+                let currentValue;
+                try {
+                    currentValue = JSON.parse(fs.readFileSync(currentFile, 'utf8'));
+                }
+                catch {
+                    continue;
+                }
+                if (currentValue?.$schema_version === 5) {
+                    return currentFile;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * 启动时检查 schema 版本（daemon 启动时调用）。
+ * 扫描所有配置文件，如有版本不匹配则警告一次。
+ */
+export function checkSchemaVersionsOnStartup(selfAid) {
+    schemaVersionWarningsEnabled = true;
+    const p = resolvePaths();
+    // 检查 process 层
+    try {
+        read(ConfigTarget.Process);
+    }
+    catch { }
+    // 检查 defaults 层
+    try {
+        read(ConfigTarget.Defaults);
+    }
+    catch { }
+    // 检查 agent 层（如果提供了 AID）
+    if (selfAid) {
+        try {
+            read(ConfigTarget.Agent, { self: selfAid });
+        }
+        catch { }
+    }
+    schemaVersionWarningsEnabled = false;
+}
+// Schema 版本警告控制：只在启动时检查一次
+let schemaVersionWarningsEnabled = false;
+function configWarn(...args) {
+    console.warn(...args);
+}
+// ── 路径解析 ──────────────────────────────────────────────────────────────
+function targetPath(target, sel) {
+    const p = resolvePaths();
+    switch (target) {
+        case ConfigTarget.Process: return p.daemonConfig;
+        case ConfigTarget.Defaults: return p.defaultsConfig;
+        case ConfigTarget.Agent:
+            requireSelf(sel, target);
+            return agentConfigPath(sel.self);
+        case ConfigTarget.Relation:
+            requirePeer(sel, target);
+            return agentRelationConfig(sel.self, sel.peerKey);
+        case ConfigTarget.Contact:
+            requireSelf(sel, target);
+            return agentContactConfig(sel.self);
+        case ConfigTarget.RoleRegistry:
+            requireSelf(sel, target);
+            return agentRolesIndex(sel.self);
+        case ConfigTarget.Role:
+            requireSelf(sel, target);
+            if (!isRoleName(sel?.roleId))
+                throw new ConfigError('ROLE_REQUIRED', 'role 需要合法的 selector.roleId');
+            return agentRoleConfig(sel.self, sel.roleId);
+    }
+}
+function requireSelf(sel, target) {
+    if (!sel?.self)
+        throw new ConfigError('SELF_REQUIRED', `${target} 需要 selector.self`);
+}
+function requirePeer(sel, target) {
+    if (!sel?.self || !sel?.peerKey)
+        throw new ConfigError('PEER_REQUIRED', `${target} 需要 selector.self + peerKey`);
+}
+// ── env 作用域 ────────────────────────────────────────────────────────────
+function envScopeFor(sel) {
+    const root = resolvePaths().root;
+    const scope = { rootDir: root };
+    if (sel?.self)
+        scope.agentDir = agentDir(sel.self);
+    if (sel?.self && sel?.peerKey)
+        scope.relationDir = path.join(agentRelationsDir(sel.self), sel.peerKey);
+    return scope;
+}
+/** 读单个配置文件，返回强类型对象；不存在返回 null（不自动创建）。未知字段保留但不校验。 */
+export function read(target, sel, opts = {}) {
+    const file = targetPath(target, sel);
+    let raw;
+    if (opts.cache) {
+        raw = fileCache.get(file, () => atomicReadJson(file), { policy: 'mtime', group: groupFor(target, sel) });
+    }
+    else {
+        raw = atomicReadJson(file);
+    }
+    if (raw === null)
+        return null;
+    // schema 版本迁移（read 时若 $schema_version < current）
+    const migrated = migrateIfNeeded(target, raw, file);
+    const normalized = target === ConfigTarget.Agent
+        ? normalizeAgentConfigForRead(migrated, sel?.self)
+        : target === ConfigTarget.Relation
+            ? foldLegacyProactiveBlock(migrated)
+            : migrated;
+    if (!opts.expand)
+        return normalized;
+    const resolver = buildEnvResolver(envScopeFor(sel));
+    return expandVars(normalized, resolver);
+}
+function normalizeAgentConfigForRead(value, aid) {
+    const config = foldLegacyProactiveBlock(normalizeAgentLifecycle(value));
+    const mutable = config;
+    normalizeShowActivitiesCompat(mutable);
+    // AID 校验（如果提供了 aid）
+    if (aid && mutable.aid && mutable.aid !== aid) {
+        const filePath = targetPath(ConfigTarget.Agent, { self: aid });
+        throw new ConfigError('VALIDATION_ERROR', `${filePath}: aid field "${mutable.aid}" != directory name "${aid}"`);
+    }
+    // Legacy configs used top-level "agents" for baseagent settings.
+    // Keep read compatibility, but never write the obsolete field back.
+    if (mutable.agents && typeof mutable.agents === 'object' && !Array.isArray(mutable.agents)) {
+        mutable.baseagents = mutable.baseagents && typeof mutable.baseagents === 'object' && !Array.isArray(mutable.baseagents)
+            ? { ...mutable.agents, ...mutable.baseagents }
+            : mutable.agents;
+        delete mutable.agents;
+    }
+    // 清理 projects.defaultPath 尾部斜杠
+    if (mutable.projects?.defaultPath && typeof mutable.projects.defaultPath === 'string') {
+        mutable.projects.defaultPath = mutable.projects.defaultPath.replace(/[/\\]+$/, '');
+    }
+    return config;
+}
+function groupFor(target, sel) {
+    if (sel?.self && target === ConfigTarget.Agent) {
+        return `config:${sel.self}`;
+    }
+    if (target === ConfigTarget.Relation) {
+        return 'relation-prefs';
+    }
+    if (sel?.self && target === ConfigTarget.Contact) {
+        return `contact:${sel.self}`;
+    }
+    if (sel?.self && (target === ConfigTarget.RoleRegistry || target === ConfigTarget.Role)) {
+        return `role:${sel.self}`;
+    }
+    return 'config';
+}
+function normalizeAgentConfigForWrite(value) {
+    const mutable = { ...value };
+    normalizeShowActivitiesCompat(mutable);
+    // AID 格式校验
+    if (mutable.aid && !isValidAid(mutable.aid)) {
+        throw new ConfigError('VALIDATION_ERROR', `Invalid aid "${mutable.aid}" (must be a valid multi-level domain like mybot.agentid.pub)`);
+    }
+    // 规范化 projects 字段：只保留 rootPath 和 defaultPath
+    if (mutable.projects && typeof mutable.projects === 'object') {
+        const projects = mutable.projects;
+        const normalized = {};
+        if (typeof projects.rootPath === 'string')
+            normalized.rootPath = projects.rootPath;
+        if (typeof projects.defaultPath === 'string')
+            normalized.defaultPath = projects.defaultPath;
+        if (Object.keys(normalized).length > 0) {
+            mutable.projects = normalized;
+        }
+        else {
+            delete mutable.projects;
+        }
+    }
+    return mutable;
+}
+function normalizeRelationConfigForWrite(value) {
+    const mutable = { ...value };
+    normalizeShowActivitiesCompat(mutable);
+    return mutable;
+}
+function normalizeShowActivitiesCompat(value) {
+    if (value.show_activities === true)
+        value.show_activities = 'all';
+    else if (value.show_activities === false)
+        value.show_activities = 'none';
+}
+/**
+ * 迁移：旧的顶层 `proactive` 块 → `responseModeParams['single-session']`。
+ *
+ * single-session 合并后，proactive 首工具表态/工具汇报开关是该模式的特有参数，
+ * 运行时只从 responseModeParams['single-session'] 读（见 coordinator.resolveMode）。
+ * 存量配置里这两个键落在废弃的顶层 proactive 块，若不迁移会静默失效。
+ *
+ * 读时就地折叠：把 proactive 的两个已知键搬进模式桶（桶内已显式设置的同名键不覆盖），
+ * 删除 proactive 块。随后任何 write 都会持久化迁移后的形态，磁盘上的旧块随之消失。
+ * 逐文件（层）迁移，跨层合并交给 mergeLayers（responseModeParams 按模式 id dict 合并）。
+ */
+function foldLegacyProactiveBlock(value) {
+    const block = value.proactive;
+    if (!block || typeof block !== 'object' || Array.isArray(block))
+        return value;
+    const migrated = {};
+    if (typeof block.pre_tool_1stmsgchk === 'boolean')
+        migrated.pre_tool_1stmsgchk = block.pre_tool_1stmsgchk;
+    if (typeof block.tool_use_reminder === 'boolean')
+        migrated.tool_use_reminder = block.tool_use_reminder;
+    const mutable = { ...value };
+    delete mutable.proactive;
+    if (Object.keys(migrated).length === 0)
+        return mutable;
+    const params = (mutable.responseModeParams && typeof mutable.responseModeParams === 'object' && !Array.isArray(mutable.responseModeParams))
+        ? { ...mutable.responseModeParams }
+        : {};
+    const bucket = (params['single-session'] && typeof params['single-session'] === 'object' && !Array.isArray(params['single-session']))
+        ? { ...params['single-session'] }
+        : {};
+    // 桶内已显式设置的同名键优先，迁移值只补空缺
+    params['single-session'] = { ...migrated, ...bucket };
+    mutable.responseModeParams = params;
+    return mutable;
+}
+/** Write config with schema validation and atomic persistence. */
+export function write(target, value, sel, opts = {}) {
+    const file = targetPath(target, sel);
+    if (target === ConfigTarget.RoleRegistry) {
+        writeRoleRegistry(sel.self, value);
+        finishConfigWrite(target, sel, file);
+        return;
+    }
+    if (target === ConfigTarget.Role) {
+        writeRoleDefinition(sel.self, sel.roleId, value);
+        finishConfigWrite(target, sel, file);
+        return;
+    }
+    const schema = loadSchema(TARGET_SCHEMA[target]);
+    const withVer = ensureSchemaVersion(value, schema.version);
+    const migrated = withVer;
+    // Agent config 写入规范化（aid 校验、projects 字段清理）
+    const normalized = target === ConfigTarget.Agent
+        ? normalizeAgentConfigForWrite(migrated)
+        : target === ConfigTarget.Relation
+            ? normalizeRelationConfigForWrite(migrated)
+            : migrated;
+    // 1. Schema 校验
+    if (!opts.skipValidate) {
+        validateOrThrow(schema, normalized, target);
+        // 1b. responseModeParams 桶内容校验：主 schema 把 responseModeParams 当黑箱，
+        //     此处使用“模式桶 schema”逐桶校验内容（桶键 = 已登记的响应模式 id）。
+        if (target === ConfigTarget.Agent || target === ConfigTarget.Relation) {
+            validateResponseModeParams(normalized?.responseModeParams, target);
+        }
+    }
+    // 2. 写入文件
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWriteJson(file, normalized);
+    finishConfigWrite(target, sel, file);
+}
+function finishConfigWrite(target, sel, file) {
+    if (fileCacheAvailable())
+        fileCache.invalidate(file);
+    if (sel?.self && (target === ConfigTarget.Agent || target === ConfigTarget.RoleRegistry || target === ConfigTarget.Role)) {
+        clearRoleStoreCache(sel.self);
+    }
+    const event = { target, selector: { ...(sel ?? {}) } };
+    for (const listener of configWriteListeners) {
+        try {
+            listener(event);
+        }
+        catch (error) {
+            configWarn(`[config] write listener failed for ${target}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+/** Notify cache and security listeners after a caller-owned atomic transaction commits. */
+export function notifyConfigWrite(target, sel) {
+    finishConfigWrite(target, sel, targetPath(target, sel));
+}
+function ensureSchemaVersion(value, version) {
+    return value && typeof value === 'object'
+        ? { ...value, $schema_version: version }
+        : value;
+}
+function validateOrThrow(schema, value, target) {
+    const ok = schema.validate(value);
+    const scopeErrors = validateProcessOnlyFields(target, value);
+    if (!ok || scopeErrors.length > 0) {
+        const errs = [
+            ...scopeErrors,
+            ...(schema.validate.errors || []).map(e => {
+                const extra = typeof e.params?.additionalProperty === 'string'
+                    ? ` (additionalProperty=${e.params.additionalProperty})`
+                    : '';
+                return `${e.instancePath || '/'} ${e.message}${extra}`;
+            }),
+        ].join('; ');
+        throw new ConfigError('SCHEMA_INVALID', `${target} 配置不合 schema(${schema.logicalName}.v${schema.version}): ${errs}`);
+    }
+}
+function validateProcessOnlyFields(target, value) {
+    if (target === ConfigTarget.Process || !value || typeof value !== 'object')
+        return [];
+    const debug = value.debug;
+    if (!debug || typeof debug !== 'object' || !Object.prototype.hasOwnProperty.call(debug, 'eckSnapshots'))
+        return [];
+    return ['/debug/eckSnapshots is only allowed in process config'];
+}
+/**
+ * responseModeParams 桶专项校验。
+ *
+ * 主 config schema 把 responseModeParams 当黑箱（{type:object}）放行，桶内部由本函数
+ * 用「模式桶 schema」逐桶校验：桶键 = 响应模式 id，须是已在 _meta.json 登记的 schema。
+ *   - 未登记的桶键：收集后统一报错，点名列出，提示用 `ec response list` 查可用模式；
+ *   - 已登记：用 loadSchema(modeId) 校验该桶内容（enum / additionalProperties 等）。
+ *
+ * 纯 schema 驱动，不 import response-system（避免 config→response-system 反向依赖）；
+ * 「桶键≡已注册模式」经由「模式必带同名 schema 且登记进 _meta」这一约定保证。
+ */
+function validateResponseModeParams(params, target) {
+    if (!params || typeof params !== 'object' || Array.isArray(params))
+        return;
+    const unregistered = [];
+    for (const [modeId, bucket] of Object.entries(params)) {
+        if (!isSchemaName(modeId)) {
+            unregistered.push(modeId);
+            continue;
+        }
+        const modeSchema = loadSchema(modeId);
+        if (!modeSchema.validate(bucket)) {
+            const errs = (modeSchema.validate.errors || [])
+                .map(e => {
+                const extra = typeof e.params?.additionalProperty === 'string'
+                    ? ` (additionalProperty=${e.params.additionalProperty})`
+                    : '';
+                return `${e.instancePath || '/'} ${e.message}${extra}`;
+            })
+                .join('; ');
+            throw new ConfigError('SCHEMA_INVALID', `${target} responseModeParams["${modeId}"] 不合模式 schema(${modeSchema.logicalName}.v${modeSchema.version}): ${errs}`);
+        }
+    }
+    if (unregistered.length > 0) {
+        throw new ConfigError('SCHEMA_INVALID', `${target} responseModeParams 含未注册的响应模式桶键: ${unregistered.map(k => `"${k}"`).join(', ')}。` +
+            `桶键必须对应已注册的响应模式（用 \`ec response list\` 查看可用模式）。`);
+    }
+}
+/**
+ * 纯 schema 校验（不写盘、无副作用）。返回错误信息数组，空数组表示通过。
+ * 供 config-store.validateAgentConfig 等只校验不落盘的场景使用。
+ */
+export function validateConfig(target, value) {
+    const schema = loadSchema(TARGET_SCHEMA[target]);
+    const withVer = ensureSchemaVersion(value, schema.version);
+    const ok = schema.validate(withVer);
+    const errors = validateProcessOnlyFields(target, withVer);
+    if (ok && errors.length === 0)
+        return [];
+    return [
+        ...errors,
+        ...(schema.validate.errors || []).map(e => {
+            const extra = typeof e.params?.additionalProperty === 'string'
+                ? ` (additionalProperty=${e.params.additionalProperty})`
+                : '';
+            return `${e.instancePath || '/'} ${e.message}${extra}`;
+        }),
+    ];
+}
+export function validateConfigFile(target, sel) {
+    const value = atomicReadJson(targetPath(target, sel));
+    if (value === null)
+        return { exists: false, errors: [] };
+    return { exists: true, errors: validateConfig(target, value) };
+}
+function fileCacheAvailable() {
+    try {
+        return !!fileCache;
+    }
+    catch {
+        return false;
+    }
+}
+// ── ensureFile ────────────────────────────────────────────────────────────
+/** 按 schema 的 required/default 生成骨架并写入（幂等：已存在不覆盖）。 */
+export function ensureFile(target, sel) {
+    const file = targetPath(target, sel);
+    if (fs.existsSync(file))
+        return;
+    const schema = loadSchema(TARGET_SCHEMA[target]);
+    const skeleton = { $schema_version: schema.version };
+    const props = schema.raw.properties || {};
+    const required = schema.raw.required || [];
+    for (const key of required) {
+        if (key === '$schema_version')
+            continue;
+        if (key === 'aid' && sel?.self) {
+            skeleton.aid = sel.self;
+            continue;
+        }
+        const spec = props[key];
+        if (spec && 'default' in spec)
+            skeleton[key] = spec.default;
+        else if (spec?.type === 'array')
+            skeleton[key] = [];
+        else if (spec?.type === 'object')
+            skeleton[key] = {};
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWriteJson(file, skeleton);
+}
+// ── schema 版本迁移 ───────────────────────────────────────────────────────
+//
+// 同步路径只做版本号判断和告警。跨版本迁移由部署期一次性脚本完成，
+// 避免基础设施热路径长期承载会静默改变权限策略的业务迁移逻辑。
+function migrateIfNeeded(target, raw, file) {
+    const logical = TARGET_SCHEMA[target];
+    const cur = currentVersion(logical);
+    const have = raw?.$schema_version;
+    if (typeof have === 'number' && have < cur && schemaVersionWarningsEnabled) {
+        configWarn(`[config] ${file}: $schema_version ${have} < current ${cur} for "${logical}" - run kits/migrations/migrate-role-config-v4.mjs`);
+    }
+    return raw;
+}
+export function resolveAgentConfig(sel, opts = {}) {
+    // Use agent-config as the H-chain field table, but static owners only come from agent config.
+    const fields = loadSchema('agent-config').fields;
+    const agentConfig = sel.self ? read(ConfigTarget.Agent, sel, opts) : null;
+    const relationConfig = (sel.self && sel.peerKey) ? read(ConfigTarget.Relation, sel, opts) : null;
+    const layers = [
+        stripStaticOwnerField(read(ConfigTarget.Defaults, undefined, opts)),
+        agentConfig,
+        stripRelationRoleData(stripStaticOwnerField(relationConfig)),
+    ];
+    const merged = mergeLayers(layers, fields);
+    return merged;
+}
+function stripStaticOwnerField(config) {
+    if (!config)
+        return config;
+    if (!Object.prototype.hasOwnProperty.call(config, 'owners') && !Object.prototype.hasOwnProperty.call(config, 'admins'))
+        return config;
+    const { owners: _owners, admins: _admins, ...rest } = config;
+    return rest;
+}
+function stripRelationRoleData(config) {
+    if (!config || (!Object.prototype.hasOwnProperty.call(config, 'role')
+        && !Object.prototype.hasOwnProperty.call(config, 'roles')))
+        return config;
+    const { role: _role, roles: _legacyRoles, ...rest } = config;
+    return rest;
+}
+// ── effective（合并视图）─────────────────────────────────────────────────
+/**
+ * 合并视图：只合并物理覆盖链 defaults → agent/config → relation/config。
+ */
+export function resolveEffective(sel, opts = {}) {
+    const config = resolveAgentConfig(sel, opts);
+    const effective = {
+        $schema_version: config.$schema_version ?? currentVersion('agent-config'),
+        aid: config.aid ?? sel.self ?? '',
+        enabled: config.enabled,
+        lifecycle: config.lifecycle,
+        initialized: config.initialized,
+        owners: config.owners,
+        aun: config.aun,
+        channels: config.channels ?? [],
+        models: config.models,
+        projects: config.projects,
+        capabilities: config.capabilities,
+        debug: config.debug,
+        observable: config.observable,
+        extra_backup: config.extra_backup,
+        // Runtime configuration parameters
+        active_baseagent: config.active_baseagent,
+        baseagents: config.baseagents,
+        chatmode: config.chatmode,
+        mentionMode: config.mentionMode,
+        model: config.model,
+        responseMode: config.responseMode,
+        responseModeParams: config.responseModeParams,
+        flush_delay: config.flush_delay,
+        debounce: config.debounce,
+        show_activities: config.show_activities,
+        session_renew: config.session_renew,
+        render: config.render,
+        sessionManifests: config.sessionManifests,
+        enable_rich_content: config.enable_rich_content,
+    };
+    return normalizeEffectiveCompatibility(effective);
+}
+function normalizeEffectiveCompatibility(effective) {
+    normalizeShowActivitiesCompat(effective);
+    const behavior = {};
+    for (const field of EFFECTIVE_BEHAVIOR_FIELDS) {
+        if (effective[field] !== undefined)
+            behavior[field] = effective[field];
+    }
+    if (Object.keys(behavior).length > 0) {
+        effective.behavior = behavior;
+    }
+    return effective;
+}
+const EFFECTIVE_BEHAVIOR_FIELDS = [
+    'active_baseagent',
+    'baseagents',
+    'chatmode',
+    'mentionMode',
+    'flush_delay',
+    'debounce',
+    'show_activities',
+    'session_renew',
+    'render',
+    'sessionManifests',
+    'enable_rich_content',
+];
+/**
+ * 给定 selector 作用域 + 顶层字段名，判定写入落点。
+ * 兼容旧调用：仅按顶层字段路由。新写入请优先使用 routeFieldPath()。
+ */
+export function routeField(topField, scope) {
+    return routeFieldPath(topField, scope);
+}
+/**
+ * 给定 selector 作用域 + 完整字段路径，判定 canonical 写入落点。
+ * v3 设计：所有参数统一在 config.json，按作用域路由到对应层级。
+ */
+export function routeFieldPath(fieldPath, scope) {
+    const topField = fieldPath.split('.')[0];
+    if (scope === 'process')
+        return routeIn(DAEMON_SCHEMA_NAME, ConfigTarget.Process, topField);
+    if (scope === 'defaults') {
+        if (isBehaviorConfigFieldPath(fieldPath) && topField !== 'session_renew') {
+            throw new ConfigError('DEFAULT_BEHAVIOR_REJECT', `--default 不支持行为字段: ${fieldPath}`);
+        }
+        return routeIn('defaults', ConfigTarget.Defaults, topField);
+    }
+    if (isBehaviorConfigFieldPath(fieldPath)) {
+        // v3 设计：行为字段按作用域路由到对应 schema
+        if (scope === 'agent') {
+            return routeIn('agent-config', ConfigTarget.Agent, topField);
+        }
+        // relation 作用域：行为字段位于 relation-config
+        return routeIn('relation-config', ConfigTarget.Relation, topField);
+    }
+    if (scope === 'agent')
+        return routeIn('agent-config', ConfigTarget.Agent, topField);
+    return routeIn('relation-config', ConfigTarget.Relation, topField);
+}
+function routeIn(name, target, topField) {
+    // $schema_version 是元数据字段，特殊处理
+    if (topField === '$schema_version') {
+        return {
+            field: topField,
+            target,
+            schema: name,
+            merge: 'replace',
+            enum: undefined
+        };
+    }
+    const s = loadSchema(name);
+    if (!s.fields.has(topField)) {
+        const known = [...s.fields.keys()].sort();
+        const suggestion = suggestField(topField, known);
+        throw new ConfigError('UNKNOWN_FIELD', `Unknown config field "${topField}" for ${name}.`
+            + (suggestion ? ` Did you mean "${suggestion}"?` : '')
+            + ` Run "ec config fields" to list valid fields.`);
+    }
+    return mkRoute(s, target, topField);
+}
+/** 为未知字段找一个最接近的合法字段名（编辑距离 ≤2 才提示），用于 UNKNOWN_FIELD 纠错。 */
+function suggestField(input, candidates) {
+    let best;
+    let bestDist = Infinity;
+    for (const c of candidates) {
+        const d = editDistance(input.toLowerCase(), c.toLowerCase());
+        if (d < bestDist) {
+            bestDist = d;
+            best = c;
+        }
+    }
+    return bestDist <= 2 ? best : undefined;
+}
+function editDistance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 0; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[a.length][b.length];
+}
+function mkRoute(s, target, topField) {
+    const spec = s.fields.get(topField);
+    return { field: topField, target, schema: s.logicalName, merge: spec.merge, enum: spec.enum };
+}
+/** 列出某作用域下所有可配置字段（供 ec config fields 使用）。 */
+export function listFields(scope) {
+    const out = [];
+    const add = (name, target) => {
+        const s = loadSchema(name);
+        for (const f of s.fields.keys())
+            out.push(mkRoute(s, target, f));
+    };
+    if (scope === 'process') {
+        add(DAEMON_SCHEMA_NAME, ConfigTarget.Process);
+        return out;
+    }
+    if (scope === 'defaults') {
+        add('defaults', ConfigTarget.Defaults);
+        return out;
+    }
+    if (scope === 'agent') {
+        add('agent-config', ConfigTarget.Agent);
+        return out;
+    }
+    // relation
+    add('relation-config', ConfigTarget.Relation);
+    return out;
+}
+export { ConfigTarget as Target };
+/**
+ * 读取单个字段并返回来源信息。
+ * 沿覆盖链查找，返回第一个定义该字段的层级。
+ */
+export function readConfiguredFieldWithSource(field, sel, opts = {}) {
+    const parts = field.split('.');
+    const topField = parts[0];
+    // 按覆盖链顺序查找：relation → agent → defaults
+    const targets = [];
+    if (sel.self && sel.peerKey)
+        targets.push(ConfigTarget.Relation);
+    if (sel.self)
+        targets.push(ConfigTarget.Agent);
+    targets.push(ConfigTarget.Defaults);
+    for (const target of targets) {
+        const config = read(target, sel, opts);
+        if (!config)
+            continue;
+        // 检查顶层字段是否存在
+        if (!(topField in config))
+            continue;
+        // 提取字段值（支持嵌套）
+        let value = config[topField];
+        for (let i = 1; i < parts.length; i++) {
+            if (value && typeof value === 'object' && parts[i] in value) {
+                value = value[parts[i]];
+            }
+            else {
+                value = undefined;
+                break;
+            }
+        }
+        // 如果值存在，返回并携带来源
+        if (value !== undefined) {
+            const file = path.relative(resolvePaths().root, targetPath(target, sel));
+            return {
+                value,
+                source: { target, file }
+            };
+        }
+    }
+    return null;
+}
+/** Raw configured-layer lookup retained as the public ConfigManager API. */
+export function readFieldWithSource(field, sel, opts = {}) {
+    return readConfiguredFieldWithSource(field, sel, opts);
+}
+/**
+ * Resolve effective values and their deciding source through one implementation.
+ * Without fields, all leaf paths are returned as a flat dot-path map.
+ */
+export function resolveEffectiveWithSources(sel, opts = {}) {
+    const { fields, ...readOpts } = opts;
+    const effective = resolveEffective(sel, readOpts);
+    const paths = fields ?? listEffectiveLeafPaths(effective);
+    const result = {};
+    for (const field of paths) {
+        const configured = readConfiguredFieldWithSource(field, sel, readOpts);
+        const value = readNestedField(effective, field);
+        result[field] = {
+            value,
+            source: configured?.source ?? null,
+        };
+    }
+    return result;
+}
+/** Thin single-field view over resolveEffectiveWithSources(). */
+export function resolveEffectiveFieldWithSource(field, sel, opts = {}) {
+    return (resolveEffectiveWithSources(sel, { ...opts, fields: [field] })[field]
+        ?? { value: undefined, source: null });
+}
+function readNestedField(value, field) {
+    let current = value;
+    for (const part of field.split('.')) {
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function listEffectiveLeafPaths(value) {
+    const paths = [];
+    const visit = (current, prefix) => {
+        if (current === undefined)
+            return;
+        if (!current || typeof current !== 'object' || Array.isArray(current)) {
+            if (prefix)
+                paths.push(prefix);
+            return;
+        }
+        const entries = Object.entries(current).filter(([, child]) => child !== undefined);
+        // Dotted dictionary keys (for example role field permissions) cannot be
+        // represented unambiguously as another dot-path segment.
+        if (prefix && entries.some(([key]) => key.includes('.'))) {
+            paths.push(prefix);
+            return;
+        }
+        if (entries.length === 0) {
+            if (prefix)
+                paths.push(prefix);
+            return;
+        }
+        for (const [key, child] of entries) {
+            if (!prefix && key === 'behavior')
+                continue; // compatibility mirror of top-level behavior fields
+            visit(child, prefix ? `${prefix}.${key}` : key);
+        }
+    };
+    visit(value, '');
+    return paths;
+}