package com.gzzm.lobster.llm;

/**
 * CancelReason —— 取消原因 / Cancellation reason classification.
 *
 * <p>关键语义区分：只有 {@link #UPSTREAM}（上游模型失败）允许 LlmRuntime fallback 到
 * 下一个备选模型；其他三类都是用户意图或系统预算决策，必须硬终止，不得重试。
 *
 * <p>Only {@link #UPSTREAM} allows model fallback; the other three are
 * user/system decisions and must hard-abort.
 *
 * @see StreamingSession
 * @see RunCancelledException
 */
public enum CancelReason {

    /** 用户主动取消（ESC / stop button） —— 绝不 fallback。 */
    USER,

    /** run 级 deadline 到期 —— 绝不 fallback。 */
    TIMEOUT,

    /** token / 费用预算耗尽 —— 绝不 fallback。 */
    BUDGET,

    /** 上游模型异常（网络 / 5xx / parse error） —— 允许 fallback。 */
    UPSTREAM
}