evolcore 0.0.25 → 0.0.27

package/dist/cli/agent-create.js

@@ -1,18 +1,34 @@
 import fs from 'fs';
+import { randomBytes, createHash } from 'crypto';
 import path from 'path';
 import readline from 'readline';
-import { resolvePaths, aunPath as defaultAunPath } from '../paths.js';
+import { parse } from 'yaml';
+import { resolvePaths, aunPath as defaultAunPath, agentConfig, agentDataDir, agentPersonalDir, aidLocalDir, agentMdPath } from '../paths.js';
 import { loadDefaults, loadAgent, saveAgent, ensureAgentDirSkeleton, loadDaemonConfig } from '../config-store.js';
 import { ConfigTarget, write as cfgWrite, ensureFile as cfgEnsure, read as cfgRead } from '../config/config-manager.js';
 import { ipcQuery } from '../ipc.js';
 import { CONFIG_SCHEMA_VERSION } from '../types.js';
 import { ensureInitialRoleRegistry } from '../config/role-service.js';
+import { addContact } from '../config/contact-request-service.js';
 import { getCodexAppServerAvailability } from '../agents/codex-runner.js';
 import { resolveEcagentConfig } from '../agents/baseagent.js';
 import { AUTO_BASEAGENT_CANDIDATES, BASEAGENT_CANDIDATES, detectAvailableBaseagents, } from '../agents/baseagent-availability.js';
 import { agentProjectRootFromDefaults, deriveAgentProjectPath } from '../utils/project-path.js';
 import { isValidAid } from '../aun/aid/validation.js';
