evolcore 0.0.25 → 0.0.27

package/dist/aun/aid/agentmd.js

@@ -4,10 +4,47 @@ import { parseDocument } from 'yaml';
 import { getAidStore, loadAid, SLOT } from './store.js';
 import { agentMdPath, aidLocalDir, resolveRoot } from '../../paths.js';
 export const DEFAULT_AGENT_DESCRIPTION = 'EvolCore AI agent.';
+/**
+ * AUN 主体类型白名单。没有 `ai` / `codeagent` 这类取值：使用大模型且没有
+ * 专用主体类型的服务程序默认归为 `agent`。新建 AID 未指定类型时使用 DEFAULT_AGENT_TYPE。
+ */
+export const AGENT_TYPES = ['human', 'agent', 'group', 'service', 'device', 'org', 'host'];
+export const DEFAULT_AGENT_TYPE = 'agent';
+/**
+ * 归一化主体类型：大小写不敏感，统一收敛为白名单里的小写形式。
+ * `--type AGENT` / `Agent` 都接受，最终写进 agent.md 的一律是小写 `agent`。
+ * 返回 undefined 表示输入不是可识别的类型（交由 validateAgentType 报错）。
+ */
+export function normalizeAgentType(type) {
+    if (typeof type !== 'string')
+        return undefined;
+    const lowered = type.trim().toLowerCase();
+    return AGENT_TYPES.includes(lowered) ? lowered : undefined;
+}
+/** Return a human-readable validation error for a type value, or null when valid. */
+export function validateAgentType(type) {
+    if (typeof type !== 'string' || !type.trim())
+        return 'must be a non-empty string';
+    if (!normalizeAgentType(type))
+        return `must be one of ${AGENT_TYPES.join(', ')}`;
+    return null;
+}
+/**
+ * agent.md 的尺寸与字段上限，取值必须与 fastaun 的 agent-md-schema 保持一致，
+ * 否则本地校验通过、上传时才被 SDK 拒绝（失败点后移且提示不同）。
+ * 参考 @agentunion/fastaun dist/agent-md-schema.js。
+ */
+export const AGENT_MD_MAX_PAYLOAD_BYTES = 4096;
+export const AGENT_DESCRIPTION_MAX_LENGTH = 100;
+export const AGENT_AVATAR_MAX_LENGTH = 256;
+/** 按 Unicode 码点计数——与 SDK 的 Array.from(value).length 对齐（代理对算一个字符）。 */
+function codePointLength(value) {
+    return Array.from(value).length;
+}
 export const AGENT_TAG_MIN_COUNT = 3;
 export const AGENT_TAG_MAX_COUNT = 6;
 export const AGENT_TAG_MAX_LENGTH = 50;
-const AGENT_TAG_PATTERN = /^[\p{L}\p{N}]+$/u;
+const AGENT_TAG_PATTERN = /^[\p{L}\p{N}-]+$/u;
 /** Return a human-readable validation error for one tag, or null when valid. */
 export function validateAgentTag(tag) {
     if (typeof tag !== 'string' || !tag.trim())
@@ -17,7 +54,7 @@ export function validateAgentTag(tag) {
         return `must be at most ${AGENT_TAG_MAX_LENGTH} characters`;
     }
     if (!AGENT_TAG_PATTERN.test(normalized)) {
-        return 'must contain only Unicode letters and numbers';
+        return 'must contain only Unicode letters, numbers, and hyphens';
     }
     return null;
 }
@@ -49,6 +86,12 @@ export function validateAgentTags(tags, options = {}) {
     }
     return errors;
 }
+function resolveAgentMdAunPath(opts) {
+    return opts?.aunPath ?? opts?.store?.aunPath ?? resolveRoot();
+}
+// A process can host agents that deliberately use different AUN keystore
+// roots. Keep their display-name state separate so one root cannot shadow the
+// other with a same-named AID.
 const displayNameCache = new Map();
 const displayNamePending = new Map();
 const displayNameRevision = new Map();
