foliko 1.1.93 → 2.0.1

package/src/agent/main.js

@@ -0,0 +1,337 @@
+'use strict';
+
+/**
+ * MainAgent - 主对话 Agent
+ * 完整的对话 Agent，支持 session、工具注册、上下文压缩
+ */
+
+const { BaseAgent } = require('./base');
+const { Logger, LOG_LEVELS } = require('../common/logger');
+const { PROMPT_PRIORITY, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_TEMPERATURE } = require('../common/constants');
+const { SystemPromptBuilder } = require('./prompt');
+const os = require('os');
+
+const _agentLogger = new Logger({ namespace: 'agent', level: LOG_LEVELS.INFO });
+const logger = {
+  info: (ctx, msg, data) => _agentLogger.info(`[${ctx}] ${msg}`, data !== undefined ? data : ''),
+  warn: (ctx, msg, data) => _agentLogger.warn(`[${ctx}] ${msg}`, data !== undefined ? data : ''),
+  error: (ctx, msg, data) => _agentLogger.error(`[${ctx}] ${msg}`, data !== undefined ? data : ''),
+  debug: (ctx, msg, data) => _agentLogger.debug(`[${ctx}] ${msg}`, data !== undefined ? data : ''),
+};
+
+class MainAgent extends BaseAgent {
+  constructor(framework, config = {}) {
+    super(framework, config);
+
+    this.name = config.name || 'Agent';
+    this.model = config.model || 'deepseek-chat';
+    this.apiKey = config.apiKey;
+    this.baseURL = config.baseURL;
+    this.provider = config.provider || 'deepseek';
+    this.providerOptions = {
+      ...config.providerOptions,
+      maxOutputTokens: config.providerOptions?.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
+      temperature: config.providerOptions?.temperature ?? DEFAULT_TEMPERATURE,
+    };
+
+    this._originalPrompt = config.systemPrompt || '你是一个智能助手。当用户提出问题或任务时，你会主动分析需求，选择合适的工具来获取信息或执行操作。你善于将复杂任务拆解为多个步骤，通过工具协作完成。';
+    this._sharedPrompt = config.sharedPrompt || '';
+    const metadata = config.metadata || {};
+    this._metadata = new Map(Object.entries(metadata));
+
+    this._chatHandler = null;
+    this._tools = new Map();
+    this._skipSyncTools = config.skipSyncTools || false;
+    this._subAgents = new Map();
+    this._systemPromptBuilder = new SystemPromptBuilder();
+    this._registerDefaultPromptParts();
+    this.systemPrompt = this._buildSystemPrompt();
+
+    // Initialize chat handler
+    const { NotificationManager } = require('../notification/manager');
+    this._notificationManager = new NotificationManager(framework);
+    this._initChatHandler();
+  }
+
+  _registerDefaultPromptParts() {
+    this._systemPromptBuilder.register('original-prompt', PROMPT_PRIORITY.ORIGINAL_PROMPT, () => this._originalPrompt);
+    this._systemPromptBuilder.register('shared-prompt', PROMPT_PRIORITY.SHARED_PROMPT, () => {
+      return this._sharedPrompt ? this._replacePlaceholders(this._sharedPrompt) : null;
+    });
+    this._systemPromptBuilder.register('datetime', PROMPT_PRIORITY.DATETIME, () => {
+      const now = new Date();
+      const timeStr = now.toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });
+      const dateStr = now.toLocaleDateString('zh-CN', { timeZone: 'Asia/Shanghai', weekday: 'long' });
+      return `【当前时间】${timeStr}（${dateStr}）`;
+    });
+    this._systemPromptBuilder.register('metadata', PROMPT_PRIORITY.METADATA, () => {
+      if (this._metadata.size === 0) return null;
+      const metaParts = ['【元数据】'];
+      for (const [key, value] of this._metadata) {
+        metaParts.push(`- ${key}: ${typeof value === 'object' ? JSON.stringify(value) : value}`);
+      }
+      return metaParts.join('\n');
+    });
+    this._systemPromptBuilder.register('capabilities', PROMPT_PRIORITY.CAPABILITIES, () => this._buildCapabilitiesDescription());
+  }
+
+  _getMetadataValue(key) {
+    if (this._metadata.has(key)) return this._metadata.get(key);
+    switch (key) {
+      case 'WORK_DIR': case 'CWD': return this.framework?.getCwd?.() ?? process.cwd();
+      case 'HOME_DIR': return os.homedir();
+      case 'HOST_NAME': return os.hostname();
+      case 'PLATFORM': return process.platform;
+      case 'TIME': return new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });
+      case 'DATE': return new Date().toISOString().split('T')[0];
+      default: return `{{${key}}}`;
+    }
+  }
+
+  _replacePlaceholders(template) {
+    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => this._getMetadataValue(key));
+  }
+
+  _buildCapabilitiesDescription() {
+    const plugins = this.framework.pluginManager.getAll();
+    if (!plugins || plugins.length === 0) return '';
+    const keyPlugins = plugins.filter(p => p.name !== 'defaults' && p.name !== 'agent');
+    if (keyPlugins.length === 0) return '';
+    const lines = ['## 系统能力', ''];
+    keyPlugins.forEach((plugin, index) => {
+      const name = plugin.instance?.name || plugin.name || 'unknown';
+      const description = plugin.instance?.description || '无描述';
+      lines.push(`${index + 1}. **${name}**：${description}`);
+    });
+    return lines.join('\n');
+  }
+
+  _buildSystemPrompt() {
+    if (!this._systemPromptDirty && this._systemPromptCache !== null) return this._systemPromptCache;
+    this._systemPromptCache = this._systemPromptBuilder.build();
+    this._systemPromptDirty = false;
+    return this._systemPromptCache;
+  }
+
+  _invalidateSystemPromptCache() {
+    this._systemPromptDirty = true;
+    this._systemPromptBuilder.invalidateAll();
+  }
+
+  _refreshContext() {
+    this.systemPrompt = this._buildSystemPrompt();
+    if (this._chatHandler) this._chatHandler.setSystemPrompt(this.systemPrompt);
+  }
+
+  _initChatHandler() {
+    const { AgentChatHandler } = require('./chat');
+    let aiClient = null;
+    const aiPlugin = this.framework.pluginManager?.get('ai');
+    if (aiPlugin) aiClient = aiPlugin.getAIClient();
+
+    this._chatHandler = new AgentChatHandler(this, {
+      model: this.model, provider: this.provider, apiKey: this.apiKey,
+      baseURL: this.baseURL, providerOptions: this.providerOptions,
+      maxContextTokens: this.config.maxContextTokens,
+      compressionThreshold: this.config.compressionThreshold,
+      compressionMessageThreshold: this.config.compressionMessageThreshold,
+      keepRecentMessages: this.config.keepRecentMessages,
+      enableSmartCompress: this.config.enableSmartCompress,
+    });
+    if (aiClient) this._chatHandler.setAIClient(aiClient);
+
+    this._chatHandler.on('message', (msg) => this.emit('message', msg));
+    this._chatHandler.on('chunk', (chunk) => this.emit('chunk', chunk));
+    this._chatHandler.on('tool-call', (tool) => this.emit('tool-call', tool));
+    this._chatHandler.on('tool-result', (result) => this.emit('tool-result', result));
+    this._chatHandler.on('error', (err) => this.emit('error', err));
+    this._syncTools();
+  }
+
+  getOriginalPrompt() { return this._originalPrompt; }
+
+  setSystemPrompt(prompt) {
+    this._originalPrompt = prompt;
+    this.systemPrompt = this._buildSystemPrompt();
+    if (this._chatHandler) this._chatHandler.setSystemPrompt(this.systemPrompt);
+    return this;
+  }
+
+  registerPromptPart(name, priority, provider) {
+    this._systemPromptBuilder.register(name, priority, provider);
+    this._invalidateSystemPromptCache();
+    this._refreshContext();
+    return this;
+  }
+
+  unregisterPromptPart(name) {
+    this._systemPromptBuilder.unregister(name);
+    this._invalidateSystemPromptCache();
+    this._refreshContext();
+    return this;
+  }
+
+  registerTool(tool) {
+    this.framework.registerTool(tool);
+    if (this._chatHandler) this._chatHandler.registerTool(tool);
+    this._invalidateSystemPromptCache();
+    this._refreshContext();
+    return this;
+  }
+
+  getTools() { return this.framework.getTools(); }
+
+  _syncTools() {
+    const tools = this.framework.getTools();
+    for (const tool of tools) {
+      if (this._chatHandler) this._chatHandler.registerTool(tool);
+    }
+  }
+
+  registerSubAgent(name, agent, role, goal) {
+    this._subAgents.set(name, { agent, role, goal });
+    this._invalidateSystemPromptCache();
+    this._refreshContext();
+    return this;
+  }
+
+  unregisterSubAgent(name) {
+    this._subAgents.delete(name);
+    this._invalidateSystemPromptCache();
+    this._refreshContext();
+    return this;
+  }
+
+  getSubAgents() { return this._subAgents; }
+
+  async chat(message, options = {}) {
+    if (this._status === 'error') this._status = 'idle';
+    this._status = 'busy';
+    this.emit('status', { status: 'busy' });
+    try {
+      const enhancedMessage = this._notificationManager.enhanceMessage(message);
+      if (!this._skipSyncTools) this._syncTools();
+      const result = await this._chatHandler.chat(enhancedMessage, options);
+      this._status = 'idle';
+      this.emit('status', { status: 'idle' });
+      return result;
+    } catch (err) {
+      this._status = 'error';
+      logger.error('Agent', `chat failed: ${err.message}`, { stack: err.stack });
+      this.emit('status', { status: 'error', error: err.message });
+      throw err;
+    }
+  }
+
+  async pushMessage(message, options = {}) {
+    const ctx = this.framework.getExecutionContext();
+    if (ctx?.sessionId && !options.sessionId) options.sessionId = ctx.sessionId;
+    return this.chat(message, options);
+  }
+
+  async *chatStream(message, options = {}) {
+    if (this._status === 'busy') throw new Error('Agent is busy');
+    if (this._status === 'error') this._status = 'idle';
+    this._status = 'busy';
+    this.emit('status', { status: 'busy' });
+    try {
+      const enhancedMessage = this._notificationManager.enhanceMessage(message);
+      if (!this._skipSyncTools) this._syncTools();
+      yield* this._chatHandler.chatStream(enhancedMessage, options);
+      this._status = 'idle';
+      this.emit('status', { status: 'idle' });
+    } catch (err) {
+      this._status = 'error';
+      logger.error('Agent', `chatStream failed: ${err.message}`, { stack: err.stack });
+      this.emit('status', { status: 'error', error: err.message });
+      throw err;
+    }
+  }
+
+  createSessionScope(sessionId) { return this._chatHandler.createSessionScope(sessionId); }
+  async sendMessage(message, options = {}) { return this._chatHandler.sendMessage(message, options); }
+  async *sendMessageStream(message, options = {}) { yield* this._chatHandler.sendMessageStream(message, options); }
+  async sendBatch(messages, options = {}) { return this._chatHandler.sendBatch(messages, options); }
+  cancelSession(sessionId) { return this._chatHandler.cancelSession(sessionId); }
+
+  setMetadata(keyOrObj, value) {
+    if (typeof keyOrObj === 'string') {
+      this._metadata.set(keyOrObj, value);
+    } else if (keyOrObj && typeof keyOrObj === 'object') {
+      for (const [key, val] of Object.entries(keyOrObj)) this._metadata.set(key, val);
+    }
+    this._invalidateSystemPromptCache();
+    this._refreshContext();
+    return this;
+  }
+
+  getMetadata(key) { return this._metadata.get(key); }
+  deleteMetadata(key) { this._metadata.delete(key); this._refreshContext(); return this; }
+  clearMetadata() { this._metadata.clear(); this._refreshContext(); return this; }
+
+  clearContext(sessionId) {
+    if (!sessionId || !this._chatHandler) return;
+    this._chatHandler._chatSession?.clearSessionMessages(sessionId, true);
+    const sessionCtx = this.framework?.getSessionContext(sessionId);
+    if (sessionCtx) {
+      sessionCtx.clearMessages();
+      if (sessionCtx.compressionState) sessionCtx.compressionState.count = 0;
+      if (sessionCtx.metadata) sessionCtx.metadata.compressionCount = 0;
+    }
+    const sessionManager = this.framework?._sessionContexts?.get(sessionId);
+    if (sessionManager) {
+      const { generateEntryId, EntryTypes } = require('../session/entry');
+      sessionManager._appendEntry({
+        id: generateEntryId(sessionManager.byId), type: EntryTypes.SESSION_INFO,
+        info: 'context_cleared', timestamp: Date.now(),
+      });
+    }
+  }
+
+  async compressContext(sessionId) {
+    if (!sessionId || !this._chatHandler) throw new Error('AgentChatHandler not available');
+    const chatHandler = this._chatHandler;
+    const messageStore = chatHandler._chatSession?.getSessionMessageStore(sessionId);
+    if (!messageStore) throw new Error('MessageStore not available');
+    messageStore.historyLoaded = false;
+    chatHandler._chatSession?.loadHistory(sessionId);
+    let messages = messageStore.messages;
+    const sessionCtx = this.framework?.getSessionContext(sessionId);
+    if (!messages?.length && sessionCtx) {
+      messages = sessionCtx.getMessages();
+      messageStore.messages = messages;
+    }
+    if (!messages?.length) throw new Error('No messages to compress');
+    if (!chatHandler._contextCompressor) throw new Error('ContextCompressor not available');
+    const before = messages.length;
+    await chatHandler._contextCompressor.compress(sessionId, messages, messageStore);
+    const after = messages.length;
+    if (sessionCtx) sessionCtx.replaceMessages(messages);
+    const sessionManager = this.framework?._sessionContexts?.get(sessionId);
+    if (sessionManager) {
+      const { generateEntryId, EntryTypes } = require('../session/entry');
+      sessionManager._appendEntry({
+        id: generateEntryId(sessionManager.byId), type: EntryTypes.COMPACTION,
+        summary: messages.find(m => m.role === 'assistant' && m.content?.startsWith('['))?.content || '',
+        firstKeptEntryId: null, tokensBefore: before, timestamp: Date.now(),
+      });
+    }
+    return { before, after, keepRecent: chatHandler._contextCompressor._keepRecentMessages };
+  }
+
+  getCurrentAgentId() { return this.name; }
+
+  destroy() {
+    for (const [name, { agent }] of this._subAgents) {
+      if (typeof agent.destroy === 'function') agent.destroy();
+    }
+    this._subAgents.clear();
+    if (this._chatHandler) this._chatHandler.destroy();
+    this._tools.clear();
+    this.removeAllListeners();
+    this.emit('destroyed');
+    logger.info('Agent', `Agent "${this.name}" destroyed`);
+  }
+}
+
+module.exports = { MainAgent };