-import { AGENT_TAG_MAX_COUNT, AGENT_TAG_MIN_COUNT, DEFAULT_AGENT_DESCRIPTION, validateAgentTags, } from '../aun/aid/agentmd.js';
+import { AGENT_DESCRIPTION_MAX_LENGTH, AGENT_TAG_MAX_COUNT, AGENT_TAG_MIN_COUNT, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_TYPE, normalizeAgentType, validateAgentTags, validateAgentType, buildInitialAgentMd, validateAgentMdFrontmatter, } from '../aun/aid/agentmd.js';
+import { atomicWriteJson } from '../utils/atomic-write.js';
+import { isHClassPath, isLClassPath, isSameOrDescendant } from '../core/permission/protected-paths.js';
+import { MAIN_CLI_BIN } from '../product.js';
+/** Parse the current Agent's Bootstrap welcome subcommand. */
+export function parseAgentWelcomeArgs(args) {
+    const tail = args.at(-2) === '--format' && args.at(-1) === 'json' ? args.slice(0, -2) : args;
+    if (tail.length === 1 && tail[0] === 'show')
+        return { action: 'show' };
+    if (tail.length === 2 && tail[0] === '--text' && typeof tail[1] === 'string') {
+        return { action: 'set', text: tail[1] };
+    }
+    throw new Error(`用法: ${MAIN_CLI_BIN} agent welcome show | --text <text> [--format json]`);
+}
 export function parseAgentTags(raw) {
     if (raw === undefined)
         return undefined;
@@ -89,6 +105,42 @@ function withStaticOwners(config, ownersInput) {
 function withStaticOwner(config, owner) {
     return withStaticOwners(config, owner ? [owner] : undefined);
 }
+/**
+ * An Agent owner must be able to receive the new Agent's Bootstrap reply.
+ * Contact admission is per local Agent, so materialize the new AID in each
+ * locally managed owner's contact book immediately after creation. Human or
+ * remote owners have no local contact book and are reported as skipped.
+ */
+export async function syncOwnerContactsAfterCreate(createdAid, owners) {
+    const synced = [];
+    const skipped = [];
+    const errors = [];
+    for (const ownerAid of [...new Set((owners ?? []).map(value => value.trim()).filter(Boolean))]) {
+        if (ownerAid === createdAid)
+            continue;
+        const ownerConfig = path.join(resolvePaths().agentsDir, ownerAid, 'config.json');
+        if (!fs.existsSync(ownerConfig)) {
+            skipped.push(ownerAid);
+            continue;
+        }
+        try {
+            await addContact({
+                selfAid: ownerAid,
+                primaryId: createdAid,
+                actorId: 'agent-create-owner-sync',
+            });
+            synced.push(ownerAid);
+        }
+        catch (error) {
+            errors.push(`${ownerAid}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        ...(synced.length > 0 ? { ownerContactsSynced: synced } : {}),
+        ...(skipped.length > 0 ? { ownerContactsSkipped: skipped } : {}),
+        ...(errors.length > 0 ? { ownerContactSyncErrors: errors } : {}),
+    };
+}
 function pickDefaultBaseagent(available) {
     return AUTO_BASEAGENT_CANDIDATES.find(candidate => available.includes(candidate)) ?? null;
 }
@@ -137,13 +189,25 @@ export function resolveAgentCreatePlan(options) {
     const owner = options.owner?.trim() || (owners === undefined ? daemon.owners?.[0] : undefined);
     const ownerSource = owners !== undefined || 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;
+    // description 是可选字段：用户显式传入的必须合规（超长会在校验阶段被拒）；
+    // 从 package.json 推导出来的超长值直接弃用、回落默认短描述——用户没设过它，
+    // 不该因此让创建命令失败。
+    const explicitDescription = options.description?.trim();
+    const packageDescription = metadata.description
+        && Array.from(metadata.description).length <= AGENT_DESCRIPTION_MAX_LENGTH
+        ? metadata.description
+        : undefined;
+    const description = explicitDescription || packageDescription || DEFAULT_AGENT_DESCRIPTION;
+    // 大小写不敏感：能识别就收敛成小写；无法识别时保留原值，交给 validateAgentCreatePlan 报错。
+    const requestedType = options.type?.trim();
+    const type = requestedType ? (normalizeAgentType(requestedType) ?? requestedType) : DEFAULT_AGENT_TYPE;
     const configExists = isValidAid(aid) && fs.existsSync(path.join(resolvePaths().agentsDir, aid, 'config.json'));
     return {
-        aid, project, baseagent, owner, owners, handoff: options.handoff, name, description, tags: options.tags,
+        aid, project, baseagent, owner, owners, handoff: options.handoff, name, description, type, tags: options.tags,
         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',
+        descriptionSource: explicitDescription ? 'argument' : packageDescription ? 'package' : 'default',
+        typeSource: options.type?.trim() ? 'argument' : 'default',
     };
 }
 export function validateAgentCreatePlan(plan) {
@@ -159,6 +223,16 @@ export function validateAgentCreatePlan(plan) {
         if (tagErrors.length > 0)
             return `Invalid tags: ${tagErrors.join('; ')}`;
     }
+    const typeError = validateAgentType(plan.type);
+    if (typeError)
+        return `Invalid --type: ${typeError}`;
+    // 只有显式传入的 --description 才会超限（package.json 的超长值在 resolve 阶段
+    // 已被弃用）。必须在这里就拒绝：否则 plan 通过、直到 agentmdPut 上传才失败，
+    // 而那处是 warn 级不中断创建，最终留下一张 SDK 兜底名片（--type/--name 全部丢失）。
+    const descriptionLength = Array.from(plan.description).length;
+    if (descriptionLength > AGENT_DESCRIPTION_MAX_LENGTH) {
+        return `Invalid --description: ${descriptionLength} characters exceeds the agent.md limit of ${AGENT_DESCRIPTION_MAX_LENGTH}. Pass a shorter --description.`;
+    }
     if (!plan.baseagent)
         return 'No usable baseagent detected. Pass --baseagent or configure a baseagent in agents/defaults.json.';
     if (!BASEAGENT_CANDIDATES.includes(plan.baseagent)) {
@@ -219,6 +293,8 @@ export async function agentCreateInteractive(opts = {}) {
             }
             aid = candidate;
         }
+        if (hasSuppliedInitialization(aid))
+            return { ok: false, error: 'Use agent initialize --resume for this target' };
         const agentDirPath = path.join(p.agentsDir, aid);
         const configExists = fs.existsSync(path.join(agentDirPath, 'config.json'));
         if (configExists) {
@@ -344,6 +420,8 @@ export async function agentCreateInteractive(opts = {}) {
         ensureInitialRoleRegistry(aid);
         saveInitialBehavior(aid, baseagent);
         ensureAgentDirSkeleton(aid);
+        if (owner)
+            await syncOwnerContactsAfterCreate(aid, [owner]);
         let agentmdUploaded = false;
         try {
             const content = buildInitialAgentMd({ aid, name: agentName, description: agentDescription, tags: agentTags });
@@ -399,7 +477,21 @@ export async function agentCreateInteractive(opts = {}) {
                 ownerBoundAid = await promptAgentOwnerManually(aid);
             }
         }
-        return { ok: true, aid, configPath: toPosix(path.join(agentDirPath, 'config.json')), aidCreated, agentmdUploaded, hotLoaded, hotLoadError, ownerBoundAid, ownerBindSkipped, ownerBindInterrupted };
+        const finalOwnerAid = owner ?? ownerBoundAid;
+        const ownerContactSync = await syncOwnerContactsAfterCreate(aid, finalOwnerAid ? [finalOwnerAid] : undefined);
+        return {
+            ok: true,
+            aid,
+            configPath: toPosix(path.join(agentDirPath, 'config.json')),
+            aidCreated,
+            agentmdUploaded,
+            hotLoaded,
+            hotLoadError,
+            ownerBoundAid,
+            ownerBindSkipped,
+            ownerBindInterrupted,
+            ...ownerContactSync,
+        };
     }
     finally {
         if (ownRl) {
@@ -449,8 +541,21 @@ export async function agentCreateNonInteractive(opts, runtime = {}) {
         if (tagErrors.length > 0)
             return failValidating(`Invalid tags: ${tagErrors.join('; ')}`);
     }
+    if (opts.type !== undefined) {
+        const typeError = validateAgentType(opts.type);
+        if (typeError)
+            return failValidating(`Invalid --type: ${typeError}`);
+    }
+    if (opts.description !== undefined) {
+        const descriptionLength = Array.from(opts.description).length;
+        if (descriptionLength > AGENT_DESCRIPTION_MAX_LENGTH) {
+            return failValidating(`Invalid description: ${descriptionLength} characters exceeds the agent.md limit of ${AGENT_DESCRIPTION_MAX_LENGTH}. Pass a shorter --description.`);
+        }
+    }
     if (!isValidAid(opts.aid))
         return failValidating(`Invalid AID "${opts.aid}": must be a valid multi-level domain (e.g. mybot.agentid.pub)`);
+    if (hasSuppliedInitialization(opts.aid))
+        return failValidating('Use agent initialize --resume for this target');
     const agentDirPath = path.join(p.agentsDir, opts.aid);
     const configExists = fs.existsSync(path.join(agentDirPath, 'config.json'));
     if (configExists && !opts.force)
@@ -518,11 +623,13 @@ export async function agentCreateNonInteractive(opts, runtime = {}) {
     ensureInitialRoleRegistry(opts.aid);
     saveInitialBehavior(opts.aid, baseagent);
     ensureAgentDirSkeleton(opts.aid);
+    const ownerContactSync = await syncOwnerContactsAfterCreate(opts.aid, opts.owners ?? (opts.owner ? [opts.owner] : undefined));
     opts.onPhase?.('config_saved', 'done');
     opts.onPhase?.('uploading_agentmd', 'begin');
     let agentmdUploaded = false;
+    let agentmdError;
     try {
-        const content = buildInitialAgentMd({ aid: opts.aid, name: opts.name, description: opts.description, tags: opts.tags });
+        const content = buildInitialAgentMd({ aid: opts.aid, name: opts.name, description: opts.description, type: opts.type, tags: opts.tags });
         const aunPath = process.env.AUN_HOME || defaultAunPath();
         let lastError;
         for (let attempt = 1; attempt <= 3; attempt++) {
@@ -538,12 +645,15 @@ export async function agentCreateNonInteractive(opts, runtime = {}) {
                 lastError = e;
             }
         }
-        if (!agentmdUploaded)
-            opts.onPhase?.('uploading_agentmd', 'warn', `upload failed: ${lastError?.message || lastError}`);
+        if (!agentmdUploaded) {
+            agentmdError = `upload failed: ${lastError?.message || lastError}`;
+            opts.onPhase?.('uploading_agentmd', 'warn', agentmdError);
+        }
         await new Promise(r => setTimeout(r, 0));
     }
     catch (e) {
-        opts.onPhase?.('uploading_agentmd', 'warn', `generation failed: ${e?.message || e}`);
+        agentmdError = `generation failed: ${e?.message || e}`;
+        opts.onPhase?.('uploading_agentmd', 'warn', agentmdError);
     }
     let hotLoaded = false;
     let hotLoadError;
@@ -572,5 +682,510 @@ export async function agentCreateNonInteractive(opts, runtime = {}) {
         hotLoadError = error instanceof Error ? error.message : String(error);
         opts.onPhase?.('hot_loading', 'warn', hotLoadError);
     }
-    return { ok: true, aid: opts.aid, ownerAid: (opts.owners ?? (opts.owner ? [opts.owner] : undefined))?.[0], configPath: toPosix(path.join(agentDirPath, 'config.json')), aidCreated, agentmdUploaded, hotLoaded, hotLoadError };
+    return {
+        ok: true,
+        aid: opts.aid,
+        ownerAid: (opts.owners ?? (opts.owner ? [opts.owner] : undefined))?.[0],
+        configPath: toPosix(path.join(agentDirPath, 'config.json')),
+        aidCreated,
+        agentmdUploaded,
+        agentmdError,
+        hotLoaded,
+        hotLoadError,
+        ...ownerContactSync,
+    };
+}
+// ---- One-shot Agent initialization (kept with Agent creation) ----
+export const INITIALIZATION_PERSONA_MAX_BYTES = 64 * 1024;
+export function validateInitializationPersonaContent(content) {
+    if (content.includes('\0'))
+        return 'persona 只能包含文本内容';
+    if (Buffer.byteLength(content, 'utf8') > INITIALIZATION_PERSONA_MAX_BYTES) {
+        return `persona 不能超过 ${INITIALIZATION_PERSONA_MAX_BYTES} bytes`;
+    }
+    return null;
+}
+export function initializationPath(aid) {
+    return path.join(agentDataDir(aid), 'initialization.json');
+}
+export function initializationFingerprint(plan) {
+    return createHash('sha256').update(JSON.stringify([
+        plan.aid, plan.project, plan.baseagent, plan.owners, plan.name,
+        plan.description, plan.type, plan.tags, plan.persona ?? null,
+    ])).digest('hex');
+}
+export function readInitialization(aid) {
+    const file = initializationPath(aid);
+    if (!fs.existsSync(file))
+        return null;
+    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (record.version !== 1 || record.plan?.aid !== aid || !/^init-[a-f0-9]{24}$/.test(record.operationId)
+        || !['in_progress', 'failed', 'complete', 'cancelled'].includes(record.status)
+        || initializationFingerprint(record.plan) !== record.fingerprint) {
+        throw new Error('INITIALIZE_STATE_INVALID');
+    }
+    return record;
+}
+export function saveInitialization(record) {
+    const file = initializationPath(record.plan.aid);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    record.updatedAt = Date.now();
+    atomicWriteJson(file, record);
+    // The hot backup also contains the private plan snapshot.
+    for (const target of [file, `${file}_`])
+        if (fs.existsSync(target))
+            fs.chmodSync(target, 0o600);
+}
+/** Pure summary: never expose the persona, project path or authorization snapshot. */
+export function initializationSummary(aid) {
+    try {
+        const r = readInitialization(aid);
+        if (!r)
+            return undefined;
+        return {
+            mode: 'supplied', operationId: r.operationId, fingerprint: r.fingerprint,
+            status: r.status, phase: r.phase, complete: r.status === 'complete',
+            code: r.code, error: r.error, retryable: r.status === 'failed',
+            nextStep: r.status === 'failed' ? `ec agent initialize ${aid} --resume` : undefined,
+            agentmd: { published: r.published === true, verified: r.verified === true },
+            persona: { provided: r.plan.persona !== undefined },
+            welcome: r.welcome, startedAt: r.startedAt, updatedAt: r.updatedAt,
+        };
+    }
+    catch {
+        return { mode: 'supplied', status: 'failed', complete: false, code: 'INITIALIZE_STATE_INVALID' };
+    }
+}
+/** Persistent guard also covers a removed/tampered config marker. */
+export function initializationBlocksTasks(config) {
+    try {
+        const r = readInitialization(config.aid);
+        if (!r && config.initialization === undefined)
+            return false;
+        return !r || config.initialization?.operationId !== r.operationId
+            || config.initialization.mode !== 'supplied' || config.lifecycle !== 'active'
+            || r.status !== 'complete';
+    }
+    catch {
+        return true;
+    }
+}
+export function hasSuppliedInitialization(aid) {
+    return fs.existsSync(initializationPath(aid));
+}
+function failure(code, error = code) {
+    throw Object.assign(new Error(error), { code });
+}
+export function validateInitializationPlan(plan) {
+    if (!plan.name?.trim() || !plan.description?.trim() || !Array.isArray(plan.tags) || !plan.owners?.length) {
+        failure('INITIALIZE_FIELDS_REQUIRED', 'Explicit name, description, tags and owners are required');
+    }
+    if (plan.type !== 'agent')
+        failure('INVALID_ARGS', 'Initialized targets must have type=agent');
+    const error = validateAgentCreatePlan({
+        ...plan, force: false, configExists: false, baseagentSource: 'argument', ownerSource: 'argument',
+        nameSource: 'argument', descriptionSource: 'argument', typeSource: 'argument',
+    });
+    if (error)
+        failure('INVALID_ARGS', error);
+    if (!path.isAbsolute(plan.project))
+        failure('INVALID_ARGS', 'project must be an absolute path');
+    if (fs.existsSync(plan.project) && !fs.statSync(plan.project).isDirectory())
+        failure('INVALID_ARGS', 'project is not a directory');
+    const card = validateAgentMdFrontmatter(buildInitialAgentMd(plan), plan.aid);
+    if (!card.valid)
+        failure('INVALID_ARGS', card.errors.join('; '));
+    if (plan.persona !== undefined) {
+        if (typeof plan.persona !== 'string')
+            failure('INVALID_ARGS', 'persona must be text');
+        const personaError = validateInitializationPersonaContent(plan.persona);
+        if (personaError)
+            failure('INVALID_ARGS', personaError);
+    }
+}
+function cardHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function matchesCard(content, plan) {
+    if (!validateAgentMdFrontmatter(content, plan.aid).valid)
+        return false;
+    const fields = parse(content.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? '');
+    return fields?.aid === plan.aid && fields.name === plan.name && fields.description === plan.description
+        && fields.type === plan.type && JSON.stringify(fields.tags) === JSON.stringify(plan.tags);
+}
+/** Daemon-owned, durable creation. All public entry points authorize before calling this service. */
+export class AgentInitializationService {
+    deps;
+    running = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    status(aid) {
+        const summary = initializationSummary(aid);
+        if (!summary)
+            return { ok: false, code: 'NOT_FOUND', error: 'No initialization record', aid };
+        const config = loadAgent(aid);
+        const complete = summary.complete === true && config?.lifecycle === 'active';
+        return {
+            ok: summary.status !== 'failed' && summary.status !== 'cancelled', aid, accepted: true,
+            ...summary, complete, lifecycle: config?.lifecycle ?? null,
+            usable: complete && this.deps.usable(aid), initialization: summary,
+        };
+    }
+    start(plan, actor, dryRun = false) {
+        if (this.deps.authorize && !this.deps.authorize(actor))
+            failure('NOT_ALLOWED');
+        validateInitializationPlan(plan);
+        const fingerprint = initializationFingerprint(plan);
+        const existing = readInitialization(plan.aid);
+        if (existing) {
+            if (existing.actor !== actor || existing.fingerprint !== fingerprint)
+                failure('INITIALIZE_PLAN_CONFLICT');
+            const config = loadAgent(plan.aid);
+            if (existing.status === 'complete'
+                && (!config || config.initialization?.operationId !== existing.operationId)) {
+                failure('INITIALIZE_STATE_INVALID');
+            }
+            return dryRun ? { ok: true, dryRun: true, aid: plan.aid, fingerprint } : this.status(plan.aid);
+        }
+        if (fs.existsSync(agentConfig(plan.aid)) || fs.existsSync(aidLocalDir(plan.aid)))
+            failure('INITIALIZE_TARGET_EXISTS');
+        if (dryRun) {
+            const { persona, ...safe } = plan;
+            return { ok: true, dryRun: true, aid: plan.aid, plan: safe, fingerprint, persona: { provided: persona !== undefined } };
+        }
+        const r = {
+            version: 1, operationId: `init-${randomBytes(12).toString('hex')}`, actor, plan, fingerprint,
+            status: 'in_progress', phase: 'planned', startedAt: Date.now(), updatedAt: Date.now(),
+        };
+        saveInitialization(r);
+        this.launch(r);
+        return this.status(plan.aid);
+    }
+    resume(aid, actor) {
+        if (this.deps.authorize && !this.deps.authorize(actor))
+            failure('NOT_ALLOWED');
+        const r = readInitialization(aid);
+        if (!r)
+            failure('NOT_FOUND');
+        if (r.actor !== actor)
+            failure('INITIALIZE_OWNER_MISMATCH');
+        if (r.status === 'cancelled')
+            failure('INITIALIZE_CANCELLED');
+        if (r.status !== 'complete' && !this.running.has(aid)) {
+            validateInitializationPlan(r.plan);
+            r.status = 'in_progress';
+            delete r.error;
+            delete r.code;
+            saveInitialization(r);
+            this.launch(r);
+        }
+        return this.status(aid);
+    }
+    async cancel(aid) {
+        const r = readInitialization(aid);
+        if (!r || r.status === 'complete')
+            return;
+        r.status = 'cancelled';
+        r.code = 'INITIALIZE_CANCELLED';
+        saveInitialization(r);
+        await this.running.get(aid);
+    }
+    async settle(aid) { await this.running.get(aid); }
+    launch(r) {
+        const aid = r.plan.aid;
+        const work = Promise.resolve().then(() => this.run(r)).catch(error => {
+            // Cancellation wins over a stale worker, including delete while network I/O was pending.
+            let current;
+            try {
+                current = readInitialization(aid);
+            }
+            catch {
+                return;
+            }
+            if (!current || current.status === 'cancelled')
+                return;
+            r.status = 'failed';
+            r.code = error.code ?? 'INITIALIZE_FAILED';
+            // External provider errors may contain credentials or payloads; expose the failing phase instead.
+            r.error = `Initialization failed at ${r.phase} (${r.code})`;
+            saveInitialization(r);
+        }).catch(() => { })
+            .finally(() => this.running.delete(aid));
+        this.running.set(aid, work);
+    }
+    check(r) {
+        if (this.deps.authorize && !this.deps.authorize(r.actor))
+            failure('NOT_ALLOWED');
+        const current = readInitialization(r.plan.aid);
+        if (!current || current.operationId !== r.operationId || current.status === 'cancelled')
+            failure('INITIALIZE_CANCELLED');
+        const config = loadAgent(r.plan.aid);
+        if (r.configSaved && (!config || config.enabled === false))
+            failure('INITIALIZE_TARGET_CHANGED');
+        if (config && (config.initialization?.operationId !== r.operationId
+            || JSON.stringify(config.owners) !== JSON.stringify(r.plan.owners)
+            || config.active_baseagent !== r.plan.baseagent || config.projects?.defaultPath !== r.plan.project)) {
+            failure('INITIALIZE_TARGET_CHANGED');
+        }
+    }
+    phase(r, phase) {
+        this.check(r);
+        r.phase = phase;
+        saveInitialization(r);
+    }
+    async run(r) {
+        const p = r.plan;
+        this.phase(r, 'registering_aid');
+        await this.deps.register(p.aid);
+        this.phase(r, 'config_saved');
+        fs.mkdirSync(p.project, { recursive: true });
+        if (!loadAgent(p.aid)) {
+            saveAgent({
+                $schema_version: CONFIG_SCHEMA_VERSION, aid: p.aid, enabled: true, lifecycle: 'created',
+                initialization: { mode: 'supplied', operationId: r.operationId }, channels: [], owners: p.owners,
+                projects: { defaultPath: p.project }, active_baseagent: p.baseagent,
+                baseagents: { [p.baseagent]: {} }, chatmode: { private: 'interactive', group: 'proactive', nothuman: 'proactive' },
+            });
+        }
+        r.configSaved = true;
+        this.phase(r, 'persona_saved');
+        ensureAgentDirSkeleton(p.aid);
+        ensureInitialRoleRegistry(p.aid);
+        if (p.persona !== undefined) {
+            const file = path.join(agentPersonalDir(p.aid), 'persona.md');
+            if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') !== p.persona)
+                failure('INITIALIZE_PLAN_CONFLICT');
+            fs.writeFileSync(file, p.persona, { encoding: 'utf8', mode: 0o600 });
+        }
+        await syncOwnerContactsAfterCreate(p.aid, p.owners);
+        this.phase(r, 'uploading_agentmd');
+        let remote;
+        if (r.publicationStarted) {
+            // Resolve unknown publish outcomes before attempting a second write.
+            try {
+                remote = await this.deps.fetch(p.aid);
+                this.check(r);
+                if (!matchesCard(remote.content, p) || !remote.verified) {
+                    if (r.published || (r.previousCardHash !== 'none' && cardHash(remote.content) !== r.previousCardHash)) {
+                        failure('INITIALIZE_AGENTMD_VERIFY_FAILED');
+                    }
+                    remote = undefined; // The pre-publication card is still remote: retry the same frozen plan.
+                }
+            }
+            catch (error) {
+                const code = String(error.code ?? '');
+                const message = error instanceof Error ? error.message : String(error);
+                if (code !== 'AGENTMD_NOT_FOUND' && !/not found|404|missing/i.test(message)) {
+                    failure('INITIALIZE_AGENTMD_VERIFY_FAILED');
+                }
+                remote = undefined;
+            }
+        }
+        else {
+            try {
+                const previous = await this.deps.fetch(p.aid);
+                this.check(r);
+                r.previousCardHash = cardHash(previous.content);
+            }
+            catch (error) {
+                const code = String(error.code ?? '');
+                const message = error instanceof Error ? error.message : String(error);
+                if (code !== 'AGENTMD_NOT_FOUND' && !/not found|404|missing/i.test(message))
+                    failure('INITIALIZE_AGENTMD_VERIFY_FAILED');
+                // A newly registered AID normally has no remote card yet.
+                r.previousCardHash = 'none';
+                this.check(r);
+            }
+        }
+        if (!remote) {
+            r.publicationStarted = true;
+            saveInitialization(r);
+            await this.deps.publish(p.aid, buildInitialAgentMd(p));
+            this.check(r);
+            r.published = true;
+            saveInitialization(r);
+            remote = await this.deps.fetch(p.aid);
+        }
+        this.check(r);
+        if (!remote.verified || !matchesCard(remote.content, p))
+            failure('INITIALIZE_AGENTMD_VERIFY_FAILED');
+        if (!fs.existsSync(agentMdPath(p.aid)) || !matchesCard(fs.readFileSync(agentMdPath(p.aid), 'utf8'), p)) {
+            failure('INITIALIZE_AGENTMD_VERIFY_FAILED');
+        }
+        r.published = true;
+        r.verified = true;
+        this.phase(r, 'hot_loading');
+        const config = loadAgent(p.aid);
+        if (config.lifecycle !== 'active') {
+            config.lifecycle = 'bootstrapping';
+            saveAgent(config);
+        }
+        await this.deps.hotLoad(p.aid);
+        this.phase(r, 'activating');
+        if (p.persona !== undefined && fs.readFileSync(path.join(agentPersonalDir(p.aid), 'persona.md'), 'utf8') !== p.persona) {
+            failure('INITIALIZE_PLAN_CONFLICT');
+        }
+        r.activationPrepared = true;
+        saveInitialization(r);
+        const result = await this.deps.activate(p.aid);
+        this.check(r);
+        if (!result.ok)
+            failure(result.code ?? 'INITIALIZE_WELCOME_UNAVAILABLE');
+        if (loadAgent(p.aid)?.lifecycle !== 'active')
+            failure('INITIALIZE_STATE_INVALID');
+        // Activation is durable even if a post-commit network delivery failed.
+        r.welcome = result.welcome;
+        r.phase = 'active';
+        r.status = 'complete';
+        saveInitialization(r);
+    }
+}
+/** Called only after the IPC adapter has validated the local control token. */
+export function executeLocalInitializationCommand(service, command) {
+    try {
+        if (!Array.isArray(command.argv) || command.argv.some(value => typeof value !== 'string')) {
+            return { ok: false, code: 'INVALID_ARGS', error: 'argv required' };
+        }
+        const argv = command.argv;
+        const parsed = parseInitializationArgs(argv);
+        if (command.poll === true)
+            return service.status(parsed.aid);
+        if (parsed.resume) {
+            const record = readInitialization(parsed.aid);
+            if (!record)
+                return { ok: false, code: 'NOT_FOUND', error: 'No initialization record' };
+            return service.resume(parsed.aid, record.actor);
+        }
+        return service.start(resolveInitializationPlan(argv), 'local-control', parsed.dryRun);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            code: error.code ?? 'INVALID_ARGS',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** Shared strict grammar for CLI, permission inspection and daemon dispatch. */
+export function parseInitializationArgs(args) {
+    const resume = args[0] === 'initialize';
+    if ((!resume && args[0] !== 'new') || !isValidAid(args[1] ?? ''))
+        throw new Error('Invalid initialization command or AID');
+    const booleans = new Set(resume ? ['--resume'] : ['--initialize', '--non-interactive', '--dry-run']);
+    const strings = new Set(resume ? ['--wait', '--format'] : [
+        '--project', '--baseagent', '--owner', '--owners', '--name', '--description', '--tags', '--type',
+        '--persona-file', '--persona-text', '--wait', '--format',
+    ]);
+    const seen = new Set();
+    const values = {};
+    for (let i = 2; i < args.length; i++) {
+        const flag = args[i];
+        if (seen.has(flag) || (!strings.has(flag) && !booleans.has(flag)))
+            throw new Error(`Unsupported or repeated option: ${flag}`);
+        seen.add(flag);
+        if (strings.has(flag)) {
+            const value = args[++i];
+            if (value === undefined || value.startsWith('--'))
+                throw new Error(`${flag} requires a value`);
+            values[flag] = value;
+        }
+    }
+    if (!seen.has(resume ? '--resume' : '--initialize'))
+        throw new Error(resume ? '--resume required' : '--initialize required');
+    if (values['--format'] !== undefined && values['--format'] !== 'json')
+        throw new Error('--format must be json');
+    if (seen.has('--persona-file') && seen.has('--persona-text'))
+        throw new Error('persona sources are mutually exclusive');
+    if (!resume) {
+        for (const key of ['--name', '--description', '--tags'])
+            if (!values[key]?.trim())
+                throw new Error(`${key} must be explicitly supplied`);
+        parseAgentOwnerArgs(args);
+        parseAgentTags(values['--tags']);
+    }
+    const wait = values['--wait'] === undefined ? 60 : Number(values['--wait']);
+    if (!Number.isInteger(wait) || wait < 0 || wait > 300)
+        throw new Error('--wait must be an integer from 0 to 300');
+    return { aid: args[1], resume, dryRun: seen.has('--dry-run'), wait, values };
+}
+export function resolveInitializationPlan(args) {
+    const parsed = parseInitializationArgs(args);
+    if (parsed.resume)
+        throw new Error('A resume request cannot supply a new plan');
+    const v = parsed.values;
+    if (v['--persona-file'] !== undefined)
+        throw new Error('CLI must submit persona file contents as text');
+    const p = resolveAgentCreatePlan({
+        aid: parsed.aid, project: v['--project'], baseagent: v['--baseagent'], ...parseAgentOwnerArgs(args),
+        name: v['--name'], description: v['--description'], tags: parseAgentTags(v['--tags']), type: v['--type'],
+    });
+    return {
+        aid: p.aid, project: p.project, baseagent: p.baseagent ?? '', owners: p.owners ?? (p.owner ? [p.owner] : []),
+        name: p.name, description: p.description, tags: p.tags, type: p.type,
+        ...(v['--persona-text'] !== undefined ? { persona: v['--persona-text'] } : {}),
+    };
+}
+export function readInitializationPersona(file, managed) {
+    const resolved = path.resolve(file);
+    if (!/\.(md|txt)$/i.test(resolved))
+        throw new Error('persona file must be .md or .txt');
+    const stat = fs.lstatSync(resolved);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536)
+        throw new Error('persona must be a regular text file of at most 64 KiB');
+    if (managed) {
+        const real = fs.realpathSync(resolved);
+        const roots = [process.cwd(), process.env.TMPDIR].filter((r) => !!r && path.isAbsolute(r));
+        const allowed = roots.some(root => isSameOrDescendant(real, fs.realpathSync(root)));
+        if (!allowed || isHClassPath(real) || isLClassPath(real))
+            throw new Error('persona file must be inside the project or current TMPDIR');
+    }
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(resolved));
+    const error = validateInitializationPersonaContent(text);
+    if (error)
+        throw new Error(error);
+    return text;
+}
+export async function runInitializationCommand(args) {
+    const parsed = parseInitializationArgs(args);
+    const managed = !!process.env.EVOLCORE_SESSION_ID;
+    const argv = [...args];
+    if (parsed.values['--persona-file'] !== undefined) {
+        const at = argv.indexOf('--persona-file');
+        argv.splice(at, 2, '--persona-text', readInitializationPersona(parsed.values['--persona-file'], managed));
+    }
+    if (!parsed.resume) {
+        const at = argv.indexOf('--project');
+        if (at < 0)
+            argv.push('--project', process.cwd());
+        else
+            argv[at + 1] = path.resolve(argv[at + 1]);
+    }
+    const request = async (poll) => {
+        if (managed) {
+            const { runManagedAgentOperation } = await import('./agent.js');
+            const r = await runManagedAgentOperation(poll ? ['show', parsed.aid, '--format', 'json'] : argv);
+            if (!poll || !r.ok || !r.initialization)
+                return r;
+            const init = r.initialization;
+            return { ...init, ok: !['failed', 'cancelled'].includes(init.status), aid: parsed.aid,
+                accepted: true, lifecycle: r.lifecycle, usable: init.complete && r.connection?.status === 'connected' };
+        }
+        return await ipcQuery(resolvePaths().socket, {
+            type: 'evolagent.initialize', argv, poll,
+        }, 10_000) ?? { ok: false, code: 'DAEMON_UNAVAILABLE', error: 'Initialization requires a running daemon' };
+    };
+    let result = await request(false);
+    if (parsed.dryRun)
+        return result;
+    const deadline = Date.now() + parsed.wait * 1000;
+    while (result.ok && !result.complete && result.accepted && Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, 500));
+        result = await request(true);
+    }
+    if (result.ok && !result.complete && result.accepted)
+        return { ...result, ok: false, code: 'INITIALIZE_PENDING', error: 'Initialization is still running; inspect agent show' };
+    if (result.complete && !result.usable)
+        return { ...result, ok: false, code: 'INITIALIZE_NOT_USABLE', error: 'Initialized; runtime is not currently connected' };
+    return result;
 }