evolcore 0.0.23 → 0.0.25

package/dist/cli/agent.js

@@ -1,32 +1,19 @@
 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, loadDaemonConfig } from '../config-store.js';
-import { ConfigTarget, write as cfgWrite, ensureFile as cfgEnsure, read as cfgRead, initConfigManager } from '../config/config-manager.js';
+import { resolvePaths, agentMdPath as getAgentMdPathFromPaths, agentPersonalDir, aunPath as defaultAunPath } from '../paths.js';
+import { loadDefaults, loadAllAgents, loadAgent, saveAgent, ensureAgentDirSkeleton } from '../config-store.js';
+import { 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 { ipcQuery, IpcTransportError } from '../ipc.js';
 import { CONFIG_SCHEMA_VERSION } from '../types.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 { resolveEcagentConfig } from '../agents/baseagent.js';
 import { agentProjectRootFromDefaults, deriveAgentProjectPath } from '../utils/project-path.js';
+import { isValidChannelName } from '../core/channel-loader.js';
 import { AGENT_DELEGATION_TOKEN_ENV } from '../core/auth/agent-delegation.js';
 import { readTaskRuntimeContextFromEnv } from './task-context.js';
-import { isValidAid } from '../aun/aid/validation.js';
-import { DEFAULT_AGENT_DESCRIPTION } from '../aun/aid/agentmd.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] };
-}
+import { isHClassPath, isLClassPath, isSameOrDescendant } from '../core/permission/protected-paths.js';
+export { agentCreateInteractive, agentCreateNonInteractive, parseAgentOwnerArgs, resolveAgentCreatePlan, validateAgentCreatePlan, validateAgentOwnerOptions, } from './agent-create.js';
 /** Route agent lifecycle commands from a managed task through daemon IPC. */
 export async function runManagedAgentOperation(argv) {
     const sessionId = process.env.EVOLCORE_SESSION_ID;
@@ -53,174 +40,32 @@ export async function runManagedAgentOperation(argv) {
         return { ok: false, code: 'DAEMON_UNAVAILABLE', error: error instanceof Error ? error.message : String(error) };
     }
 }
