/**
 * 模块: 上下文守护 (Context Watchdog) v6.5.3
 *
 * 解决场景：长会话不知不觉吃满 ctx 窗口 → 龙虾原生在 overflow **错误发生后**才
 * 走 model-fallback；用户体验是"突然报错"或"突然丢上下文"，没有预警。
 *
 * 龙虾原生已有（不复制，红线 #2）：
 *   - isContextOverflowError / isLikelyContextOverflowError 错误检测
 *   - model-fallback.ts ctx overflow 触发后做 model fallback
 *   - /compact 命令 + before_compaction / after_compaction hook
 *
 * 龙虾原生没有的（本模块补）：
 *   1. **会话级 token 累加追踪**：hook llm_output 拿 usage 实时累加到 sessionKey
 *   2. **三阶预警**（70%/85%/95%）：在 overflow **之前** 注入 prependContext，
 *      让 LLM 主动收尾 / 走 /compact / 切大 ctx 模型
 *   3. **after_compaction 自动归零**：龙虾刚 compact 完，session 重置 token 计数
 *   4. **enhance_ctx_status 工具**：LLM 主动查当前用量
 *
 * 非侵入式保证：
 *   - 零 child_process / 零新 npm 依赖
 *   - 不修龙虾核心 / 不复制 model-fallback / 不抢龙虾 routing 决策
 *   - 仅观察 + 提醒（通过 prompt supplement）；仅在 ctx 逼近上限（默认 95%）时才强切大 ctx 模型防 overflow
 *
 * 实测痛点（2026-05-11）：
 *   用户长会话 + 跨日续接 + 多轮工具调用，token 累计到 180K+ 还没主动 /compact，
 *   突然遇到 200K 上限报错。三阶预警让 LLM 在 70% 就开始 awareness，
 *   85% 强烈建议收尾，95% 命令式停手。
 */
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
import type { ContextWatchdogConfig } from "../types.js";
/**
 * v6.6.7: 用户配置驱动的候选 model — 修 v6.6.x 强切硬编码 LONG_CTX_CANDIDATES 的设计错误。
 *
 * 用户截图明确指出："你应该看 openclaw.json 里面配置的几个模型，按照这个里面的配置切换"
 *
 * 之前问题：LONG_CTX_CANDIDATES_DEFAULT 硬编码 claude/gemini/kimi——用户机器上没装
 * 这些 provider（实际是 deepseek + minimax），三重过滤后返 null 不强切（v6.6.4 已修
 * 错切的 bug，但还是没真正切——浪费"P0-1 真实切换"的设计）。
 *
 * 新设计：从 cfg.agents.defaults.model.{primary, fallbacks} 读用户配置的 model 列表 →
 * cfg.models.providers[<provider>].models[<bareId>] join 拿 contextWindow + cost →
 * 按 ctx 降序（或 cost 升序）选第一个 ctx 比当前大的。
 */
export interface UserModelCandidate {
    fullId: string;
    bareId: string;
    provider: string;
    contextWindow: number;
    costInPerM?: number;
    costOutPerM?: number;
}
export declare function registerContextWatchdog(api: OpenClawPluginApi, config?: ContextWatchdogConfig): void;