evolcore 0.0.11 → 0.0.12

package/dist/index.js

@@ -45,12 +45,12 @@ import { buildEnvelope } from './core/message/message-utils.js';
 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 { MenuRequestDeduper, hasValidMenuId, menuFailure, menuPayloadFingerprint, parseMenuControl, validateMenuRequest } from './core/command/menu-protocol.js';
-import { evaluateEvolMenuVersionGate, evolMenuResponseTransportMetadata } from './core/command/evol-menu-version-gate.js';
+import { evaluateEvolMenuVersionGate, evolMenuResponseTransportMetadata, MenuRequestDeduper, hasValidMenuId, menuFailure, menuPayloadFingerprint, parseMenuControl, validateMenuRequest } 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';
 import { BootstrapService, completeBootstrapWithWelcome } from './core/bootstrap-service.js';
+import { postBootstrapWelcomeOperationId } from './core/bootstrap-messages.js';
 import { MessageCache } from './core/message/message-cache.js';
 import { CommandHandler, isProcessLevelOwner } from './core/command/command-handler.js';
 import { EventBus } from './core/event-bus.js';
@@ -62,6 +62,7 @@ import { InteractionRouter } from './core/interaction-router.js';
 import { registerAdapterInteractions } from './core/interaction-registration.js';
 import { AgentDelegationRegistry, authorizeDelegatedAunMsgSend } from './core/auth/agent-delegation.js';
 import { authorizeOperation, buildAuthSubject } from './core/auth/auth-gateway.js';
+import { parsePeerKey } from './core/relation/peer-identity.js';
 import { isHClassPath } from './core/protected-paths.js';
 import { ChannelLoader, tryParseChannelKey } from './core/channel-loader.js';
 import { AgentLoader } from './core/baseagent-loader.js';
@@ -90,6 +91,7 @@ import { validateModelSelectionForRole } from './core/model/model-permission.js'
 import { constrainRuntimePermissionMode, validateRuntimeStringFieldOverride, } from './core/role/runtime-policy.js';
 import { atomicWriteJson } from './core/session/session-fs-store.js';
 import { appendMessageLog, buildOutboundEntry, classifyAunPayloadForLog } from './core/message/message-log.js';
+import { normalizeAunMentionEntries } from './aun/msg/mention-schema.js';
 import { MAIN_PACKAGE_NAME } from './product.js';
 import fs from 'fs';
 import crypto from 'crypto';