@@ -64,9 +107,13 @@ export function parseAgentDisplayName(content) {
     const name = frontmatter.match(/^name:\s*["']?(.+?)["']?\s*$/m)?.[1]?.trim();
     return name || undefined;
 }
-function readLocalAgentDisplayName(aid) {
+function displayNameKey(aid, aunPath) {
+    const root = path.resolve(aunPath ?? resolveRoot());
+    return `${root}\u0000${aid.toLowerCase()}`;
+}
+function readLocalAgentDisplayName(aid, aunPath) {
     try {
-        return parseAgentDisplayName(fs.readFileSync(agentMdPath(aid), 'utf-8'));
+        return parseAgentDisplayName(fs.readFileSync(agentMdPath(aid, aunPath), 'utf-8'));
     }
     catch {
         return undefined;
@@ -77,60 +124,87 @@ function readLocalAgentDisplayName(aid) {
  * Local content is returned immediately; a missing value starts one shared
  * background refresh and remains undefined until a later lookup.
  */
-export function resolveAgentDisplayName(aid) {
+export function resolveAgentDisplayName(aid, opts) {
     const normalizedAid = normalizeAid(aid);
     if (!normalizedAid)
         return undefined;
-    const cached = displayNameCache.get(normalizedAid);
+    const aunPath = resolveAgentMdAunPath(opts);
+    const key = displayNameKey(normalizedAid, aunPath);
+    const cached = displayNameCache.get(key);
     if (cached)
         return cached;
-    const localName = readLocalAgentDisplayName(normalizedAid);
+    const localName = readLocalAgentDisplayName(normalizedAid, aunPath);
     if (localName) {
-        displayNameCache.set(normalizedAid, localName);
+        displayNameCache.set(key, localName);
         return localName;
     }
-    void refreshAgentDisplayName(normalizedAid);
+    void refreshAgentDisplayName(normalizedAid, opts);
     return undefined;
 }
 /** Fetch agent.md once and update the shared display-name cache. */
-export function refreshAgentDisplayName(aid) {
+export function refreshAgentDisplayName(aid, opts) {
     const normalizedAid = normalizeAid(aid);
     if (!normalizedAid)
         return Promise.resolve(undefined);
-    const existing = displayNamePending.get(normalizedAid);
+    const aunPath = resolveAgentMdAunPath(opts);
+    const key = displayNameKey(normalizedAid, aunPath);
+    const existing = displayNamePending.get(key);
     if (existing)
         return existing;
-    const revision = displayNameRevision.get(normalizedAid) ?? 0;
+    const revision = displayNameRevision.get(key) ?? 0;
     let pending;
-    pending = agentmdGet(normalizedAid)
+    pending = agentmdGet(normalizedAid, { aunPath, store: opts?.store })
         .then(content => {
         const name = typeof content === 'string' ? parseAgentDisplayName(content) : undefined;
-        if ((displayNameRevision.get(normalizedAid) ?? 0) !== revision)
+        if ((displayNameRevision.get(key) ?? 0) !== revision)
             return undefined;
         if (name)
-            displayNameCache.set(normalizedAid, name);
+            displayNameCache.set(key, name);
         return name;
     })
         .catch(() => undefined)
         .finally(() => {
-        if (displayNamePending.get(normalizedAid) === pending) {
-            displayNamePending.delete(normalizedAid);
+        if (displayNamePending.get(key) === pending) {
+            displayNamePending.delete(key);
         }
     });
-    displayNamePending.set(normalizedAid, pending);
+    displayNamePending.set(key, pending);
     return pending;
 }
-export function invalidateAgentDisplayName(aid) {
+export function invalidateAgentDisplayName(aid, aunPath) {
     const normalizedAid = normalizeAid(aid);
     if (!normalizedAid)
         return;
-    displayNameCache.delete(normalizedAid);
-    displayNamePending.delete(normalizedAid);
-    displayNameRevision.set(normalizedAid, (displayNameRevision.get(normalizedAid) ?? 0) + 1);
+    if (aunPath !== undefined) {
+        const key = displayNameKey(normalizedAid, aunPath);
+        displayNameCache.delete(key);
+        displayNamePending.delete(key);
+        displayNameRevision.set(key, (displayNameRevision.get(key) ?? 0) + 1);
+        return;
+    }
+    const suffix = `\u0000${normalizedAid.toLowerCase()}`;
+    const keys = new Set([
+        ...displayNameCache.keys(),
+        ...displayNamePending.keys(),
+        ...displayNameRevision.keys(),
+    ]);
+    for (const key of keys) {
+        if (!key.endsWith(suffix))
+            continue;
+        displayNameCache.delete(key);
+        displayNamePending.delete(key);
+        displayNameRevision.set(key, (displayNameRevision.get(key) ?? 0) + 1);
+    }
 }
 export function buildInitialAgentMd(opts) {
     const agentName = opts.name?.trim() || opts.aid.split('.')[0];
-    const agentType = opts.type || 'ai';
+    // 未指定类型时用 DEFAULT_AGENT_TYPE（agent）；指定了就必须落在 AGENT_TYPES 白名单内。
+    // 大小写不敏感，写进 agent.md 的一律是归一化后的小写形式。
+    const requestedType = opts.type?.trim() || DEFAULT_AGENT_TYPE;
+    const typeError = validateAgentType(requestedType);
+    if (typeError)
+        throw new Error(`Invalid agent.md type: ${typeError}`);
+    const agentType = normalizeAgentType(requestedType) ?? DEFAULT_AGENT_TYPE;
     const description = opts.description?.trim() || DEFAULT_AGENT_DESCRIPTION;
     const rawTags = opts.tags?.length ? opts.tags : ['evolcore'];
     const tagErrors = validateAgentTags(rawTags);
@@ -155,8 +229,9 @@ function yamlDoubleQuote(value) {
 export function validateAgentMdFrontmatter(content, expectedAid) {
     const errors = [];
     const payload = stripAgentMdSignature(content);
-    if (Buffer.byteLength(payload, 'utf8') > 4 * 1024) {
-        errors.push('agent.md must not exceed 4KB before the signature block');
+    const payloadBytes = Buffer.byteLength(payload, 'utf8');
+    if (payloadBytes > AGENT_MD_MAX_PAYLOAD_BYTES) {
+        errors.push(`agent.md frontmatter and body must not exceed ${AGENT_MD_MAX_PAYLOAD_BYTES} bytes before the signature block (current: ${payloadBytes} bytes)`);
     }
     const frontmatter = payload.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
     if (!frontmatter)
@@ -185,15 +260,44 @@ export function validateAgentMdFrontmatter(content, expectedAid) {
     requiredString('name');
     requiredString('type');
     const version = requiredString('version');
-    const description = requiredString('description');
+    // description 是可选字段（fastaun ≥0.5.13 起不再要求非空）：缺失或空串都合法，
+    // 仅在实际提供时校验类型与长度，与 SDK 的 agent-md-schema 保持一致。
+    const rawDescription = values.description;
+    let description;
+    if (rawDescription !== undefined && rawDescription !== null) {
+        if (typeof rawDescription !== 'string') {
+            errors.push('agent.md frontmatter description must be a string');
+        }
+        else {
+            description = rawDescription.trim();
+        }
+    }
     if (expectedAid && aid && aid !== expectedAid) {
         errors.push(`agent.md frontmatter aid must match upload target ${expectedAid}`);
     }
     if (version && !/^\d+\.\d+\.\d+$/.test(version)) {
         errors.push('agent.md frontmatter version must use major.minor.patch format');
     }
-    if (description && description.length > 100) {
-        errors.push('agent.md frontmatter description must be at most 100 characters');
+    // 长度按 Unicode 码点计、且对未 trim 的原值计数——与 SDK 完全一致，
+    // 否则含 emoji 或尾随空格的名片会本地放行、上传才被拒。
+    if (typeof rawDescription === 'string') {
+        const length = codePointLength(rawDescription);
+        if (length > AGENT_DESCRIPTION_MAX_LENGTH) {
+            errors.push(`agent.md frontmatter description must be at most ${AGENT_DESCRIPTION_MAX_LENGTH} characters (current: ${length})`);
+        }
+    }
+    // avatar：SDK 有 256 字符上限，本地此前完全没校验。
+    const rawAvatar = values.avatar;
+    if (rawAvatar !== undefined && rawAvatar !== null) {
+        if (typeof rawAvatar !== 'string') {
+            errors.push('agent.md frontmatter avatar must be a string');
+        }
+        else {
+            const length = codePointLength(rawAvatar);
+            if (length > AGENT_AVATAR_MAX_LENGTH) {
+                errors.push(`agent.md frontmatter avatar must be at most ${AGENT_AVATAR_MAX_LENGTH} characters (current: ${length})`);
+            }
+        }
     }
     if (values.tags !== undefined) {
         const tagErrors = validateAgentTags(values.tags);
@@ -281,10 +385,10 @@ function verifyLocal(store, aid, content) {
     }
 }
 export async function agentmdGet(aid, opts) {
-    const aunPath = opts?.aunPath ?? resolveRoot();
+    const aunPath = resolveAgentMdAunPath(opts);
     const store = opts?.store ?? await getAidStore({ slotId: SLOT.cli, aunPath });
     const ownStore = !opts?.store;
-    const localPath = agentMdPath(aid);
+    const localPath = agentMdPath(aid, aunPath);
     try {
         let content;
         let verification;
@@ -294,6 +398,14 @@ export async function agentmdGet(aid, opts) {
             verification = normalizeVerification(r.data.verification);
         }
         else {
+            if (opts?.remoteOnly) {
+                const code = String(r.error?.code ?? '');
+                const message = String(r.error?.message ?? r.error);
+                if (code === 'AGENTMD_NOT_FOUND' || /not found|404|missing/i.test(message)) {
+                    throw Object.assign(new Error(`agent.md not found for ${aid}`), { code: 'AGENTMD_NOT_FOUND' });
+                }
+                throw new Error(`Remote agent.md verification unavailable for ${aid}`);
+            }
             // Network/fetch failed — fall back to local file.
             if (!fs.existsSync(localPath)) {
                 throw new Error(`fetch agent.md failed for ${aid}: ${r.error.message}`);
@@ -326,10 +438,10 @@ export async function agentmdPut(content, opts) {
     if (!validation.valid) {
         throw new Error(`invalid agent.md frontmatter: ${validation.errors.join('; ')}`);
     }
-    const aunPath = opts.aunPath ?? resolveRoot();
+    const aunPath = resolveAgentMdAunPath(opts);
     const store = opts.store ?? await getAidStore({ slotId: SLOT.cli, aunPath });
     const ownStore = !opts.store;
-    const dir = aidLocalDir(opts.aid);
+    const dir = aidLocalDir(opts.aid, aunPath);
     const filePath = path.join(dir, 'agent.md');
     const existed = fs.existsSync(filePath);
     // 先写本地文件（与旧行为一致：本地内容更新应在上传失败时仍保留）
@@ -370,10 +482,10 @@ export async function agentmdPut(content, opts) {
  * so a freshly-built store reports local_found=false and will fetch.
  */
 export async function agentmdSync(aid, opts) {
-    const aunPath = opts?.aunPath ?? resolveRoot();
+    const aunPath = resolveAgentMdAunPath(opts);
     const store = opts?.store ?? await getAidStore({ slotId: SLOT.cli, aunPath });
     const ownStore = !opts?.store;
-    const localPath = agentMdPath(aid);
+    const localPath = agentMdPath(aid, aunPath);
     try {
         // AIDStore owns the agent.md consistency API in fastaun 0.5.x.  Keep this
         // runtime guard because callers and test doubles can still accidentally
@@ -382,9 +494,11 @@ export async function agentmdSync(aid, opts) {
         if (typeof candidate.checkAgentMd !== 'function' || typeof candidate.downloadAgentMd !== 'function') {
             throw new TypeError('invalid AIDStore: checkAgentMd/downloadAgentMd unavailable');
         }
-        const check = await store.checkAgentMd(aid, 30);
+        // A change event can describe Last-Modified alone. Bypass the SDK's
+        // independent freshness cache when Core knows its snapshot is stale.
+        const check = opts?.forceRefresh ? undefined : await store.checkAgentMd(aid, opts?.ttlDays ?? 30);
         // In sync (cache fresh) — return local file content with cached verification status.
-        if (check.ok && !check.data.needs_update && check.data.local_found) {
+        if (check?.ok && !check.data.needs_update && check.data.local_found) {
             const content = fs.existsSync(localPath) ? fs.readFileSync(localPath, 'utf-8') : undefined;
             const verification = check.data.verify_status
                 ? normalizeVerification({ status: check.data.verify_status, reason: check.data.verify_error || undefined })
@@ -395,6 +509,7 @@ export async function agentmdSync(aid, opts) {
         // SDK's downloadAgentMd persists to disk internally (AgentMdManager.saveRecord → writeContent).
         const fetched = await store.downloadAgentMd(aid);
         if (fetched.ok) {
+            invalidateAgentDisplayName(aid);
             return { changed: true, content: fetched.data.content, verification: normalizeVerification(fetched.data.verification) };
         }
         // Fetch failed (network) — fall back to local file if present.

package/dist/aun/aid/client.js

@@ -39,7 +39,7 @@ export function suppressSdkLogs() {
     };
 }
 // ==================== SDK package ====================
-export const MIN_AUN_CORE_SDK = [0, 5, 6];
+export const MIN_AUN_CORE_SDK = [0, 5, 17];
 export const AUN_CORE_SDK_PKG = '@agentunion/fastaun';
 function compareVersion(a, min) {
     const parts = a.split('.').map(n => parseInt(n, 10));

package/dist/aun/aid/control-aid.js

@@ -1,10 +1,183 @@
 import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { parseDocument } from 'yaml';
 import { aidCreate } from './index.js';
 import { DEFAULT_AID_DOMAIN, normalizeAidDomain } from './domain.js';
 import { getAidStore, SLOT } from './store.js';
+import { validateAgentMdDocument, verifyAgentMdUpload } from '@agentunion/fastaun';
+import { agentMdPath, resolvePaths } from '../../paths.js';
+import { PeerIdentityCache } from '../../core/relation/peer-identity.js';
+import { agentmdPut, buildInitialAgentMd, invalidateAgentDisplayName, stripAgentMdSignature } from './agentmd.js';
 import { logger } from '../../utils/logger.js';
 const MAX_ATTEMPTS = 5;
 export { DEFAULT_AID_DOMAIN } from './domain.js';
+/** Human-facing platform label used in the control AID's agent.md name. */
+export function controlHostPlatformLabel(platform = process.platform) {
+    switch (String(platform).trim().toLowerCase()) {
+        case 'win32':
+        case 'windows':
+            return 'Win';
+        case 'linux':
+            return 'Linux';
+        case 'darwin':
+        case 'macos':
+        case 'mac':
+            return 'MacOS';
+        default: {
+            const value = String(platform).trim();
+            return value ? `${value[0].toUpperCase()}${value.slice(1)}` : 'Host';
+        }
+    }
+}
+/** Build the stable display name for a daemon/control AID. */
+export function buildControlAgentName(aid, platform = process.platform) {
+    const normalized = String(aid ?? '').trim().replace(/^@/, '');
+    const prefix = normalized.split('.', 1)[0] || normalized || 'unknown';
+    return `${controlHostPlatformLabel(platform)}主机-${prefix}`;
+}
+const CONTROL_AGENT_DESCRIPTION = 'EvolCore daemon host.';
+const CONTROL_AGENT_TAGS = ['evolcore', 'control', 'host'];
+const controlAgentMdPending = new Map();
+function readJsonFile(filePath) {
+    try {
+        const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasCanonicalControlFrontmatter(content, aid, name, aunRoot) {
+    try {
+        // A frontmatter-only match is insufficient here: an unsigned or malformed
+        // local card must be republished so the SDK can produce a valid signature.
+        validateAgentMdDocument(content, { expectedAid: aid, requireSignature: true });
+        const payload = stripAgentMdSignature(content);
+        const frontmatter = payload.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+        if (!frontmatter)
+            return false;
+        const document = parseDocument(frontmatter);
+        if (document.errors.length > 0)
+            return false;
+        const fields = document.toJS();
+        if (!fields || typeof fields !== 'object' || Array.isArray(fields))
+            return false;
+        const values = fields;
+        const canonical = typeof values.aid === 'string'
+            && values.aid.trim().toLowerCase() === aid.toLowerCase()
+            && typeof values.name === 'string'
+            && values.name.trim() === name
+            && typeof values.type === 'string'
+            && values.type.trim().toLowerCase() === 'host';
+        if (!canonical)
+            return false;
+        // The SDK validator checks that a signature block is well formed, but it
+        // deliberately does not verify the signature against the local cert.
+        // A damaged or stale control card must be republished, otherwise peers
+        // continue to reject it even though the frontmatter looks canonical.
+        const certPath = path.join(aunRoot, 'AIDs', aid, 'public', 'cert.pem');
+        const certPem = fs.readFileSync(certPath, 'utf8');
+        verifyAgentMdUpload(content, certPem, aid);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function clearControlAgentPeerCaches(aid, root = resolvePaths().root) {
+    const agentsDir = path.join(root, 'agents');
+    // A first-run installation may not have created any EvolCore agent yet.
+    // There is no cache to clear in that state, and ENOENT is not a warning.
+    if (!fs.existsSync(agentsDir))
+        return;
+    try {
+        for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            PeerIdentityCache.clear('aun', aid, path.join(agentsDir, entry.name));
+        }
+    }
+    catch (error) {
+        logger.warn(`[control-aid] 清理旧身份缓存失败（不影响名片发布）: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Ensure a daemon/control AID has a signed host agent.md.
+ *
+ * Registration in fastaun creates a default `type: agent` card. This helper
+ * upgrades that card, supplements cards missing on older installations, and
+ * is idempotent once the local card is canonical. Upload errors are allowed to
+ * propagate to the caller so startup can log them without becoming blocked.
+ */
+export async function ensureControlAgentMd(aid, opts = {}) {
+    const normalizedAid = String(aid ?? '').trim().replace(/^@/, '');
+    if (!normalizedAid)
+        throw new Error('control AID is required');
+    const aunRoot = opts.aunPath ?? opts.store?.aunPath ?? resolvePaths().root;
+    const cacheRoot = opts.cacheRoot ?? resolvePaths().root;
+    const pendingKey = path.resolve(aunRoot) + '\u0000' + normalizedAid.toLowerCase();
+    const pending = controlAgentMdPending.get(pendingKey);
+    if (pending)
+        return pending;
+    const run = (async () => {
+        const name = buildControlAgentName(normalizedAid, opts.platform);
+        const localPath = agentMdPath(normalizedAid, aunRoot);
+        const metadataPath = path.join(path.dirname(localPath), 'agentmd.json');
+        let existing;
+        try {
+            existing = fs.readFileSync(localPath, 'utf8');
+        }
+        catch { /* missing */ }
+        const metadata = readJsonFile(metadataPath);
+        const remoteMissing = String(metadata?.remote_status ?? '').trim().toLowerCase() === 'missing';
+        const needsPublish = !existing || !hasCanonicalControlFrontmatter(existing, normalizedAid, name, aunRoot) || remoteMissing;
+        if (!needsPublish)
+            return { aid: normalizedAid, name, published: false };
+        const content = buildInitialAgentMd({
+            aid: normalizedAid,
+            name,
+            type: 'host',
+            description: CONTROL_AGENT_DESCRIPTION,
+            tags: CONTROL_AGENT_TAGS,
+        });
+        try {
+            await agentmdPut(content, { aid: normalizedAid, store: opts.store, aunPath: aunRoot });
+        }
+        catch (error) {
+            // agentmdPut intentionally keeps edits to an existing card on failure;
+            // a control-card migration must restore the old card so a transient
+            // gateway failure cannot make the local state look successfully migrated.
+            try {
+                if (existing !== undefined) {
+                    fs.mkdirSync(path.dirname(localPath), { recursive: true });
+                    fs.writeFileSync(localPath, existing, 'utf8');
+                }
+                else {
+                    fs.unlinkSync(localPath);
+                }
+            }
+            catch { /* preserve the original upload error */ }
+            throw error;
+        }
+        // The upload changes the control AID's display name. Drop the process-wide
+        // name cache so subsequent context/status rendering cannot keep the legacy
+        // `agent` name until the normal TTL refresh.
+        invalidateAgentDisplayName(normalizedAid);
+        clearControlAgentPeerCaches(normalizedAid, cacheRoot);
+        return { aid: normalizedAid, name, published: true };
+    })();
+    controlAgentMdPending.set(pendingKey, run);
+    try {
+        return await run;
+    }
+    finally {
+        if (controlAgentMdPending.get(pendingKey) === run)
+            controlAgentMdPending.delete(pendingKey);
+    }
+}
 function environmentValue(name) {
     if (!Object.prototype.hasOwnProperty.call(process.env, name))
         return undefined;
@@ -66,7 +239,7 @@ async function candidateExists(store, candidate) {
  * 查重通过但注册失败时也换候选重试，覆盖查重与注册之间的竞态。
  * - 查重走 GET 证书（见 candidateExists；不拉 agent.md，控制 AID 本就不传 agent.md）
  * - fail-fast：查重探测失败（网关不可达）立即抛错，不掩盖成"均冲突"
- * - agent.md 不上传：aidCreate 仅注册身份 + 写私钥，不调 agentmdPut
+ * - 注册后补发控制主机 agent.md；失败只告警，不丢弃已经注册的 AID
  */
 export async function generateControlAid(aidDomain) {
     const finalAidDomain = aidDomain === undefined
@@ -83,6 +256,12 @@ export async function generateControlAid(aidDomain) {
             }
             try {
                 const created = await aidCreate(candidate);
+                try {
+                    await ensureControlAgentMd(created.aid, { store: created.store });
+                }
+                catch (e) {
+                    logger.warn(`[control-aid] ${created.aid} agent.md 发布失败（控制面可继续，后续启动会重试）: ${e instanceof Error ? e.message : String(e)}`);
+                }
                 // 清理 aidCreate 内部另开的 client/store——关闭失败不可丢弃已注册的 AID（否则下次 init
                 // 会把它当冲突，白白消耗一次重试）。close 异常降级为 warn。
                 try {

package/dist/aun/aid/identity.js

@@ -76,7 +76,7 @@ export function aidList(aunPath) {
                     canSign: hasPrivateKey && hasCert && !certExpired && keyMatchesCert === true,
                 }),
                 hasPrivateKey,
-                hasAgentMd: fs.existsSync(agentMdPath(e.name)),
+                hasAgentMd: fs.existsSync(agentMdPath(e.name, root)),
                 hasCert,
                 certExpired,
                 keyMatchesCert,
@@ -114,7 +114,7 @@ export async function verifySignAbility(aid, opts) {
         // signAgentMd validates the same frontmatter contract as a published agent.md.
         // Keep the probe minimal, but make it a valid document so self-checks do not
         // reject otherwise healthy identities before exercising sign + verify.
-        const probe = `---\naid: "${aid}"\nname: "probe"\ntype: "ai"\nversion: "1.0.0"\ndescription: "Local signing self-check"\ntags:\n  - evolcore\n---\n`;
+        const probe = `---\naid: "${aid}"\nname: "probe"\ntype: "agent"\nversion: "1.0.0"\ndescription: "Local signing self-check"\ntags:\n  - evolcore\n---\n`;
         const signRes = aidObj.signAgentMd(probe);
         if (!signRes.ok) {
             return { ok: false, reason: `sign failed: ${String(signRes.error?.message || signRes.error?.code).slice(0, 120)}` };
@@ -265,7 +265,7 @@ export async function aidShow(aid, opts) {
     const aunPath = opts?.aunPath ?? defaultAunPath();
     const aidDir = path.join(aunPath, 'AIDs', aid);
     const hasPrivateKey = fs.existsSync(path.join(aidDir, 'private'));
-    const hasAgentMd = fs.existsSync(agentMdPath(aid));
+    const hasAgentMd = fs.existsSync(agentMdPath(aid, aunPath));
     let certExpiresAt = null;
     let certSubject = null;
     let certExpired = false;
@@ -323,7 +323,7 @@ export async function aidShow(aid, opts) {
         }
         if (hasAgentMd) {
             try {
-                const content = fs.readFileSync(agentMdPath(aid), 'utf-8');
+                const content = fs.readFileSync(agentMdPath(aid, aunPath), 'utf-8');
                 if (!content.includes('AUN-SIGNATURE')) {
                     agentMdSignature = 'unsigned';
                 }

package/dist/aun/aid/index.js

@@ -1,5 +1,5 @@
 export { AGENT_TAG_MIN_COUNT, AGENT_TAG_MAX_COUNT, AGENT_TAG_MAX_LENGTH, validateAgentTag, validateAgentTags, } from './agentmd.js';
 export { isValidAid, aidList, aidListVerified, aidCreate, aidShow, aidDelete, aidLookup, verifySignAbility, probePkiRecoverability, appendAidLifecycle, readAidLifecycle } from './identity.js';
-export { DEFAULT_AGENT_DESCRIPTION, buildInitialAgentMd, validateAgentMdFrontmatter, agentmdGet, agentmdPut, agentmdSync, invalidateAgentDisplayName, parseAgentDisplayName, refreshAgentDisplayName, resolveAgentDisplayName, stripAgentMdSignature, updateAgentMdFrontmatterAvatar, updateAgentMdFrontmatterName, } from './agentmd.js';
+export { AGENT_TYPES, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_TYPE, normalizeAgentType, validateAgentType, buildInitialAgentMd, validateAgentMdFrontmatter, agentmdGet, agentmdPut, agentmdSync, invalidateAgentDisplayName, parseAgentDisplayName, refreshAgentDisplayName, resolveAgentDisplayName, stripAgentMdSignature, updateAgentMdFrontmatterAvatar, updateAgentMdFrontmatterName, } from './agentmd.js';
 export { MIN_AUN_CORE_SDK, AUN_CORE_SDK_PKG, isAunSdkVersionOk, resolveAunCoreSdkPkg, ensureAunSdk, isAunSdkReady, downloadCaRoot, suppressSdkLogs, } from './client.js';
 export { getAidStore, loadClient, loadAid, AidLoadError, SLOT } from './store.js';

package/dist/aun/aid/store.js

@@ -80,10 +80,10 @@ export async function loadClient(store, aid) {
 /**
  * Enable bounded multi-page group pulls for the long-lived daemon client.
  *
- * The SDK's background realtime recovery path intentionally passes
- * `maxPages=1`; for a daemon this can strand a backlog after a tail sync.
- * This adapter only expands that sentinel value and leaves all other pull
- * options unchanged. It is isolated to the client that explicitly opts in.
+ * Older SDK recovery paths used `maxPages=1`; for a daemon that can strand a
+ * backlog after a tail sync. SDK 0.5.15 normally chooses a larger recovery
+ * window, but this adapter still expands an explicit single-page request and
+ * keeps older clients safe. It is isolated to the client that opts in.
  */
 export function enableFullGroupPullPagination(client) {
     const target = client;
@@ -110,13 +110,12 @@ export function enableFullGroupPullPagination(client) {
 /**
  * Make SDK pull delivery wait until EvolCore's application handlers finish.
  *
- * fastaun 0.5.13 publishes message events with dispatcher.enqueue(), then
- * advances its sequence tracker immediately.  That is a transport watermark,
- * so a daemon restart can acknowledge a message before the application has
- * durably claimed it.  The SDK keeps _publishAppEvent private, but the public
- * client is intentionally adapted here in one place: preserve the SDK's
- * normal publication path and wait for its dispatcher queue for pulled
- * message events before the pull operation commits the sequence.
+ * fastaun publishes message events asynchronously, while the sequence tracker
+ * is a transport watermark. A daemon restart can therefore acknowledge a
+ * pulled message before the application has durably claimed it. SDK 0.5.15
+ * split protocol and application queues; prefer its application-only flush so
+ * an unrelated protocol event cannot delay the pull commit. Older SDKs fall
+ * back to the combined flush method.
  */
 export function enableReliableMessageDelivery(client) {
     const target = client;
@@ -124,7 +123,12 @@ export function enableReliableMessageDelivery(client) {
         return false;
     const publish = target._publishAppEvent;
     const dispatcher = target._dispatcher;
-    if (typeof publish !== 'function' || !dispatcher || typeof dispatcher.flush !== 'function')
+    const flushApplication = typeof dispatcher?.flushApplication === 'function'
+        ? dispatcher.flushApplication.bind(dispatcher)
+        : typeof dispatcher?.flush === 'function'
+            ? dispatcher.flush.bind(dispatcher)
+            : undefined;
+    if (typeof publish !== 'function' || !flushApplication)
         return false;
     const wrappedPublish = async function (event, payload, source, ...rest) {
         const result = await publish.call(this, event, payload, source, ...rest);
@@ -135,7 +139,7 @@ export function enableReliableMessageDelivery(client) {
             && source !== 'push'
             && source !== 'inline-push';
         if (reliable)
-            await dispatcher.flush();
+            await flushApplication();
         return result;
     };
     Object.defineProperty(target, RELIABLE_MESSAGE_DELIVERY_PATCH, {