evolcore 0.0.20 → 0.0.21

package/dist/core/auth/auth-gateway.js

@@ -8,6 +8,11 @@ import { resolveRuntimePermissionMode } from '../role/runtime-policy.js';
 export function isCrossAgentTriggerOperationAllowed(input) {
     return input.control || input.daemonOwner === true || input.taskAgentAid === input.targetAgentAid;
 }
+/** A delegated identity may authorize ordinary work, but it is not a human approval for persistent host execution. */
+export function canApprovePersistentFullAccessTrigger(input) {
+    return input.daemonOwner
+        && (input.source === 'direct-user' || input.source === 'management-channel');
+}
 export function buildAuthSubject(input) {
     const chatType = input.chatType === 'group' ? 'group' : 'private';
     const actorId = input.actorId;
@@ -22,17 +27,31 @@ export function buildAuthSubject(input) {
         peerType: input.peerType,
     });
     const processOwners = input.processOwners ?? [];
+    const fullAccessAuthorization = input.trustedFullAccessAuthorization;
+    const isFullAccessRun = input.trustedProcessRole === 'fullaccess-run'
+        && fullAccessAuthorization?.permissionMode === 'fullaccess'
+        && fullAccessAuthorization.processRole === 'fullaccess-run'
+        && fullAccessAuthorization.dataScope === 'daemon';
     const isDaemonService = input.trustedProcessRole === 'daemon-service';
