/**
 * MemoryCoordinator — 记忆系统统一协调器
 *
 * 设计原则 (CoALA / MemGPT / Generative Agents / Mem0):
 *   - Single Coordinator: 所有记忆操作通过此模块路由
 *   - Budget-Aware Injection: 记忆注入受统一 token 预算管控
 *   - Extract-Update Write Path: 写入经去重/合并/冲突解决
 *   - Graceful Degradation: 任意子系统故障不影响核心执行
 *
 * 生命周期:
 *   - Bootstrap 模式: 会话级 (orchestrator 创建, 贯穿所有维度)
 *   - User Chat 模式: 实例级 (AgentRuntime 创建)
 *
 * @module MemoryCoordinator
 */
import { ActiveContext } from './ActiveContext.js';
import type { DimensionReportInput, SessionStore } from './SessionStore.js';
/** PersistentMemory 接口 (声明式) */
interface PersistentMemoryLike {
    toPromptSection(opts: {
        source?: string;
    }): Promise<string> | string;
    append(entry: {
        type: string;
        content: string;
        source: string;
        importance: number;
    }): void;
}
/** ConversationStore 接口 (声明式) */
interface ConversationStoreLike {
    load(conversationId: string, opts?: {
        tokenBudget?: number;
    }): unknown[];
    summarize(conversationId: string, opts?: {
        aiProvider?: unknown;
    }): Promise<unknown>;
}
/** AiProvider 接口 (声明式) */
interface AiProviderLike {
    [key: string]: unknown;
}
/** MemoryCoordinator 构造选项 */
export interface MemoryCoordinatorConfig {
    persistentMemory?: PersistentMemoryLike | null;
    sessionStore?: SessionStore | null;
    conversationLog?: ConversationStoreLike | null;
    mode?: 'user' | 'bootstrap';
    totalMemoryBudget?: number;
}
/** 静态记忆 Prompt 选项 */
export interface StaticMemoryOptions {
    mode?: 'user' | 'analyst' | 'producer';
    taskContext?: string;
    currentDimId?: string;
    focusKeywords?: string[];
    scopeId?: string;
}
/** 维度 scope 配置 */
export interface DimensionScopeConfig {
    lightweight?: boolean;
    maxRecentRounds?: number;
}
export declare class MemoryCoordinator {
    #private;
    _lastSurplus: number;
    /**
     * @param [config.persistentMemory] PersistentMemory 实例
     * @param [config.sessionStore] SessionStore 实例 (bootstrap 模式)
     * @param [config.conversationLog] ConversationStore 实例
     * @param [config.totalMemoryBudget=4000] 记忆 section 的 token 总预算
     */
    constructor(config?: MemoryCoordinatorConfig);
    /**
     * 配置总预算 (由 AgentRuntime.execute 入口调用)
     * @param options.totalContextBudget 模型总上下文 token 数
     */
    configure({ totalContextBudget, model }?: {
        totalContextBudget?: number;
        model?: string;
    }): void;
    /**
     * 按模式分配预算
     * @param [totalTokens] 覆盖总预算
     */
    allocateBudget(mode: 'user' | 'analyst' | 'producer', totalTokens?: number): void;
    getTotalBudget(): number;
    getBudgetAllocation(): {
        activeContext: number;
        sessionStore: number;
        persistentMemory: number;
        conversationLog: number;
    };
    /**
     * 获取消息缓冲区可用预算 (F2)
     * @param totalContextBudget 模型总上下文 token
     */
    getMessageBudget(totalContextBudget: number, systemPromptEstimate?: number, toolSchemaEstimate?: number, safetyMargin?: number): number;
    /**
     * 构建静态记忆 prompt (execute 入口调用一次)
     * 包含: PersistentMemory + ConversationLog + SessionStore 上下文
     *
     * @param [options.mode] 'user' | 'analyst' | 'producer'
     * @param [options.taskContext] 当前任务描述 (用于 relevance 打分)
     * @param [options.currentDimId] 当前维度 (用于 SessionStore 过滤)
     * @param [options.focusKeywords] 聚焦关键词
     */
    buildStaticMemoryPrompt(options?: StaticMemoryOptions): Promise<string>;
    /**
     * 构建动态记忆 prompt (每轮调用)
     * 包含: ActiveContext / WorkingMemory 上下文
     */
    buildDynamicMemoryPrompt(options?: StaticMemoryOptions): string;
    /** 合并构建完整记忆 prompt (便捷方法) */
    buildMemoryPrompt(options?: StaticMemoryOptions): Promise<string>;
    /**
     * 记录工具调用观察 (合并 WM.observe + TRC.set)
     * @param round 当前迭代轮次
     * @param [cacheHit=false] 本次是否缓存命中
     */
    recordObservation(toolName: string, args: Record<string, unknown>, result: unknown, round: number, cacheHit?: boolean): void;
    /**
     * 记录关键发现 (从 note_finding handler 调用)
     * @param importance 1-10
     * @param [scopeId] 显式指定 scope (并行安全)
     * @returns 响应消息
     */
    noteFinding(finding: string, evidence: string, importance: number, round: number, scopeId?: string): string;
    /**
     * 从对话中提取记忆
     *
     * 写入路由 (WriteRouter):
     *   - 规则 1: 只在 user 源触发规则匹配 (B4 fix)
     *   - 规则 2: [MEMORY] 标签提取 (所有源)
     *
     * @param prompt 用户输入
     * @param reply AI 回复
     */
    extractFromConversation(prompt: string, reply: string, source: 'user' | 'system'): void;
    /** 获取缓存的工具结果 */
    getCachedResult(toolName: string, args: Record<string, unknown>): unknown | null;
    /** 缓存工具结果 */
    cacheToolResult(toolName: string, args: Record<string, unknown>, result: unknown): void;
    /**
     * 创建维度作用域 (D2/D3: 多 scope 支持)
     *
     * @param scopeId 如 'api-patterns:analyst', 'api-patterns:producer'
     * @param [config.lightweight=false] 轻量模式 (User Chat)
     * @returns WorkingMemory (Phase 2) / ActiveContext (Phase 3)
     */
    createDimensionScope(scopeId: string, config?: DimensionScopeConfig): ActiveContext;
    /**
     * 完成维度: 蒸馏 + 存储到 SessionStore
     * @param [report] 附加报告数据
     */
    completeDimension(scopeId: string, report?: DimensionReportInput): void;
    /**
     * 完成会话: 触发 Consolidator
     * @returns |null>}
     */
    completeSession(): Promise<{
        consolidated: number;
    } | null>;
    /** 获取当前或指定 scope 的 ActiveContext / WorkingMemory */
    getActiveContext(scopeId?: string): ActiveContext | null;
    /** 获取 SessionStore */
    getSessionStore(): SessionStore | null;
    /** 获取 PersistentMemory */
    getPersistentMemory(): PersistentMemoryLike | null;
    /** 获取 ConversationLog / ConversationStore */
    getConversationLog(): ConversationStoreLike | null;
    /** 对话更新后触发自动摘要 */
    onConversationUpdated(conversationId: string, aiProvider: AiProviderLike | null): Promise<void>;
    /** 保存 checkpoint */
    checkpoint(projectRoot: string): Promise<void>;
    /** 恢复 checkpoint */
    restore(projectRoot: string): Promise<boolean>;
    dispose(): void;
}
export default MemoryCoordinator;