/**
 * 会话消息队列的共享领域模型：类型、快照合并规则与中文文案。
 *
 * 这里是**单一定义处**：AgentSession 的状态机、agent-react 与内置 Web 的队列 UI
 * 都只用这一份判定，避免"能不能编辑 / 旧快照要不要覆盖"各写一遍后各自演进。
 * 服务端语义见 issue #2529 与 local://frontend-queue-contract.md。
 */
/** 等待消息的服务端生命周期状态。 */
export type QueuedMessageStatus = "pending" | "delivering" | "claimed" | "consumed" | "cancelled";
/** 队列里的一条等待消息；权威快照只包含 pending（等待执行）与 delivering（等待接收）。 */
export interface QueuedMessage {
    id: string;
    content: string;
    position: number;
    version: number;
    status: QueuedMessageStatus;
    created_at: string;
    updated_at: string;
    /** 立即补充指向的当前运行 id；普通等待条目没有。 */
    target_run_id?: string;
    /** 领取或投递失败的原因。 */
    error?: string;
}
/** 服务端权威队列快照。`revision` 单调递增，客户端据此丢弃过期快照。 */
export interface SessionQueueSnapshot {
    session_id: string;
    revision: number;
    paused: boolean;
    pause_reason: string | null;
    items: QueuedMessage[];
}
/**
 * 还没有拿到服务端快照时的占位。
 *
 * `session_id` 为空表示"身份未知"：`shouldApplySnapshot` 会跳过会话身份校验、
 * 只比较 revision，这样第一份快照（哪怕 revision 为 0 的暂停态）也能装进来。
 */
export declare const EMPTY_SESSION_QUEUE: SessionQueueSnapshot;
/**
 * 队列命令的 ack 线格式。
 *
 * `conflict` 表示乐观并发或状态校验失败，此时快照字段是服务端最新值，客户端必须
 * 据此刷新本地并保留用户草稿；`error` 时快照字段可能缺失（如鉴权失败），此时只报错、
 * 不改动本地队列。
 */
export interface QueueAck {
    /** `queued` 只出现在 `chat:send` 的运行中改道：消息已进等待队列，不是失败。 */
    status: "ok" | "conflict" | "error" | "queued";
    /**
     * 只有 `queued` 会带：服务端判定这次改道时该会话是否有运行。
     * 客户端据此对齐流式标记，不用自己的猜测。
     */
    running?: boolean;
    message?: string | null;
    session_id?: string;
    revision?: number;
    paused?: boolean;
    pause_reason?: string | null;
    items?: QueuedMessage[];
}
/** 解析后的队列操作结果；UI 只看这一个结构。 */
export interface QueueOperationResult {
    ok: boolean;
    conflict: boolean;
    /** 服务端快照；缺失时为 null，调用方不得据此清空本地队列。 */
    snapshot: SessionQueueSnapshot | null;
    message: string | null;
    /**
     * 服务端给的机器可读失败原因（如 `owner_timeout` / `route_broken` / `owner_busy`），
     * 供调用方决定要不要重试；`message` 是可以直接展示的业务文案。
     */
    code?: string;
}
/** 判定一份载荷是不是完整的权威队列快照（广播事件用）。 */
export declare function isSessionQueueSnapshot(value: unknown): value is SessionQueueSnapshot;
/**
 * 是否用 `next` 覆盖 `current`。
 *
 * 规则只有两条：会话身份必须一致（还没拿到过快照时不校验），且 revision 必须严格
 * 更新——相等或更旧一律不采纳，乱序到达的旧快照不会把新状态顶回去。
 */
export declare function shouldApplySnapshot(current: SessionQueueSnapshot | undefined, next: SessionQueueSnapshot): boolean;
/**
 * 解析 `emitWithAck` 的返回值。
 *
 * - `ok` / `queued` / `conflict` 且能解析成快照 → `snapshot` 有值；
 * - `queued` → `ok=true`：`chat:send` 在运行中改道进了等待队列，调用方要撤掉乐观消息；
 * - `conflict` → `ok=false, conflict=true`（快照可能仍缺失，调用方按 null 处理）；
 * - `error` 或结构不合法 → `ok=false, conflict=false`，`message` 为服务端文案或兜底。
 */
export declare function parseQueueAck(response: unknown, fallbackSessionId: string): QueueOperationResult;
/** 等待中的条目才能改正文；已经交给运行或开始执行的条目不再可编辑。 */
export declare function canEditQueuedMessage(item: QueuedMessage): boolean;
/** 等待中的条目才能删除。 */
export declare function canCancelQueuedMessage(item: QueuedMessage): boolean;
/**
 * 能否立即补充。条目本身必须是等待中的；"会话是否正在运行"由调用方判断——
 * 服务端会在没有可接收补充的任务时返回冲突。
 */
export declare function canDeliverQueuedMessage(item: QueuedMessage): boolean;
/** 面向前端展示的状态文案；已离开队列视图的状态没有文案。 */
export declare function queuedMessageStatusLabel(status: QueuedMessageStatus): string;
/** 暂停原因文案；未知原因原样透出，没有原因返回 null。 */
export declare function queuePauseReasonLabel(reason: string | null | undefined): string | null;