@@ -207,7 +209,7 @@ function originFromActorSession(session, authenticatedPeerId, authenticatedChann
 }
 function seedUpgradeCheckTrigger(manager, owner) {
     const now = Date.now();
-    const scriptName = 'upgrade-check.sh';
+    const scriptName = 'upgrade-check.cjs';
     const definition = normalizeTriggerDefinition({
         $schema_version: 3.1,
         id: '__upgrade-check',
@@ -234,7 +236,7 @@ function seedUpgradeCheckTrigger(manager, owner) {
             type: 'script',
             script: {
                 path: scriptName,
-                runtime: 'bash',
+                runtime: 'node',
                 timeoutMs: 60_000,
             },
             permissionMode: 'bypass',
@@ -260,67 +262,107 @@ 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'));
-    fs.writeFileSync(scriptPath, [
-        '#!/usr/bin/env bash',
-        'set -euo pipefail',
-        '',
-        `CLI_PATH=${JSON.stringify(cliPath)}`,
-        `PACKAGE_JSON=${JSON.stringify(packageJsonPath)}`,
-        `DEV_MODE=${devMode ? '1' : '0'}`,
-        '',
-        'json() {',
-        '  local outcome="$1"',
-        '  local text="$2"',
-        '  node -e \'console.log(JSON.stringify({ outcome: process.argv[1], text: process.argv[2], files: [] }))\' "$outcome" "$text"',
-        '}',
-        '',
-        'if [ "$DEV_MODE" = "1" ]; then',
-        '  json "noop" "upgrade check skipped in dev mode"',
-        '  exit 0',
-        'fi',
-        '',
-        'local_version="$(node -e \'try { console.log(require(process.argv[1]).version || "") } catch { process.exit(0) }\' "$PACKAGE_JSON")"',
-        `remote_version="$(npm view ${MAIN_PACKAGE_NAME} version 2>/dev/null || true)"`,
-        '',
-        'if [ -z "$remote_version" ]; then',
-        '  json "error" "failed to check evolcore latest version"',
-        '  exit 0',
-        'fi',
-        '',
-        'if [ -z "$local_version" ]; then',
-        '  json "error" "failed to read local ec version"',
-        '  exit 0',
-        'fi',
-        '',
-        'version_cmp="$(node -e \'',
-        'const [a, b] = process.argv.slice(1);',
-        'const pa = a.split("-")[0].split(".").map(Number);',
-        'const pb = b.split("-")[0].split(".").map(Number);',
-        'const n = Math.max(pa.length, pb.length);',
-        'let out = 0;',
-        'for (let i = 0; i < n; i++) {',
-        '  const av = Number.isFinite(pa[i]) ? pa[i] : 0;',
-        '  const bv = Number.isFinite(pb[i]) ? pb[i] : 0;',
-        '  if (av < bv) { out = -1; break; }',
-        '  if (av > bv) { out = 1; break; }',
-        '}',
-        'console.log(out);',
-        '\' "$local_version" "$remote_version")"',
-        '',
-        'if [ "$version_cmp" != "-1" ]; then',
-        '  json "noop" "evolcore is already up to date ($local_version; latest $remote_version)"',
-        '  exit 0',
-        'fi',
-        '',
-        'if [ ! -f "$CLI_PATH" ]; then',
-        '  json "error" "restart-monitor entry not found: $CLI_PATH"',
-        '  exit 0',
-        'fi',
-        '',
-        'nohup node "$CLI_PATH" restart-monitor >/dev/null 2>&1 &',
-        'json "success" "evolcore upgrade available: ${local_version:-unknown} -> $remote_version; restart-monitor started"',
-        '',
-    ].join('\n'));
+    fs.writeFileSync(scriptPath, `#!/usr/bin/env node
+const { existsSync, readFileSync } = require('node:fs');
+const { spawn } = require('node:child_process');
+
+const CLI_PATH = ${JSON.stringify(cliPath)};
+const PACKAGE_JSON = ${JSON.stringify(packageJsonPath)};
+const PACKAGE_NAME = ${JSON.stringify(MAIN_PACKAGE_NAME)};
+const DEV_MODE = ${devMode ? 'true' : 'false'};
+
+function emit(outcome, text) {
+  process.stdout.write(JSON.stringify({ outcome, text, files: [] }));
+}
+
+function compareVersions(a, b) {
+  const pa = a.split('-')[0].split('.').map(Number);
+  const pb = b.split('-')[0].split('.').map(Number);
+  const count = Math.max(pa.length, pb.length);
+  for (let i = 0; i < count; i += 1) {
+    const av = Number.isFinite(pa[i]) ? pa[i] : 0;
+    const bv = Number.isFinite(pb[i]) ? pb[i] : 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+async function latestVersion() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 10_000);
+  try {
+    const response = await fetch('https://registry.npmjs.org/' + encodeURIComponent(PACKAGE_NAME) + '/latest', {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return typeof data.version === 'string' ? data.version : null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  if (DEV_MODE) {
+    emit('noop', 'upgrade check skipped in dev mode');
+    return;
+  }
+
+  let localVersion;
+  try {
+    localVersion = JSON.parse(readFileSync(PACKAGE_JSON, 'utf8')).version;
+  } catch {
+    emit('error', 'failed to read local ec version');
+    return;
+  }
+  if (typeof localVersion !== 'string' || !localVersion) {
+    emit('error', 'failed to read local ec version');
+    return;
+  }
+
+  let remoteVersion;
+  try {
+    remoteVersion = await latestVersion();
+  } catch {
+    remoteVersion = null;
+  }
+  if (!remoteVersion) {
+    emit('error', 'failed to check evolcore latest version');
+    return;
+  }
+  if (compareVersions(localVersion, remoteVersion) >= 0) {
+    emit('noop', 'evolcore is already up to date (' + localVersion + '; latest ' + remoteVersion + ')');
+    return;
+  }
+  if (!existsSync(CLI_PATH)) {
+    emit('error', 'restart-monitor entry not found: ' + CLI_PATH);
+    return;
+  }
+
+  try {
+    const child = spawn(process.execPath, [CLI_PATH, 'restart-monitor'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: process.platform === 'win32',
+      env: { ...process.env },
+    });
+    child.unref();
+    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)));
+  }
+}
+
+main().catch((error) => {
+  emit('error', 'upgrade check failed: ' + (error && error.message ? error.message : String(error)));
+});
+`);
+    // Remove the pre-Node script left by older installations so it cannot be
+    // selected by a stale trigger definition or run manually by accident.
+    fs.rmSync(path.join(dir, 'upgrade-check.sh'), { force: true });
+    fs.rmSync(path.join(dir, 'upgrade-check.js'), { force: true });
     fs.chmodSync(scriptPath, 0o755);
     atomicWriteJson(manager.definitionPath(definition.id), definition);
     fs.rmSync(manager.activePath(definition.id), { force: true });
@@ -338,7 +380,9 @@ function removeLegacyAgentUpgradeCheck(manager) {
         return;
     const isLegacySystemOrigin = existing.origin?.channelKey === '__system__' || existing.origin?.channelKey === 'daemon';
     const isUpgradeScript = existing.execution.type === 'script'
-        && existing.execution.script?.path === 'upgrade-check.sh';
+        && (existing.execution.script?.path === 'upgrade-check.sh'
+            || existing.execution.script?.path === 'upgrade-check.js'
+            || existing.execution.script?.path === 'upgrade-check.cjs');
     if (!isLegacySystemOrigin || !isUpgradeScript)
         return;
     fs.rmSync(manager.triggerDir('__upgrade-check'), { recursive: true, force: true });
@@ -396,6 +440,13 @@ async function runBindBootstrapDaemon(daemonCfg) {
             await controlChannel.sendMessage(opts.channelId, JSON.stringify(response));
         }
     });
+    const controlToken = crypto.randomBytes(32).toString('base64url');
+    fs.mkdirSync(path.dirname(resolvePaths().controlToken), { recursive: true });
+    fs.writeFileSync(resolvePaths().controlToken, controlToken, { mode: 0o600 });
+    try {
+        fs.chmodSync(resolvePaths().controlToken, 0o600);
+    }
+    catch { }
     const ipcServer = new IpcServer(resolvePaths().socket, () => ({
         pid: process.pid,
         uptime: Math.round(process.uptime() * 1000),
@@ -417,6 +468,7 @@ async function runBindBootstrapDaemon(daemonCfg) {
             };
         })(),
     }));
+    ipcServer.setControlToken(controlToken);
     ipcServer.setBindExecutor({
         begin: (cmd) => bindService.begin(cmd),
         status: (taskId) => bindService.status(taskId),
@@ -1129,6 +1181,7 @@ async function main() {
         return { ok: result.ok, message_id: result.message_id, error: result.error };
     }, undefined, { queueTtlMs: taskExecutionTtlMs });
     responseEngine.setHandoffRuntime(handoffRuntime);
+    cmdHandler.setHandoffRuntime(handoffRuntime);
     // Trigger runtime: daemon-level script + feedback scheduler.
     const triggerSchedulers = new Map();
     const targetSessionLocks = new TargetSessionLockRegistry();
@@ -1993,7 +2046,7 @@ async function main() {
         const delegation = agentDelegationRegistry.validate(delegationToken, sessionId, delegationCommandHash);
         if (!delegation.ok)
             return { ok: false, code: delegation.code, error: delegation.reason };
-        return cmdHandler.handleCtl(cmd, sessionId);
+        return cmdHandler.handleCtl(cmd, sessionId, delegation.grant);
     });
     // Register every IPC executor/provider before exposing the endpoint. The
     // function declaration is hoisted, while its invocation remains here so a
@@ -2080,10 +2133,11 @@ async function main() {
                 }
                 else {
                     try {
-                        const ecwebProc = spawn('node', [ecwebEntry], {
+                        const ecwebProc = spawn(process.execPath, [ecwebEntry], {
                             cwd: ecwebPath,
                             detached: true,
                             stdio: 'ignore',
+                            windowsHide: platform.isWindows,
                             env: { ...process.env, EVOLCORE_HOME: resolvePaths().root }
                         });
                         ecwebProc.unref();
@@ -2259,6 +2313,9 @@ async function main() {
     const recoveryAids = triggerStartupAgents.map(agent => agent.aid);
     for (const aid of recoveryAids) {
         try {
+            const discarded = await handoffRuntime.discardExpired([aid]);
+            if (discarded > 0)
+                logger.info(`[Handoff] discarded ${discarded} expired handoff(s) for ${aid}`);
             const expired = handoffRuntime.expireQueued([aid]);
             if (expired > 0)
                 logger.info(`[Handoff] expired ${expired} stale queued delivery item(s) for ${aid}`);
@@ -2344,7 +2401,27 @@ async function main() {
     function configureIpc() {
         // M3: direct call (not cast) — wire EvolAgentRegistry into IPC for evolagent.* handlers
         ipcServer.setAgentRegistry(agentRegistry);
-        ipcServer.setBootstrapCompleteExecutor(async (aid) => {
+        ipcServer.setControlToken(triggerControlToken);
+        ipcServer.setBootstrapCompleteExecutor(async (aid, auth) => {
+            if (auth?.sessionId) {
+                const authorization = await authorizeManagedAgentOperation({
+                    sessionId: auth.sessionId,
+                    delegationToken: auth.delegationToken,
+                    delegationCommandHash: auth.delegationCommandHash,
+                    targetAid: aid,
+                }, 'agent.bootstrapComplete');
+                if (!authorization.ok)
+                    return authorization;
+            }
+            else {
+                const providedToken = typeof auth?.controlToken === 'string' ? Buffer.from(auth.controlToken) : undefined;
+                const expectedToken = Buffer.from(triggerControlToken);
+                if (!providedToken
+                    || providedToken.length !== expectedToken.length
+                    || !crypto.timingSafeEqual(providedToken, expectedToken)) {
+                    return { ok: false, code: 'INVALID_CONTROL_TOKEN', error: 'valid local control token is required' };
+                }
+            }
             const aunInstance = channelInstances.find(candidate => {
                 if (candidate.channelType !== 'aun')
                     return false;
@@ -2353,7 +2430,30 @@ async function main() {
                 return owner?.aid === aid;
             });
             const welcome = aunInstance?.channel;
-            return completeBootstrapWithWelcome(bootstrapService, aid, welcome);
+            const ownerAid = getFirstStaticAgentOwner(aid);
+            const owningAgent = agentRegistry.get(aid);
+            const sessions = aunInstance && ownerAid && owningAgent
+                ? {
+                    ensurePostBootstrapMainSession: async () => {
+                        const channel = aunInstance.adapter.channelName;
+                        const active = await sessionManager.getActiveSession(channel, ownerAid);
+                        const ensured = await sessionManager.ensureNewMainSessionForOperation({
+                            channel,
+                            channelId: ownerAid,
+                            projectPath: active?.projectPath || owningAgent.projectPath || defaultProjectPath,
+                            baseagent: owningAgent.baseagent || active?.baseagent || primaryBaseagent,
+                            operationId: postBootstrapWelcomeOperationId(aid),
+                            identityMetadata: {
+                                ...(active?.metadata ?? {}),
+                                channelKey: aunInstance.adapter.channelKey,
+                                peerId: ownerAid,
+                            },
+                        });
+                        return { sessionId: ensured.session.id, created: ensured.created };
+                    },
+                }
+                : undefined;
+            return completeBootstrapWithWelcome(bootstrapService, aid, welcome, sessions);
         });
         ipcServer.setDingtalkContactBindExecutor({
             register: (cmd) => registerPendingDingtalkContactBind(cmd),
@@ -2378,6 +2478,10 @@ async function main() {
         ipcServer.setMenuExecutor((payload, auth) => cmdHandler.execMenuForEcweb(payload, auth));
         ipcServer.setConfigOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleConfigOperation(argv, sessionId, delegationToken, delegationCommandHash));
         ipcServer.setContactOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleContactOperation(argv, sessionId, delegationToken, delegationCommandHash));
+        ipcServer.setAidOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleAidOperation(argv, sessionId, delegationToken, delegationCommandHash));
+        ipcServer.setGroupOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleGroupOperation(argv, sessionId, delegationToken, delegationCommandHash));
+        ipcServer.setMsgOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleMsgOperation(argv, sessionId, delegationToken, delegationCommandHash));
+        ipcServer.setFsOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleFsOperation(argv, sessionId, delegationToken, delegationCommandHash));
         cmdHandler.setDaemonStatusProvider(() => {
             const aidState = controlChannel?.getAidState?.();
             return {
@@ -2446,30 +2550,82 @@ async function main() {
             aidStatsCollector.recordOutbound(params.aid, params.toPeer, Buffer.byteLength(params.text || '', 'utf-8'), params.text, false, params.encrypt, params.chatmode, 'send');
         });
         ipcServer.setTaskRuntimeContextProvider(({ sessionId }) => responseEngine.getTaskRuntimeContext(sessionId));
-        ipcServer.setHandoffReturnExecutor((params) => responseEngine.returnHandoffResult(params));
-        ipcServer.setHandoffStatusExecutor(async (params) => {
-            if (!params.sessionId)
-                return { ok: false, code: 'HANDOFF_CALL_SESSION_REQUIRED', error: 'current session is required' };
+        ipcServer.setCodexPreToolUseExecutor(async (params) => {
+            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);
+                if (result.applicable)
+                    return result;
+            }
+            return {
+                ok: false,
+                applicable: true,
+                decision: 'deny',
+                reason: 'No active EvolCore Codex runner accepted this managed hook request',
+            };
+        });
+        const resolveManagedHandoffScope = async (params, operation) => {
+            const delegation = agentDelegationRegistry.validate(params.delegationToken, params.sessionId, params.delegationCommandHash);
+            if (!delegation.ok)
+                return { ok: false, code: delegation.code, error: delegation.reason };
             const runtime = responseEngine.getTaskRuntimeContext(params.sessionId);
             const session = await sessionManager.getSessionById(params.sessionId);
             const selfAid = runtime?.selfAid || session?.selfAID;
-            if (!selfAid)
-                return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found' };
-            return handoffRuntime.status(selfAid, params.handoffId)
-                ?? { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found' };
-        });
-        const resolveHandoffQueryAid = async (params) => {
+            if (!selfAid || !session) {
+                return { ok: false, code: 'HANDOFF_CALL_SESSION_INVALID', error: 'current session is invalid' };
+            }
+            if (delegation.grant.selfAid !== selfAid) {
+                return { ok: false, code: 'INVALID_DELEGATION', error: 'delegation self agent does not match current session' };
+            }
+            if (params.agent && params.agent !== selfAid) {
+                return { ok: false, code: 'HANDOFF_AGENT_SCOPE_MISMATCH', error: 'agent does not match the current session' };
+            }
+            let conversationId;
+            try {
+                conversationId = parsePeerKey(delegation.grant.peerKey).channelId;
+            }
+            catch {
+                return { ok: false, code: 'INVALID_DELEGATION', error: 'delegation contains an invalid relation key' };
+            }
+            const subject = buildAuthSubject({
+                selfAid,
+                actorId: delegation.grant.actorId,
+                channel: delegation.grant.channel,
+                channelType: delegation.grant.channelType,
+                channelId: conversationId,
+                chatType: delegation.grant.chatType,
+                conversationId,
+                processOwners: daemonCfg.owners ?? [],
+            });
+            const managementRole = isManagementRole(subject.role);
+            const decision = authorizeOperation({
+                source: 'agent-tool',
+                subject,
+                intent: {
+                    operation,
+                    scope: managementRole ? 'agent' : 'relation',
+                    source: 'agent-tool',
+                    args: {
+                        self: selfAid,
+                        peer: conversationId,
+                        peerKey: delegation.grant.peerKey,
+                    },
+                },
+                auditMetadata: { taskId: delegation.grant.taskId, messageId: delegation.grant.messageId },
+            });
+            if (!decision.allow) {
+                return {
+                    ok: false,
+                    code: decision.command?.code ?? 'ROLE_ACCESS_DENIED',
+                    error: decision.reason,
+                };
+            }
+            return { ok: true, aid: selfAid, currentSessionId: params.sessionId, managementRole };
+        };
+        const resolveHandoffQueryScope = async (params, operation) => {
             if (params.sessionId) {
-                const runtime = responseEngine.getTaskRuntimeContext(params.sessionId);
-                const session = await sessionManager.getSessionById(params.sessionId);
-                const selfAid = runtime?.selfAid || session?.selfAID;
-                if (!selfAid) {
-                    return { ok: false, code: 'HANDOFF_CALL_SESSION_INVALID', error: 'current session is invalid' };
-                }
-                if (params.agent && params.agent !== selfAid) {
-                    return { ok: false, code: 'HANDOFF_AGENT_SCOPE_MISMATCH', error: 'agent does not match the current session' };
-                }
-                return { ok: true, aid: selfAid };
+                return resolveManagedHandoffScope({ ...params, sessionId: params.sessionId }, operation);
             }
             if (!params.agent) {
                 return { ok: false, code: 'HANDOFF_AGENT_REQUIRED', error: '--agent is required outside a task context' };
@@ -2477,23 +2633,56 @@ async function main() {
             if (!agentRegistry.get(params.agent)) {
                 return { ok: false, code: 'HANDOFF_AGENT_NOT_FOUND', error: `agent not found: ${params.agent}` };
             }
-            return { ok: true, aid: params.agent };
+            return { ok: true, aid: params.agent, currentSessionId: undefined, managementRole: true };
         };
+        ipcServer.setHandoffReturnExecutor(async (params) => {
+            if (!params.sessionId)
+                return responseEngine.returnHandoffResult(params);
+            const scope = await resolveManagedHandoffScope({ ...params, sessionId: params.sessionId }, 'ec.handoff.return');
+            if (!scope.ok)
+                return scope;
+            return responseEngine.returnAuthorizedHandoffResult({ sessionId: params.sessionId, handoffId: params.handoffId, content: params.content }, scope.aid);
+        });
+        ipcServer.setHandoffStatusExecutor(async (params) => {
+            const scope = await resolveHandoffQueryScope(params, 'ec.handoff.status');
+            if (!scope.ok)
+                return scope;
+            const status = handoffRuntime.status(scope.aid, params.handoffId);
+            if (!status)
+                return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found' };
+            if (!scope.managementRole
+                && status.origin_session_id !== scope.currentSessionId
+                && status.target_session_id !== scope.currentSessionId) {
+                return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found in the current session' };
+            }
+            return status;
+        });
         ipcServer.setHandoffListExecutor(async (params) => {
-            const scope = await resolveHandoffQueryAid(params);
+            const scope = await resolveHandoffQueryScope(params, 'ec.handoff.list');
             if (!scope.ok)
                 return scope;
+            if (!scope.managementRole && params.filterSessionId && params.filterSessionId !== scope.currentSessionId) {
+                return { ok: false, code: 'HANDOFF_SESSION_SCOPE_MISMATCH', error: 'only the current session can be queried' };
+            }
             return handoffRuntime.listHandoffs({
                 selfAid: scope.aid,
                 state: params.state,
-                sessionId: params.filterSessionId,
+                sessionId: scope.managementRole ? params.filterSessionId : scope.currentSessionId,
                 limit: params.limit,
             });
         });
         ipcServer.setHandoffTraceExecutor(async (params) => {
-            const scope = await resolveHandoffQueryAid(params);
+            const scope = await resolveHandoffQueryScope(params, 'ec.handoff.trace');
             if (!scope.ok)
                 return scope;
+            if (!scope.managementRole) {
+                const status = handoffRuntime.status(scope.aid, params.handoffId);
+                if (!status
+                    || (status.origin_session_id !== scope.currentSessionId
+                        && status.target_session_id !== scope.currentSessionId)) {
+                    return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found in the current session' };
+                }
+            }
             return handoffRuntime.traceHandoff(scope.aid, params.handoffId, params.limit)
                 ?? { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found' };
         });
@@ -2565,12 +2754,27 @@ async function main() {
             if (!payload) {
                 return { ok: false, error: 'message payload is required', code: 'INVALID_PAYLOAD' };
             }
+            try {
+                if (Object.prototype.hasOwnProperty.call(payload, 'mentions')) {
+                    payload = { ...payload, mentions: normalizeAunMentionEntries(payload.mentions) };
+                }
+                if (params.scope === 'group' && params.mentions !== undefined) {
+                    const normalizedMentions = normalizeAunMentionEntries(params.mentions);
+                    if (normalizedMentions.length > 0) {
+                        payload = { ...payload, mentions: normalizedMentions };
+                    }
+                }
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    code: error?.code ?? 'INVALID_MENTION_SCHEMA',
+                };
+            }
             if (params.thread && typeof payload.thread_id !== 'string') {
                 payload = { ...payload, thread_id: params.thread };
             }
-            if (params.scope === 'group' && params.mentions?.length) {
-                payload = { ...payload, mentions: params.mentions };
-            }
             let targetSessionId;
             if (params.originSessionId && params.originMessageId) {
                 try {
@@ -2824,7 +3028,7 @@ async function main() {
                 agent.status = 'running';
                 // 连接
                 await channelLoader.connectAll(instances, { onConnected: markChannelConnected });
-                await handoffRuntime.recover([aid]);
+                await handoffRuntime.recover([aid], { discardExpired: false });
                 await ensureTriggerSchedulerStarted(agent);
                 handoffRuntime.resumeAgent(aid);
                 resumed = true;
@@ -3003,6 +3207,88 @@ async function main() {
                     return { ok: false, error: `unknown action: ${params.action}` };
             }
         });
+        async function authorizeManagedAgentOperation(params, operation) {
+            const delegation = agentDelegationRegistry.validate(params.delegationToken, params.sessionId, params.delegationCommandHash);
+            if (!delegation.ok)
+                return { ok: false, code: delegation.code, error: delegation.reason };
+            const session = await sessionManager.getSessionById(params.sessionId);
+            if (!session || session.selfAID !== delegation.grant.selfAid) {
+                return { ok: false, code: 'INVALID_DELEGATION', error: 'delegation does not match the current session' };
+            }
+            if (params.targetAid && params.targetAid !== delegation.grant.selfAid) {
+                return { ok: false, code: 'SCOPE_MISMATCH', error: 'only the current Agent can be targeted' };
+            }
+            let conversationId;
+            try {
+                conversationId = parsePeerKey(delegation.grant.peerKey).channelId;
+            }
+            catch {
+                return { ok: false, code: 'INVALID_DELEGATION', error: 'delegation contains an invalid relation key' };
+            }
+            const subject = buildAuthSubject({
+                selfAid: delegation.grant.selfAid,
+                actorId: delegation.grant.actorId,
+                channel: delegation.grant.channel,
+                channelType: delegation.grant.channelType,
+                channelId: conversationId,
+                chatType: delegation.grant.chatType,
+                conversationId,
+                processOwners: daemonCfg.owners ?? [],
+            });
+            if (!isManagementRole(subject.role)) {
+                return { ok: false, code: 'ROLE_ACCESS_DENIED', error: `${operation} requires Agent admin permission` };
+            }
+            const decision = authorizeOperation({
+                source: 'agent-tool',
+                subject,
+                intent: {
+                    operation,
+                    scope: operation === 'system.status' ? 'process' : 'agent',
+                    source: 'agent-tool',
+                    args: { self: delegation.grant.selfAid, aid: params.targetAid ?? delegation.grant.selfAid },
+                },
+                auditMetadata: { taskId: delegation.grant.taskId, messageId: delegation.grant.messageId },
+            });
+            return decision.allow
+                ? { ok: true, aid: delegation.grant.selfAid }
+                : { ok: false, code: decision.code, error: decision.reason };
+        }
+        ipcServer.setQueueOperationExecutor(async (params) => {
+            const operation = `ec.queue.${params.action ?? 'read'}`;
+            const authorization = await authorizeManagedAgentOperation(params, operation);
+            if (!authorization.ok)
+                return authorization;
+            const handle = agentRegistry.get(authorization.aid);
+            if (!handle?.name)
+                return { ok: false, code: 'AGENT_NOT_FOUND', error: 'current Agent not found' };
+            if (!params.action)
+                return { ok: true, items: messageQueue.getQueueItemsByAgent(handle.name) };
+            if (params.action === 'clear')
+                return { ok: true, cleared: messageQueue.clearByAgent(handle.name) };
+            if (params.action === 'cancel') {
+                if (!params.messageId)
+                    return { ok: false, code: 'INVALID_ARGUMENT', error: 'missing messageId' };
+                return { ok: true, cancelled: messageQueue.cancelMessageById(handle.name, params.messageId) };
+            }
+            if (!params.sessionKey)
+                return { ok: false, code: 'INVALID_ARGUMENT', error: 'missing sessionKey' };
+            const targetSessionId = messageQueue.findSessionIdBySessionKey(params.sessionKey);
+            if (!targetSessionId)
+                return { ok: false, code: 'SESSION_NOT_FOUND', error: `session not found: ${params.sessionKey}` };
+            const targetSession = await sessionManager.getSessionById(targetSessionId);
+            if (!targetSession || targetSession.selfAID !== authorization.aid) {
+                return { ok: false, code: 'SCOPE_MISMATCH', error: 'session does not belong to the current Agent' };
+            }
+            return { ok: true, interrupted: await messageQueue.interruptBySession(targetSessionId) };
+        });
+        ipcServer.setStatusAuthorizationExecutor(async (params) => {
+            const authorization = await authorizeManagedAgentOperation(params, 'system.status');
+            return authorization.ok ? { ok: true } : authorization;
+        });
+        ipcServer.setStorageAuthorizationExecutor(async (params) => {
+            const authorization = await authorizeManagedAgentOperation({ ...params, targetAid: params.aid }, params.operation);
+            return authorization.ok ? { ok: true } : authorization;
+        });
         ipcServer.setTriggerExecutor(async (cmd) => {
             const schedulerFor = (agentAid) => {
                 const scheduler = triggerSchedulers.get(agentAid);