package/src/agent/prompt.js

@@ -0,0 +1,78 @@
+'use strict';
+
+class SystemPromptPart {
+  constructor(name, priority, provider) {
+    this.name = name;
+    this.priority = priority;
+    this._provider = provider;
+    this._dirty = true;
+    this._cached = null;
+  }
+
+  get() {
+    if (this._dirty || this._cached === null) {
+      try {
+        this._cached = this._provider();
+        this._dirty = false;
+      } catch (e) {
+        console.warn(`[SystemPromptPart:${this.name}] Provider failed:`, e.message);
+        this._cached = null;
+      }
+    }
+    return this._cached;
+  }
+
+  invalidate() { this._dirty = true; }
+}
+
+class SystemPromptBuilder {
+  constructor() {
+    this._parts = new Map();
+    this._orderedParts = [];
+  }
+
+  register(name, priority, provider) {
+    this._parts.set(name, new SystemPromptPart(name, priority, provider));
+    this._reorder();
+    return this;
+  }
+
+  unregister(name) {
+    this._parts.delete(name);
+    this._reorder();
+    return this;
+  }
+
+  invalidate(name) {
+    const part = this._parts.get(name);
+    if (part) part.invalidate();
+    return this;
+  }
+
+  invalidateAll() {
+    for (const part of this._parts.values()) part.invalidate();
+    return this;
+  }
+
+  getPart(name) {
+    const part = this._parts.get(name);
+    return part ? part.get() : null;
+  }
+
+  build() {
+    const parts = [];
+    for (const part of this._orderedParts) {
+      const content = part.get();
+      if (content && content.trim()) parts.push(content.trim());
+    }
+    return parts.join('\n\n');
+  }
+
+  getPartNames() { return [...this._parts.keys()]; }
+
+  _reorder() {
+    this._orderedParts = Array.from(this._parts.values()).sort((a, b) => a.priority - b.priority);
+  }
+}
+
+module.exports = { SystemPromptBuilder, SystemPromptPart };

