evolcore 0.0.22 → 0.0.24

package/dist/index.js

@@ -45,7 +45,7 @@ import { ResponseEngine } from './core/message/response-engine.js';
 import { MessageQueue } from './core/message/message-queue.js';
 import { MessageBridge } from './core/message/message-bridge.js';
 import { evaluateOutboundContactAdmission } from './core/message/message-admission.js';
-import { evaluateEvolMenuVersionGate, evolMenuResponseTransportMetadata, MenuRequestDeduper, hasValidMenuId, menuFailure, menuPayloadFingerprint, normalizeMenuResponseTiming, parseMenuControl, validateMenuRequest, withMenuProcessingTime, logMenuRequestCompleted, logMenuRequestReceived } from './core/command/menu-protocol.js';
+import { enforceMenuResponseSize, evaluateMenuClientCompatibility, evolMenuResponseTransportMetadata, MenuRequestDeduper, hasValidMenuId, menuFailure, menuPayloadFingerprint, normalizeMenuResponseTiming, parseMenuControl, validateMenuRequest, withMenuProcessingTime, logMenuRequestCompleted, logMenuRequestReceived } from './core/command/menu-protocol.js';
 import { readInstalledEvolcoreVersion } from './utils/evolcore-version.js';
 import { recoverAllRoleMutationsSync } from './core/command/role-menu.js';
 import { HandoffRuntime } from './core/handoff/runtime.js';
@@ -74,7 +74,7 @@ import { AgentReloadBusyError, AgentReloadCoordinator } from './core/agent-reloa
 import { buildReloadHooks } from './core/channel-loader.js';
 import { IpcServer } from './ipc.js';
 import { logger, setLogLevel } from './utils/logger.js';
-import { fetchEcwebPairCode } from './utils/ecweb-utils.js';
+import { remoteAccessService } from './core/auth/remote-access-store.js';
 import { createEcwebSupervisor } from './utils/ecweb-supervisor.js';
 import { writeMain, removeAll, isMainWinner, scanInstances } from './utils/instance-registry.js';
 import { detectDuplicates } from './core/evolagent-registry.js';
@@ -100,6 +100,7 @@ import { MAIN_PACKAGE_NAME } from './product.js';
 import fs from 'fs';
 import crypto from 'crypto';
 import { fileURLToPath } from 'url';
