@zhin.js/agent 0.3.1 → 1.0.2

package/lib/zhin-agent/index.js

@@ -1,64 +1,47 @@
 /**
- * ZhinAgent — 全局持久 AI 大脑
- *
- * 核心能力：
- *   1. 全局单例，应用生命周期内常驻
- *   2. Skill 感知：两级过滤 Skill → Tool
- *   3. 双层记忆：per-scene（对话上下文）+ per-user（长期偏好）
- *   4. 任务规划：复杂请求自动分解为子步骤
- *   5. 多模态输出：结构化 OutputElement[]
- *   6. 智能路径选择：纯闲聊走轻量路径，工具请求走完整路径
- *   7. 用户画像：跨会话个性化记忆
- *   8. 速率限制：防止单用户过度消耗资源
- *   9. 流式输出：onChunk 回调实时推送部分文本
- *  10. 情绪感知：根据用户语气调整回复风格
- *  11. 定时任务：cron_add 持久化定时任务
- *  12. 多模态输入：图片/音频直接传给视觉模型
+ * ZhinAgent — IM Agent 门面类（组合 ideal 模块；实现见 init/ + internal/）。
  */
 import { randomUUID } from 'node:crypto';
-import { formatCompact, Logger } from '@zhin.js/logger';
-import { createMemorySessionManager, resolveIMSessionIdFromMessage, } from '@zhin.js/ai';
-import { ConversationMemory, createMemoryContextRepository, MemoryIMSessionStore, MemoryImTranscriptStore, getModel, registerLlmApiFromProviders, sdkEntryFromProvider, } from '@zhin.js/ai';
-import { TurnTracker } from './turn-tracker.js';
-import { ZhinAgentEventEmitter } from './event-emitter.js';
+import { resolveIMSessionIdFromMessage } from '@zhin.js/core';
+import { Logger } from '@zhin.js/logger';
+import { MemoryIMSessionStore, ConversationMemory, createMemoryContextRepository, MemoryImTranscriptStore, RateLimiter, } from '@zhin.js/ai';
+import { createMemorySystemForHost } from '../memory/memory-system.js';
+import { ZhinAgentEventEmitter } from '../event/event-emitter.js';
 import { UserProfileStore } from '../user-profile.js';
-import { RateLimiter } from '@zhin.js/ai';
-import { SubagentManager } from '../subagent.js';
 import { buildParentContextPreamble } from '../subagent-parent-context.js';