package/src/agent/sub.js

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * SubAgent - 轻量子 Agent
+ * 继承 BaseAgent，使用 AI SDK 直接执行单次任务
+ * 不需要 session、上下文压缩等复杂功能
+ */
+
+const { BaseAgent } = require('./base');
+const { cleanResponse } = require('../utils');
+const { generateText, tool, stepCountIs, ToolLoopAgent } = require('ai');
+const { z } = require('zod');
+const { logger } = require('../common/logger');
+const { validateAll } = require('../utils/message-validator');
+const { isNetworkError, calculateDelay } = require('../common/retry');
+
+class SubAgent extends BaseAgent {
+  constructor(config = {}) {
+    super(config.framework || null, config);
+
+    this.name = config.name || 'SubAgent';
+    this.role = config.role || '助手';
+    this.description = config.description || '';
+    this.model = config.model || 'deepseek-chat';
+    this.provider = config.provider || 'deepseek';
+    this.apiKey = config.apiKey;
+    this.baseURL = config.baseURL;
+    this.providerOptions = config.providerOptions || {};
+
+    this.defaulTools = ['ext_skill', 'loadSkill', 'ext_call', 'subagent_call', 'mcp_call', 'mcp_tool_schema'];
+    this.bindTools = {
+      read: 'read_file', write: 'write_file', edit: 'modify_file',
+      glob: 'read_directory', grep: 'search_file', bash: 'bash',
+    };
+
+    this._customSystemPrompt = config.systemPrompt || null;
+    this.parentTools = config.parentTools;
+    this.tools = config.tools || {};
+    this.maxRetries = config.maxRetries ?? 2;
+    this.retryDelay = config.retryDelay ?? 5000;
+    this.disableTools = config.disableTools ?? false;
+    this._promptParts = [];
+    this._isSubagent = true;
+
+    this.providerOptions.deepseek = this.providerOptions.deepseek || {};
+    this.providerOptions.deepseek.thinking = { type: 'disabled' };
+
+    if (this.framework) {
+      this.framework.once('framework:ready', () => {
+        const extExecutor = this.framework?.pluginManager?.get('extension-executor');
+        extExecutor?._refreshAllAgentsExtPrompt?.(this.framework);
+      });
+    }
+  }
+
+  registerPromptPart(name, priority = 100, provider) {
+    this._promptParts.push({ name, priority, provider });
+    this._promptParts.sort((a, b) => a.priority - b.priority);
+    return this;
+  }
+
+  _validateMessagesPairing(messages) { return validateAll(messages); }
+
+  _registerTools(tools) {
+    if (Array.isArray(tools)) {
+      for (const t of tools) { if (t?.name) this.tools[t.name] = t; }
+    } else if (tools && typeof tools === 'object') {
+      for (const [name, t] of Object.entries(tools)) { this.tools[name] = t; }
+    }
+  }
+
+  addTool(toolDef) { this.tools[toolDef.name] = toolDef; return this; }
+  getTools() { return Object.values(this.tools); }
+
+  _getAIProvider() {
+    const { createAI } = require('../llm/provider');
+    return createAI({ provider: this.provider, model: this.model, apiKey: this.apiKey, baseURL: this.baseURL });
+  }
+
+  _buildAITools() {
+    const tools = {};
+    const all_tools = this.framework?.getTools() || [];
+    let parentTools = [];
+    if (Array.isArray(this.parentTools)) {
+      parentTools = this.parentTools.map(key => this.bindTools[key.toLocaleLowerCase()] || key);
+      for (const toolName of parentTools) {
+        const toolDef = all_tools.find(t => t.name === toolName);
+        if (toolDef) tools[toolDef.name] = toolDef;
+      }
+      for (const tool of all_tools.filter(a => this.defaulTools.includes(a.name))) {
+        tools[tool.name] = tool;
+      }
+    } else {
+      all_tools.forEach(item => { tools[item.name] = item; });
+    }
+    return { ...tools, ...this.tools };
+  }
+
+  _buildSystemPrompt() {
+    const lines = [];
+    const roleName = this.role || '助手';
+    const descText = this.description || '';
+    lines.push(`你是 ${roleName}。`);
+    if (descText) lines.push(descText);
+    lines.push('');
+    const now = new Date();
+    lines.push(`【当前时间】${now.toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' })}（${now.toLocaleDateString('zh-CN', { timeZone: 'Asia/Shanghai', weekday: 'long' })}）`);
+    if (this._customSystemPrompt) lines.push(this._customSystemPrompt);
+    const mainAgent = this.framework?.getMainAgent?.();
+    if (mainAgent) {
+      const mainPrompt = mainAgent.getOriginalPrompt();
+      if (mainPrompt) { lines.push('## 主Agent的系统提示词'); lines.push(mainPrompt); lines.push(''); }
+    }
+    const subagentManager = this.framework?.pluginManager?.get('subagent-manager');
+    if (subagentManager?._buildDescription) lines.push(subagentManager._buildDescription());
+    lines.push('');
+    const extExecutor = this.framework?.pluginManager?.get('extension-executor');
+    const extDesc = extExecutor?._buildExtensionsDescription?.();
+    if (extDesc) { lines.push(extDesc); lines.push(''); }
+    for (const part of this._promptParts) {
+      try {
+        const content = typeof part.provider === 'function' ? part.provider() : '';
+        if (content?.trim()) lines.push('', content.trim());
+      } catch (err) {
+        logger.warn(`[SubAgent:${this.name}] Prompt part '${part.name}' failed:`, err.message);
+      }
+    }
+    lines.push('', '## 核心职责', `- **专注本职**：只完成与 ${this.role} 相关的任务`, '- **不越界**：不要代替其他子Agent完成任务', '- **返回结果**：返回简洁明确的操作结果', '');
+    lines.push('当你被调用时，你应该：', '1. 仔细理解任务要求', '2. 如果任务不在职责范围内，返回"此任务不在我的职责范围内"', '3. 使用你的工具集完成任务', '4. 返回完整结果');
+    lines.push('', '## 禁止事项', '- 处理本职外的任务', '- 代替其他子Agent执行操作', '- 在回复中透露内部实现细节', '- 不先调用 ext_skill/loadSkill 就直接使用 ext_call');
+    return lines.join('\n');
+  }
+
+  async chat(taskOrMessages, options = {}) {
+    const maxSteps = options?.maxSteps || 30;
+    const maxRetries = options?.maxRetries ?? this.maxRetries;
+    const retryDelay = options?.retryDelay ?? this.retryDelay;
+    const aiProvider = this._getAIProvider();
+
+    let messages = Array.isArray(taskOrMessages) ? [...taskOrMessages] : [{ role: 'user', content: taskOrMessages }];
+
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const tools = this.disableTools ? {} : this._buildAITools();
+        const systemPrompt = this.disableTools ? this._customSystemPrompt : this._buildSystemPrompt();
+        const validated = this._validateMessagesPairing(messages);
+        if (validated.length !== messages.length) { messages.length = 0; messages.push(...validated); }
+
+        const agent = new ToolLoopAgent({
+          model: aiProvider(this.model),
+          instructions: systemPrompt,
+          tools,
+          stopWhen: stepCountIs(maxSteps),
+        });
+
+        const result = await agent.generate({ messages, ...this.providerOptions, abortSignal: options.signal });
+        messages.push(...result.response.messages);
+        const full_text = cleanResponse(result.text);
+        this.emit('complete', { message: full_text, steps: result.steps?.length || 0 });
+        return { success: true, message: full_text, steps: result.steps?.length || 0, messages };
+      } catch (err) {
+        lastError = err;
+        if (isNetworkError(err) && attempt < maxRetries) {
+          logger.warn(`[SubAgent:${this.name}] AI unavailable, retrying (${attempt + 1}/${maxRetries})`);
+          await new Promise(resolve => setTimeout(resolve, retryDelay * Math.pow(2, attempt)));
+          continue;
+        }
+        logger.warn(`[SubAgent:${this.name}] chat error: ${err.message}`);
+        const friendlyMessage = this._getFriendlyError(err);
+        this.emit('error', { error: friendlyMessage });
+        return { success: false, message: '', error: friendlyMessage, steps: 0, messages };
+      }
+    }
+  }
+
+  _getFriendlyError(err) {
+    if (isNetworkError(err)) return 'AI 服务暂时不可用，请稍后重试';
+    const errorMessages = {
+      AI_NoContentGeneratedError: 'AI 未生成有效内容',
+      AI_NoSuchModelError: '指定的 AI 模型不存在',
+      AI_NoSuchProviderError: 'AI 提供商配置错误',
+      AI_LoadAPIKeyError: 'AI API 密钥配置错误',
+    };
+    return errorMessages[err?.name || ''] || err?.message?.split('\n')[0] || '未知错误';
+  }
+
+  setRole(role) { this.role = role; this._customSystemPrompt = null; }
+  setDescription(description) { this.description = description; }
+  setSystemPrompt(prompt) { this._customSystemPrompt = prompt; }
+
+  destroy() {
+    this.removeAllListeners();
+    this.tools = {};
+  }
+}
+
+module.exports = { SubAgent };