-// ==================== Helpers ====================
-const BASEAGENT_CANDIDATES = ['claude', 'codex', 'gemini', 'ecagent'];
-const AUTO_BASEAGENT_CANDIDATES = ['claude', 'codex', 'gemini'];
-function isBaseagentAvailable(baseagent) {
-    if (baseagent === 'codex')
-        return isCodexAppServerAvailable();
-    if (baseagent === 'ecagent')
-        return true;
-    return commandExists(baseagent);
-}
-function detectAvailableBaseagents() {
-    return BASEAGENT_CANDIDATES.filter(isBaseagentAvailable);
-}
-function pickDefaultBaseagent(available) {
-    return AUTO_BASEAGENT_CANDIDATES.find(candidate => available.includes(candidate)) ?? null;
-}
-function readProjectMetadata(project) {
-    try {
-        const packageJsonPath = path.join(project, 'package.json');
-        if (!fs.existsSync(packageJsonPath))
-            return {};
-        const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-        return {
-            name: typeof parsed.name === 'string' ? parsed.name.trim() : undefined,
-            description: typeof parsed.description === 'string' ? parsed.description.trim() : undefined,
-        };
-    }
-    catch {
-        return {};
-    }
-}
-function projectSlug(project) {
-    const basename = path.basename(project) || 'agent';
-    const slug = basename
-        .normalize('NFKD')
-        .replace(/[^a-zA-Z0-9-]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .toLowerCase()
-        .slice(0, 63)
-        .replace(/-+$/g, '');
-    return slug || 'agent';
-}
-/**
- * Resolve non-interactive creation defaults without performing any network or
- * filesystem mutation. The CLI uses this for both execution and --dry-run.
- */
-export function resolveAgentCreatePlan(options) {
-    const aid = options.aid.trim();
-    const project = path.resolve(options.project || process.cwd());
-    const metadata = readProjectMetadata(project);
-    const defaults = loadDefaults();
-    const daemon = loadDaemonConfig();
-    const configuredBaseagent = defaults?.active_baseagent;
-    const available = detectAvailableBaseagents();
-    const defaultBaseagent = configuredBaseagent && available.includes(configuredBaseagent)
-        ? configuredBaseagent
-        : pickDefaultBaseagent(available) ?? undefined;
-    const baseagent = options.baseagent || defaultBaseagent;
-    const baseagentSource = options.baseagent
-        ? 'argument'
-        : configuredBaseagent && baseagent === configuredBaseagent
-            ? 'defaults'
-            : 'detected';
-    const owner = options.owner?.trim() || daemon.owners?.[0];
-    const ownerSource = options.owner?.trim() ? 'argument' : owner ? 'daemon' : 'none';
-    const name = options.name?.trim() || metadata.name || projectSlug(project);
-    const description = options.description?.trim() || metadata.description || DEFAULT_AGENT_DESCRIPTION;
-    const configExists = isValidAid(aid)
-        && fs.existsSync(path.join(resolvePaths().agentsDir, aid, 'config.json'));
-    return {
-        aid,
-        project,
-        baseagent,
-        owner,
-        name,
-        description,
-        force: options.force === true,
-        configExists,
-        baseagentSource,
-        ownerSource,
-        nameSource: options.name?.trim() ? 'argument' : metadata.name ? 'package' : 'directory',
-        descriptionSource: options.description?.trim() ? 'argument' : metadata.description ? 'package' : 'default',
-    };
-}
-export function validateAgentCreatePlan(plan) {
-    if (!isValidAid(plan.aid)) {
-        return `Invalid AID "${plan.aid}": must be a valid multi-level domain (e.g. mybot.agentid.pub)`;
-    }
-    if (plan.configExists && !plan.force) {
-        return `Agent "${plan.aid}" already exists (use --force to overwrite)`;
-    }
-    if (!plan.baseagent) {
-        return 'No usable baseagent detected. Pass --baseagent or configure a baseagent in agents/defaults.json.';
-    }
-    if (!BASEAGENT_CANDIDATES.includes(plan.baseagent)) {
-        return `Invalid baseagent: ${plan.baseagent} (options: ${BASEAGENT_CANDIDATES.join('/')})`;
-    }
-    if (!isBaseagentAvailable(plan.baseagent)) {
-        return `${plan.baseagent} is not available in the current environment`;
-    }
-    if (plan.baseagent === 'ecagent') {
-        const reason = ecagentUnavailableReason();
-        if (reason)
-            return reason;
-    }
-    if (plan.owner && !isValidAid(plan.owner)) {
-        return `Invalid owner: ${plan.owner}`;
-    }
-    return null;
-}
-function ecagentUnavailableReason() {
-    try {
-        resolveEcagentConfig({ agents: { ecagent: {} } });
-        return undefined;
-    }
-    catch (error) {
-        return error instanceof Error ? error.message : String(error);
-    }
+function getAgentMdPath(aid) {
+    return getAgentMdPathFromPaths(aid);
 }
-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 toPosix(value) {
+    return value ? value.replace(/\\/g, '/') : null;
 }
 function readAgentMdIdentity(aid) {
-    const agentMdFilePath = getAgentMdPathFromPaths(aid);
+    const file = getAgentMdPath(aid);
     try {
-        if (!fs.existsSync(agentMdFilePath))
+        if (!fs.existsSync(file))
             return { name: null, description: null };
-        const content = fs.readFileSync(agentMdFilePath, 'utf-8');
-        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-        if (!fmMatch)
+        const content = fs.readFileSync(file, 'utf8');
+        const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!frontmatter)
             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);
+        const body = frontmatter[1];
         return {
-            name: nameMatch?.[1]?.trim() || null,
-            description: descMatch?.[1]?.trim() || null,
+            name: body.match(/^name:\s*["']?(.+?)["']?\s*$/m)?.[1]?.trim() || null,
+            description: body.match(/^description:\s*["']?(.+?)["']?\s*$/m)?.[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, '/');
-}
+// ==================== Helpers ====================
 // ==================== agentList ====================
 function toAgentListItem(info, stale = false) {
     const storedStatus = info.status || 'unknown';
@@ -360,499 +205,6 @@ export async function agentShow(aid) {
         ...(stale ? { stale: true } : {}),
     };
 }
-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 || (available.length === 1 && available[0] === 'ecagent' && ecagentUnavailableReason())) {
-            return { ok: false, error: `No usable baseagent detected. Install claude/gemini CLI or codex CLI with app-server, or configure bundled ecagent.` };
-        }
-        const defaultBa = pickDefaultBaseagent(available);
-        let baseagent;
-        if (available.length === 1 && defaultBa) {
-            console.log(`  Baseagent: ${defaultBa}`);
-            baseagent = defaultBa;
-        }
-        else {
-            let chosen = null;
-            while (chosen === null) {
-                const defaultHint = defaultBa ? ` [${defaultBa}]` : '';
-                const input = (await ask(`Baseagent (${available.join('/')})${defaultHint}: `)).trim() || defaultBa;
-                if (!input) {
-                    console.log('  ecagent is optional; enter ecagent to select it explicitly.');
-                    continue;
-                }
-                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;
-                }
-                if (input === 'ecagent') {
-                    const reason = ecagentUnavailableReason();
-                    if (reason) {
-                        console.log(`  ecagent is unavailable: ${reason}`);
-                        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');
-            const content = buildInitialAgentMd({ aid, name: agentName, 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;
-        let ownerBindInterrupted = 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);
-                if (bound.action === 'bound') {
-                    ownerBoundAid = bound.boundAid;
-                    console.log(`  ✓ 已配置 agent owner: ${bound.boundAid}`);
-                }
-                else if (bound.action === 'manual') {
-                    ownerBindSkipped = true;
-                    ownerBoundAid = await promptAgentOwnerManually(aid);
-                }
-                else {
-                    ownerBindInterrupted = true;
-                }
-            }
-            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,
-            ownerBindInterrupted,
-        };
-    }
-    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, runtime = {}) {
-    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 || (available.length === 1 && available[0] === 'ecagent' && ecagentUnavailableReason())) {
-        return failValidating(`No usable baseagent detected. Install claude/gemini CLI or codex CLI with app-server, or configure bundled ecagent.`);
-    }
-    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('/')})`);
-        }
-        if (opts.baseagent === 'ecagent') {
-            const reason = ecagentUnavailableReason();
-            if (reason)
-                return failValidating(reason);
-        }
-        baseagent = opts.baseagent;
-    }
-    else {
-        const defaultBaseagent = pickDefaultBaseagent(available);
-        if (!defaultBaseagent)
-            return failValidating('ecagent is optional; pass --baseagent ecagent after configuring its API key');
-        baseagent = defaultBaseagent;
-    }
-    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 content = buildInitialAgentMd({
-            aid: opts.aid,
-            name: opts.name,
-            description: opts.description,
-        });
-        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}`);
-    }
-    // Core-owned callers invoke the already-loaded runtime directly. Standalone
-    // CLI callers retain the IPC path so this module remains usable without a
-    // daemon instance in the current process.
-    let hotLoaded = false;
-    let hotLoadError;
-    opts.onPhase?.('hot_loading', 'begin');
-    try {
-        if (runtime.hotLoadAgent) {
-            await runtime.hotLoadAgent(opts.aid);
-            hotLoaded = true;
-            opts.onPhase?.('hot_loading', 'done');
-        }
-        else {
-            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 (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        hotLoadError = message;
-        opts.onPhase?.('hot_loading', 'warn', message);
-    }
-    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() {
@@ -930,32 +282,32 @@ export async function agentReload(aid, options = {}) {
         }
         // Full resync
         try {
-            const result = await ipcQuery(p.socket, { type: 'evolagent.resync' }, AGENT_RESYNC_TIMEOUT_MS);
+            const result = await ipcQuery(p.socket, { type: 'evolagent.resync' }, AGENT_RESYNC_TIMEOUT_MS, { throwOnError: true });
             if (result === null) {
-                return { ok: false, error: 'evolcore 未运行，请先 ec start' };
+                return { ok: false, code: 'IPC_INVALID_RESPONSE', error: 'daemon IPC 未返回有效响应，请检查 ec status' };
             }
             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' };
+        catch (error) {
+            return { ok: false, code: error instanceof IpcTransportError ? `IPC_${error.code}` : 'IPC_FAILED', error: String(error instanceof Error ? error.message : error) };
         }
     }
     // Single agent reload
     try {
-        const result = await ipcQuery(p.socket, { type: 'evolagent.reload', name: aid, force: options.force === true }, AGENT_RELOAD_TIMEOUT_MS);
+        const result = await ipcQuery(p.socket, { type: 'evolagent.reload', name: aid, force: options.force === true }, AGENT_RELOAD_TIMEOUT_MS, { throwOnError: true });
         if (result === null) {
-            return { ok: false, error: 'evolcore 未运行，请先 ec start 后再 reload' };
+            return { ok: false, code: 'IPC_INVALID_RESPONSE', error: 'daemon IPC 未返回有效响应，请检查 ec status' };
         }
         if (result?.ok) {
             return { ok: true };
         }
         return { ok: false, code: result?.code, error: result?.error || 'unknown error' };
     }
-    catch {
-        return { ok: false, error: 'evolcore 未运行，请先 ec start 后再 reload' };
+    catch (error) {
+        return { ok: false, code: error instanceof IpcTransportError ? `IPC_${error.code}` : 'IPC_FAILED', error: String(error instanceof Error ? error.message : error) };
     }
 }
 // ==================== agentEnable / agentDisable ====================
@@ -1105,6 +457,107 @@ export async function agentSet(aid, key, rawValue, options = {}) {
     catch { }
     return { ok: true, aid, key, value, reloaded };
 }
+export const AGENT_PERSONA_MAX_BYTES = 64 * 1024;
+function validatePersonaContent(content) {
+    if (content.includes('\0'))
+        return 'persona 只能包含文本内容';
+    if (Buffer.byteLength(content, 'utf8') > AGENT_PERSONA_MAX_BYTES) {
+        return `persona 不能超过 ${AGENT_PERSONA_MAX_BYTES} bytes`;
+    }
+    return null;
+}
+function readPersonaSource(file) {
+    const resolved = path.resolve(file);
+    if (!/\.(?:md|txt)$/i.test(resolved)) {
+        return { ok: false, code: 'INVALID_ARGS', error: '--file 只接受 .md 或 .txt 文本文件' };
+    }
+    try {
+        const stat = fs.statSync(resolved);
+        if (!stat.isFile())
+            return { ok: false, code: 'INVALID_ARGS', error: `--file 必须指向普通文件: ${resolved}` };
+        const content = fs.readFileSync(resolved, 'utf8');
+        const error = validatePersonaContent(content);
+        return error ? { ok: false, code: 'INVALID_ARGS', error } : { ok: true, content };
+    }
+    catch (e) {
+        return { ok: false, code: 'READ_FAILED', error: `无法读取 --file: ${e?.message || e}` };
+    }
+}
+/** Read or replace the current Agent's personal/persona.md. */
+export async function agentPersona(aid, options = {}) {
+    if (options.text !== undefined && options.file !== undefined)
+        return { ok: false, code: 'INVALID_ARGS', error: '--text 与 --file 不能同时使用' };
+    const managedSession = !!process.env.EVOLCORE_SESSION_ID && !options.trustedLocal;
+    let text = options.text;
+    if (options.file !== undefined) {
+        if (managedSession) {
+            const resolved = path.resolve(options.file);
+            const projectRoot = path.resolve(process.cwd());
+            const tempRoot = process.env.TMPDIR?.trim() && path.isAbsolute(process.env.TMPDIR)
+                ? path.resolve(process.env.TMPDIR)
+                : undefined;
+            const allowed = isSameOrDescendant(resolved, projectRoot)
+                || (!!tempRoot && isSameOrDescendant(resolved, tempRoot));
+            if (!allowed || isHClassPath(resolved) || isLClassPath(resolved)) {
+                return { ok: false, code: 'INVALID_ARGS', error: '--file 必须位于当前项目或会话 $TMPDIR，且不能读取 EvolCore 受保护路径' };
+            }
+            try {
+                const stat = fs.lstatSync(resolved);
+                if (stat.isSymbolicLink() || !stat.isFile()) {
+                    return { ok: false, code: 'INVALID_ARGS', error: '--file 必须指向当前项目或会话 $TMPDIR 内的普通文件' };
+                }
+                const realPath = fs.realpathSync(resolved);
+                const realProjectRoot = fs.realpathSync(projectRoot);
+                const realTempRoot = tempRoot ? fs.realpathSync(tempRoot) : undefined;
+                const realAllowed = isSameOrDescendant(realPath, realProjectRoot)
+                    || (!!realTempRoot && isSameOrDescendant(realPath, realTempRoot));
+                if (!realAllowed || isHClassPath(realPath) || isLClassPath(realPath)) {
+                    return { ok: false, code: 'INVALID_ARGS', error: '--file 解析后越出允许目录或命中 EvolCore 受保护路径' };
+                }
+            }
+            catch (e) {
+                return { ok: false, code: 'READ_FAILED', error: `无法校验 --file: ${e?.message || e}` };
+            }
+        }
+        const source = readPersonaSource(options.file);
+        if (!source.ok)
+            return source;
+        text = source.content;
+    }
+    if (text !== undefined) {
+        const error = validatePersonaContent(text);
+        if (error)
+            return { ok: false, code: 'INVALID_ARGS', error };
+    }
+    const managedArgs = options.text !== undefined
+        ? ['persona', '--text', text]
+        : options.file !== undefined
+            ? ['persona', '--text', text]
+            : ['persona', 'show'];
+    if (managedSession) {
+        const managed = await runManagedAgentOperation(managedArgs);
+        if (!managed.ok)
+            return managed;
+        return { ok: true, aid, content: managed.content ?? null, ...(managed.path ? { path: managed.path } : {}), ...(managed.saved ? { saved: true } : {}) };
+    }
+    const personaPath = path.join(agentPersonalDir(aid), 'persona.md');
+    if (text === undefined) {
+        try {
+            return { ok: true, aid, content: fs.existsSync(personaPath) ? fs.readFileSync(personaPath, 'utf8') : null, path: personaPath };
+        }
+        catch (e) {
+            return { ok: false, code: 'READ_FAILED', error: e?.message || String(e) };
+        }
+    }
+    try {
+        fs.mkdirSync(path.dirname(personaPath), { recursive: true });
+        fs.writeFileSync(personaPath, text, 'utf8');
+        return { ok: true, aid, content: text, path: personaPath, saved: true };
+    }
+    catch (e) {
+        return { ok: false, code: 'WRITE_FAILED', error: e?.message || String(e) };
+    }
+}
 /**
  * Add or overwrite a channel instance on a per-agent config.
  *