-import { getAgentDispatcher } from '../orchestrator/agent-dispatcher.js';
-import { DEFAULT_CONFIG, isPhaseTraceEnabled, isPromptTraceEnabled, isPromptTraceVerbose, } from './config.js';
-import { DeferredWorkerRunner } from '../deferred-worker-runner.js';
-import { deliverDeferredAutoContinueReply } from './deferred-delivery.js';
-import { processTextTurn, processMultimodalTurn } from './turn-pipeline.js';
-import { manualCompactSession } from './compaction-runtime.js';
-import { archiveSessionByKey, beginTurnSession, } from './session-io.js';
-import { asPrivate } from './zhin-agent-private.js';
-import { PromptController } from './prompt-controller.js';
-import { getActiveTurnTracker, runInTurnContext as runInTurnContextAls } from './turn-context.js';
-import { normalizePromptMessages } from './prompt-input.js';
-import { resolveToolRequesterRole } from '../security/owner-approve-always-store.js';
-import { bindingToModelConfig } from '../routing/runtime-binding.js';
-import { buildDisciplinedPrompt as assembleDisciplinedPrompt } from './prompt-assembly.js';
-import { resolveAgentToolsForTurn as resolveToolsForTurn, runDeferredWorker as runDeferredWorkerTurn, } from './tool-orchestration.js';
-import { buildDeferredAutoContinueUserMessage } from './deferred-auto-continue.js';
-export { PromptAccessDeniedError } from './prompt-access.js';
-export { formatAiHandlerCompleteLog, formatZhinAgentTurnUsage } from './turn-metrics.js';
-export * from './prompt-builder.js';
-export * from './prompt-templates.js';
-export * from './task-continuation.js';
+import { DEFAULT_CONFIG, isPhaseTraceEnabled, isPromptTraceEnabled, isPromptTraceVerbose, } from '../config/index.js';
+import { processTextTurn, processMultimodalTurn } from '../turn/turn-pipeline.js';
+import { resolveContextTailMessageLimit } from '../context/context-tail-limit.js';
+import { archiveSessionByKey } from '../session/session-io.js';
+import { asPrivate } from '../internal/as-private.js';
+import { PromptController } from '../turn/prompt-controller.js';
+import { getActiveTurnTracker } from '../internal/turn-context.js';
+import { computeDeferredDelta } from '../turn/turn-deferred-delta.js';
+import { resolveDeferredToolsConfig } from '../tool-catalog/resolve-config.js';
+import { buildDisciplinedPrompt as assembleDisciplinedPrompt } from '../prompt/assembly.js';
+import { createInboundTurnQueue, runWithInboundQueue } from '../turn/inbound-queue-runtime.js';
+import { continueAfterDeferredWorker, continueAfterSubagent } from '../turn/auto-continue.js';
+import { createSubagentSystem } from '../subagent/subagent-system-init.js';
+import { processTextTurnStream } from '../turn/process-stream.js';
+import { followUpMessage, runPromptTurn, steerMessage } from '../turn/prompt-api.js';
+import { appendActiveSkills, getTurnActiveSkills, initInboundTurnContext as bridgeInitInboundTurnContext, initScheduleTurnContext as bridgeInitScheduleTurnContext, runInTurnContext as bridgeRunInTurnContext, } from '../turn/turn-context-bridge.js';
+import { emitSessionCompactEvent, emitSessionNewEvent } from '../event/session-events.js';
+import { applyZhinAgentConfigure, wireZhinAgentLlmApiLayer } from '../init/configure-zhin-agent.js';
+import { disposeZhinAgentResources } from '../init/dispose-zhin-agent.js';
+import { clearZhinAgentRuntimeModules, createZhinAgentRuntimeModules, } from './runtime-modules.js';
+export { PromptAccessDeniedError } from '../turn/prompt-access.js';
+export { formatAiHandlerCompleteLog, formatZhinAgentTurnUsage } from '../turn/turn-metrics.js';
+export * from '../prompt/prompt-builder.js';
+export * from '../prompt/templates.js';
+export * from '../turn/task-continuation.js';
 const logger = new Logger(null, 'ZhinAgent');
