/**
 * 多 Bot 协作回合协议。
 *
 * 这里故意只使用平台稳定用户 ID。每个 Bot 的本地 users.id 可能不同，
 * 不能把本地短号当成跨设备协议字段。
 */
export type CollabStatus = "running" | "finished" | "stopped" | "blocked";
export type CollabParticipant = {
    platformId: string;
    name?: string;
};
export type CollabTurnDecision = {
    action: "handoff";
    to: string;
} | {
    action: "finish";
};
export type CollabState = {
    /** 从启动消息稳定推导的短链号；跨设备协议字段。 */
    chainId: string;
    scopeKey: string;
    chatId: string;
    threadId?: string;
    participants: CollabParticipant[];
    currentBotId: string;
    /** 当前 Bot 的回合编号，从 1 开始。 */
    turn: number;
    status: CollabStatus;
    startPlatformMsgId: string;
    lastPlatformMsgId?: string;
    lastRunId?: string;
};
export type CollabMention = {
    platformUserId?: string;
    name?: string;
    isBot?: boolean;
    isApp?: boolean;
};
export type CollabHistoryMessage = {
    senderPlatformId?: string;
    senderIsBot?: boolean;
    platformMsgId?: string;
    contentText?: string;
    mentions?: CollabMention[];
};
export type CollabDecisionErrorCode = "missing" | "invalid-action" | "missing-target" | "unknown-target" | "self-target" | "not-current" | "not-running";
export type CollabDecisionValidation = {
    ok: true;
    decision: CollabTurnDecision;
} | {
    ok: false;
    code: CollabDecisionErrorCode;
    message: string;
};
export type CollabMessageProtocol = {
    chainId: string;
    turn: number;
    finished: boolean;
};
/** 启动消息是唯一跨设备共同可见的链根，短号只用于消息展示和快速匹配。 */
export declare function collabChainId(startPlatformMsgId: string): string;
/** 协作协议由 Engine 追加到正文末尾，Agent 输出不得自行承担该职责。 */
export declare function renderCollabProtocol(protocol: CollabMessageProtocol): string;
/** 取正文中最后一条协议；卡片 footer 可能在它后面，因此不要求字符串绝对结尾。 */
export declare function parseCollabProtocol(text: string): CollabMessageProtocol | undefined;
/** 防止 Agent 回显或伪造协议行；唯一可信来源是 Engine。 */
export declare function stripCollabProtocols(text: string): string;
/** 按平台消息中的出现顺序提取唯一的应用/Bot 参与者。 */
export declare function collectCollabParticipants(mentions: readonly CollabMention[] | undefined): CollabParticipant[];
/** 判断一条人类消息是否显式启动了多 Bot 协作。 */
export declare function isCollabStartMessage(message: CollabHistoryMessage): boolean;
/** 为第一个被 @ 的 Bot 创建协作状态；其他被 @ 的 Bot 只保存这条消息。 */
export declare function createCollabState(input: {
    scopeKey: string;
    chatId: string;
    threadId?: string;
    startPlatformMsgId?: string;
    mentions?: readonly CollabMention[];
    currentBotId: string;
}): CollabState | undefined;
/** 严格校验 Agent 提交的回合动作。 */
export declare function validateCollabTurnDecision(raw: unknown, state: CollabState, currentBotId: string): CollabDecisionValidation;
/** 在消息发送成功后推进本地状态。发送失败时不要调用此函数。 */
export declare function applyCollabDecision(state: CollabState, decision: CollabTurnDecision, platformMsgId?: string, runId?: string): CollabState;
/** 用 Engine 的结构化动作生成一条全员可收到的协议消息。
 * @ 列表第一个 Bot 是下一棒；finish 时没有执行者，按原参与顺序广播收尾。
 */
export declare function appendCollabProtocolMessage(content: string, state: CollabState, decision: CollabTurnDecision, options?: {
    requester?: CollabParticipant;
}): string;
/**
 * 从本地缓存的消息链重建协作状态。
 * 这用于另一台 Bot 设备收到真实 at 后恢复，不依赖共享数据库或共享内存。
 */
export declare function rebuildCollabState(input: {
    scopeKey: string;
    chatId: string;
    threadId?: string;
    messages: readonly CollabHistoryMessage[];
}): CollabState | undefined;
/** 给 Agent 的内部回合上下文。稳定 ID 只供命令使用，不应写入用户正文。 */
export declare function buildCollabTurnContext(state: CollabState, currentBotId: string): string;