hyacinth-ai 0.9.6

package/dist/orchestrator/loop.d.ts

@@ -0,0 +1,331 @@
+import type { Provider } from '../provider/interface.js';
+import type { ProviderRouter } from '../provider/router.js';
+import type { ModelRouter } from '../provider/model-router.js';
+import type { ModelRole } from '../provider/model-router.js';
+import { LayeredContextComposer } from '../context/composer.js';
+import { CompressorOrchestrator } from '../context/compressor.js';
+import type { ToolExecutor } from '../tools/executor.js';
+import type { ToolRegistry } from '../tools/registry.js';
+import type { ConversationStore } from '../memory/conversation.js';
+import type { EventStore } from '../memory/events.js';
+import type { StatsManager } from '../memory/stats.js';
+import type { SummaryStore } from '../memory/summary.js';
+import { LLMOrchestrator } from './planner.js';
+import type { SkillRegistry } from '../skills/registry.js';
+import type { MCPBridge } from '../mcp/bridge.js';
+import type { DependencyAnalyzer } from '../dependency/analyzer.js';
+import type { AgentRegistry } from '../agents/registry.js';
+import type { LifecycleSupervisor } from '../lifecycle/supervisor.js';
+import { ImageStore } from '../multimodal/index.js';
+import type { MachineRegistry } from '../machine/registry.js';
+import { HeartbeatScheduler } from '../schedule/scheduler.js';
+import type { RuntimeConfigCenter } from '../runtime/config-center.js';
+import type { ComposeStrategy } from '../context/precision/index.js';
+import type { IContextRouter } from '../context/router.js';
+import type { ToolBundleRegistry } from '../tools/bundle-registry.js';
+import type { TurnRecorder } from '../rollback/turn-recorder.js';
+/** Decoupled output interface — CLI and TUI implement this */
+export interface OutputHandler {
+    onText?(content: string): void;
+    onThinking?(content: string): void;
+    onToolUse?(name: string, inputSummary: string, toolId?: string): void;
+    onToolResult?(content: string, isError: boolean, toolId?: string): void;
+    onDiff?(toolId: string, filePath: string, diffLines: Array<{
+        kind: string;
+        text: string;
+    }>): void;
+    onStatus?(message: string, level: 'info' | 'warn' | 'error'): void;
+    onTurnStart?(): void;
+    onFlush?(): void;
+    /** 用户中断：清理动画和临时状态 */
+    onInterrupt?(): void;
+    /** Request user permission for dangerous tool execution. Returns 'yes' (once), 'no' (deny), 'always' (add to allowlist), or 'aor' (unrestricted — skip all future checks). */
+    onPermissionRequest?(toolName: string, input: Record<string, unknown>): Promise<'yes' | 'no' | 'always' | 'aor'>;
+    /** Ask the user structured questions with options. Each question supports multi-select and custom input.
+     *  Returns a JSON string mapping question index → selected answers. */
+    onAskUser?(questions: AskUserQuestion[]): Promise<string>;
+}
+/** A single question for ask_user */
+export interface AskUserQuestion {
+    question: string;
+    header?: string;
+    options?: string[];
+    multiSelect?: boolean;
+    customInput?: boolean;
+}
+/** Per-turn cache hit statistics */
+export interface CacheTurnRecord {
+    turn: number;
+    timestamp: string;
+    inputTokens: number;
+    outputTokens: number;
+    hitTokens: number;
+    missTokens: number;
+    hitRate: number;
+}
+/** Info available to output handlers after each turn */
+export interface TurnInfo {
+    turnCount: number;
+    maxTurns: number;
+    tokensUsed: number;
+    maxContextTokens: number;
+    planStepsTotal?: number;
+    planStepsDone?: number;
+    sessionId: string;
+    compressCount: number;
+    /** 缓存命中 tokens（仅 DeepSeek/OpenAI 等支持返回，其他厂商为 undefined） */
+    cacheHitTokens?: number;
+    /** 缓存未命中 tokens */
+    cacheMissTokens?: number;
+    /** 当前轮次缓存命中率 (0-100)，不支持的 provider 为 undefined */
+    cacheHitRate?: number;
+    /** 所有轮次的缓存记录（用于分析缓存稳定性） */
+    cacheHistory?: CacheTurnRecord[];
+}
+export declare function imageToAscii(imagePath: string, maxWidth?: number): Promise<{
+    text: string;
+    width: number;
+} | null>;
+/**
+ * AgentLoop — 串联所有模块的完整 Agent 主循环
+ *
+ * 核心流程：compose -> LLM -> parse -> tool -> compose 的循环
+ *
+ * 通过 OutputHandler 接口解耦输出：
+ * - 传 null → 无输出（静默模式）
+ * - 传实现 → 输出到 TUI / CLI / 日志 等任意目标
+ */
+export declare class AgentLoop {
+    private provider;
+    private contextComposer;
+    private compressor;
+    private toolExecutor;
+    private toolRegistry;
+    private conversationStore;
+    private eventStore;
+    private statsManager;
+    private sessionDir;
+    private summaryStore;
+    private maxTurns;
+    private maxContextTokens;
+    private skillRegistry?;
+    private mcpBridge?;
+    private dependencyAnalyzer?;
+    private personaDir?;
+    private providerRouter?;
+    private modelRouter?;
+    private turnRecorder?;
+    private abortController;
+    private interrupted;
+    /** 串行化锁：确保 run() 不会并发执行 */
+    private _runMutex;
+    private recentToolNames;
+    private currentSummary;
+    private orchestrator;
+    private activePlan;
+    private agentRegistry?;
+    private outputHandler;
+    private compressCount;
+    private needsAggressiveCompress;
+    private cacheHitTokens;
+    private cacheMissTokens;
+    private cacheTurns;
+    private logCacheHits;
+    private currentTurn;
+    /** 公开只读访问器 — 供 TurnRecorder / RollbackTool 等查询当前回合号 */
+    get turnNumber(): number;
+    private lastSavedSummary;
+    private pendingImpactInfo;
+    private requestId;
+    private logger;
+    private flowRegistry;
+    /** 旁路Agent 管理器（factory 注入） */
+    bypassManager?: import('../bypass/manager.js').BypassManager;
+    /** 本轮用户消息的旁路注入缓存（preTurn 首轮产出，后续迭代复用） */
+    private _bypassInjections?;
+    private activeProvider?;
+    private scheduler;
+    private schedulerInitialized;
+    /** 定时任务触发后待注入对话的通知 */
+    pendingTaskNotifications: Array<{
+        name: string;
+        firedAt: string;
+    }>;
+    /** 当前正在执行的定时任务名（供 TUI 显示上下文），run 前设置，run 后清除 */
+    pendingTaskName: string | null;
+    /** 知识库状态引用（factory 注入） */
+    kbState: {
+        lastQuery: string;
+    } | null;
+    /** 图片索引存储（会话级） */
+    readonly imageStore: ImageStore;
+    /** 待注入图片队列（view_image 工具填充，下次 compose 前消费） */
+    readonly pendingImageInjections: Array<{
+        imgId: string;
+        data: string;
+        media_type: string;
+    }>;
+    /** 渠道预取图片（渠道层在 run() 前写入，_runInternal 一次性消费） */
+    channelImages: Array<{
+        data: string;
+        media_type: string;
+    }> | null;
+    /** Fallback 通知（onFallback 回调写入，runTurn 一次性消费后清空） */
+    pendingFallbackInfo: string | null;
+    /** 上下文组装策略（精确模式切换用，deprecated：新代码使用 activeRouter） */
+    composeStrategy: ComposeStrategy | null;
+    /** 当前激活的上下文路由器，初始化为 NormalRouter，首次 syncRouter() 时同步到全局状态 */
+    activeRouter: IContextRouter;
+    /** Whether any tools were executed inline during the current stream */
+    private inlineToolExecuted;
+    /** Stores results from inline tool execution, keyed by tool_use_id */
+    private inlineToolResults;
+    /** Tools that require user confirmation before execution */
+    private dangerousTools;
+    /** Tools whitelisted by user (skip confirmation — session-level, from 'always' response) */
+    private allowlistTools;
+    /** AOR (Absence of Restriction): skip all future permission checks for this session */
+    private unrestrictedTools;
+    /** Allowed bash commands (glob pattern matched, from config) */
+    private allowedCommands;
+    private configCenter?;
+    private contextDirty;
+    private loopGuard;
+    private resultBuffer;
+    private bundleRegistry?;
+    private gitManager;
+    private switchingProvider;
+    private bypassProvider?;
+    private lastContextTokens;
+    private needsCompression;
+    private pendingCompression;
+    private lifecycleSupervisor;
+    private previousProviderWasLocal;
+    /** 当前 AgentLoop 的 thinking 状态（per-session 隔离） */
+    private thinkingEnabled;
+    private thinkingEffort;
+    constructor(provider: Provider, contextComposer: LayeredContextComposer, compressor: CompressorOrchestrator, orchestrator: LLMOrchestrator, toolExecutor: ToolExecutor, toolRegistry: ToolRegistry, conversationStore: ConversationStore, eventStore: EventStore, statsManager: StatsManager, sessionDir: string, summaryStore: SummaryStore, maxTurns: number | undefined, maxContextTokens: number, outputHandler?: OutputHandler | null, skillRegistry?: SkillRegistry | undefined, mcpBridge?: MCPBridge | undefined, dependencyAnalyzer?: DependencyAnalyzer | undefined, agentRegistry?: AgentRegistry, personaDir?: string | undefined, flowRegistry?: MachineRegistry, providerRouter?: ProviderRouter | undefined, dangerousTools?: Set<string>, allowlistTools?: Set<string>, configCenter?: RuntimeConfigCenter, modelRouter?: ModelRouter | undefined, turnRecorder?: TurnRecorder | undefined);
+    /**
+     * 中断当前运行：设置 interrupted 标志，中止 Provider 请求，
+     * 并通过 OutputHandler 通知上层
+     */
+    interrupt(): void;
+    /** Get current turn/mode info for status display */
+    getTurnInfo(turnCount: number, tokensUsed: number): TurnInfo;
+    private getRecentToolCallNames;
+    /** Bootstrap Flow 是否活跃（供 CLI/TUI 判断是否需要发送空消息启动引导） */
+    get bootstrapActive(): boolean;
+    /** 就地切换到指定 session，无需重启进程 */
+    switchSession(newSessionDir: string): Promise<void>;
+    /** 设置调度器 */
+    setScheduler(scheduler: HeartbeatScheduler): void;
+    /**
+     * 陪伴模式：从 JSONL 中移除本轮工具调用完整回合。
+     * 找到最后一条 user 文本消息，从它开始截断文件——
+     * 整个工具调用回合（user → tool_use → tool_result → 跟进文本）都不留痕迹。
+     */
+    private removeLastRoundFromJsonl;
+    /**
+     * 陪伴模式工具调用清理：
+     * - companion_mode 切换 → 剥离工具痕迹，保留 LLM 文本
+     * - 其他工具 → 整轮砍掉（原有行为）
+     * - 找不到触发消息（跨 session） → 处理整个文件
+     */
+    private cleanCompanionJsonl;
+    /**
+     * 陪伴模式定时任务专用：只移除触发提示词和工具链，保留模型自然回复。
+     * 效果：模型看起来像是"主动"搭话，而非响应系统指令。
+     */
+    private removeTriggerFromJsonl;
+    /**
+     * 同步全局 Router 到当前 loop。
+     * 每轮 runTurn 开头调用，所有渠道的 loop 自动切换会话和上下文行为。
+     */
+    syncRouter(): Promise<void>;
+    /** 获取调度器 */
+    getScheduler(): HeartbeatScheduler | null;
+    /** 添加定时任务 */
+    addScheduledTask(name: string, scheduleType: 'daily', time: string): Promise<void>;
+    /** 注入 LifecycleSupervisor，用于运行时切换 provider 时自动管理本地模型进程 */
+    setLifecycleSupervisor(supervisor: LifecycleSupervisor): void;
+    /** 注入工具包注册表（在 factory.ts 中紧接 AgentLoop 创建后调用） */
+    setBundleRegistry(registry: ToolBundleRegistry): void;
+    /** 运行时替换 outputHandler（用于 server 模式按请求切换流式输出） */
+    setOutputHandler(handler: OutputHandler): void;
+    /** 获取当前 active Provider（考虑 Router 路由） */
+    getActiveProvider(): Provider;
+    /** 运行时切换 KVCache 隔离 ID（模式切换用：普通↔陪伴） */
+    setActiveUserId(userId: string): void;
+    /** 由 factory 注入：旁路Agent 共享的 Provider 实例 */
+    setBypassProvider(provider: Provider): void;
+    /** 运行时切换旁路Agent 的 KVCache 隔离 ID（与主Agent 同步切换） */
+    setBypassUserId(userId: string): void;
+    /** 切换 Provider 路由模式 */
+    toggleProvider(): void;
+    /** 切换到指定名称的 Provider */
+    /** 注册新 Provider（用于 switch_provider 工具带 api_key 动态注册） */
+    registerProvider(name: string, provider: Provider): void;
+    switchProvider(providerName: string): Promise<void>;
+    /** 从 RuntimeConfigCenter 中的配置 + 环境变量动态创建 Provider */
+    private tryCreateProviderFromConfig;
+    /** 订阅 RuntimeConfigCenter 变更，让 update_config 即时生效 */
+    subscribeConfig(): void;
+    /** 切换回自动路由模式 */
+    switchToAutoRoute(): void;
+    /** 获取 Provider 路由信息 */
+    getProviderRoutingInfo(): {
+        providerLabel: string;
+        isLocal: boolean;
+        mode: string;
+    } | null;
+    setModelSource(role: ModelRole, source: 'main' | 'local'): void;
+    getModelSources(): Record<ModelRole, 'main' | 'local'> | null;
+    /** 定时任务触发时唤醒 Agent，自动发起一轮对话 */
+    notifyTaskFired(taskName: string): Promise<void>;
+    /**
+     * 运行一轮对话（从用户输入到 Agent 停止或调用工具后继续）
+     */
+    run(userInput: string): Promise<void>;
+    /**
+     * run() 的内部实现，由串行化锁保护
+     */
+    private _runInternal;
+    /**
+     * 内部方法：执行一轮 LLM 调用
+     */
+    private runTurn;
+    /**
+     * 检测本轮文本输出是否陷入循环。
+     * 在 assistant 消息和工具结果全部写入 conversation 后调用，
+     * 确保反射消息位于本轮对话末尾，下一轮 compose 时 LLM 能正确感知上下文。
+     */
+    private checkTextLoop;
+    /** Check if a bash command matches any allowedCommands glob pattern */
+    private isCommandAllowed;
+    /**
+     * 内部方法：执行工具调用并写回结果
+     */
+    private executeTools;
+    /**
+     * Execute a single tool inline during the SSE stream.
+     * Stores the result for later conversation append; fires onToolResult for real-time feedback.
+     */
+    private executeSingleToolInline;
+    /**
+     * Flush inline tool results to the conversation store and run dependency analysis.
+     * Called after the assistant message has been appended to maintain correct message ordering.
+     */
+    private flushInlineToolResults;
+    /**
+     * 回收已处理图片：将非最后一轮的 image base64 替换为占位符。
+     *
+     * - 保留最后一条 user 消息中的图片（模型当前轮还在看）
+     * - 更早的图片 → 用模型后续的回复作为描述，替换为纯文本占位符
+     * - 无模型描述时 → 用元信息占位符
+     * - 替换后的占位符包含 img_id，模型可通过 view_image 重新查看
+     */
+    recycleProcessedImages(): Promise<void>;
+    /** 释放资源：停路由器（含 WorldEngine）+ 停调度器 */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=loop.d.ts.map