autosnippet/dist/lib/agent/AgentRuntime.d.ts

Extract code patterns into a knowledge base for AI coding assistants

/**
 * AgentRuntime — 统一 Agent 执行引擎 (The Brain)
 *
 * 核心思想: 不存在类型分野，只有 ONE Runtime。
 * 只有 ONE Runtime，由 Capability + Strategy + Policy 配置驱动。
 *
 * AgentRuntime 是:
 *   - ReAct 循环的宿主 (Thought → Action → Observation)
 *   - Capability 的组合容器 (加载哪些技能)
 *   - Policy 的执行者 (遵守哪些约束)
 *   - Strategy 的被委托者 (Strategy 调用 runtime.reactLoop())
 *
 * 认知架构 (CoALA):
 *   Perception → Working Memory → Reasoning → Action → Reflection
 *   │             │                │           │         │
 *   AgentMessage   history+memory   LLM call    Tools    Policy.validateAfter
 *
 * 引擎级能力:
 *   - ContextWindow: 三级递进压缩，动态 token 预算 (可选注入)
 *   - ExplorationTracker: 阶段状态机 + 信号收集 + Nudge + Graceful exit (可选注入)
 *   - AI 错误恢复: consecutiveAiErrors 2-strike → context reset → forced summary
 *   - 空响应重试: consecutiveEmptyResponses + rollback (system 场景)
 *   - 熔断器感知: _circuitState === 'OPEN' → 直接合成摘要
 *   - 工具调用数量限制: MAX_TOOL_CALLS_PER_ITER = 8
 *   - 提交去重: submittedTitles / submittedPatterns
 *   - cleanFinalAnswer: 去除 nudge 噪声
 *
 * @module AgentRuntime
 */
import { AgentEventBus } from './AgentEventBus.js';
import type { AgentMessage } from './AgentMessage.js';
import { type AgentResult, type FileCacheEntry, type ReactLoopOpts, type RuntimeConfig, type ToolCallEntry, type ToolCallHook } from './AgentRuntimeTypes.js';
import { AgentState } from './AgentState.js';
import { Capability } from './capabilities.js';
import { PolicyEngine } from './policies.js';
export type { AgentResult, AiError, FileCacheEntry, FunctionCall, LLMResult, ProgressEvent, ReactLoopOpts, RuntimeConfig, ToolCallEntry, ToolCallHook, ToolMetadata, } from './AgentRuntimeTypes.js';
export { MAX_TOOL_CALLS_PER_ITER } from './AgentRuntimeTypes.js';
export declare class AgentRuntime {
    #private;
    onToolCall: ToolCallHook | null;
    id: string;
    presetName: string;
    state: AgentState;
    bus: AgentEventBus;
    aiProvider: import("../external/ai/AiProvider.js").AiProvider;
    toolRegistry: import("./tools/ToolRegistry.js").ToolRegistry;
    container: Record<string, unknown> | null;
    capabilities: Capability[];
    strategy: import("./strategies.js").Strategy;
    policies: PolicyEngine;
    persona: Record<string, unknown>;
    memoryConfig: Record<string, unknown>;
    onProgress: ((event: import("./AgentRuntimeTypes.js").ProgressEvent) => void) | null;
    lang: string | null;
    logger: import("winston").Logger;
    iterationCount: number;
    toolCallHistory: ToolCallEntry[];
    tokenUsage: {
        input: number;
        output: number;
    };
    startTime: number;
    constructor(config: RuntimeConfig);
    /**
     * 执行 Agent — 入口
     *
     * @param message 统一消息
     * @param [opts] 策略特定选项 (如 FanOut 的 items)
     */
    execute(message: AgentMessage, opts?: Record<string, unknown>): Promise<AgentResult>;
    /**
     * 核心 ReAct 循环。Strategy 调用此方法执行实际的 LLM + Tool 交互。
     *
     * 引擎级能力通过可选参数注入:
     *   - contextWindow → 三级递进压缩 + 动态工具结果限额
     *   - tracker → ExplorationTracker 阶段管理 + Nudge + Graceful exit
     *   - trace → ActiveContext 推理链记录
     *   - memoryCoordinator → 缓存/动态提示/观察记录
     *   - sharedState → 提交去重 { submittedTitles, submittedPatterns }
     *   - source → 'user' | 'system' (影响错误恢复 + 强制摘要行为)
     *
     * 向后兼容: 以上参数均为可选。不提供时退化为原始裸循环。
     *
     * @param prompt 用户/系统提示
     * @param [opts.history] 对话历史
     * @param [opts.context] 额外上下文
     * @param [opts.capabilityOverride] 临时覆盖 capability (Pipeline 阶段用)
     * @param [opts.budgetOverride] 临时覆盖 budget
     * @param [opts.systemPromptOverride] 完全覆盖系统提示词 (Bootstrap 阶段专用)
     * @param [opts.onToolCall] 本轮独立的工具调用钩子，优先于 runtime 级
     * @param [opts.contextWindow] 上下文窗口管理器
     * @param [opts.tracker] ExplorationTracker 实例
     * @param [opts.trace] ActiveContext 实例
     * @param [opts.memoryCoordinator] MemoryCoordinator 实例
     * @param [opts.sharedState] 共享状态 { submittedTitles, submittedPatterns }
     * @param [opts.source] 'user' | 'system'
     * @param [opts.toolChoiceOverride] 首轮 toolChoice 覆盖 ('required'/'auto'/'none')
     *   首轮强制 LLM 生成 tool call（LLM 自行决定调哪个工具、传什么参数）。
     *   这不是替 LLM 做决定，而是告诉 LLM "你必须调用某个工具"。
     *   仅在第一轮生效，后续轮次恢复正常 toolChoice 逻辑。
     */
    reactLoop(prompt: string, opts?: ReactLoopOpts): Promise<{
        reply: string;
        toolCalls: any[];
        tokenUsage: {
            input: number;
            output: number;
        };
        iterations: number;
    }>;
    /** 中止执行 */
    abort(reason?: string): void;
    /**
     * 注入内存文件缓存（bootstrap 场景: allFiles 已在内存中，避免重复磁盘读取）
     * @param files [{ relativePath, content, name }]
     */
    setFileCache(files: FileCacheEntry[] | null): void;
    /** 项目根目录 (供 ToolExecutionPipeline 等访问) */
    get projectRoot(): string;
    /** 文件缓存 (供 ToolExecutionPipeline 等访问) */
    get fileCache(): FileCacheEntry[] | null;
    /** 发送进度事件 (公开方法，供 ToolExecutionPipeline 中间件调用) */
    emitProgress(type: string, data?: Record<string, unknown>): void;
}
export default AgentRuntime;