evolcore 0.0.1 → 0.0.2

package/dist/cli/agent.js

@@ -0,0 +1,1059 @@
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+import { resolvePaths, agentMdPath as getAgentMdPathFromPaths, aunPath as defaultAunPath } from '../paths.js';
+import { loadDefaults, loadAllAgents, loadAgent, saveAgent, ensureAgentDirSkeleton } from '../config-store.js';
+import { ConfigTarget, write as cfgWrite, ensureFile as cfgEnsure, read as cfgRead, initConfigManager } from '../config/config-manager.js';
+import { resolveConfigCommand } from '../config/resolved-config-op.js';
+import { executeResolvedConfigCommand } from '../config/config-operation-service.js';
+import { ipcQuery } from '../ipc.js';
+import { CONFIG_SCHEMA_VERSION } from '../types.js';
+import { withLifecycleForWrite } from '../config/lifecycle.js';
+import { ensureInitialRoleRegistry } from '../config/role-service.js';
+import { isValidChannelName } from '../core/channel-loader.js';
+import { commandExists } from '../utils/cross-platform.js';
+import { getCodexAppServerAvailability, isCodexAppServerAvailable } from '../agents/codex-runner.js';
+import { agentProjectRootFromDefaults, deriveAgentProjectPath } from '../utils/project-path.js';
+import { AGENT_DELEGATION_TOKEN_ENV } from '../core/auth/agent-delegation.js';
+function withStaticOwner(config, owner) {
+    const value = owner?.trim();
+    if (!value)
+        return config;
+    const owners = config.owners ?? [];
+    if (owners.includes(value))
+        return config;
+    return { ...config, owners: [...owners, value] };
+}
+// ==================== Helpers ====================
+const BASEAGENT_CANDIDATES = ['claude', 'codex', 'gemini'];
+function isBaseagentAvailable(baseagent) {
+    if (baseagent === 'codex')
+        return isCodexAppServerAvailable();
+    return commandExists(baseagent);
+}
+function detectAvailableBaseagents() {
+    return BASEAGENT_CANDIDATES.filter(isBaseagentAvailable);
+}
+function pickDefaultBaseagent(available) {
+    if (available.length === 0)
+        return null;
+    return available.includes('claude') ? 'claude' : available[0];
+}
+function buildBaseagentsBlock(chosen) {
+    return { [chosen]: {} };
+}
+const DEFAULT_CHATMODE = { private: 'interactive', group: 'proactive', nothuman: 'proactive' };
+/**
+ * 写入新 agent 的初始配置（所有字段统一在 config.json）。
+ * mentionMode 不写初始值，继承 schema 出厂默认（disabled）。
+ */
+function saveInitialBehavior(aid, baseagent) {
+    const behavior = {
+        active_baseagent: baseagent,
+        baseagents: buildBaseagentsBlock(baseagent),
+        chatmode: { ...DEFAULT_CHATMODE },
+    };
+    const sel = { self: aid };
+    const existingBehavior = cfgRead(ConfigTarget.Agent, sel) || {};
+    cfgEnsure(ConfigTarget.Agent, sel);
+    cfgWrite(ConfigTarget.Agent, { ...existingBehavior, ...behavior }, sel);
+}
+function readAgentMdIdentity(aid) {
+    const agentMdFilePath = getAgentMdPathFromPaths(aid);
+    try {
+        if (!fs.existsSync(agentMdFilePath))
+            return { name: null, description: null };
+        const content = fs.readFileSync(agentMdFilePath, 'utf-8');
+        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch)
+            return { name: null, description: null };
+        const fm = fmMatch[1];
+        const nameMatch = fm.match(/^name:\s*["']?(.+?)["']?\s*$/m);
+        const descMatch = fm.match(/^description:\s*["']?(.+?)["']?\s*$/m);
+        return {
+            name: nameMatch?.[1]?.trim() || null,
+            description: descMatch?.[1]?.trim() || null,
+        };
+    }
+    catch {
+        return { name: null, description: null };
+    }
+}
+function getAgentMdPath(aid) {
+    return getAgentMdPathFromPaths(aid);
+}
+/** Normalize path separators to forward slashes for cross-platform consistent display. */
+function toPosix(p) {
+    if (!p)
+        return null;
+    return p.replace(/\\/g, '/');
+}
+// ==================== agentList ====================
+export async function agentList() {
+    const p = resolvePaths();
+    // Try IPC first (running process has real status)
+    try {
+        const result = await ipcQuery(p.socket, { type: 'evolagent.list' });
+        if (result && result.ok && result.agents) {
+            const agents = result.agents.map((info) => ({
+                aid: info.aid || info.name,
+                name: info.name,
+                personalName: info.personalName || null,
+                status: info.status || 'stopped',
+                channels: info.channels || [],
+                projectPath: toPosix(info.projectPath || null),
+                baseagent: info.baseagent || null,
+                model: info.model || null,
+                lastActivity: info.lastActivity || null,
+            }));
+            return { ok: true, agents };
+        }
+    }
+    catch { }
+    // Cold mode: read from disk
+    const { EvolAgentRegistry } = await import('../core/evolagent-registry.js');
+    const registry = new EvolAgentRegistry(p.agentsDir);
+    registry.loadAll();
+    const agents = registry.list().map((info) => ({
+        aid: info.aid || info.name,
+        name: info.name,
+        personalName: info.personalName || null,
+        status: info.status || 'stopped',
+        channels: info.channels || [],
+        projectPath: toPosix(info.projectPath || null),
+        baseagent: info.baseagent || null,
+        model: info.model || null,
+        lastActivity: info.lastActivity || null,
+    }));
+    return { ok: true, agents };
+}
+// ==================== agentShow ====================
+export async function agentShow(aid) {
+    const p = resolvePaths();
+    let agentInfo = null;
+    let connectionInfo = null;
+    // Try IPC for live data
+    try {
+        const [showResp, aidsResp, statsResp] = await Promise.all([
+            ipcQuery(p.socket, { type: 'evolagent.show', name: aid }),
+            ipcQuery(p.socket, { type: 'aun-aids' }),
+            ipcQuery(p.socket, { type: 'aun-aid-stats' }),
+        ]);
+        if (showResp?.ok && showResp.agent) {
+            agentInfo = showResp.agent;
+        }
+        // Build connection info from aun-aids + aun-aid-stats (same source as watch aid)
+        if (aidsResp?.ok && aidsResp.aids) {
+            const aidEntry = aidsResp.aids.find((a) => a.aid === aid);
+            if (aidEntry) {
+                const stats = statsResp?.ok && statsResp.stats
+                    ? statsResp.stats.find((s) => s.aid === aid)
+                    : null;
+                const now = Date.now();
+                connectionInfo = {
+                    status: aidEntry.status || 'unknown',
+                    uptime_ms: (aidEntry.status === 'connected' && aidEntry.lastConnectedAt)
+                        ? now - aidEntry.lastConnectedAt : null,
+                    reconnect_count: aidEntry.reconnectCount ?? 0,
+                    messages_received: stats?.messagesReceived ?? 0,
+                    messages_sent: stats?.messagesSent ?? 0,
+                    bytes_received: stats?.bytesReceived ?? 0,
+                    bytes_sent: stats?.bytesSent ?? 0,
+                    last_received_at: stats?.lastReceivedAt ? new Date(stats.lastReceivedAt).toISOString() : null,
+                    last_sent_at: stats?.lastSentAt ? new Date(stats.lastSentAt).toISOString() : null,
+                    unique_peer_count: stats?.uniquePeerCount ?? 0,
+                };
+            }
+        }
+    }
+    catch { }
+    // Cold mode fallback for agent info
+    if (!agentInfo) {
+        const { EvolAgentRegistry } = await import('../core/evolagent-registry.js');
+        const registry = new EvolAgentRegistry(p.agentsDir);
+        registry.loadAll();
+        const agent = registry.get(aid);
+        if (!agent) {
+            const allList = registry.list();
+            const available = allList.map((i) => i.name).join(', ');
+            return { ok: false, error: `Agent "${aid}" not found.${available ? ` Available: ${available}` : ''}` };
+        }
+        agentInfo = {
+            name: agent.name,
+            aid: agent.aid || agent.name,
+            status: agent.status,
+            baseagent: agent.baseagent,
+            model: agent.model,
+            effort: agent.effort,
+            projectPath: agent.projectPath,
+            channels: agent.channelInstanceNames?.() || [],
+            activeSessions: agent.activeSessions || 0,
+            lastActivity: agent.lastActivity || null,
+            error: agent.error,
+            chatmode: agent.config?.chatmode || null,
+        };
+    }
+    const identity = readAgentMdIdentity(aid);
+    const agentMdPath = getAgentMdPath(aid);
+    return {
+        ok: true,
+        aid,
+        status: agentInfo.status || 'stopped',
+        identity,
+        config: {
+            baseagent: agentInfo.baseagent || null,
+            model: agentInfo.model || null,
+            effort: agentInfo.effort || null,
+            chatmode: agentInfo.chatmode || null,
+            channels: agentInfo.channels || [],
+        },
+        connection: connectionInfo,
+        sessions: {
+            active: agentInfo.activeSessions || 0,
+            last_activity: agentInfo.lastActivity ? new Date(agentInfo.lastActivity).toISOString() : null,
+        },
+        paths: {
+            config: toPosix(path.join(p.agentsDir, aid, 'config.json')),
+            agent_md: toPosix(agentMdPath),
+            project: toPosix(agentInfo.projectPath || null),
+            data: toPosix(path.join(p.agentsDir, aid, 'data')),
+        },
+    };
+}
+export async function agentCreateInteractive(opts = {}) {
+    const p = resolvePaths();
+    const ownRl = !opts.rl;
+    const rl = opts.rl ?? readline.createInterface({
+        input: opts.stdin || process.stdin,
+        output: opts.stdout || process.stdout,
+    });
+    const ask = (q) => new Promise(r => rl.question(q, r));
+    try {
+        const { isValidAid, aidCreate } = await import('../aun/aid/index.js');
+        const aidPrompt = opts.suggestedName
+            ? `AID [${opts.suggestedName}]: `
+            : 'AID (e.g. mybot.agentid.pub): ';
+        let aid = '';
+        while (!aid) {
+            const aidInput = (await ask(aidPrompt)).trim();
+            const candidate = aidInput || opts.suggestedName;
+            if (!candidate) {
+                console.log('  ⚠ AID is required.');
+                continue;
+            }
+            if (!isValidAid(candidate)) {
+                console.log(`  ⚠ Invalid AID "${candidate}": must be a valid multi-level domain (e.g. mybot.agentid.pub)`);
+                continue;
+            }
+            aid = candidate;
+        }
+        const agentDirPath = path.join(p.agentsDir, aid);
+        const configExists = fs.existsSync(path.join(agentDirPath, 'config.json'));
+        if (configExists) {
+            const ans = (await ask(`Agent "${aid}" already exists. Overwrite config.json? (AID 与 agent.md 保留) [y/N]: `)).trim().toLowerCase();
+            if (ans !== 'y' && ans !== 'yes') {
+                return { ok: false, error: 'Aborted.' };
+            }
+        }
+        console.log(`\nCreating agent: ${aid}\n`);
+        let aidCreated = false;
+        try {
+            const result = await aidCreate(aid);
+            try {
+                await result.client.close();
+            }
+            catch { /* ignore */ }
+            aidCreated = !result.alreadyExisted;
+            console.log(`  ✓ AID ${result.alreadyExisted ? 'reused' : 'created'}: ${aid}`);
+        }
+        catch (e) {
+            return { ok: false, error: `AID creation failed: ${e?.message || e}` };
+        }
+        // Project path
+        let suggestedProjectPath = '';
+        try {
+            const defaults = loadDefaults();
+            const rootPath = agentProjectRootFromDefaults(defaults, p.root);
+            suggestedProjectPath = deriveAgentProjectPath(rootPath, aid);
+        }
+        catch {
+            suggestedProjectPath = deriveAgentProjectPath(agentProjectRootFromDefaults(null, p.root), aid);
+        }
+        const projectInput = (await ask(`Project path [${suggestedProjectPath}]: `)).trim();
+        const projectPath = projectInput || suggestedProjectPath;
+        if (!path.isAbsolute(projectPath)) {
+            return { ok: false, error: 'Project path must be an absolute path.' };
+        }
+        if (!fs.existsSync(projectPath)) {
+            const create = (await ask(`Project path does not exist. Create? [Y/n]: `)).trim().toLowerCase();
+            if (create === '' || create === 'y' || create === 'yes') {
+                try {
+                    fs.mkdirSync(projectPath, { recursive: true });
+                }
+                catch (e) {
+                    return { ok: false, error: `Failed to create project path "${projectPath}": ${e?.message || e}` };
+                }
+                console.log(`  ✓ Created ${projectPath}`);
+            }
+            else {
+                return { ok: false, error: 'Aborted.' };
+            }
+        }
+        // Baseagent
+        const available = detectAvailableBaseagents();
+        if (available.length === 0) {
+            return { ok: false, error: `No usable baseagent detected. Install claude/gemini CLI or codex CLI with app-server.` };
+        }
+        const defaultBa = pickDefaultBaseagent(available);
+        let baseagent;
+        if (available.length === 1) {
+            console.log(`  Baseagent: ${defaultBa}`);
+            baseagent = defaultBa;
+        }
+        else {
+            let chosen = null;
+            while (chosen === null) {
+                const input = (await ask(`Baseagent (${available.join('/')}) [${defaultBa}]: `)).trim() || defaultBa;
+                if (!BASEAGENT_CANDIDATES.includes(input)) {
+                    console.log(`  Invalid choice. Options: ${BASEAGENT_CANDIDATES.join('/')}`);
+                    continue;
+                }
+                if (!available.includes(input)) {
+                    console.log(`  ${input} is not available in the current environment. Available: ${available.join('/')}`);
+                    continue;
+                }
+                chosen = input;
+            }
+            baseagent = chosen;
+        }
+        // Owner: only prompt if daemon (daemon.json) has owners configured.
+        // If daemon has no owner, agent owner is meaningless and should be skipped entirely.
+        const { loadDaemonConfig } = await import('../config-store.js');
+        const daemonCfg = loadDaemonConfig();
+        const daemonHasOwner = daemonCfg.owners && daemonCfg.owners.length > 0;
+        let owner;
+        let skipQrBinding = false;
+        if (daemonHasOwner) {
+            const defaultOwner = daemonCfg.owners[0];
+            while (true) {
+                const prompt = `Owner AID [${defaultOwner}]: `;
+                const ownerInput = (await ask(prompt)).trim();
+                // User pressed Enter - use default owner
+                if (!ownerInput) {
+                    owner = defaultOwner;
+                    break;
+                }
+                // User entered "new" or "qr" - trigger QR binding flow
+                if (ownerInput.toLowerCase() === 'new' || ownerInput.toLowerCase() === 'qr') {
+                    owner = undefined;
+                    skipQrBinding = false;
+                    break;
+                }
+                // User entered a specific AID - validate and use it
+                if (!isValidAid(ownerInput)) {
+                    console.log(`  ⚠ Invalid Owner AID "${ownerInput}": must be a valid multi-level domain (e.g. alice.agentid.pub)`);
+                    console.log(`  提示: 直接回车使用 ${defaultOwner}，输入 "new" 扫码绑定新 AID`);
+                    continue;
+                }
+                owner = ownerInput;
+                skipQrBinding = true; // Skip QR if user manually entered an AID
+                break;
+            }
+        }
+        // Name + description for agent.md
+        const defaultName = aid.split('.')[0];
+        const agentName = (await ask(`Display name [${defaultName}]: `)).trim() || defaultName;
+        const agentDescription = (await ask('Description (optional): ')).trim() || '';
+        if (ownRl)
+            rl.close();
+        const agentConfig = withStaticOwner({
+            $schema_version: CONFIG_SCHEMA_VERSION,
+            aid,
+            enabled: true,
+            lifecycle: 'created',
+            channels: [],
+            projects: { defaultPath: projectPath },
+        }, owner);
+        saveAgent(agentConfig);
+        ensureInitialRoleRegistry(aid);
+        saveInitialBehavior(aid, baseagent);
+        ensureAgentDirSkeleton(aid);
+        // Generate and upload agent.md
+        let agentmdUploaded = false;
+        try {
+            const { buildInitialAgentMd, agentmdPut } = await import('../aun/aid/index.js');
+            let content = buildInitialAgentMd({ aid });
+            content = content.replace(/^name:\s*".*?"$/m, `name: "${agentName}"`);
+            if (agentDescription) {
+                content = content.replace(/^description:\s*".*?"$/m, `description: "${agentDescription}"`);
+            }
+            const aunPath = process.env.AUN_HOME || defaultAunPath();
+            // agentmdPut 会写本地文件到 agentMdPath(aid) 并调用 publishAgentMd
+            // Upload with retry (3 attempts, 2s delay between retries)
+            const MAX_ATTEMPTS = 3;
+            const RETRY_DELAY_MS = 2000;
+            let lastError;
+            for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+                try {
+                    if (attempt > 1) {
+                        process.stdout.write(`  ↻ agent.md 上传重试 (${attempt}/${MAX_ATTEMPTS})...\n`);
+                        await new Promise(r => setTimeout(r, RETRY_DELAY_MS));
+                    }
+                    await agentmdPut(content, { aid, aunPath });
+                    agentmdUploaded = true;
+                    break;
+                }
+                catch (e) {
+                    lastError = e;
+                }
+            }
+            if (!agentmdUploaded) {
+                console.warn(`  ⚠ agent.md upload failed: ${lastError?.message || lastError}`);
+                console.warn(`  → Retry later with: ec aid agentmd put ${aid}`);
+            }
+            // Yield to allow the SDK WebSocket to fully close before IPC
+            await new Promise(r => setTimeout(r, 0));
+        }
+        catch (e) {
+            console.warn(`  ⚠ agent.md generation failed: ${e?.message || e}`);
+        }
+        // Attempt hot-load via IPC (if daemon is running).
+        // Cold-starting a new agent (connecting AUN WebSocket) routinely takes
+        // >3s, so use a generous timeout to avoid a false "service not running"
+        // report while the daemon actually finishes bringing the agent online.
+        let hotLoaded = false;
+        let hotLoadError;
+        try {
+            const ipcResult = await ipcQuery(p.socket, { type: 'evolagent.load', aid }, 30_000);
+            if (ipcResult?.ok) {
+                hotLoaded = true;
+            }
+            else if (ipcResult) {
+                hotLoadError = ipcResult.error;
+            }
+        }
+        catch { /* daemon not running */ }
+        let ownerBoundAid;
+        let ownerBindSkipped = false;
+        // Only prompt for agent owner binding if:
+        // 1. User didn't manually input owner during setup (owner is undefined)
+        // 2. User didn't skip QR binding explicitly (skipQrBinding is false)
+        // 3. We're in an interactive terminal
+        // 4. The daemon (daemon.json) has at least one owner configured
+        if (!owner && !skipQrBinding && process.stdin.isTTY && daemonHasOwner) {
+            console.log('\n📡 Agent owner 绑定 — 请用 evol app 扫描二维码，10 分钟内有效\n');
+            try {
+                const { runAgentOwnerQrBindFlow } = await import('./init-channel.js');
+                const bound = await runAgentOwnerQrBindFlow(aid, agentName, 'append');
+                if (bound?.boundAid) {
+                    ownerBoundAid = bound.boundAid;
+                    console.log(`  ✓ 已配置 agent owner: ${bound.boundAid}`);
+                }
+                else {
+                    ownerBindSkipped = true;
+                    ownerBoundAid = await promptAgentOwnerManually(aid);
+                }
+            }
+            catch (e) {
+                ownerBindSkipped = true;
+                console.log(`  ⚠ 扫码绑定不可用: ${e?.message || e}`);
+                ownerBoundAid = await promptAgentOwnerManually(aid);
+            }
+        }
+        return {
+            ok: true,
+            aid,
+            configPath: toPosix(path.join(agentDirPath, 'config.json')),
+            aidCreated,
+            agentmdUploaded,
+            hotLoaded,
+            hotLoadError,
+            ownerBoundAid,
+            ownerBindSkipped,
+        };
+    }
+    finally {
+        if (ownRl) {
+            try {
+                rl.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+async function promptAgentOwnerManually(aid) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        while (true) {
+            const raw = await new Promise(resolve => rl.question('\n扫码未完成。手动输入 agent owner AID（留空跳过）: ', resolve));
+            const owner = raw.trim();
+            if (!owner) {
+                console.log('  已跳过 agent owner 配置');
+                return undefined;
+            }
+            const { isValidAid } = await import('../aun/aid/index.js');
+            if (!isValidAid(owner)) {
+                console.log('  ⚠ Owner AID 格式无效（需合法多级域名，如 alice.agentid.pub）');
+                continue;
+            }
+            const agent = loadAgent(aid);
+            if (!agent) {
+                console.log(`  ⚠ 无法加载 agent 配置: ${aid}`);
+                return undefined;
+            }
+            saveAgent(withStaticOwner(agent, owner));
+            try {
+                const result = await ipcQuery(resolvePaths().socket, { type: 'evolagent.reload', name: aid }, 30_000);
+                if (result?.ok)
+                    console.log('  ✓ agent owner 已热重载');
+            }
+            catch { /* daemon not running */ }
+            console.log(`  ✓ 已配置 agent owner: ${owner}`);
+            return owner;
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function agentCreateNonInteractive(opts) {
+    const p = resolvePaths();
+    const { isValidAid, aidCreate } = await import('../aun/aid/index.js');
+    opts.onPhase?.('validating', 'begin');
+    /** 校验失败：透出 failed 进度并返回原结构（控制流不变）。 */
+    const failValidating = (error) => {
+        opts.onPhase?.('validating', 'failed', error);
+        return { ok: false, error };
+    };
+    if (!isValidAid(opts.aid)) {
+        return failValidating(`Invalid AID "${opts.aid}": must be a valid multi-level domain (e.g. mybot.agentid.pub)`);
+    }
+    const agentDirPath = path.join(p.agentsDir, opts.aid);
+    const configExists = fs.existsSync(path.join(agentDirPath, 'config.json'));
+    if (configExists && !opts.force) {
+        return failValidating(`Agent "${opts.aid}" already exists: ${agentDirPath}/config.json (use --force to overwrite)`);
+    }
+    // Baseagent
+    const available = detectAvailableBaseagents();
+    if (available.length === 0) {
+        return failValidating(`No usable baseagent detected. Install claude/gemini CLI or codex CLI with app-server.`);
+    }
+    let baseagent;
+    if (opts.baseagent) {
+        if (!BASEAGENT_CANDIDATES.includes(opts.baseagent)) {
+            return failValidating(`Invalid baseagent: ${opts.baseagent} (options: ${BASEAGENT_CANDIDATES.join('/')})`);
+        }
+        if (!available.includes(opts.baseagent)) {
+            const reason = opts.baseagent === 'codex'
+                ? getCodexAppServerAvailability().reason
+                : undefined;
+            return failValidating(reason || `${opts.baseagent} is not available in the current environment (available: ${available.join('/')})`);
+        }
+        baseagent = opts.baseagent;
+    }
+    else {
+        baseagent = pickDefaultBaseagent(available);
+    }
+    if (!path.isAbsolute(opts.project)) {
+        return failValidating(`--project must be absolute: ${opts.project}`);
+    }
+    if (!fs.existsSync(opts.project)) {
+        try {
+            fs.mkdirSync(opts.project, { recursive: true });
+        }
+        catch (e) {
+            return failValidating(`Failed to create ${opts.project}: ${e?.message || e}`);
+        }
+    }
+    if (opts.owner && !isValidAid(opts.owner)) {
+        return failValidating(`Invalid owner: ${opts.owner}`);
+    }
+    opts.onPhase?.('validating', 'done');
+    // Register AID
+    opts.onPhase?.('registering_aid', 'begin');
+    let aidCreated = false;
+    try {
+        const result = await aidCreate(opts.aid);
+        try {
+            await result.client.close();
+        }
+        catch { /* ignore */ }
+        aidCreated = !result.alreadyExisted;
+        opts.onPhase?.('registering_aid', 'done', aidCreated ? 'created' : 'existed');
+    }
+    catch (e) {
+        const error = `AID creation failed: ${e?.message || e}`;
+        opts.onPhase?.('registering_aid', 'failed', error);
+        return { ok: false, error };
+    }
+    // Force 模式下若 agent 已存在，保留生命周期（避免重复 bootstrap/welcome）。
+    let preservedLifecycle = 'created';
+    if (configExists) {
+        try {
+            const existing = loadAgent(opts.aid);
+            if (existing?.lifecycle)
+                preservedLifecycle = existing.lifecycle;
+        }
+        catch { /* ignore */ }
+    }
+    const agentConfig = withStaticOwner({
+        $schema_version: CONFIG_SCHEMA_VERSION,
+        aid: opts.aid,
+        enabled: true,
+        lifecycle: preservedLifecycle,
+        channels: [],
+        projects: { defaultPath: opts.project },
+    }, opts.owner);
+    opts.onPhase?.('config_saved', 'begin');
+    saveAgent(agentConfig);
+    ensureInitialRoleRegistry(opts.aid);
+    saveInitialBehavior(opts.aid, baseagent);
+    ensureAgentDirSkeleton(opts.aid);
+    opts.onPhase?.('config_saved', 'done');
+    // Generate and upload agent.md
+    opts.onPhase?.('uploading_agentmd', 'begin');
+    let agentmdUploaded = false;
+    try {
+        const { buildInitialAgentMd, agentmdPut } = await import('../aun/aid/index.js');
+        const agentName = opts.name || opts.aid.split('.')[0];
+        const agentDescription = opts.description || '';
+        let content = buildInitialAgentMd({ aid: opts.aid });
+        content = content.replace(/^name:\s*".*?"$/m, `name: "${agentName}"`);
+        if (agentDescription) {
+            content = content.replace(/^description:\s*".*?"$/m, `description: "${agentDescription}"`);
+        }
+        const aunPath = process.env.AUN_HOME || defaultAunPath();
+        // agentmdPut 会写本地文件到 agentMdPath(aid) 并调用 publishAgentMd
+        const MAX_ATTEMPTS = 3;
+        const RETRY_DELAY_MS = 2000;
+        let lastError;
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+            try {
+                if (attempt > 1)
+                    await new Promise(r => setTimeout(r, RETRY_DELAY_MS));
+                await agentmdPut(content, { aid: opts.aid, aunPath });
+                agentmdUploaded = true;
+                opts.onPhase?.('uploading_agentmd', 'done');
+                break;
+            }
+            catch (e) {
+                lastError = e;
+            }
+        }
+        if (!agentmdUploaded) {
+            console.warn(`⚠ agent.md upload failed: ${lastError?.message || lastError}`);
+            console.warn(`  Retry later with: ec aid agentmd put ${opts.aid}`);
+            opts.onPhase?.('uploading_agentmd', 'warn', `upload failed: ${lastError?.message || lastError}`);
+        }
+        await new Promise(r => setTimeout(r, 0));
+    }
+    catch (e) {
+        console.warn(`⚠ agent.md generation failed: ${e?.message || e}`);
+        opts.onPhase?.('uploading_agentmd', 'warn', `generation failed: ${e?.message || e}`);
+    }
+    // Attempt hot-load via IPC (if daemon is running).
+    // Cold-starting a new agent (connecting AUN WebSocket) routinely takes
+    // >3s, so use a generous timeout to avoid a false "service not running"
+    // report while the daemon actually finishes bringing the agent online.
+    let hotLoaded = false;
+    let hotLoadError;
+    opts.onPhase?.('hot_loading', 'begin');
+    try {
+        const ipcResult = await ipcQuery(p.socket, { type: 'evolagent.load', aid: opts.aid }, 30_000);
+        if (ipcResult?.ok) {
+            hotLoaded = true;
+            opts.onPhase?.('hot_loading', 'done');
+        }
+        else if (ipcResult) {
+            hotLoadError = ipcResult.error;
+            opts.onPhase?.('hot_loading', 'warn', hotLoadError);
+        }
+        else {
+            opts.onPhase?.('hot_loading', 'warn', 'daemon not running');
+        }
+    }
+    catch {
+        opts.onPhase?.('hot_loading', 'warn', 'daemon not running'); /* daemon not running */
+    }
+    return {
+        ok: true,
+        aid: opts.aid,
+        ownerAid: opts.owner,
+        configPath: toPosix(path.join(agentDirPath, 'config.json')),
+        aidCreated,
+        agentmdUploaded,
+        hotLoaded,
+        hotLoadError,
+    };
+}
+// ==================== agentSyncAids (deprecated) ====================
+/** @deprecated sync-aids 已废弃，不再从 CLI 调用 */
+export async function agentSyncAids() {
+    const p = resolvePaths();
+    const { aidList } = await import('../aun/aid/index.js');
+    const aunPath = process.env.AUN_HOME || defaultAunPath();
+    const allAids = aidList(aunPath);
+    const localAids = allAids.filter(a => a.hasPrivateKey).map(a => a.aid);
+    if (localAids.length === 0) {
+        return { ok: true, created: [], template: null, hotReloaded: false };
+    }
+    const { agents } = loadAllAgents();
+    const existingAids = new Set(agents.map(a => a.aid));
+    // Find template (earliest mtime)
+    let templateAgent = agents[0] || null;
+    if (agents.length > 1) {
+        let earliestMtime = Infinity;
+        for (const a of agents) {
+            const configPath = path.join(p.agentsDir, a.aid, 'config.json');
+            try {
+                const stat = fs.statSync(configPath);
+                if (stat.mtimeMs < earliestMtime) {
+                    earliestMtime = stat.mtimeMs;
+                    templateAgent = a;
+                }
+            }
+            catch { }
+        }
+    }
+    if (!templateAgent) {
+        return { ok: false, error: '没有可用的模板 agent。请先创建第一个 agent：ec agent new <aid>' };
+    }
+    const defaults = loadDefaults();
+    const rootPath = agentProjectRootFromDefaults(defaults, p.root);
+    const created = [];
+    for (const aid of localAids) {
+        if (existingAids.has(aid))
+            continue;
+        const projectPath = deriveAgentProjectPath(rootPath, aid);
+        const { roles: _legacyRoles, ...templateConfig } = JSON.parse(JSON.stringify(templateAgent));
+        const newConfig = {
+            ...templateConfig,
+            aid,
+            channels: [],
+            projects: { defaultPath: projectPath },
+            $schema_version: CONFIG_SCHEMA_VERSION,
+        };
+        try {
+            saveAgent(newConfig);
+            ensureInitialRoleRegistry(aid);
+            ensureAgentDirSkeleton(aid);
+            created.push(aid);
+        }
+        catch { }
+    }
+    // Hot-reload if running
+    let hotReloaded = false;
+    if (created.length > 0) {
+        try {
+            const result = await ipcQuery(p.socket, { type: 'evolagent.resync' });
+            hotReloaded = !!result?.ok;
+        }
+        catch { }
+    }
+    return { ok: true, created, template: templateAgent.aid, hotReloaded };
+}
+// ==================== agentReload ====================
+export async function agentReload(aid) {
+    const p = resolvePaths();
+    if (!aid) {
+        // Full resync
+        try {
+            const result = await ipcQuery(p.socket, { type: 'evolagent.resync' });
+            if (result === null) {
+                return { ok: false, error: 'evolcore 未运行，请先 ec start' };
+            }
+            if (result?.ok) {
+                return { ok: true, results: result.results || [] };
+            }
+            return { ok: false, error: result?.error || 'unknown error' };
+        }
+        catch {
+            return { ok: false, error: 'evolcore 未运行，请先 ec start' };
+        }
+    }
+    // Single agent reload
+    try {
+        const result = await ipcQuery(p.socket, { type: 'evolagent.reload', name: aid });
+        if (result === null) {
+            return { ok: false, error: 'evolcore 未运行，请先 ec start 后再 reload' };
+        }
+        if (result?.ok) {
+            return { ok: true };
+        }
+        return { ok: false, error: result?.error || 'unknown error' };
+    }
+    catch {
+        return { ok: false, error: 'evolcore 未运行，请先 ec start 后再 reload' };
+    }
+}
+// ==================== agentEnable / agentDisable ====================
+export async function agentEnable(aid) {
+    return agentSetEnabled(aid, true);
+}
+export async function agentDisable(aid) {
+    return agentSetEnabled(aid, false);
+}
+async function agentSetEnabled(aid, enabled) {
+    const p = resolvePaths();
+    let config;
+    try {
+        config = loadAgent(aid);
+    }
+    catch (e) {
+        return { ok: false, error: `Failed to read config: ${e?.message || e}` };
+    }
+    if (!config) {
+        return { ok: false, error: `Agent "${aid}" not found` };
+    }
+    config.enabled = enabled;
+    saveAgent(config);
+    // Try to hot-reload if daemon is running, but don't fail if it's not
+    let reloaded = false;
+    try {
+        const result = await ipcQuery(p.socket, { type: 'evolagent.reload', name: aid }, 1000);
+        if (result?.ok) {
+            reloaded = true;
+        }
+    }
+    catch {
+        // Daemon not running or unreachable — that's ok, config is already saved
+    }
+    return { ok: true, aid, enabled, reloaded };
+}
+async function runManagedAgentConfig(args, options) {
+    const sessionId = process.env.EVOLCORE_SESSION_ID;
+    if (!sessionId || options.trustedLocal)
+        return { managed: false };
+    const delegationToken = process.env[AGENT_DELEGATION_TOKEN_ENV];
+    if (!delegationToken) {
+        return {
+            managed: true,
+            error: { ok: false, code: 'DELEGATION_REQUIRED', error: `${AGENT_DELEGATION_TOKEN_ENV} is not set for the active task` },
+        };
+    }
+    try {
+        const response = await ipcQuery(resolvePaths().socket, {
+            type: 'config.op',
+            argv: ['config', ...args],
+            sessionId,
+            delegationToken,
+        }, 10_000);
+        if (!response) {
+            return { managed: true, error: { ok: false, code: 'DAEMON_UNAVAILABLE', error: 'Unable to connect to the evolcore daemon' } };
+        }
+        if (!response.ok || !response.result?.ok) {
+            return {
+                managed: true,
+                error: { ok: false, code: response.code || 'CONFIG_AUTH_FAILED', error: response.error || 'config operation failed' },
+            };
+        }
+        return { managed: true, response };
+    }
+    catch {
+        return { managed: true, error: { ok: false, code: 'DAEMON_UNAVAILABLE', error: 'Unable to connect to the evolcore daemon' } };
+    }
+}
+function executeLocalAgentConfig(args) {
+    initConfigManager();
+    const resolved = resolveConfigCommand(['config', ...args]);
+    if (!resolved.ok)
+        return { ok: false, code: resolved.code, error: resolved.reason };
+    return executeResolvedConfigCommand(resolved.command);
+}
+export async function agentGet(aid, key, options = {}) {
+    const managed = await runManagedAgentConfig(['get', key, '--self', aid], options);
+    if (managed.managed) {
+        if ('error' in managed)
+            return managed.error;
+        const result = managed.response.result;
+        if (result.ok && result.subcommand === 'get')
+            return { ok: true, aid, key, value: result.value };
+        return { ok: false, code: 'UNEXPECTED_RESULT', error: 'config get returned an unexpected result' };
+    }
+    const p = resolvePaths();
+    if (!fs.existsSync(path.join(p.agentsDir, aid, 'config.json'))) {
+        return { ok: false, error: `Agent "${aid}" not found` };
+    }
+    try {
+        const result = executeLocalAgentConfig(['get', key, '--self', aid]);
+        return result.ok && result.subcommand === 'get'
+            ? { ok: true, aid, key, value: result.value }
+            : { ok: false, code: result.ok ? 'UNEXPECTED_RESULT' : result.code, error: result.ok ? 'config get returned an unexpected result' : result.error };
+    }
+    catch (e) {
+        return { ok: false, error: e?.message || String(e) };
+    }
+}
+export async function agentSet(aid, key, rawValue, options = {}) {
+    const managed = await runManagedAgentConfig(['set', key, rawValue, '--self', aid], options);
+    if (managed.managed) {
+        if ('error' in managed)
+            return managed.error;
+        const result = managed.response.result;
+        if (result.ok && result.subcommand === 'set') {
+            return { ok: true, aid, key, value: result.value, reloaded: false };
+        }
+        return { ok: false, code: 'UNEXPECTED_RESULT', error: 'config set returned an unexpected result' };
+    }
+    const p = resolvePaths();
+    if (!fs.existsSync(path.join(p.agentsDir, aid, 'config.json'))) {
+        return { ok: false, error: `Agent "${aid}" not found` };
+    }
+    let value;
+    try {
+        const result = executeLocalAgentConfig(['set', key, rawValue, '--self', aid]);
+        if (!result.ok)
+            return { ok: false, code: result.code, error: result.error };
+        if (result.subcommand !== 'set')
+            return { ok: false, code: 'UNEXPECTED_RESULT', error: 'config set returned an unexpected result' };
+        value = result.value;
+    }
+    catch (e) {
+        return { ok: false, error: e?.message || String(e) };
+    }
+    // Try hot-reload
+    let reloaded = false;
+    try {
+        const result = await ipcQuery(p.socket, { type: 'evolagent.reload', name: aid });
+        reloaded = !!result?.ok;
+    }
+    catch { }
+    return { ok: true, aid, key, value, reloaded };
+}
+/**
+ * Add or overwrite a channel instance on a per-agent config.
+ *
+ * - AUN type is rejected: AUN is implicit (managed by agent.aid + channel-loader),
+ *   writing to channels[] has no effect.
+ * - mode='add' + existing (type, name) → error
+ * - mode='overwrite' + missing (type, name) → error
+ *
+ * Saves config atomically and triggers a hot-reload IPC. If the daemon is not
+ * running or reload fails, returns reloaded:false (no error).
+ */
+export async function agentChannelUpsert(opts) {
+    const p = resolvePaths();
+    const SUPPORTED_TYPES = new Set(['feishu', 'wechat', 'dingtalk', 'qqbot', 'wecom']);
+    if (opts.channel.type === 'aun') {
+        return { ok: false, error: 'AUN channel cannot be configured via channels[] (managed implicitly by agent.aid)' };
+    }
+    if (!SUPPORTED_TYPES.has(opts.channel.type)) {
+        return { ok: false, error: `Unsupported channel type: ${opts.channel.type} (allowed: ${[...SUPPORTED_TYPES].join('/')})` };
+    }
+    if (!isValidChannelName(opts.channel.name)) {
+        return { ok: false, error: `Invalid channel name: ${JSON.stringify(opts.channel.name)} (empty or contains '#')` };
+    }
+    let config;
+    try {
+        config = loadAgent(opts.aid);
+    }
+    catch (e) {
+        return { ok: false, error: `Failed to load agent config: ${e?.message || e}` };
+    }
+    if (!config) {
+        return { ok: false, error: `Agent "${opts.aid}" not found` };
+    }
+    const channels = config.channels || [];
+    const matchIdx = channels.findIndex(c => c.type === opts.channel.type && c.name === opts.channel.name);
+    if (opts.mode === 'add') {
+        if (matchIdx >= 0) {
+            return { ok: false, error: `Channel (${opts.channel.type}, ${opts.channel.name}) already exists; pick a different name or use overwrite` };
+        }
+        channels.push(opts.channel);
+    }
+    else {
+        if (matchIdx < 0) {
+            return { ok: false, error: `Channel (${opts.channel.type}, ${opts.channel.name}) not found` };
+        }
+        channels[matchIdx] = opts.channel;
+    }
+    config.channels = channels;
+    saveAgent(config);
+    let reloaded = false;
+    try {
+        const result = await ipcQuery(p.socket, { type: 'evolagent.reload', name: opts.aid });
+        reloaded = !!result?.ok;
+    }
+    catch { /* daemon not running or reload failed */ }
+    return {
+        ok: true,
+        aid: opts.aid,
+        channelKey: `${opts.channel.type}#${opts.aid}#${opts.channel.name}`,
+        reloaded,
+    };
+}
+// ==================== agentDelete ====================
+export async function agentDelete(aid, purge = false) {
+    const p = resolvePaths();
+    const agentDir = path.join(p.agentsDir, aid);
+    const configPath = path.join(agentDir, 'config.json');
+    if (!fs.existsSync(configPath)) {
+        return { ok: false, error: `Agent "${aid}" not found` };
+    }
+    // Try to stop via IPC first
+    let stopped = false;
+    try {
+        const result = await ipcQuery(p.socket, { type: 'evolagent.reload', name: aid });
+        stopped = !!result?.ok;
+    }
+    catch { }
+    if (purge) {
+        fs.rmSync(agentDir, { recursive: true, force: true });
+    }
+    else {
+        fs.unlinkSync(configPath);
+        // 清理构建进度文件（非 purge 删除只移除 config.json，需显式清理 create-status.json）
+        const { removeCreateStatus } = await import('../core/message/create-status.js');
+        removeCreateStatus(agentDir);
+    }
+    // Trigger resync so daemon drops the agent
+    try {
+        await ipcQuery(p.socket, { type: 'evolagent.resync' });
+    }
+    catch { }
+    return { ok: true, aid, purged: purge, stopped };
+}
+// ==================== agentRename ====================
+export async function agentRename(aid, name) {
+    const config = loadAgent(aid);
+    if (!config) {
+        return { ok: false, error: `Agent "${aid}" not found` };
+    }
+    const agentMdFilePath = getAgentMdPath(aid);
+    if (!fs.existsSync(agentMdFilePath)) {
+        return { ok: false, error: `agent.md not found: ${toPosix(agentMdFilePath)}` };
+    }
+    const content = fs.readFileSync(agentMdFilePath, 'utf-8');
+    const quotedName = JSON.stringify(name);
+    let next;
+    if (/^---\n[\s\S]*?\n---/.test(content)) {
+        const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+        const bodyStart = frontmatter ? frontmatter[0].length : 0;
+        const fm = frontmatter?.[1] ?? '';
+        const nextFm = /^name:\s*.*$/m.test(fm)
+            ? fm.replace(/^name:\s*.*$/m, `name: ${quotedName}`)
+            : `name: ${quotedName}\n${fm}`;
+        next = `---\n${nextFm}\n---${content.slice(bodyStart)}`;
+    }
+    else {
+        next = `---\naid: ${JSON.stringify(aid)}\nname: ${quotedName}\n---\n${content}`;
+    }
+    fs.mkdirSync(path.dirname(agentMdFilePath), { recursive: true });
+    fs.writeFileSync(agentMdFilePath, next);
+    return { ok: true, aid, name };
+}
+// ==================== agentReady ====================
+export async function agentReady(aid) {
+    const p = resolvePaths();
+    const config = loadAgent(aid);
+    if (!config)
+        return { ok: false, error: `Agent "${aid}" not found` };
+    saveAgent(withLifecycleForWrite(config, 'active'));
+    let reloaded = false;
+    try {
+        const result = await ipcQuery(p.socket, { type: 'evolagent.bootstrapComplete', aid }, 30_000);
+        reloaded = !!result?.ok;
+    }
+    catch { /* daemon not running */ }
+    return { ok: true, aid, reloaded };
+}