+import * as platform from './utils/cross-platform.js';
 const controlMenuDeduper = new MenuRequestDeduper();
 /** 出站 payload 摘要（用于 channel-out.log） */
 function summarizeOutboundPayload(payload) {
@@ -134,6 +135,7 @@ function summarizeOutboundPayload(payload) {
             break;
         case 'status.started':
         case 'status.progress':
+        case 'status.notice':
         case 'status.requires_action':
         case 'status.queued':
         case 'status.completed':
@@ -326,11 +328,21 @@ function seedUpgradeCheckTrigger(manager, owner) {
     const cliPath = path.join(packageRoot, 'dist', 'cli', 'index.js');
     const packageJsonPath = path.join(packageRoot, 'package.json');
     const devMode = fs.existsSync(path.join(packageRoot, 'src', 'index.ts'));
+    // Resolve the launch argv at generation time: in a checkout this points the
+    // monitor at src/ through tsx, so a `npm run build` that wipes dist/ cannot
+    // take the watchdog down with it.
+    const monitorEntry = platform.resolveCliEntry(packageRoot);
+    const stageParent = path.join(resolvePaths().root, 'data', 'monitor-stage');
     fs.writeFileSync(scriptPath, `#!/usr/bin/env node
-const { existsSync, readFileSync } = require('node:fs');
+const fs = require('node:fs');
+const path = require('node:path');
+const { existsSync, readFileSync } = fs;
 const { spawn } = require('node:child_process');
 
-const CLI_PATH = ${JSON.stringify(cliPath)};
+const CLI_PATH = ${JSON.stringify(monitorEntry.entry)};
+const CLI_ARGS = ${JSON.stringify(monitorEntry.args)};
+const PACKAGE_ROOT = ${JSON.stringify(packageRoot)};
+const STAGE_PARENT = ${JSON.stringify(stageParent)};
 const PACKAGE_JSON = ${JSON.stringify(packageJsonPath)};
 const PACKAGE_NAME = ${JSON.stringify(MAIN_PACKAGE_NAME)};
 const DEV_MODE = ${devMode ? 'true' : 'false'};
@@ -405,14 +417,60 @@ async function main() {
     return;
   }
 
+  // Installed mode: copy the monitor out of the package before it upgrades that
+  // same package. Mirrors prepareMonitorStage(); kept inline because this file
+  // is generated standalone CJS. Any failure degrades to launching in place —
+  // losing upgrade isolation beats losing the upgrade.
+  let launchArgs = CLI_ARGS;
+  const launchEnv = { ...process.env };
+  if (!DEV_MODE && STAGE_PARENT) {
+    try {
+      const stageDir = path.join(STAGE_PARENT, 'upgrade-' + process.pid + '-' + Date.now());
+      fs.mkdirSync(stageDir, { recursive: true });
+      fs.cpSync(path.join(PACKAGE_ROOT, 'dist'), path.join(stageDir, 'dist'), { recursive: true });
+      if (existsSync(PACKAGE_JSON)) fs.copyFileSync(PACKAGE_JSON, path.join(stageDir, 'package.json'));
+      const modulesSource = path.join(PACKAGE_ROOT, 'node_modules');
+      if (existsSync(modulesSource)) {
+        const staged = path.join(stageDir, 'node_modules');
+        try {
+          // junction works unelevated on Windows; dir symlink elsewhere.
+          fs.symlinkSync(modulesSource, staged, process.platform === 'win32' ? 'junction' : 'dir');
+          fs.readdirSync(staged);
+        } catch (linkError) {
+          fs.rmSync(staged, { recursive: true, force: true });
+          fs.cpSync(modulesSource, staged, { recursive: true });
+        }
+      }
+      const stagedEntry = path.join(stageDir, 'dist', 'cli', 'index.js');
+      if (existsSync(stagedEntry)) {
+        launchArgs = [stagedEntry];
+        launchEnv.EVOLCORE_TARGET_PACKAGE_ROOT = PACKAGE_ROOT;
+        launchEnv.EVOLCORE_MONITOR_STAGE = stageDir;
+      }
+    } catch (stageError) {
+      // Fall through with the in-place entry.
+    }
+  }
+
   try {
-    const child = spawn(process.execPath, [CLI_PATH, 'restart-monitor'], {
+    const child = spawn(process.execPath, [...launchArgs, 'restart-monitor'], {
       detached: true,
       stdio: 'ignore',
       windowsHide: process.platform === 'win32',
-      env: { ...process.env },
+      env: launchEnv,
     });
     child.unref();
+    const pid = child.pid;
+    // The daemon is still running here — the monitor is what stops it. So a
+    // monitor that dies on load costs the upgrade, not the service; still,
+    // report it accurately instead of claiming success.
+    await new Promise(resolve => setTimeout(resolve, 3000));
+    let alive = false;
+    try { process.kill(pid, 0); alive = true; } catch (e) { alive = false; }
+    if (!alive) {
+      emit('error', 'restart-monitor exited during startup; upgrade to ' + remoteVersion + ' not applied');
+      return;
+    }
     emit('success', 'evolcore upgrade available: ' + localVersion + ' -> ' + remoteVersion + '; restart-monitor started');
   } catch (error) {
     emit('error', 'failed to start restart-monitor: ' + (error && error.message ? error.message : String(error)));
@@ -551,6 +609,7 @@ async function runBindBootstrapDaemon(daemonCfg) {
         })(),
     }));
     ipcServer.setControlToken(controlToken);
+    ipcServer.setRemoteAccessService(remoteAccessService);
     ipcServer.setShutdownExecutor(async (reason) => {
         if (!shutdown) {
             pendingShutdownReason = reason;
@@ -1065,7 +1124,7 @@ async function main() {
     agentLoader.register(new GeminiAgentPlugin());
     agentLoader.register(new EcagentAgentPlugin());
     const creationErrors = [];
-    const agentInstances = agentLoader.createAll(agentRegistry, {
+    const agentInstances = await agentLoader.createAll(agentRegistry, {
         onSessionIdUpdate: async (sessionId, agentSessionId, context) => {
             return await sessionManager.updateAgentSessionIdBySessionId(sessionId, agentSessionId, context?.turn);
         },
@@ -1354,6 +1413,7 @@ async function main() {
         baseagent: primaryAgent?.baseagent || 'codex',
         projectPath: primaryAgent?.projectPath || process.cwd(),
     };
+    cmdHandler.setDaemonTriggerOwner(daemonTriggerOwner.aid, daemonChannel.channelName);
     const triggerBaseagentsForAgent = (agentAid) => {
         const ownerName = agentRegistry.get(agentAid)?.name
             ?? (agentAid === daemonTriggerOwner.aid ? primaryAgent?.name : undefined);
@@ -1491,8 +1551,9 @@ async function main() {
         }
         if (definition.execution.effort && !actor.daemonPrivileged) {
             const baseagent = definition.execution.baseagent
-                ?? agentRegistry.get(definition.agentAid)?.baseagent
-                ?? 'claude';
+                ?? agentRegistry.get(definition.agentAid)?.baseagent;
+            if (!baseagent)
+                throw new Error('cannot determine Trigger baseagent');
             const effortDecision = validateRuntimeStringFieldOverride({
                 selfAid: definition.agentAid,
                 role: actor.role,
@@ -2152,6 +2213,7 @@ async function main() {
             const pendingRouteContext = restartDelivery.delivery ? { delivery: restartDelivery.delivery } : {};
             const replyContext = {
                 ...(pendingRouteContext ?? {}),
+                ...(pending.threadId ? { threadId: pending.threadId } : {}),
                 ...(pending.rootId ? { replyToMessageId: pending.rootId, replyInThread: !!pending.threadId } : {}),
             };
             const owningAgent = agentRegistry.resolveByChannel(adapter.channelKey);
@@ -2163,10 +2225,23 @@ async function main() {
                 ...(restartDelivery.delivery ? { delivery: restartDelivery.delivery } : {}),
                 replyContext: Object.keys(replyContext).length > 0 ? replyContext : undefined,
             });
+            // restart-monitor 会在回滚/升级时写入 outcome：必须如实告诉发起方这次跑的是
+            // 哪个版本，否则 agent 会以为自己的改动或升级已经生效。
+            const restartNotice = pending.outcome === 'rolled-back'
+                ? {
+                    text: `⚠️ 服务已重启，但运行的是上一个版本。${pending.outcomeReason ? `原因：${pending.outcomeReason}。` : ''}本次改动未生效，请检查后重试。`,
+                    subtype: 'restarted-rolled-back',
+                }
+                : pending.outcome === 'upgraded'
+                    ? {
+                        text: `✅ 服务重启成功！${pending.outcomeReason ? `${pending.outcomeReason}` : ''}`,
+                        subtype: 'restarted-upgraded',
+                    }
+                    : { text: '✅ 服务重启成功！', subtype: 'restarted' };
             await sendSystemPayload(adapter, envelope, {
                 kind: 'system.notice',
-                text: '✅ 服务重启成功！',
-                subtype: 'restarted',
+                text: restartNotice.text,
+                subtype: restartNotice.subtype,
             });
             pendingRestartNoticeSent = true;
             fs.rmSync(pendingFile, { force: true });
@@ -2309,6 +2384,7 @@ async function main() {
         return cmdHandler.handleCtl(cmd, sessionId, delegation.grant);
     });
     ipcServer.setDaemonRuntimeEpoch(agentDelegationRegistry.getRuntimeEpoch());
+    cmdHandler.setDaemonMonitorProvider(() => ipcServer.getMonitorSnapshot().snapshot);
     // Register every IPC executor/provider before exposing the endpoint. The
     // function declaration is hoisted, while its invocation remains here so a
     // failed bind still aborts before any AUN connection is attempted.
@@ -2378,10 +2454,10 @@ async function main() {
         catch (e) {
             logger.warn(`控制 AID 首连失败（后台自动重连，不影响 daemon 主流程）: ${e?.message || e}`);
         }
-        // 控制 AID 接收 owner 指令：
-        // 1. /pair — ECWeb 配对码（文本快路径）
+        // 控制 AID 接收 daemon-owner 或有效远程访问 token 授权的指令：
+        // 1. /pair — daemon 远程控制配对码（文本快路径）
         // 2. menu.* JSON — 路由到 cmdHandler.execMenuForControl（进程级 + 全量权限）
-        // 发送方身份由 AUN X.509 证书链验证，非 owner 完全静默。
+        // 发送方身份由 AUN X.509 证书链验证；非 Menu 文本仍只接受 daemon-owner。
         controlChannel.onMessage(async (opts) => {
             let activeMenuRequest;
             let menuCompletionLogged = false;
@@ -2389,6 +2465,11 @@ async function main() {
                 source: 'control-aun',
                 selfAid: daemonCfg.aid,
                 messageId: opts.messageId,
+                requesterAid: opts.peerId,
+                authMethod: opts.protectedHeaders?.auth_method === 'remote-access-token' || opts.protectedHeaders?.auth_method === 'ecweb-token'
+                    ? opts.protectedHeaders.auth_method
+                    : 'daemon-owner',
+                clientName: opts.protectedHeaders?.client_name ?? 'evol',
             };
             try {
                 const menuTiming = normalizeMenuResponseTiming(opts);
@@ -2402,7 +2483,7 @@ async function main() {
                 }
                 const menuResponseContext = () => controlReplyContext(opts, evolMenuResponseTransportMetadata());
                 const sendControlMenuResponse = async (response) => {
-                    const timedResponse = withMenuProcessingTime(response, menuTiming);
+                    const timedResponse = withMenuProcessingTime(enforceMenuResponseSize(response, 128 * 1024 - 1024), menuTiming);
                     const request = activeMenuRequest ?? {
                         type: 'menu.unknown',
                         id: response.id,
@@ -2450,7 +2531,21 @@ async function main() {
                     menuCompletionLogged = true;
                     return;
                 }
-                if (menuControl.isMenu && !isRoleMenu && !isProcessLevelOwner(opts.peerId, currentProcessOwners)) {
+                const menuClientCompatibilityError = menuControl.isMenu
+                    ? evaluateMenuClientCompatibility({ encrypted: opts.encrypted, protectedHeaders: opts.protectedHeaders })
+                    : null;
+                if (menuControl.isMenu && menuClientCompatibilityError) {
+                    await sendControlMenuResponse(menuFailure({ id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) }, menuClientCompatibilityError));
+                    return;
+                }
+                const protectedMenuHeaders = opts.protectedHeaders;
+                const hasRemoteAccessToken = protectedMenuHeaders?.auth_method === 'remote-access-token'
+                    || protectedMenuHeaders?.auth_method === 'ecweb-token';
+                if (text.toLowerCase() === '/pair' && !isProcessLevelOwner(opts.peerId, currentProcessOwners)) {
+                    logger.debug(`控制 AID 收到非 owner 配对请求，忽略: from=${opts.peerId}`);
+                    return;
+                }
+                if (menuControl.isMenu && !isRoleMenu && !hasRemoteAccessToken && !isProcessLevelOwner(opts.peerId, currentProcessOwners)) {
                     const response = menuFailure({ id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) }, {
                         code: 'NOT_ALLOWED',
                         message: formatAuthorizationDenial('Control-channel process operations require DaemonOwner.', 'DAEMON_OWNER_REQUIRED'),
@@ -2459,40 +2554,28 @@ async function main() {
                     await sendControlMenuResponse(response);
                     return;
                 }
-                if (!isRoleMenu && !isProcessLevelOwner(opts.peerId, currentProcessOwners)) {
+                if (!isRoleMenu && !hasRemoteAccessToken && !isProcessLevelOwner(opts.peerId, currentProcessOwners)) {
                     logger.debug(`控制 AID 收到非 owner 消息，忽略: from=${opts.peerId}`);
                     return;
                 }
                 if (text.toLowerCase() === '/pair') {
-                    const port = ecwebService(loadDaemonConfig().services)?.port ?? DEFAULT_ECWEB_PORT;
-                    const pair = await fetchEcwebPairCode(port, opts.peerId);
-                    let reply;
-                    if (pair) {
-                        const mins = Math.max(0, Math.round((pair.expiresAt - Date.now()) / 60000));
-                        reply = `ECWeb 配对码：${pair.code}（约 ${mins} 分钟内有效）\n在浏览器打开 ECWeb 后输入此码登录`;
-                    }
-                    else {
-                        reply = 'ECWeb 未运行或暂不可达。请在主机运行 ec watch web 启动后重试。';
-                    }
+                    const pair = remoteAccessService.getPairingCode(opts.peerId);
+                    const mins = Math.max(0, Math.round((pair.expiresAt - Date.now()) / 60000));
+                    const reply = `远程控制配对码：${pair.code}（约 ${mins} 分钟内有效）`;
                     await controlChannel.sendMessage(opts.channelId, reply, controlReplyContext(opts));
                     return;
                 }
-                // menu.* JSON 路由：owner 已在上方校验，转交 execMenuForControl（fromControlChannel=true）
+                // menu.* JSON 路由：准入来源在上方分流，最终 token/owner 校验由 execMenuForControl 完成。
                 if (menuControl.isMenu) {
-                    const versionError = evaluateEvolMenuVersionGate({
-                        encrypted: opts.encrypted,
-                        protectedHeaders: opts.protectedHeaders,
-                    });
-                    if (versionError) {
-                        await sendControlMenuResponse(menuFailure({ id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) }, versionError));
-                        return;
-                    }
                     const validationError = validateMenuRequest(menuControl.request);
                     if (validationError) {
                         await sendControlMenuResponse(menuFailure({ id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) }, validationError));
                         return;
                     }
-                    const deduped = await controlMenuDeduper.execute([opts.channelId, opts.peerId, menuControl.id].join('\u001f'), menuPayloadFingerprint(menuControl.raw), () => cmdHandler.execMenuForControl(parsed, opts.peerId));
+                    const deduped = await controlMenuDeduper.execute([opts.channelId, opts.peerId, menuControl.id].join('\u001f'), menuPayloadFingerprint(menuControl.raw), () => cmdHandler.execMenuForControl(parsed, opts.peerId, {
+                        encrypted: opts.encrypted,
+                        protectedHeaders: opts.protectedHeaders,
+                    }));
                     if ('retry' in deduped) {
                         if (deduped.replayed) {
                             logger.warn(`[MenuControl] category=request-replay request=${menuControl.id}`
@@ -2512,7 +2595,7 @@ async function main() {
                     return;
                 }
                 // owner 发的其他内容：提示可用指令
-                await controlChannel.sendMessage(opts.channelId, '可用指令：/pair（获取 ECWeb 登录配对码）', controlReplyContext(opts));
+                await controlChannel.sendMessage(opts.channelId, '可用指令：/pair（获取远程控制配对码）', controlReplyContext(opts));
             }
             catch (e) {
                 if (activeMenuRequest && !menuCompletionLogged) {
@@ -2648,9 +2731,18 @@ async function main() {
                 continue;
             }
             const evolName = owningAgent.aid;
-            const baseagentName = session.baseagent || primaryBaseagent;
-            const agent = agentMap.get(`${evolName}::${baseagentName}`) || agentMap.get(primaryRunnerKey);
+            const baseagentName = typeof session.baseagent === 'string' ? session.baseagent.trim() : '';
+            if (!baseagentName) {
+                logger.error(`[Resume] session ${session.id}: missing baseagent binding, refusing implicit runner fallback`);
+                sessionManager.clearProcessing(session.id);
+                continue;
+            }
+            // Recovery must resume on the exact Agent × baseagent runner recorded by
+            // the Session. Never fall back to the primary runner: doing so can bind
+            // an in-flight session to a different backend.
+            const agent = agentMap.get(`${evolName}::${baseagentName}`);
             if (!agent) {
+                logger.error(`[Resume] session ${session.id}: runner unavailable for ${evolName}::${baseagentName}; refusing fallback`);
                 sessionManager.clearProcessing(session.id);
                 continue;
             }
@@ -2688,6 +2780,7 @@ async function main() {
         // M3: direct call (not cast) — wire EvolAgentRegistry into IPC for evolagent.* handlers
         ipcServer.setAgentRegistry(agentRegistry);
         ipcServer.setControlToken(triggerControlToken);
+        ipcServer.setRemoteAccessService(remoteAccessService);
         ipcServer.setBootstrapCompleteExecutor(async (aid, auth) => {
             if (auth?.sessionId) {
                 const authorization = await authorizeManagedAgentOperation({
@@ -2716,11 +2809,12 @@ async function main() {
                 return owner?.aid === aid;
             });
             const welcome = aunInstance?.channel;
-            const ownerAid = getFirstStaticAgentOwner(aid);
             const owningAgent = agentRegistry.get(aid);
-            const sessions = aunInstance && ownerAid && owningAgent
+            const firstOwnerAid = getFirstStaticAgentOwner(aid);
+            const sessions = aunInstance && firstOwnerAid && owningAgent
                 ? {
-                    ensurePostBootstrapMainSession: async () => {
+                    ensurePostBootstrapMainSession: async (owner) => {
+                        const ownerAid = owner || firstOwnerAid;
                         const channel = aunInstance.adapter.channelName;
                         const active = await sessionManager.getActiveSession(channel, ownerAid);
                         const ensured = await sessionManager.ensureNewMainSessionForOperation({
@@ -2728,7 +2822,7 @@ async function main() {
                             channelId: ownerAid,
                             projectPath: active?.projectPath || owningAgent.projectPath || defaultProjectPath,
                             baseagent: owningAgent.baseagent || active?.baseagent || primaryBaseagent,
-                            operationId: postBootstrapWelcomeOperationId(aid),
+                            operationId: postBootstrapWelcomeOperationId(aid, ownerAid),
                             identityMetadata: {
                                 ...(active?.metadata ?? {}),
                                 channelKey: aunInstance.adapter.channelKey,
@@ -2840,15 +2934,18 @@ async function main() {
             for (const runner of new Set(agentMap.values())) {
                 if (typeof runner?.evaluatePreToolUse !== 'function')
                     continue;
-                const result = await runner.evaluatePreToolUse(params.threadId, params.toolName, params.toolInput, params.signal, params.callId);
+                const result = await runner.evaluatePreToolUse(params.threadId, params.toolName, params.toolInput, params.signal, params.callId, params.sessionToken);
                 if (result.applicable)
                     return result;
             }
+            // A credential that no runner issued is forged or belongs to a thread
+            // whose rollout is gone. Never allow it; uncredentialed calls were
+            // already allowed by the IPC layer before reaching this executor.
             return {
                 ok: false,
                 applicable: true,
                 decision: 'deny',
-                reason: 'No active EvolCore Codex runner accepted this managed hook request',
+                reason: 'No active EvolCore Codex runner accepted this managed hook credential',
             };
         });
         const resolveManagedHandoffScope = async (params, operation) => {
@@ -3181,7 +3278,7 @@ async function main() {
                 const creationErrors = [];
                 const staged = candidate.config.enabled === false
                     ? []
-                    : agentLoader.createForAgent(candidate, {
+                    : await agentLoader.createForAgent(candidate, {
                         onSessionIdUpdate: async (sessionId, agentSessionId, context) => {
                             return await sessionManager.updateAgentSessionIdBySessionId(sessionId, agentSessionId, context?.turn);
                         },
@@ -3281,7 +3378,7 @@ async function main() {
                     throw new Error(agentRuntimeError);
                 }
                 const creationErrors = [];
-                const newAgentInstances = agentLoader.createForAgent(agent, {
+                const newAgentInstances = await agentLoader.createForAgent(agent, {
                     onSessionIdUpdate: async (sessionId, agentSessionId, context) => {
                         return await sessionManager.updateAgentSessionIdBySessionId(sessionId, agentSessionId, context?.turn);
                     },
@@ -3472,7 +3569,7 @@ async function main() {
             hotLoad: coreHotLoadAgent,
             resync: coreResyncAgents,
             create: async (options) => {
-                const { agentCreateNonInteractive } = await import('./cli/agent.js');
+                const { agentCreateNonInteractive } = await import('./cli/agent-create.js');
                 return await agentCreateNonInteractive(options, { hotLoadAgent: coreHotLoadAgent });
             },
             aunAids: () => channelInstances.flatMap((inst) => {
@@ -3721,12 +3818,20 @@ async function main() {
                 const aid = argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined;
                 if (!aid)
                     return fail('INVALID_ARGS', 'ec agent new requires an AID');
-                const { agentCreateNonInteractive, resolveAgentCreatePlan, validateAgentCreatePlan } = await import('./cli/agent.js');
+                const { agentCreateNonInteractive, resolveAgentCreatePlan, validateAgentCreatePlan, parseAgentOwnerArgs } = await import('./cli/agent-create.js');
+                let ownerOptions;
+                try {
+                    ownerOptions = parseAgentOwnerArgs(argv);
+                }
+                catch (error) {
+                    return fail('INVALID_ARGS', error instanceof Error ? error.message : String(error));
+                }
                 const plan = resolveAgentCreatePlan({
                     aid,
                     project: value('--project'),
                     baseagent: value('--baseagent'),
-                    owner: value('--owner'),
+                    ...ownerOptions,
+                    handoff: value('--handoff'),
                     name: value('--name'),
                     description: value('--description'),
                     force: argv.includes('--force'),
@@ -3734,23 +3839,75 @@ async function main() {
                 const validationError = validateAgentCreatePlan(plan);
                 if (validationError)
                     return fail('INVALID_ARGS', validationError);
+                if (argv.includes('--handoff')) {
+                    if (!delegation.grant.messageId)
+                        return fail('INVALID_ARGS', '--handoff requires an originating message');
+                    if (!plan.handoff?.trim())
+                        return fail('INVALID_ARGS', '--handoff requires non-empty context');
+                    if ((plan.owners?.[0] ?? plan.owner) !== taskAid) {
+                        return fail('INVALID_ARGS', '--handoff requires the creating Agent to be the first Owner');
+                    }
+                    if (plan.configExists)
+                        return fail('INVALID_ARGS', '--handoff requires a new Agent');
+                }
                 if (argv.includes('--dry-run'))
                     return { ok: true, result: { ok: true, dryRun: true, plan } };
+                let handoffId;
+                if (plan.handoff) {
+                    try {
+                        const created = await handoffRuntime.createOutbound({
+                            selfAid: taskAid,
+                            to: aid,
+                            originSessionId: sessionId,
+                            originMessageId: delegation.grant.messageId,
+                            payload: { type: 'text', text: plan.handoff },
+                            encrypt: true,
+                            targetChatType: 'private',
+                            explicitReturnPolicy: 'required',
+                            contextOnly: true,
+                            originAuthorization: {
+                                actorId: delegation.grant.actorId,
+                                channelKey: delegation.grant.channel,
+                                channelType: delegation.grant.channelType,
+                                chatType: delegation.grant.chatType,
+                                peerKey: delegation.grant.peerKey,
+                            },
+                            causation: responseEngine.getTaskRuntimeContext(sessionId)?.causation,
+                        });
+                        handoffId = created.handoff?.handoff_id;
+                        if (!handoffId)
+                            return fail('INVALID_ARGS', '--handoff requires a different target session');
+                    }
+                    catch (error) {
+                        return fail('HANDOFF_PREPARE_FAILED', error instanceof Error ? error.message : String(error));
+                    }
+                }
                 const createOptions = {
                     aid: plan.aid,
                     project: plan.project,
                     baseagent: plan.baseagent,
                     owner: plan.owner,
+                    owners: plan.owners,
                     name: plan.name,
                     description: plan.description,
                     force: argv.includes('--force'),
                 };
-                const result = agentApplicationService
-                    ? await agentApplicationService.create(createOptions)
-                    : await agentCreateNonInteractive(createOptions);
-                return !result.ok
-                    ? fail(result.code ?? 'INTERNAL', result.error)
-                    : { ok: true, result: { ...result, configPath: '[redacted]' } };
+                try {
+                    const result = agentApplicationService
+                        ? await agentApplicationService.create(createOptions)
+                        : await agentCreateNonInteractive(createOptions);
+                    if (!result.ok) {
+                        if (handoffId)
+                            handoffRuntime.store.discard(taskAid, handoffId, 'operation_failed');
+                        return fail(result.code ?? 'INTERNAL', result.error);
+                    }
+                    return { ok: true, result: { ...result, configPath: '[redacted]', ...(handoffId ? { handoff_id: handoffId } : {}) } };
+                }
+                catch (error) {
+                    if (handoffId)
+                        handoffRuntime.store.discard(taskAid, handoffId, 'operation_failed');
+                    return fail('INTERNAL', error instanceof Error ? error.message : String(error));
+                }
             }
             if (operation === 'agent.delete') {
                 const result = agentApplicationService