-// ============================================================================
-// ZhinAgent
-// ============================================================================
-import { PromptAccessDeniedError } from './prompt-access.js';
 export class ZhinAgent {
     provider;
     providerResolver = null;
     activeBinding = null;
     config;
-    skillRegistry = null;
-    orchestrator = null;
-    sessions;
+    /** ideal 模块槽位；经 getter/setter 供 configure 与 asPrivate(host) 读写 */
+    runtimeModules;
     imSessionStore = new MemoryIMSessionStore();
     agentSessionStore;
     contextRepository;
@@ -67,9 +50,9 @@ export class ZhinAgent {
     externalTools = new Map();
     userProfiles;
     rateLimiter;
-    subagentManager = null;
+    subagentSystem = null;
     bootstrapContext = '';
-    activeSkillsContext = '';
+    alwaysSkillsBaseline = '';
     skillsSummaryXML = '';
     modelRegistry = null;
     phaseTraceEnabled;
@@ -77,7 +60,6 @@ export class ZhinAgent {
     promptTraceVerbose;
     emitter = new ZhinAgentEventEmitter();
     deferredCatalog = [];
-    deferredWorkerRunner = new DeferredWorkerRunner();
     lastToolSearchDeferredStats;
     promptController;
     deferredResultSender = null;
@@ -86,6 +68,29 @@ export class ZhinAgent {
     memoryPersistenceReady;
     resolveMemoryPersistenceReady;
     memoryPersistenceDone = false;
+    inboundQueueConfig;
+    inboundTurnQueue;
+    turnContextState = {
+        alwaysSkillsBaseline: '',
+    };
+    get skillRegistry() { return this.runtimeModules.skillRegistry; }
+    set skillRegistry(value) { this.runtimeModules.skillRegistry = value; }
+    get skillSystem() { return this.runtimeModules.skillSystem; }
+    set skillSystem(value) { this.runtimeModules.skillSystem = value; }
+    get orchestrator() { return this.runtimeModules.orchestrator; }
+    set orchestrator(value) { this.runtimeModules.orchestrator = value; }
+    get agentCore() { return this.runtimeModules.agentCore; }
+    set agentCore(value) { this.runtimeModules.agentCore = value; }
+    get toolSystem() { return this.runtimeModules.toolSystem; }
+    set toolSystem(value) { this.runtimeModules.toolSystem = value; }
+    get contextSystem() { return this.runtimeModules.contextSystem; }
+    set contextSystem(value) { this.runtimeModules.contextSystem = value; }
+    get memorySystem() { return this.runtimeModules.memorySystem; }
+    set memorySystem(value) { this.runtimeModules.memorySystem = value; }
+    get sessionSystem() { return this.runtimeModules.sessionSystem; }
+    set sessionSystem(value) { this.runtimeModules.sessionSystem = value; }
+    get eventSystem() { return this.runtimeModules.eventSystem; }
+    set eventSystem(value) { this.runtimeModules.eventSystem = value; }
     get phaseConfig() {
         return { phaseTraceEnabled: this.phaseTraceEnabled, onPhaseTrace: this.config.onPhaseTrace };
     }
@@ -95,16 +100,27 @@ export class ZhinAgent {
             promptTraceVerbose: this.promptTraceVerbose,
         };
     }
+    get autoContinueHost() {
+        return {
+            config: this.config,
+            promptController: this.promptController,
+            getDeferredAutoContinueDepth: (k) => this.getDeferredAutoContinueDepth(k),
+            setDeferredAutoContinueDepth: (k, d) => this.deferredAutoContinueDepthBySession.set(k, d),
+            resetDeferredAutoContinueDepth: (k) => this.resetDeferredAutoContinueDepth(k),
+            getDeferredResultSender: () => this.getDeferredResultSender(),
+            runInTurnContext: (turnId, fn) => this.runInTurnContext(turnId, fn),
+        };
+    }
     constructor(provider, config) {
         this.provider = provider;
-        this.config = { ...DEFAULT_CONFIG, ...config };
+        const merged = { ...DEFAULT_CONFIG, ...config };
+        this.config = merged;
         this.phaseTraceEnabled = isPhaseTraceEnabled(this.config);
         this.promptTraceEnabled = isPromptTraceEnabled(this.config);
         this.promptTraceVerbose = isPromptTraceVerbose(this.config);
         this.memoryPersistenceReady = new Promise((resolve) => {
             this.resolveMemoryPersistenceReady = resolve;
         });
-        this.sessions = createMemorySessionManager();
         this.memory = new ConversationMemory({
             minTopicRounds: this.config.minTopicRounds,
             slidingWindowSize: this.config.slidingWindowSize,
@@ -115,96 +131,46 @@ export class ZhinAgent {
         this.userProfiles = new UserProfileStore();
         this.rateLimiter = new RateLimiter(this.config.rateLimit);
         this.promptController = new PromptController(this.config.steeringMode, this.config.followUpMode);
+        const inbound = createInboundTurnQueue(this.config, this.emitter);
+        this.inboundQueueConfig = inbound.config;
+        this.inboundTurnQueue = inbound.queue;
         const memoryStack = createMemoryContextRepository({
-            tailMessageLimit: this.config.slidingWindowSize,
+            tailMessageLimit: resolveContextTailMessageLimit(this.config),
         });
         this.agentSessionStore = memoryStack.sessionStore;
         this.contextRepository = memoryStack.repository;
         this.imTranscriptStore = new MemoryImTranscriptStore();
+        this.turnContextState.alwaysSkillsBaseline = this.alwaysSkillsBaseline;
+        this.runtimeModules = createZhinAgentRuntimeModules(asPrivate(this));
         this.wireLlmApiLayer();
-        // DB 注入完成前由 waitForMemoryPersistence 等待；useDatabase:false 时由 bootstrap 立即 mark
     }
-    // ── DI setters ──────────────────────────────────────────────────────
-    /**
-     * 统一依赖注入入口。替代逐字段 setter。
-     * 所有 setter 现委托到此方法；新代码优先使用 configure()。
-     */
     configure(deps) {
-        if (deps.skillRegistry !== undefined) {
-            this.skillRegistry = deps.skillRegistry;
-            logger.debug(`SkillRegistry connected (${deps.skillRegistry.size} skills)`);
-        }
-        if (deps.orchestrator !== undefined) {
-            this.orchestrator = deps.orchestrator;
-            logger.debug('AgentOrchestrator connected for MCP and resources');
-        }
-        if (deps.sessionManager !== undefined) {
-            this.sessions.dispose();
-            this.sessions = deps.sessionManager;
-        }
-        if (deps.imSessionStore !== undefined)
-            this.imSessionStore = deps.imSessionStore;
-        if (deps.agentSessionStore !== undefined)
-            this.agentSessionStore = deps.agentSessionStore;
-        if (deps.contextRepository !== undefined)
-            this.contextRepository = deps.contextRepository;
-        if (deps.imTranscriptStore !== undefined)
-            this.imTranscriptStore = deps.imTranscriptStore;
-        if (deps.modelRegistry !== undefined) {
-            this.modelRegistry = deps.modelRegistry;
-            this.subagentManager?.setModelRegistry(deps.modelRegistry);
-        }
-        if (deps.hostPlugin !== undefined)
-            this.emitter.setHostPlugin(deps.hostPlugin);
-        if (deps.providerResolver !== undefined) {
-            this.providerResolver = deps.providerResolver;
-            this.wireLlmApiLayer();
-        }
-        if (deps.activeBinding !== undefined) {
-            this.activeBinding = deps.activeBinding;
-            if (deps.activeBinding) {
-                const patch = bindingToModelConfig(deps.activeBinding);
-                this.config = { ...this.config, ...patch };
-            }
-        }
-        if (deps.subagentSender !== undefined) {
-            this.subagentManager?.setSender(deps.subagentSender);
-        }
-        if (deps.deferredResultSender !== undefined)
-            this.deferredResultSender = deps.deferredResultSender;
-        if (deps.bootstrapContext !== undefined) {
-            this.bootstrapContext = deps.bootstrapContext;
-            logger.debug(`Bootstrap context set (${deps.bootstrapContext.length} chars)`);
-        }
-        if (deps.activeSkillsContext !== undefined)
-            this.activeSkillsContext = deps.activeSkillsContext || '';
-        if (deps.skillsSummaryXML !== undefined)
-            this.skillsSummaryXML = deps.skillsSummaryXML || '';
-    }
-    /** @deprecated 使用 configure({ skillRegistry }) */
-    setSkillRegistry(registry) { this.configure({ skillRegistry: registry }); }
-    /** @deprecated 使用 configure({ orchestrator }) */
-    setOrchestrator(orchestrator) { this.configure({ orchestrator }); }
-    /** @deprecated 使用 configure({ modelRegistry }) */
-    setModelRegistry(registry) { this.configure({ modelRegistry: registry }); }
-    /** @deprecated 使用 configure({ hostPlugin }) */
-    setHostPlugin(plugin) { this.configure({ hostPlugin: plugin }); }
-    /** @deprecated 使用 configure({ providerResolver }) */
-    setProviderResolver(resolver) { this.configure({ providerResolver: resolver }); }
-    wireLlmApiLayer() {
-        registerLlmApiFromProviders([sdkEntryFromProvider(this.provider)], (alias) => {
-            const p = alias === this.provider.name ? this.provider : this.providerResolver?.(alias);
-            return p?.models ?? [];
-        });
+        applyZhinAgentConfigure(this, deps);
     }
-    /** @deprecated 使用 configure({ activeBinding }) */
-    setActiveBinding(binding) {
-        if (binding === null) {
-            this.activeBinding = null;
-        }
-        else {
-            this.configure({ activeBinding: binding });
-        }
+    getTurnActiveSkills() {
+        return getTurnActiveSkills(this.turnContextState);
+    }
+    /** @deprecated 使用 getTurnActiveSkills() */
+    get activeSkillsContext() {
+        return this.getTurnActiveSkills();
+    }
+    getAlwaysSkillsBaseline() {
+        return this.alwaysSkillsBaseline;
+    }
+    initScheduleTurnContext(ctx) {
+        bridgeInitScheduleTurnContext(this.turnContextState, ctx);
+    }
+    initInboundTurnContext() {
+        bridgeInitInboundTurnContext(this.turnContextState);
+    }
+    appendActiveSkillsContext(fragment) {
+        appendActiveSkills(fragment);
+    }
+    buildDisciplinedPrompt(basePrompt) {
+        return assembleDisciplinedPrompt(asPrivate(this), basePrompt);
+    }
+    wireLlmApiLayer() {
+        wireZhinAgentLlmApiLayer(this.provider, this.providerResolver);
     }
     getActiveBinding() {
         return this.activeBinding;
@@ -221,11 +187,6 @@ export class ZhinAgent {
         }
         return this.provider;
     }
-    /** @deprecated 消息事实源已迁至 im_transcripts / agent_messages，保留空实现以兼容旧 bootstrap */
-    async upgradeMemoryToDatabase(_msgModel, _sumModel) {
-        return;
-    }
-    /** 等待 DB store 注入（bootstrap 会 mark；已 mark 时立即返回） */
     async waitForMemoryPersistence() {
         if (this.memoryPersistenceDone)
             return;
@@ -249,55 +210,30 @@ export class ZhinAgent {
         this.memoryPersistenceDone = true;
         this.resolveMemoryPersistenceReady?.();
     }
+    sharePersistenceWith(target) {
+        target.configure({
+            imSessionStore: this.imSessionStore,
+            agentSessionStore: this.agentSessionStore,
+            contextRepository: this.contextRepository,
+            imTranscriptStore: this.imTranscriptStore,
+        });
+        if (this.memoryPersistenceDone) {
+            target.markMemoryPersistenceReady();
+        }
+    }
     upgradeProfilesToDatabase(model) {
         this.userProfiles.upgradeToDatabase(model);
     }
-    initSubagentManager(createTools) {
-        this.subagentManager = new SubagentManager({
+    initSubagentSystem(createTools) {
+        this.subagentSystem = createSubagentSystem({
             provider: this.provider,
-            workspace: process.cwd(),
-            createTools,
-            subagentTools: this.config.subagentTools,
-            maxIterations: this.config.maxSubagentIterations,
-            execPolicyConfig: this.config,
+            config: this.config,
             modelRegistry: this.modelRegistry,
-            agentDispatcher: getAgentDispatcher(),
-            onSubagentUsage: (usage) => getActiveTurnTracker()?.addSubagentUsage(usage),
-            registerSubagentTask: (done) => getActiveTurnTracker()?.trackSubagent(done),
-            eventEmitter: this.emitter,
-            onEvent: (event) => {
-                const sessionId = resolveIMSessionIdFromMessage(event.origin.message);
-                const payload = this.emitter.createPayload(sessionId, event.origin.message, 'text', {
-                    source: 'subagent',
-                    path: 'agent',
-                    taskId: event.taskId,
-                    label: event.label,
-                    content: event.task,
-                    status: event.status,
-                    error: event.error,
-                    reply: event.result,
-                    agentId: event.agent,
-                    hookContext: {
-                        subagentAgent: event.agent,
-                    },
-                });
-                if (event.phase === 'spawn') {
-                    this.emitter.emit('ai.subagent.spawn', payload);
-                }
-                else if (event.phase === 'start') {
-                    this.emitter.emit('ai.subagent.start', payload);
-                }
-                else {
-                    this.emitter.emit('ai.subagent.finish', payload);
-                }
-            },
+            emitter: this.emitter,
+            createTools,
+            onSubagentComplete: (payload) => this.continueAfterSubagent(payload),
         });
-        logger.debug('SubagentManager initialized');
     }
-    /** @deprecated 使用 configure({ subagentSender }) */
-    setSubagentSender(sender) { this.configure({ subagentSender: sender }); }
-    /** @deprecated 使用 configure({ deferredResultSender }) */
-    setDeferredResultSender(sender) { this.configure({ deferredResultSender: sender }); }
     getDeferredResultSender() {
         return this.deferredResultSender;
     }
@@ -308,42 +244,20 @@ export class ZhinAgent {
         this.deferredAutoContinueDepthBySession.delete(sessionKey);
     }
     async continueAfterDeferredWorker(commMessage, taskId, goal, result) {
-        const sessionKey = resolveIMSessionIdFromMessage(commMessage);
-        const depth = this.getDeferredAutoContinueDepth(sessionKey);
-        this.deferredAutoContinueDepthBySession.set(sessionKey, depth + 1);
-        await this.promptController.waitForIdle();
-        logger.info(formatCompact({
-            deferred: 'auto_continue',
-            task_id: taskId,
-            depth: depth + 1,
-        }));
-        const message = buildDeferredAutoContinueUserMessage(taskId, goal, result.status);
-        const elements = await this.runInTurnContext(randomUUID(), () => processTextTurn(asPrivate(this), '', commMessage, [], undefined, {
-            prebuiltMessages: [message],
-            deferredAutoContinue: true,
-        }));
-        const sender = this.getDeferredResultSender();
-        if (sender && elements.length > 0) {
-            await deliverDeferredAutoContinueReply(sender, commMessage, elements);
-        }
-        logger.info(formatCompact({
-            deferred: 'auto_continue_done',
-            task_id: taskId,
-            depth: depth + 1,
-            outbound: elements.length,
-        }));
+        return continueAfterDeferredWorker(this.autoContinueHost, asPrivate(this), commMessage, taskId, goal, result);
+    }
+    async continueAfterSubagent(payload) {
+        return continueAfterSubagent(this.autoContinueHost, asPrivate(this), payload);
     }
     getActiveTurnTracker() {
         return getActiveTurnTracker();
     }
     runInTurnContext(turnId, fn) {
-        const tracker = new TurnTracker(this.config.subagentTurnWaitMs);
-        return runInTurnContextAls(turnId, tracker, fn);
+        return bridgeRunInTurnContext(this.turnContextState, this.config, turnId, fn);
     }
-    getSubagentManager() {
-        return this.subagentManager;
+    getSubagentSystem() {
+        return this.subagentSystem;
     }
-    /** fork 模式：主会话 active_leaf 链快照（不含 spawn_task / tool_search 编排噪声） */
     async buildParentContextSnapshotForSubagent(origin) {
         const sessionKey = resolveIMSessionIdFromMessage(origin.message);
         const active = await this.agentSessionStore.findActive(sessionKey);
@@ -366,11 +280,14 @@ export class ZhinAgent {
     getLastTurnMetrics() {
         return this.lastTurnMetrics;
     }
+    getLastTurnToolSnapshot() {
+        const priv = asPrivate(this);
+        const snap = priv.lastDeferredSessionSnapshot ?? { loadedTools: {}, loadedSkills: [] };
+        const deferredCfg = resolveDeferredToolsConfig(this.config);
+        return computeDeferredDelta(snap, deferredCfg.alwaysLoadedTools, priv.lastDeferredSnapshotBefore);
+    }
     beginActiveTurn() {
-        const tracker = getActiveTurnTracker();
-        if (!tracker)
-            return;
-        tracker.begin();
+        getActiveTurnTracker()?.begin();
     }
     async finalizeActiveTurn(partial) {
         const tracker = getActiveTurnTracker();
@@ -380,39 +297,10 @@ export class ZhinAgent {
         this.lastTurnMetrics = tracker.lastMetrics;
     }
     emitSessionNewEvent(sessionId, commMessage, mode, content, reply) {
-        this.emitter.emit('ai.session.new', this.emitter.createPayload(sessionId, commMessage, mode, {
-            reason: 'first_message',
-            content,
-            reply,
-        }));
+        emitSessionNewEvent(this.emitter, sessionId, commMessage, mode, content, reply);
     }
     emitSessionCompactEvent(sessionId, commMessage, mode, info) {
-        this.emitter.emit('ai.session.compact', this.emitter.createPayload(sessionId, commMessage, mode, {
-            path: 'agent',
-            compactedCount: 1,
-            savedTokens: info.microSavedTokens + info.autoSavedTokens,
-            totalTokensBefore: info.totalTokensBefore,
-            totalTokensAfter: info.totalTokensAfter,
-            result: info,
-        }));
-    }
-    // ── prompt() / steer / followUp (ADR 0009 D6) ─────────────────────
-    assertMasterForPromptControl(commMessage) {
-        const plugin = this.emitter.getHostPlugin();
-        if (!plugin) {
-            throw new PromptAccessDeniedError('steer/followUp 需要有效的 master 上下文');
-        }
-        try {
-            const role = resolveToolRequesterRole(plugin, commMessage);
-            if (role !== 'master') {
-                throw new PromptAccessDeniedError('steer/followUp 仅 master 可用');
-            }
-        }
-        catch (error) {
-            if (error instanceof PromptAccessDeniedError)
-                throw error;
-            throw new PromptAccessDeniedError('steer/followUp 需要有效的 master 上下文');
-        }
+        emitSessionCompactEvent(this.emitter, sessionId, commMessage, mode, info);
     }
     subscribe(listener) {
         return this.promptController.subscribe(listener);
@@ -433,42 +321,17 @@ export class ZhinAgent {
         this.promptController.clearFollowUpQueue(sessionKey);
     }
     steer(message, commMessage) {
-        this.assertMasterForPromptControl(commMessage);
-        const sessionKey = resolveIMSessionIdFromMessage(commMessage);
-        this.promptController.steer(sessionKey, message);
+        steerMessage(this.promptController, this.emitter, message, commMessage);
     }
     followUp(message, commMessage) {
-        this.assertMasterForPromptControl(commMessage);
-        const sessionKey = resolveIMSessionIdFromMessage(commMessage);
-        this.promptController.followUp(sessionKey, message);
+        followUpMessage(this.promptController, this.emitter, message, commMessage);
     }
-    /**
-     * 对齐 Agent.prompt：入队并执行 LLM turn（需 IM Message 通讯上下文）。
-     * process() / processMultimodal() 在 agentLoop 路径下内部委托此方法。
-     */
     async prompt(input, commMessage, options) {
-        const messages = normalizePromptMessages(input, options?.images);
-        const text = messages
-            .flatMap((message) => {
-            if (message.role !== 'user')
-                return [];
-            const user = message;
-            return user.content
-                .filter((block) => block.type === 'text')
-                .map((block) => block.text);
-        })
-            .join('\n')
-            .trim();
-        await this.runInTurnContext(randomUUID(), () => processTextTurn(asPrivate(this), text, commMessage, [], options?.onChunk, {
-            prebuiltMessages: messages,
-        }));
+        return runPromptTurn(asPrivate(this), input, commMessage, (id, fn) => this.runInTurnContext(id, fn), options);
     }
-    // ── Core processing ─────────────────────────────────────────────────
-    /** 旁听由 zhin `message.receive` 写入 im_transcripts，此处保留空实现 */
     async appendPassiveGroupChatter(_commMessage, _rawContent) {
         return;
     }
-    /** 归档当前场景 active 会话（/reset）；下次 @ 将创建新 session 纪元 */
     async archiveSessionForCommMessage(commMessage) {
         const sessionKey = resolveIMSessionIdFromMessage(commMessage);
         return archiveSessionByKey({
@@ -477,80 +340,53 @@ export class ZhinAgent {
             contextRepository: this.contextRepository,
         }, sessionKey);
     }
-    /** 手动压缩当前 session epoch（/compact） */
     async compactSessionForCommMessage(commMessage) {
-        const sessionKey = resolveIMSessionIdFromMessage(commMessage);
-        const deps = {
-            imSessionStore: this.imSessionStore,
-            agentSessionStore: this.agentSessionStore,
-            contextRepository: this.contextRepository,
-        };
-        const { sessionId } = await beginTurnSession(deps, sessionKey, commMessage);
-        const provider = this.getTurnProvider();
-        const modelId = this.config.chatModel || provider.models[0] || '';
-        const llmModel = getModel(provider.name, modelId);
-        const contextWindow = llmModel.contextWindow ?? this.config.contextTokens;
-        return manualCompactSession(this.contextRepository, {
-            host: asPrivate(this),
-            sessionId,
-            commMessage,
-            model: llmModel,
-            compactionConfig: this.config.compaction,
-            contextWindow,
-            mode: 'text',
-        });
+        const priv = asPrivate(this);
+        const memorySystem = this.memorySystem ?? createMemorySystemForHost(priv);
+        return memorySystem.compactSessionForCommMessage(priv, commMessage, this.requireSessionSystem().sessionDeps(priv));
+    }
+    requireSessionSystem() {
+        const system = this.sessionSystem;
+        if (!system) {
+            throw new Error('ZhinAgent.sessionSystem is required');
+        }
+        return system;
     }
     async process(content, commMessage, externalTools = [], onChunk) {
-        return this.runInTurnContext(randomUUID(), () => processTextTurn(asPrivate(this), content, commMessage, externalTools, onChunk));
-    }
-    resolveAgentToolsForTurn(allTools, commMessage) {
-        return resolveToolsForTurn(asPrivate(this), allTools, commMessage);
-    }
-    async runDeferredWorker(goal, toolQuery, commMessage, allTools) {
-        return runDeferredWorkerTurn(asPrivate(this), goal, toolQuery, commMessage, allTools);
+        return this.runInTurnContext(randomUUID(), () => runWithInboundQueue(commMessage, this.inboundQueueConfig, this.inboundTurnQueue, {
+            content,
+            run: (mergedContent) => processTextTurn(asPrivate(this), mergedContent, commMessage, externalTools, onChunk),
+        }));
     }
-    buildDisciplinedPrompt(basePrompt) {
-        return assembleDisciplinedPrompt(asPrivate(this), basePrompt);
+    async *processStream(content, commMessage, externalTools = []) {
+        yield* processTextTurnStream(asPrivate(this), {
+            content,
+            commMessage,
+            externalTools,
+            inboundQueueConfig: this.inboundQueueConfig,
+            inboundTurnQueue: this.inboundTurnQueue,
+            runInTurnContext: (id, fn) => this.runInTurnContext(id, fn),
+        });
     }
     async processMultimodal(parts, commMessage, onChunk) {
-        return this.runInTurnContext(randomUUID(), () => processMultimodalTurn(asPrivate(this), parts, commMessage, onChunk));
+        return this.runInTurnContext(randomUUID(), () => runWithInboundQueue(commMessage, this.inboundQueueConfig, this.inboundTurnQueue, {
+            coalesce: false,
+            run: () => processMultimodalTurn(asPrivate(this), parts, commMessage, onChunk),
+        }));
     }
-    // ── Internal helpers ────────────────────────────────────────────────
-    // ── Lifecycle ───────────────────────────────────────────────────────
     isReady() {
         return true;
     }
     dispose() {
-        this.memory.dispose();
-        this.sessions.dispose();
-        this.externalTools.clear();
-        this.userProfiles.dispose();
-        this.rateLimiter.dispose();
-        if (this.subagentManager) {
-            this.subagentManager.dispose();
-            this.subagentManager = null;
-        }
-        if (this.promptController) {
-            this.promptController.abort();
-        }
-        // 使用 Disposable 接口统一清理资源（运行时 has-dispose 检查）
-        const tryDispose = (obj) => {
-            if (obj && typeof obj.dispose === 'function') {
-                obj.dispose?.();
-            }
-        };
-        tryDispose(this.imSessionStore);
-        tryDispose(this.agentSessionStore);
-        tryDispose(this.contextRepository);
-        tryDispose(this.imTranscriptStore);
+        disposeZhinAgentResources(this);
+        this.subagentSystem = null;
         this.deferredAutoContinueDepthBySession.clear();
         this.deferredCatalog = [];
         this.lastTurnMetrics = null;
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- disposed, fields intentionally nulled
         this.provider = null;
         this.providerResolver = null;
-        this.skillRegistry = null;
-        this.orchestrator = null;
+        clearZhinAgentRuntimeModules(this.runtimeModules);
     }
 }
 //# sourceMappingURL=index.js.map