evolcore 0.0.20 → 0.0.22

package/dist/cli/watch-logs.js

@@ -1,15 +1,22 @@
 import path from 'path';
+const WATCH_LOG_FILE = /\.(?:log|jsonl|out)(?:\..+)?$/;
+/** Whether a file is a supported input for the interactive log watcher. */
+export function isWatchLogFile(file) {
+    return WATCH_LOG_FILE.test(path.basename(file));
+}
 /** 去掉轮转后缀（按小时、按日及旧版带连字符日期）。入参可为文件名或绝对路径。 */
 export function shortLogName(file) {
-    return path.basename(file, '.log')
+    const baseName = path.basename(file);
+    const stem = baseName.replace(WATCH_LOG_FILE, '');
+    return stem
         .replace(/-\d{8}(?:-\d{2})?$/, '') // -YYYYMMDD[-HH]（按日/小时轮转）
         .replace(/-\d{4}-\d{2}-\d{2}$/, ''); // -YYYY-MM-DD（按日轮转，如 ts-sdk）
 }
-/** 从 .log 文件名列表推导去重、字母序的类型列表。 */
+/** 从支持的日志文件名列表推导去重、字母序的类型列表。 */
 export function deriveLogTypes(files) {
     const set = new Set();
     for (const f of files) {
-        if (!f.endsWith('.log'))
+        if (!isWatchLogFile(f))
             continue;
         set.add(shortLogName(f));
     }

package/dist/config/builtin-roles.js

@@ -32,6 +32,7 @@ export function getBuiltinRolesConfig() {
 export function getManagementCommandPermissions(role) {
     return {
         'contact.read': { allow: true, scopes: ['agent'] },
+        'contact.add': { allow: true, scopes: ['relation'], constraints: { ownPeerOnly: true, privateOnly: true } },
         'contact.block': { allow: true, scopes: ['agent'], constraints: { requireAgentAdmin: true } },
         'connect.write': { allow: true, scopes: ['agent'], constraints: { requireAgentAdmin: true } },
         'connect.access.write': { allow: true, scopes: ['agent'], constraints: { requireAgentOwner: true } },

package/dist/config/config-field-policy.js

@@ -2,6 +2,7 @@ const BEHAVIOR_TOP_FIELDS = new Set([
     'active_baseagent',
     'chatmode',
     'mentionMode',
+    'groupSlashRequireMentions',
     'responseMode',
     'responseModeParams',
     'flush_delay',
@@ -17,6 +18,8 @@ const BEHAVIOR_TOP_FIELDS = new Set([
 const BASEAGENT_BEHAVIOR_FIELDS = new Set([
     'model',
     'effort',
+    'auxiliaryModel',
+    'auxiliaryEffort',
     'reasoning',
     'agentProgressSummaries',
     'excludeDynamicSections',
@@ -25,7 +28,7 @@ const BASEAGENT_BEHAVIOR_FIELDS = new Set([
     'mode',
     'useVertex',
 ]);
-const SUPPORTED_BASEAGENTS = new Set(['claude', 'codex', 'gemini', 'ecagent', 'hermes']);
+const SUPPORTED_BASEAGENTS = new Set(['claude', 'codex', 'gemini', 'ecagent']);
 const SENSITIVE_TOP_FIELDS = new Set([
     '$schema_version',
     'aid',
@@ -75,10 +78,17 @@ export function resolveConfigFieldRule(fieldPath) {
         const [, baseagent, leaf] = parts;
         if (!SUPPORTED_BASEAGENTS.has(baseagent))
             return { class: 'unknown' };
-        const permissionKey = `baseagents.${baseagent}.${leaf === 'reasoning' ? 'effort' : leaf}`;
-        if (leaf === 'model' && parts.length === 3)
+        const normalizedLeaf = leaf === 'reasoning'
+            ? 'effort'
+            : leaf === 'auxiliaryModel'
+                ? 'model'
+                : leaf === 'auxiliaryEffort'
+                    ? 'effort'
+                    : leaf;
+        const permissionKey = `baseagents.${baseagent}.${normalizedLeaf}`;
+        if ((leaf === 'model' || leaf === 'auxiliaryModel') && parts.length === 3)
             return scalar(permissionKey, 'string');
-        if ((leaf === 'effort' || leaf === 'reasoning') && parts.length === 3)
+        if ((leaf === 'effort' || leaf === 'reasoning' || leaf === 'auxiliaryEffort') && parts.length === 3)
             return scalar(permissionKey, 'effort');
         if (baseagent === 'claude' && (leaf === 'agentProgressSummaries' || leaf === 'excludeDynamicSections') && parts.length === 3) {
             return scalar(permissionKey, 'boolean');
@@ -101,6 +111,8 @@ export function resolveConfigFieldRule(fieldPath) {
         return scalar(field, 'nonnegative-number');
     if (field === 'mentionMode')
         return scalar(field, 'mention-mode');
+    if (field === 'groupSlashRequireMentions')
+        return scalar(field, 'boolean');
     if (field === 'show_activities')
         return scalar(field, 'show-activities');
     if (field === 'enable_rich_content')
@@ -199,7 +211,9 @@ export function relationFieldWriteOperation(fieldPath) {
         return 'mentionmode.update';
     if (/^baseagents\.[^.]+\.model$/.test(field))
         return 'model.use';
-    if (/^baseagents\.[^.]+\.(?:effort|reasoning)$/.test(field)) {
+    if (/^baseagents\.[^.]+\.auxiliaryModel$/.test(field))
+        return 'model.use';
+    if (/^baseagents\.[^.]+\.(?:effort|reasoning|auxiliaryEffort)$/.test(field)) {
         return 'model.effort';
     }
     return undefined;

package/dist/config/config-manager.js

@@ -29,6 +29,7 @@ import { clearRoleStoreCache, isRoleName } from './role-store.js';
 import { writeRoleDefinition, writeRoleRegistry } from './role-service.js';
 import { mutateContactBookTransactionSync } from './contact-book-store.js';
 import { DAEMON_SCHEMA_NAME } from '../product.js';
+import { normalizeDaemonServices } from './daemon-services.js';
 // AUN gateway discovery belongs to fastaun. Keep the retired gatewayUrl
 // compatibility handling beside the rest of the configuration read/write
 // policy so all config callers share one implementation.
@@ -595,11 +596,13 @@ export function read(target, sel, opts = {}) {
     raw = stripLegacyAunGatewayConfig(raw, file, message => configWarn(message));
     // 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;
+    const normalized = target === ConfigTarget.Process
+        ? normalizeProcessConfigCompat(normalizeDaemonServices(migrated))
+        : target === ConfigTarget.Agent
+            ? normalizeAgentConfigForRead(migrated, sel?.self)
+            : target === ConfigTarget.Relation
+                ? foldLegacyProactiveBlock(migrated)
+                : migrated;
     // Agent read compatibility may move the legacy top-level `agents` block to
     // `baseagents`, so canonicalize effort after that structural migration.
     const canonicalized = normalizeBaseagentEffortCompat(normalized);
@@ -680,12 +683,11 @@ function normalizeAgentConfigForWrite(value) {
     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
+    // 规范化 projects 字段：只保留唯一公开项目路径 defaultPath。
+    // defaults.projects.rootPath 已废弃，不能继续成为有效运行时参数。
     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) {
@@ -698,19 +700,58 @@ function normalizeAgentConfigForWrite(value) {
     return mutable;
 }
 function normalizeProcessConfigForWrite(value) {
-    const configuredAidDomain = value.aun?.defaultAidDomain;
+    let normalized;
+    try {
+        normalized = normalizeProcessConfigCompat(normalizeDaemonServices(value));
+    }
+    catch (error) {
+        throw new ConfigError('DAEMON_SERVICES_MIGRATION_REQUIRED', error instanceof Error ? error.message : String(error));
+    }
+    const configuredAidDomain = normalized.aun?.defaultAidDomain;
     if (configuredAidDomain === undefined)
-        return value;
+        return normalized;
     try {
         return {
-            ...value,
-            aun: { ...value.aun, defaultAidDomain: normalizeAidDomain(configuredAidDomain, 'aun.defaultAidDomain') },
+            ...normalized,
+            aun: { ...normalized.aun, defaultAidDomain: normalizeAidDomain(configuredAidDomain, 'aun.defaultAidDomain') },
         };
     }
     catch (error) {
         throw new ConfigError('VALIDATION_ERROR', error instanceof Error ? error.message : String(error));
     }
 }
+/**
+ * Normalize renamed process-level settings while keeping old daemon.json files
+ * readable after an upgrade. New values take precedence when both keys exist.
+ */
+export function normalizeProcessConfigCompat(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const idleMonitor = value.idleMonitor;
+    const debug = value.debug;
+    let changed = false;
+    let normalized = value;
+    if (idleMonitor && typeof idleMonitor === 'object' && !Array.isArray(idleMonitor)) {
+        const nextIdleMonitor = { ...idleMonitor };
+        if (nextIdleMonitor.apiRetryTimeout === undefined && nextIdleMonitor.retryAttemptTimeout !== undefined) {
+            nextIdleMonitor.apiRetryTimeout = nextIdleMonitor.retryAttemptTimeout;
+            changed = true;
+        }
+        if (Object.prototype.hasOwnProperty.call(nextIdleMonitor, 'retryAttemptTimeout')) {
+            delete nextIdleMonitor.retryAttemptTimeout;
+            changed = true;
+        }
+        if (changed)
+            normalized = { ...normalized, idleMonitor: nextIdleMonitor };
+    }
+    if (debug && typeof debug === 'object' && !Array.isArray(debug)
+        && Object.prototype.hasOwnProperty.call(debug, 'flusherDiag')) {
+        const nextDebug = { ...debug };
+        delete nextDebug.flusherDiag;
+        normalized = { ...normalized, debug: nextDebug };
+    }
+    return normalized;
+}
 function normalizeRelationConfigForWrite(value) {
     const mutable = normalizeBaseagentEffortCompat({ ...value });
     normalizeShowActivitiesCompat(mutable);
@@ -892,7 +933,10 @@ function acquireConfigMutationLock(file) {
                 return () => releaseConfigMutationLock(lockDir, ownerFile, token);
             }
             catch (error) {
-                if (error?.code !== 'EEXIST' && error?.code !== 'ENOTEMPTY')
+                const lockMayAlreadyExist = error?.code === 'EEXIST'
+                    || error?.code === 'ENOTEMPTY'
+                    || (process.platform === 'win32' && error?.code === 'EPERM' && fs.existsSync(lockDir));
+                if (!lockMayAlreadyExist)
                     throw error;
                 if (reclaimStaleConfigMutationLock(lockDir, ownerFile))
                     continue;
@@ -916,10 +960,10 @@ function reclaimStaleConfigMutationLock(lockDir, ownerFile) {
         pid = Number(JSON.parse(raw).pid);
     }
     catch {
-        return false;
+        return reclaimCorruptConfigMutationLock(lockDir);
     }
     if (!Number.isInteger(pid) || pid <= 0)
-        return false;
+        return reclaimCorruptConfigMutationLock(lockDir);
     try {
         process.kill(pid, 0);
         return false;
@@ -938,6 +982,24 @@ function reclaimStaleConfigMutationLock(lockDir, ownerFile) {
         }
     }
 }
+function reclaimCorruptConfigMutationLock(lockDir) {
+    try {
+        const stat = fs.statSync(lockDir);
+        if (Date.now() - stat.mtimeMs < CONFIG_MUTATION_LOCK_WAIT_MS)
+            return false;
+        const reclaimed = `${lockDir}.reclaimed-corrupt-${crypto.randomBytes(8).toString('hex')}`;
+        fs.renameSync(lockDir, reclaimed);
+        fs.rmSync(reclaimed, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return true;
+        if (error?.code === 'EEXIST' || error?.code === 'ENOTEMPTY' || error?.code === 'EPERM')
+            return false;
+        throw error;
+    }
+}
 function releaseConfigMutationLock(lockDir, ownerFile, token) {
     try {
         const owner = JSON.parse(fs.readFileSync(ownerFile, 'utf8'));
@@ -985,7 +1047,11 @@ function ensureSchemaVersion(value, version) {
 }
 function validateOrThrow(schema, value, target) {
     const ok = schema.validate(value);
-    const scopeErrors = [...validateProcessOnlyFields(target, value), ...validateProcessAidDomain(target, value)];
+    const scopeErrors = [
+        ...validateProcessOnlyFields(target, value),
+        ...validateProcessAidDomain(target, value),
+        ...validateProcessServiceNames(target, value),
+    ];
     if (!ok || scopeErrors.length > 0) {
         const errs = [
             ...scopeErrors,
@@ -1026,6 +1092,24 @@ function validateProcessAidDomain(target, value) {
         return [`/aun/defaultAidDomain ${error instanceof Error ? error.message : String(error)}`];
     }
 }
+function validateProcessServiceNames(target, value) {
+    if (target !== ConfigTarget.Process || !value || typeof value !== 'object')
+        return [];
+    const services = value.services;
+    if (!Array.isArray(services))
+        return [];
+    const seen = new Set();
+    const errors = [];
+    services.forEach((service, index) => {
+        if (!service || typeof service !== 'object' || typeof service.name !== 'string')
+            return;
+        if (seen.has(service.name))
+            errors.push(`/services/${index}/name duplicates service name ${JSON.stringify(service.name)}`);
+        else
+            seen.add(service.name);
+    });
+    return errors;
+}
 /**
  * responseModeParams 桶专项校验。
  *
@@ -1076,8 +1160,28 @@ export function validateConfig(target, value) {
         ? loadSchema('contact-book', 2)
         : loadSchema(TARGET_SCHEMA[target]);
     const withVer = ensureSchemaVersion(value, schema.version);
-    const ok = schema.validate(withVer);
-    const errors = [...validateProcessOnlyFields(target, withVer), ...validateProcessAidDomain(target, withVer)];
+    let normalized = withVer;
+    try {
+        if (target === ConfigTarget.Process)
+            normalized = normalizeProcessConfigCompat(normalizeDaemonServices(withVer));
+    }
+    catch (error) {
+        return [error instanceof Error ? error.message : String(error)];
+    }
+    const ok = schema.validate(normalized);
+    const errors = [
+        ...validateProcessOnlyFields(target, normalized),
+        ...validateProcessAidDomain(target, normalized),
+        ...validateProcessServiceNames(target, normalized),
+    ];
+    if (target === ConfigTarget.Defaults || target === ConfigTarget.Agent || target === ConfigTarget.Relation) {
+        try {
+            validateResponseModeParams(normalized?.responseModeParams, target);
+        }
+        catch (error) {
+            errors.push(error instanceof ConfigError ? error.message : String(error));
+        }
+    }
     if (ok && errors.length === 0)
         return [];
     return [
@@ -1097,7 +1201,15 @@ export function validateConfigFile(target, sel) {
         return { exists: false, errors: [] };
     // Persisted pre-removal files remain readable: validate the same sanitized
     // view used by runtime reads, while new writes are still rejected by write().
-    const sanitized = stripLegacyAunGatewayConfig(value, file, message => configWarn(message));
+    let sanitized;
+    try {
+        sanitized = target === ConfigTarget.Process
+            ? normalizeDaemonServices(stripLegacyAunGatewayConfig(value, file, message => configWarn(message)))
+            : stripLegacyAunGatewayConfig(value, file, message => configWarn(message));
+    }
+    catch (error) {
+        return { exists: true, errors: [error instanceof Error ? error.message : String(error)] };
+    }
     return { exists: true, errors: validateConfig(target, sanitized) };
 }
 function fileCacheAvailable() {
@@ -1159,21 +1271,52 @@ export function resolveAgentConfig(sel, opts = {}) {
     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)),
+        stripStaticOwnerField(normalizeDefaultsBehaviorCompat(read(ConfigTarget.Defaults, undefined, opts))),
         agentConfig,
         stripRelationRoleData(stripStaticOwnerField(relationConfig)),
     ];
     const merged = mergeLayers(layers, fields);
     return merged;
 }
+/**
+ * defaults.schema keeps the historical `config` object as the process-wide
+ * response behavior compatibility surface. Make those values participate in
+ * the normal agent/relation merge chain without leaking the compatibility
+ * container itself into EffectiveAgentConfig.
+ *
+ * Explicit canonical fields (if a future schema adds them) always win. A
+ * single default chat mode applies to the three peer categories because this
+ * compatibility field predates the per-category `chatmode` dictionary.
+ */
+export function normalizeDefaultsBehaviorCompat(defaults) {
+    if (!defaults || !defaults.config || typeof defaults.config !== 'object' || Array.isArray(defaults.config))
+        return defaults;
+    const { config, ...rest } = defaults;
+    const normalized = { ...rest };
+    const chatMode = config.chatMode;
+    if (!normalized.chatmode && (chatMode === 'interactive' || chatMode === 'proactive')) {
+        normalized.chatmode = { private: chatMode, group: chatMode, nothuman: chatMode };
+    }
+    if (normalized.mentionMode === undefined && (config.mentionMode === 'disabled' || config.mentionMode === 'mention-only')) {
+        normalized.mentionMode = config.mentionMode;
+    }
+    if (normalized.show_activities === undefined && ['all', 'text', 'none'].includes(config.show_activities)) {
+        normalized.show_activities = config.show_activities;
+    }
+    return normalized;
+}
 function stripStaticOwnerField(config) {
     if (!config)
         return config;
     if (!Object.prototype.hasOwnProperty.call(config, 'owners')
         && !Object.prototype.hasOwnProperty.call(config, 'admins')
-        && !Object.prototype.hasOwnProperty.call(config, 'access'))
+        && !Object.prototype.hasOwnProperty.call(config, 'access')
+        && !Object.prototype.hasOwnProperty.call(config, 'groupSlashRequireMentions'))
         return config;
-    const { owners: _owners, admins: _admins, access: _access, ...rest } = config;
+    // groupSlashRequireMentions is intentionally Agent-only. Relation/defaults
+    // files allow forward-compatible unknown properties, so strip it before the
+    // generic merge chain can treat a manually written value as an override.
+    const { owners: _owners, admins: _admins, access: _access, groupSlashRequireMentions: _groupSlashRequireMentions, ...rest } = config;
     return rest;
 }
 function stripRelationRoleData(config) {
@@ -1212,6 +1355,7 @@ export function resolveEffective(sel, opts = {}) {
         baseagents: config.baseagents,
         chatmode: config.chatmode,
         mentionMode: config.mentionMode,
+        groupSlashRequireMentions: config.groupSlashRequireMentions ?? true,
         model: config.model,
         responseMode: config.responseMode,
         responseModeParams: config.responseModeParams,
@@ -1243,6 +1387,7 @@ const EFFECTIVE_BEHAVIOR_FIELDS = [
     'baseagents',
     'chatmode',
     'mentionMode',
+    'groupSlashRequireMentions',
     'flush_delay',
     'debounce',
     'show_activities',

package/dist/config/contact-book-store.js

@@ -14,6 +14,7 @@ const LOCK_NAME = '.contact-book-mutation.lock';
 const JOURNAL_NAME = '.contact-book-mutation.json';
 const LOCK_WAIT_MS = 5_000;
 const LOCK_RETRY_MS = 20;
+const CORRUPT_LOCK_STALE_MS = LOCK_WAIT_MS;
 export const EMPTY_CONTACT_REVISION = crypto.createHash('sha256').update('').digest('hex');
 export class ContactMutationError extends Error {
     code;
@@ -454,7 +455,10 @@ function acquireAgentLock(selfAid) {
                 return () => releaseAgentLock(lockDir, ownerFile, lockToken);
             }
             catch (error) {
-                if (error?.code !== 'EEXIST' && error?.code !== 'ENOTEMPTY')
+                const lockMayAlreadyExist = error?.code === 'EEXIST'
+                    || error?.code === 'ENOTEMPTY'
+                    || (process.platform === 'win32' && error?.code === 'EPERM' && fs.existsSync(lockDir));
+                if (!lockMayAlreadyExist)
                     throw error;
                 if (removeStaleLock(lockDir, ownerFile))
                     continue;
@@ -478,10 +482,10 @@ function removeStaleLock(lockDir, ownerFile) {
         pid = Number(JSON.parse(rawOwner).pid);
     }
     catch {
-        return false;
+        return reclaimCorruptLock(lockDir);
     }
     if (!Number.isInteger(pid) || pid <= 0)
-        return false;
+        return reclaimCorruptLock(lockDir);
     try {
         process.kill(pid, 0);
         return false;
@@ -503,6 +507,24 @@ function removeStaleLock(lockDir, ownerFile) {
         }
     }
 }
+function reclaimCorruptLock(lockDir) {
+    try {
+        const stat = fs.statSync(lockDir);
+        if (Date.now() - stat.mtimeMs < CORRUPT_LOCK_STALE_MS)
+            return false;
+        const staleClaim = `${lockDir}.reclaimed-corrupt-${crypto.randomBytes(8).toString('hex')}`;
+        fs.renameSync(lockDir, staleClaim);
+        fs.rmSync(staleClaim, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return true;
+        if (error?.code === 'EEXIST' || error?.code === 'ENOTEMPTY' || error?.code === 'EPERM')
+            return false;
+        throw error;
+    }
+}
 function releaseAgentLock(lockDir, ownerFile, lockToken) {
     try {
         const owner = JSON.parse(fs.readFileSync(ownerFile, 'utf8'));

package/dist/config/contact-operation-service.js

@@ -4,7 +4,7 @@ import { isExplicitGroupId } from '../aun/group-identity.js';
 import { agentConfig } from '../paths.js';
 import { getContactSnapshot, resolveContactView } from './contact-book.js';
 import { ContactMutationError } from './contact-book-store.js';
-import { mutateContactWithOperation } from './contact-request-service.js';
+import { addContact, mutateContactWithOperation } from './contact-request-service.js';
 export function resolveContactCommand(argv) {
     const args = argv[0] === 'contact' ? argv.slice(1) : [...argv];
     const selfAid = String(argValue(args, '--self') || '').trim();
@@ -39,6 +39,21 @@ export function resolveContactCommand(argv) {
             },
         };
     }
+    if (command === 'add') {
+        if (!isValidAid(subcommand || '') || isExplicitGroupId(subcommand || '')) {
+            return invalid('INVALID_AID', 'primaryId must be a valid individual AID');
+        }
+        return {
+            ok: true,
+            command: {
+                kind: 'add',
+                operationId: 'contact.add',
+                selfAid,
+                primaryId: subcommand,
+                canonicalArgv: canonicalArgv(argv),
+            },
+        };
+    }
     return invalid('UNKNOWN_COMMAND', `Unknown contact command: ${positional.join(' ')}`);
 }
 export async function executeResolvedContactCommand(command, actor = 'local-cli') {
@@ -81,6 +96,22 @@ export async function executeResolvedContactCommand(command, actor = 'local-cli'
                 contactRevision: result.contactRevision,
             };
         }
+        if (command.kind === 'add') {
+            const result = await addContact({
+                selfAid: command.selfAid,
+                primaryId: command.primaryId,
+                actorId: actor,
+            });
+            return {
+                ok: true,
+                operation: 'add',
+                selfAid: command.selfAid,
+                primaryId: command.primaryId,
+                status: 'active',
+                changed: result.changed,
+                contactRevision: result.contactRevision,
+            };
+        }
         return { ok: false, code: 'CONTACT_OPERATION_FAILED', error: 'Unsupported contact operation' };
     }
     catch (error) {

package/dist/config/contact-request-service.js

@@ -38,6 +38,50 @@ export async function mutateContactWithOperation(input) {
     const { value: _value, ...mutationResult } = result;
     return mutationResult;
 }
+/**
+ * Add a canonical AUN contact as active through the Contact Book transaction.
+ * Existing pending/declined entries are intentionally promoted here, while a
+ * blocked entry remains a hard stop and must be explicitly unblocked first.
+ */
+export async function addContact(input) {
+    const primaryId = String(input.primaryId || '').trim();
+    if (!isValidAid(primaryId)) {
+        throw new ContactMutationError('INVALID_AID', `Invalid contact AID: ${primaryId}`);
+    }
+    const at = new Date(input.now ?? Date.now()).toISOString();
+    const logFile = agentContactOperations(input.selfAid);
+    const result = await mutateContactBookPrepared(input.selfAid, ({ contact, contactRevision }) => {
+        if (input.expectedContactRevision !== undefined && input.expectedContactRevision !== contactRevision) {
+            throw new ContactMutationError('CONFLICT', 'Contact book changed since it was read', {
+                expectedContactRevision: input.expectedContactRevision,
+                contactRevision,
+            });
+        }
+        if (contact.contacts[primaryId]?.status === 'blocked') {
+            throw new ContactMutationError('CONTACT_BLOCKED', `Contact is blocked: ${primaryId}`);
+        }
+        const mutations = [
+            { type: 'set-status', primaryId, status: 'active' },
+        ];
+        if (input.displayName !== undefined) {
+            mutations.push({ type: 'set-display-name', primaryId, displayName: input.displayName });
+        }
+        return {
+            mutation: mutations.length === 1 ? mutations[0] : { type: 'batch', mutations },
+            actor: input.actorId,
+            value: undefined,
+            beforeCommit: ({ contactRevision: nextRevision }) => operationLogChange(logFile, [operationRecord({
+                    at,
+                    op: 'manual-add',
+                    primaryId,
+                    actorId: input.actorId,
+                    contactRevision: nextRevision,
+                })]),
+        };
+    });
+    const { value: _value, ...mutationResult } = result;
+    return mutationResult;
+}
 export async function submitContactRequest(input) {
     const applicantAid = String(input.applicantAid || '').trim();
     const owners = listAgentOwners(input.selfAid);