-    const isDaemonOwner = !isDaemonService && isProcessOwner({
+    const isDaemonOwner = !isDaemonService && !isFullAccessRun && isProcessOwner({
         actor: roleDetail.actor,
         processOwners,
     });
     const suppliedRole = input.identity?.role && input.identity.role !== 'none' ? input.identity.role : undefined;
     const role = suppliedRole ?? roleDetail.effectiveRole ?? 'none';
-    const processRole = isDaemonService ? 'daemon-service' : isDaemonOwner ? 'daemon-owner' : 'none';
+    const processRole = isFullAccessRun
+        ? 'fullaccess-run'
+        : isDaemonService ? 'daemon-service' : isDaemonOwner ? 'daemon-owner' : 'none';
+    const dataScope = processRole === 'fullaccess-run'
+        || processRole === 'daemon-service'
+        || processRole === 'daemon-owner'
+        ? 'daemon'
+        : role === 'owner' || role === 'admin' ? 'agent' : 'relation';
     return {
         selfAid: input.selfAid,
+        agentName: input.agentName,
         actorId,
+        principalId: roleDetail.actor.principalId,
         requestId: input.requestId,
         sessionId: input.sessionId,
         channel: input.channel,
@@ -44,6 +63,8 @@ export function buildAuthSubject(input) {
         role,
         relationRole: role,
         processRole,
+        dataScope,
+        authorizedBy: isFullAccessRun ? fullAccessAuthorization.authorizedBy : undefined,
         roleSource: roleDetail.source,
         identity: input.identity ?? roleToSessionIdentity(role === 'none' ? null : role),
         isDaemonOwner,
@@ -51,8 +72,12 @@ export function buildAuthSubject(input) {
         allowAccess: processRole !== 'none' || (suppliedRole
             ? checkRoleAccess(suppliedRole, input.selfAid)
             : roleDetail.allowAccess && checkRoleAccess(role, input.selfAid)),
-        permissionMode: input.permissionMode
-            ?? resolveRuntimePermissionMode({ selfAid: input.selfAid, role }).effectiveValue,
+        canApprovePersistentFullAccess: input.canApprovePersistentFullAccess
+            ?? (isDaemonOwner && !isDaemonService),
+        permissionMode: isFullAccessRun
+            ? 'fullaccess'
+            : input.permissionMode
+                ?? resolveRuntimePermissionMode({ selfAid: input.selfAid, role }).effectiveValue,
     };
 }
 function isProcessOwner(input) {
@@ -97,6 +122,7 @@ export function authorizeOperation(params) {
         peerKey: params.subject.peerKey,
         role: params.subject.role,
         processRole: params.subject.processRole,
+        dataScope: params.subject.dataScope,
         isDaemonOwner: params.subject.isDaemonOwner,
         fromControlChannel: params.subject.fromControlChannel,
         allowExplicitRelationTarget: params.allowExplicitRelationTarget,
@@ -162,6 +188,7 @@ function auditDecision(params, decision) {
         requestId: params.auditMetadata?.requestId ?? params.subject.requestId,
         sessionId: params.auditMetadata?.sessionId ?? params.subject.sessionId,
         agentAid: params.auditMetadata?.agentAid ?? params.subject.selfAid,
+        agentName: params.auditMetadata?.agentName ?? params.subject.agentName ?? params.subject.selfAid,
         permissionMode: params.auditMetadata?.permissionMode
             ?? (decision.allow ? decision.permissionMode ?? params.subject.permissionMode : params.subject.permissionMode),
         toolName: params.auditMetadata?.toolName,
@@ -178,6 +205,8 @@ function auditDecision(params, decision) {
         channelId: params.subject.channelId,
         role: decision.allow ? decision.role : params.subject.role,
         processRole: params.subject.processRole,
+        dataScope: params.subject.dataScope,
+        authorizedBy: params.subject.authorizedBy,
         isDaemonOwner: params.subject.isDaemonOwner,
         fromControlChannel: params.subject.fromControlChannel,
         decision: decision.allow ? 'allow' : 'deny',

package/dist/core/auth/authorization-audit.js

@@ -3,12 +3,14 @@ import { LogWriter } from '../../utils/log-writer.js';
 import { resolvePaths } from '../../paths.js';
 import crypto from 'node:crypto';
 import { buildAuthorizationEventKey } from '../audit/event-key.js';
+import { normalizeExecutionPermissionMode } from '../permission/mode.js';
 export function auditCommandAuthorization(event) {
     const shouldAudit = event.source === 'menu.cli' ||
         event.decision === 'deny' ||
         (event.decision === 'allow' && event.dangerous) ||
         (event.source === 'agent-tool' && event.operation.startsWith('config.')) ||
         event.operation === 'codex.approval' ||
+        event.operation.startsWith('fullaccess.') ||
         event.operation.startsWith('role.') ||
         event.operation === 'cli.exec.raw';
     if (!shouldAudit)
@@ -16,6 +18,77 @@ export function auditCommandAuthorization(event) {
     const auditRecord = buildAuditRecord(event);
     logAuditEvent(auditRecord);
 }
+export function auditFullAccessEvent(input) {
+    const configurationEvent = input.event === 'fullaccess.trigger.configured'
+        || input.event === 'fullaccess.trigger.deescalated';
+    const executionEvent = input.event === 'fullaccess.execution.started'
+        || input.event === 'fullaccess.execution.ended'
+        || input.event === 'fullaccess.trigger.execution.started'
+        || input.event === 'fullaccess.trigger.execution.ended';
+    // The scheduler triggers a run, but the executing subject is the task-bound
+    // fullaccess identity. Keep the original owner/configuration provenance in
+    // a separate field rather than reporting the model task as a human owner.
+    const processRole = input.processRole
+        ?? (executionEvent ? 'fullaccess-run' : input.source === 'trigger' ? 'daemon-service' : 'none');
+    const actorRole = processRole === 'daemon-owner' ? 'daemon-owner' : processRole;
+    const runnerProfileActive = executionEvent && input.executionState !== 'blocked';
+    const completedEvent = input.event.endsWith('.ended') || configurationEvent;
+    auditCommandAuthorization({
+        ts: Date.now(),
+        callId: input.attemptId ?? input.runId ?? input.taskId ?? input.messageId,
+        correlationId: input.runId ?? input.taskId,
+        source: input.source === 'trigger' ? 'agent-tool' : 'slash',
+        operation: input.event,
+        // CommandScope has no separate daemon value; process is the closest
+        // existing scope for daemon-owner authorization and keeps audit records
+        // compatible with the established command-audit schema.
+        scope: 'process',
+        dangerous: true,
+        decision: input.decision ?? 'allow',
+        executed: input.executed ?? completedEvent,
+        executionState: input.executionState
+            ?? (input.decision === 'deny' ? 'blocked' : completedEvent ? 'completed' : 'authorized'),
+        decisionSource: input.decision === 'deny'
+            ? 'policy'
+            : configurationEvent
+                ? processRole === 'daemon-owner' ? 'daemon-owner' : 'policy'
+                : processRole === 'fullaccess-run'
+                    ? 'fullaccess-run'
+                    : input.source === 'trigger'
+                        ? 'trigger-definition'
+                        : 'daemon-owner',
+        actorId: input.actorId,
+        processRole,
+        dataScope: input.dataScope ?? (executionEvent ? 'daemon' : undefined),
+        authorizedBy: input.authorizedBy,
+        isDaemonOwner: processRole === 'daemon-owner',
+        agentAid: input.agentAid,
+        agentName: input.agentName,
+        sessionId: input.sessionId,
+        taskId: input.taskId,
+        messageId: input.messageId,
+        permissionMode: 'fullaccess',
+        role: actorRole,
+        reason: input.reason ?? input.result ?? input.event,
+        durationMs: input.durationMs,
+        argsSummary: {
+            source: input.source,
+            triggerId: input.triggerId,
+            runId: input.runId,
+            attemptId: input.attemptId,
+            baseagent: input.baseagent,
+            model: input.model,
+            dataScope: input.dataScope ?? (executionEvent ? 'daemon' : undefined),
+            authorizedBy: input.authorizedBy,
+            ...(runnerProfileActive ? {
+                sandbox: 'off',
+                approval: 'bypassed',
+                applicationPolicy: 'bypassed',
+            } : {}),
+            result: input.result,
+        },
+    });
+}
 /**
  * Record a tool-level preflight denial (e.g. protected-path block) in the
  * structured command-audit log. This covers interactive sessions whose
@@ -45,6 +118,7 @@ export function auditToolPreflightDenial(input) {
         argsSummary: input.summary ? { summary: input.summary } : undefined,
         sessionId: input.sessionId ?? 'unknown',
         agentAid: input.agentAid ?? 'unknown',
+        agentName: input.agentName,
         permissionMode: input.permissionMode ?? 'unknown',
         channel: input.channel,
         actorId: input.actorId,
@@ -76,6 +150,7 @@ export function auditCodexApprovalDecision(input) {
         correlationId: input.correlationId ?? input.requestId,
         sessionId: input.sessionId ?? 'unknown',
         agentAid: input.agentAid ?? 'unknown',
+        agentName: input.agentName,
         permissionMode: input.permissionMode ?? 'unknown',
         toolName: input.toolName,
         approvalMethod: input.method,
@@ -84,7 +159,40 @@ export function auditCodexApprovalDecision(input) {
         reason: input.reason,
         role: input.role ?? 'unknown',
         taskId: input.taskId,
-        argsSummary: { method: input.method },
+        argsSummary: {
+            method: input.method,
+            ...(input.parseFailure ? { parseFailure: input.parseFailure } : {}),
+        },
+    });
+}
+/**
+ * Record a runtime permission decision outside a Codex app-server approval.
+ * The shared command-audit stream distinguishes policy, human, and
+ * infrastructure denials without parsing localized log text.
+ */
+export function auditPermissionDecision(input) {
+    auditCommandAuthorization({
+        ts: Date.now(),
+        callId: input.requestId,
+        correlationId: input.requestId,
+        requestId: input.requestId,
+        sessionId: input.sessionId,
+        agentAid: input.agentAid,
+        agentName: input.agentName,
+        permissionMode: input.permissionMode,
+        toolName: input.toolName,
+        policyCode: input.policyCode,
+        decisionSource: input.decisionSource,
+        source: 'agent-tool',
+        operation: 'permission.runtime',
+        scope: 'filesystem',
+        dangerous: false,
+        role: input.role ?? 'unknown',
+        taskId: input.taskId,
+        decision: 'deny',
+        executed: false,
+        executionState: 'blocked',
+        reason: input.reason,
     });
 }
 /** Record a fail-closed infrastructure condition before a tool can execute. */
@@ -104,6 +212,7 @@ export function auditToolInfrastructureFailure(input) {
         requestId: input.callId,
         sessionId: input.sessionId ?? 'unknown',
         agentAid: input.agentAid ?? 'unknown',
+        agentName: input.agentName,
         permissionMode: input.permissionMode ?? 'unknown',
         toolName: input.toolName,
         policyCode: input.policyCode,
@@ -140,7 +249,8 @@ function buildAuditRecord(event) {
         requestId: event.requestId,
         sessionId: event.sessionId,
         agentAid: redactIdentifier(event.agentAid ?? event.selfAid),
-        permissionMode: event.permissionMode,
+        agentName: resolveAgentName(event),
+        permissionMode: normalizeAuditPermissionMode(event.permissionMode),
         toolName: event.toolName,
         approvalMethod: event.approvalMethod,
         policyCode: event.policyCode ?? event.code,
@@ -161,6 +271,8 @@ function buildAuditRecord(event) {
         channelId: redactIdentifier(event.channelId),
         role: event.role,
         processRole: event.processRole,
+        dataScope: event.dataScope,
+        authorizedBy: redactIdentifier(event.authorizedBy),
         isDaemonOwner: event.isDaemonOwner,
         fromControlChannel: event.fromControlChannel,
         taskId: event.taskId,
@@ -177,6 +289,26 @@ function buildAuditRecord(event) {
         exitCode: event.exitCode,
     };
 }
+function resolveAgentName(event) {
+    const displayName = typeof event.agentName === 'string' ? event.agentName.trim() : '';
+    if (displayName && !isUnknownAgentLabel(displayName))
+        return displayName;
+    const aid = typeof event.agentAid === 'string' ? event.agentAid.trim() : '';
+    if (aid && aid !== 'unknown')
+        return aid;
+    const selfAid = typeof event.selfAid === 'string' ? event.selfAid.trim() : '';
+    if (selfAid && selfAid !== 'unknown')
+        return selfAid;
+    return aid === 'unknown' || selfAid === 'unknown' ? 'unknown' : undefined;
+}
+function isUnknownAgentLabel(value) {
+    return value === 'unknown' || value === '<unknown>' || value === '<none>' || value === 'undefined' || value === 'null';
+}
+function normalizeAuditPermissionMode(value) {
+    if (!value || value === 'unknown')
+        return value;
+    return normalizeExecutionPermissionMode(value);
+}
 function redactIdentifier(value) {
     if (!value)
         return undefined;
@@ -212,6 +344,7 @@ function logAuditEvent(record) {
         record.correlationId ? `correlation=${record.correlationId}` : null,
         record.eventKey ? `eventKey=${record.eventKey}` : null,
         record.sessionId ? `session=${record.sessionId}` : null,
+        record.agentName ? `agentName=${JSON.stringify(record.agentName)}` : null,
         record.agentAid ? `agent=${record.agentAid}` : null,
         record.permissionMode ? `permissionMode=${record.permissionMode}` : null,
         record.toolName ? `tool=${record.toolName}` : null,
@@ -296,6 +429,21 @@ function summarizeAuthorizationArgs(operation, args) {
     for (const [key, value] of Object.entries(args)) {
         if (value === undefined)
             continue;
+        if (key === 'parseFailure' && value && typeof value === 'object' && !Array.isArray(value)) {
+            const diagnostic = value;
+            const issue = typeof diagnostic.issue === 'string' ? diagnostic.issue : undefined;
+            const offset = typeof diagnostic.offset === 'number' && Number.isFinite(diagnostic.offset)
+                ? Math.max(0, Math.floor(diagnostic.offset)) : undefined;
+            const tokenIndex = typeof diagnostic.tokenIndex === 'number' && Number.isFinite(diagnostic.tokenIndex)
+                ? Math.max(0, Math.floor(diagnostic.tokenIndex)) : undefined;
+            const dialect = typeof diagnostic.dialect === 'string' ? diagnostic.dialect : undefined;
+            const inputLength = typeof diagnostic.inputLength === 'number' && Number.isFinite(diagnostic.inputLength)
+                ? Math.max(0, Math.floor(diagnostic.inputLength)) : undefined;
+            if (issue && offset !== undefined && tokenIndex !== undefined && dialect && inputLength !== undefined) {
+                summary.parseFailure = { issue, offset, tokenIndex, dialect, inputLength };
+            }
+            continue;
+        }
         if (/^(?:self|peer|peerKey|target|targetId|session|sessionId|channelId)$/i.test(key)) {
             summary[key] = typeof value === 'string' ? redactIdentifier(value) : '[redacted]';
             continue;

package/dist/core/auth/operation-authorizer.js

@@ -95,6 +95,20 @@ function authorizeCommandInternal(ctx, resolvedConfigCommand) {
         && (resolvedConfigCommand.operationId !== operation || resolvedConfigCommand.commandScope !== intent.scope)) {
         return denyDecision(ctx, 'NOT_ALLOWED', 'Resolved config operation does not match the command intent', operation, intent.scope, opMeta.dangerous);
     }
+    // A fullaccess task is deliberately a daemon-scoped runtime identity. It
+    // still has to name a known operation and pass structural command parsing,
+    // but relation/Agent role rules, source lists, and daemon-owner gates are
+    // not meaningful limits for code already approved for host-level execution.
+    if (ctx.processRole === 'fullaccess-run' && ctx.dataScope === 'daemon') {
+        return {
+            allow: true,
+            operation,
+            scope: intent.scope,
+            role: 'fullaccess-run',
+            dangerous: opMeta.dangerous,
+            matchedRule: 'fullaccess-run-daemon-scope',
+        };
+    }
     if (ctx.chatType === 'group'
         && (resolvedConfigCommand ? isResolvedConfigMutation(resolvedConfigCommand) : isConfigMutationOperation(operation))
         && intent.scope !== 'relation') {
@@ -175,7 +189,31 @@ function authorizeCommandInternal(ctx, resolvedConfigCommand) {
     if (roleDef.allowAccess === false) {
         return denyDecision(ctx, 'ROLE_ACCESS_DENIED', `Role ${role} is not allowed to access commands`, operation, intent.scope, opMeta.dangerous);
     }
-    const matchResult = matchCommandPermission(operation, opMeta.category, roleDef.commandPermissions || {}, opMeta.dangerous);
+    let matchResult = matchCommandPermission(operation, opMeta.category, roleDef.commandPermissions || {}, opMeta.dangerous);
+    // Agent self-service contact add deliberately reuses the same low-trust
+    // relation boundary as ec.msg.send. Older per-Agent role files may still
+    // contain the historical contact.* deny without an explicit contact.add
+    // entry; preserve their safe current-peer/private-only send capability while
+    // allowing this new request workflow. An explicit contact.add rule wins.
+    if (operation === 'contact.add'
+        && !Object.prototype.hasOwnProperty.call(roleDef.commandPermissions || {}, 'contact.add')) {
+        const sendPermission = roleDef.commandPermissions?.['ec.msg.send'];
+        if (sendPermission?.allow) {
+            matchResult = {
+                permission: {
+                    ...sendPermission,
+                    scopes: ['relation'],
+                    constraints: {
+                        ...(sendPermission.constraints ?? {}),
+                        ownPeerOnly: true,
+                        privateOnly: true,
+                    },
+                },
+                matchedRule: 'ec.msg.send',
+                rank: 1000,
+            };
+        }
+    }
     if (!matchResult) {
         return denyDecision(ctx, 'NO_PERMISSION', `Role ${role} has no permission for ${operation}`, operation, intent.scope, opMeta.dangerous);
     }
@@ -274,6 +312,8 @@ function requiresDaemonOwner(ctx, resolvedConfigCommand) {
         const targetAgentAid = stringArg(args.targetAgentAid) ?? stringArg(args.self);
         return !!taskAgentAid && !!targetAgentAid && taskAgentAid !== targetAgentAid;
     }
+    if (operation.startsWith('role.') && ctx.fromControlChannel)
+        return true;
     return false;
 }
 function hasDaemonOwnerRole(ctx) {

package/dist/core/auth/operation-catalog.js

@@ -55,7 +55,7 @@ const GROUP_MANAGEMENT_OPERATIONS = [
     sources: ['agent-tool'],
 }));
 const MSG_READ_OPERATIONS = [
-    ['ec.msg.history', 'Read message history for an AUN private relation'],
+    ['ec.msg.history', 'Read message history for a controlled private relation'],
     ['ec.msg.online', 'Read online status for an AUN private relation'],
 ].map(([id, description]) => ({
     id,
@@ -476,6 +476,14 @@ const OPERATIONS = [
         description: 'Read the Agent contact block list',
         sources: ['agent-tool'],
     },
+    {
+        id: 'contact.add',
+        category: 'write-agent',
+        dangerous: false,
+        defaultScopes: ['relation'],
+        description: 'Request adding the current private relation as an Agent contact',
+        sources: ['agent-tool'],
+    },
     {
         id: 'contact.block',
         category: 'write-agent',

package/dist/core/bootstrap-service.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { randomBytes } from 'crypto';
 import { kitsTemplatesDir, agentMdPath } from '../paths.js';
-import { resolveAgentDisplayName } from '../aun/aid/agentmd.js';
+import { buildInitialAgentMd, resolveAgentDisplayName } from '../aun/aid/agentmd.js';
 import { logger } from '../utils/logger.js';
 import { loadAgent, saveAgent } from '../config-store.js';
 import { resolveAgentLifecycle, withLifecycleForWrite } from '../config/lifecycle.js';
@@ -292,7 +292,11 @@ export class BootstrapService {
         if (typeof adapter.uploadAgentMd !== 'function')
             return;
         const existing = fs.existsSync(agentMdPath(aid)) ? fs.readFileSync(agentMdPath(aid), 'utf-8') : '';
-        const content = existing.trim() || `---\naid: "${aid}"\nname: "${fallbackName}"\ntype: "codeagent"\nversion: "1.0.0"\ndescription: ""\ntags:\n  - evolcore\n  - ai-agent\n---\n`;
+        const content = existing.trim() || buildInitialAgentMd({
+            aid,
+            name: fallbackName,
+            type: 'codeagent',
+        });
         try {
             await adapter.uploadAgentMd(content);
             logger.info(`[Bootstrap] Published agent.md for ${aid}`);

package/dist/core/causation/aun-association.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { resolvePaths } from '../../paths.js';
-import { atomicReadJson, atomicWriteJson } from '../../utils/atomic-write.js';
+import { atomicReadJson, stableWriteJson } from '../../utils/atomic-write.js';
 import { cloneCausation, normalizeCausation } from './context.js';
 const DEFAULT_TTL_MS = 30 * 60 * 1000;
 const associations = new Map();
@@ -44,9 +44,12 @@ function ensureLoaded() {
 }
 function persist() {
     try {
-        // Keep the protected mount target present even when there are no pending
-        // associations. Removing it races with Bubblewrap's H-class projection.
-        atomicWriteJson(associationFile(), [...associations].map(([messageId, association]) => ({
+        // Keep the protected mount target's inode stable. Bubblewrap binds this
+        // H-class file by pathname while constructing its namespace; an atomic
+        // rename can otherwise replace the inode during bind/remount and make
+        // sandbox initialization fail. Causation state is best-effort and small,
+        // so an in-place write is preferable to changing the protected inode.
+        stableWriteJson(associationFile(), [...associations].map(([messageId, association]) => ({
             messageId,
             ...association,
         })));

package/dist/core/command/agent-control.js

@@ -8,6 +8,7 @@ import { agentProjectRootFromDefaults, deriveAgentProjectPath } from '../../util
 import { uploadAvatar } from '../../utils/avatar-upload.js';
 import { agentmdGet, agentmdPut, updateAgentMdFrontmatterName } from '../../aun/aid/agentmd.js';
 import { isValidAid } from '../../aun/aid/validation.js';
+import { isSupportedBaseagent } from '../../agents/baseagent.js';
 const SUPPORTED_AGENT_PATCH_FIELDS = new Set(['aid', 'name', 'avatar', 'active_baseagent', 'baseagents', 'projects', 'owners', 'chatmode', 'channels', 'channelOwners']);
 const HIDDEN_VALUE = '[hidden]';
 const SENSITIVE_CONFIG_KEYS = new Set([
@@ -95,6 +96,9 @@ function normalizeBaseagentsPatch(value) {
     }
     const out = {};
     for (const [name, raw] of Object.entries(value)) {
+        if (!isSupportedBaseagent(name)) {
+            return { ok: false, error: `不支持的 baseagent: ${name}（可选: claude/codex/gemini/ecagent）` };
+        }
         if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
             return { ok: false, error: `baseagents.${name} 必须是对象` };
         }
@@ -286,11 +290,11 @@ function buildCreateProgressOnlyAgent(aid, progress) {
  *  失败仅写日志 + create-status，不回传（受理即返回）。
  *  agentSet key 对照 cli/agent.ts 的 setNestedValue：
  *  model/effort → 'baseagents.<baseagent>.*'；chatmode → 'chatmode'（ChatmodeBlock 对象）。 */
-async function runCreateInBackground(opts, w) {
+async function runCreateInBackground(opts, w, service) {
     let curPhase = 'validating'; // 跟踪当前环节，供 catch 兜底时标注正确 phase
     try {
         // onPhase 把 agentCreateNonInteractive 内部环节（0-3、5）映射到进度文件
-        const res = await agentCreateNonInteractive({
+        const createOptions = {
             aid: opts.aid, name: opts.name, baseagent: opts.baseagent,
             project: opts.project, owner: opts.owner,
             onPhase: (phase, state, detail) => {
@@ -305,7 +309,10 @@ async function runCreateInBackground(opts, w) {
                 else if (state === 'failed')
                     w.finishFailed(phase, detail ?? 'failed');
             },
-        });
+        };
+        const res = service
+            ? await service.create(createOptions)
+            : await agentCreateNonInteractive(createOptions);
         if (!('ok' in res) || res.ok !== true) {
             // 硬失败：onPhase('failed') 已写终态；这里仅兜底日志（防回调未覆盖的 return 路径）
             const err = res.error;
@@ -318,17 +325,23 @@ async function runCreateInBackground(opts, w) {
             w.begin('applying_config');
             let warned;
             if (opts.model) {
-                const r = await agentSet(opts.aid, `baseagents.${opts.baseagent}.model`, opts.model);
+                const r = service
+                    ? await service.setConfig(opts.aid, `baseagents.${opts.baseagent}.model`, opts.model)
+                    : await agentSet(opts.aid, `baseagents.${opts.baseagent}.model`, opts.model);
                 if (!('ok' in r) || !r.ok)
                     warned = `model: ${r.error}`;
             }
             if (opts.effort) {
-                const r = await agentSet(opts.aid, `baseagents.${opts.baseagent}.effort`, opts.effort);
+                const r = service
+                    ? await service.setConfig(opts.aid, `baseagents.${opts.baseagent}.effort`, opts.effort)
+                    : await agentSet(opts.aid, `baseagents.${opts.baseagent}.effort`, opts.effort);
                 if (!('ok' in r) || !r.ok)
                     warned = `${warned ? warned + '; ' : ''}effort: ${r.error}`;
             }
             if (opts.chatmode) {
-                const r = await agentSet(opts.aid, 'chatmode', JSON.stringify(opts.chatmode));
+                const r = service
+                    ? await service.setConfig(opts.aid, 'chatmode', JSON.stringify(opts.chatmode))
+                    : await agentSet(opts.aid, 'chatmode', JSON.stringify(opts.chatmode));
                 if (!('ok' in r) || !r.ok)
                     warned = `${warned ? warned + '; ' : ''}chatmode: ${r.error}`;
             }
@@ -361,7 +374,7 @@ async function runCreateInBackground(opts, w) {
 /** name=agent 的 menu.action 执行。create 使用显式 owner AID；peerId 仅作为控制面鉴权主体。
  *  create 受理即返回（D3）；delete/enable/disable 同步等结果。
  *  调用方负责传入已兜底的 args.project（见 command-handler 装配）。 */
-export async function execAgentAction(action, args, peerId, eventBus) {
+export async function execAgentAction(action, args, peerId, eventBus, service) {
     const a = args ?? {};
     if (action === 'create') {
         if (!peerId)
@@ -394,13 +407,15 @@ export async function execAgentAction(action, args, peerId, eventBus) {
             project: a.project, owner,
             model, effort, chatmode: a.chatmode,
             eventBus,
-        }, progressWriter).catch(e => logger.error(`[agent-control] runCreateInBackground unhandled ${a.aid}: ${e?.message || e}`));
+        }, progressWriter, service).catch(e => logger.error(`[agent-control] runCreateInBackground unhandled ${a.aid}: ${e?.message || e}`));
         return { data: { accepted: true, aid: a.aid } };
     }
     if (action === 'delete') {
         if (!a.aid)
             return { error: '缺少 aid', code: 'INVALID_ARGS' };
-        const res = await agentDelete(a.aid, false);
+        const res = service
+            ? await service.delete(a.aid, false)
+            : await agentDelete(a.aid, false);
         if (!('ok' in res) || res.ok !== true)
             return { error: res.error, code: classifyError(res.error) };
         eventBus?.publish({ type: 'agent:deleted', aid: res.aid, purged: res.purged, timestamp: Date.now() });
@@ -410,7 +425,13 @@ export async function execAgentAction(action, args, peerId, eventBus) {
         if (!a.aid)
             return { error: '缺少 aid', code: 'INVALID_ARGS' };
         const options = { force: a.force === true };
-        const res = action === 'enable' ? await agentEnable(a.aid, options) : await agentDisable(a.aid, options);
+        const res = service
+            ? action === 'enable'
+                ? await service.enable(a.aid, options.force === true)
+                : await service.disable(a.aid, options.force === true)
+            : action === 'enable'
+                ? await agentEnable(a.aid, options)
+                : await agentDisable(a.aid, options);
         if (!('ok' in res) || res.ok !== true)
             return { error: res.error, code: res.code || classifyError(res.error) };
         eventBus?.publish({
@@ -424,7 +445,9 @@ export async function execAgentAction(action, args, peerId, eventBus) {
     if (action === 'reload') {
         if (!a.aid)
             return { error: '缺少 aid', code: 'INVALID_ARGS' };
-        const res = await agentReload(a.aid, { force: a.force === true });
+        const res = service
+            ? await service.reload(a.aid, { force: a.force === true })
+            : await agentReload(a.aid, { force: a.force === true });
         if (!('ok' in res) || res.ok !== true)
             return { error: res.error, code: res.code || classifyError(res.error) };
         eventBus?.publish({ type: 'agent:reloaded', aid: a.aid, timestamp: Date.now() });
@@ -508,6 +531,9 @@ export async function execAgentUpdate(args) {
         if (typeof p.active_baseagent !== 'string' || !p.active_baseagent.trim()) {
             return { error: `无效 active_baseagent: ${JSON.stringify(p.active_baseagent)}（必须是非空字符串）`, code: 'INVALID_ARGS' };
         }
+        if (!isSupportedBaseagent(p.active_baseagent.trim())) {
+            return { error: `不支持的 active_baseagent: ${p.active_baseagent}（可选: claude/codex/gemini/ecagent）`, code: 'INVALID_ARGS' };
+        }
         config.active_baseagent = p.active_baseagent.trim();
         touched = true;
     }
@@ -576,7 +602,7 @@ export async function execAgentUpdate(args) {
 /**
  * project 解析与 ec agent create 保持一致：
  * 显式值 > 默认项目根目录 + AID 前缀。
- * 默认项目根目录由 defaults.projects.rootPath/defaultPath 或运行时根目录推导。
+ * 默认项目根目录由 defaults.projects.defaultPath 或运行时根目录推导。
  */
 export function resolveProjectPath(explicit, aid, defaults) {
     if (explicit && explicit.trim())
@@ -585,13 +611,15 @@ export function resolveProjectPath(explicit, aid, defaults) {
     return deriveAgentProjectPath(root, aid);
 }
 /** name=agent 的 menu.query：查单个 agent 详情，附构建进度（D3）。 */
-export async function execAgentQuery(args) {
+export async function execAgentQuery(args, service) {
     const aid = args?.aid;
     if (!aid)
         return { error: '缺少 aid', code: 'INVALID_ARGS' };
     const agentDir = path.join(resolvePaths().agentsDir, aid);
     const progress = readCreateStatus(agentDir);
-    const res = await agentShow(aid);
+    const res = service
+        ? await service.show(aid)
+        : await agentShow(aid);
     if (!('ok' in res) || res.ok !== true) {
         const code = classifyError(res.error);
         if (code === 'NOT_FOUND' && progress)
@@ -616,9 +644,21 @@ export async function execAgentQuery(args) {
     return { data: progress ? { ...data, createProgress: progress } : data };
 }
 /** name=agent 的 menu.options：列出 agent（enabled 默认 / all） */
-export async function execAgentOptions(args) {
+export async function execAgentOptions(args, service) {
     const scope = args?.options === 'all' ? 'all' : 'enabled';
-    const res = await agentList();
+    const res = service
+        ? { ok: true, agents: service.list().map(info => ({
+                aid: info.aid || info.name,
+                name: info.name,
+                personalName: info.personalName || null,
+                status: info.status || 'stopped',
+                channels: info.channels || [],
+                projectPath: info.projectPath ? toPosix(info.projectPath) : null,
+                baseagent: info.baseagent || null,
+                model: info.model || null,
+                lastActivity: info.lastActivity || null,
+            })) }
+        : await agentList();
     if (!('ok' in res) || res.ok !== true)
         return { error: res.error, code: classifyError(res.error) };
     const agents = scope === 'all'