Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

96.8 KB
Raw Blame
/**
 * slack-hook-protocol/types.ts
 * ---------------------------------------------------------------------------
 * hook server <-> desktop 双工任务协议 v1 的全部类型定义。
 *
 * 协议模型(四幕):
 *   1. 连接自报家门: hello(desktop -> server, 声明工作区别名) / welcome / ping / pong
 *   2. 派活:        task.dispatch(server -> desktop) -> task.ack(立即三态应答)
 *   3. 干活:        无消息 —— 铁律「同 externalKey 同 session」由 desktop 侧保证
 *   4. 交差:        turn.end(desktop -> server, 结果回传)
 *
 * 关键约定:
 *   - externalKey 对协议是不透明字符串, 由 hook server 的 provider 生成
 *     (格式约定 `<providerId>:...`), desktop 只拿它查 session 映射并原样回传。
 *   - workspace 是别名(alias), 本地绝对路径只存在于 desktop, 永不过网线。
 *   - sessionId 仅「接管已有桌面会话」时由 server 显式指定; 普通流程不填,
 *     ack / turn.end 中回传仅作记录与调试, 不参与路由。
 *   - 可靠性: requestId 幂等(重投不重跑, 只回放上次 ack); 断线重连后
 *     server 重投未 ack 任务, desktop 补发未送达的 turn.end。
 *
 * v2 增量(版本号不变 —— type 为开放集合, 老端收到未知类型丢帧不断连):
 *   5. 绑定:   bind.start(desktop 发起) / bind.update(server 推状态) / bind.revoke
 *      —— 中心部署下「Slack 用户 ↔ 设备」的建立与解除。阶段 4 起改走
 *      Sign in with Slack(OIDC): desktop 发空 bind.start, server 签发授权
 *      链接经 bind.update(state=pending, authorizeUrl)回推, 用户在系统浏览器
 *      完成 Slack 授权后 server 回调建链, 再推 confirmed。协议只承载 desktop
 *      侧的发起与状态同步, 身份确认在 server 与 Slack 之间完成。
 *   6. 问答:   query.request(server -> desktop) / query.response —— /bind /model
 *      /effort 等指令触发时实时拉取工作区 / 模型清单, 不用连接期快照。
 *   7. 取消:   task.cancel(server -> desktop) —— /stop 中断在跑任务,
 *      desktop 以 turn.end(status=cancelled) 收口。
 *   8. 归档:   session.archive(server -> desktop) —— 私聊 /new 换代后通知
 *      desktop 归档旧代会话(按 externalKey 查绑定), 列表不再显示; 无绑定 /
 *      会话不存在时静默忽略(幂等)。
 *
 *   9. 进度:   turn.progress(desktop -> server) —— turn 执行中的渲染快照。
 *      历史: 初版只发裸累积文本, 体验不佳一度下线; 现已复活, desktop 侧
 *      合成「过程区时间线 + 部分正文」的完整快照(节流), server 侧以
 *      占位消息 + chat.update 原地刷新呈现。旧版 desktop 仍发裸文本快照,
 *      新 server 同样渲染(向后兼容); 旧 server 收到新帧静默丢弃(无害)。
 *
 *   10. 交互:  interaction.request(desktop -> server) / interaction.decision
 *      (server -> desktop) / interaction.cancel(desktop -> server) ——
 *      turn 执行中 agent 发起的用户交互(模型主动提问 AskUserQuestion /
 *      计划审阅 plan_review)以按钮卡片形式转发到 Slack thread。设计原则:
 *      **决策语义全部留在 desktop**(它持有 maker-core 的原始
 *      InteractionRequest 与按钮->决策映射), server 是"哑渲染器"——
 *      收到 request 渲染卡片, 按钮按压只回传 buttonId; desktop 侧对每个
 *      交互设超时, 超时/收口时按安全默认自决并发 cancel 让 server 改写
 *      卡片。旧 server 收到 request 丢帧不断连 -> desktop 超时默认继续,
 *      任务不会卡死(向后兼容)。权限审批(permission)已纳入本通道: server
 *      可经 dispatch options.permissionMode 为新建会话指定权限档(见
 *      TaskDispatchOptions), 非 bypass 档下 agent 的权限请求同样以按钮卡
 *      转发(允许一次 / 本会话总是允许 / 拒绝), 超时安全默认为拒绝。
 *
 *   11. 偏好:  prefs.get / prefs.set(desktop -> server) / prefs.state
 *      (server -> desktop) —— server 侧 user_prefs(按 (Slack 用户, 工作目录)
 *      的 agent/model/effort/permission 偏好, /model 卡的数据正本)的远程
 *      读写通道: desktop 设置页是同一份数据的编辑器。prefs.state 是全量
 *      快照, 既作为 get/set 的应答(replyTo 回显请求 id), 也在 /model 卡
 *      写入后主动推送(replyTo null; 设备离线静默丢, desktop 重连自拉)。
 *      旧 server 收到 prefs.get 丢帧不断连 -> desktop 侧超时降级为
 *      "服务器版本过旧"提示; 旧 desktop 收到主动 prefs.state 同样丢帧无害。
 *
 *   12. 工具:  tool.request(desktop -> server) / tool.response(server ->
 *      desktop) —— desktop 会话内 agent 调用 server 侧 Slack 网关工具
 *      (server 以绑定用户托管的 user token 调 Slack 官方 MCP / Web API)。
 *      方向与 query.* 相反: desktop 是请求方(pending map + 超时在 desktop
 *      侧), server 收到即执行并以 tool.response(replyTo 回显 requestId)
 *      应答。tool 名是开放集合(server 不认识回 UNKNOWN_TOOL), 错误一律
 *      结构化 {code, message} —— desktop 按 code 分支, 不解析文案(规则 9)。
 *      能力协商: 支持本帧族的 server 在 welcome.features 里带
 *      HOOK_FEATURE_SLACK_TOOLS; 旧 server 收到 tool.request 丢帧不断连,
 *      desktop 侧靠 feature 缺席短路 + 超时兜底(SERVER_TOO_OLD)。
 *
 *   13. 多 workspace 绑定(multi-team): 一台设备可同时持有多个
 *      (teamId, slackUserId) 绑定 —— 每个 Slack workspace(team)一条, 同
 *      team 内仍一设备一身份。能力协商双向: desktop 在 hello.features 带
 *      HOOK_FEATURE_MULTI_TEAM 声明自己会消费多绑定帧, server 在
 *      welcome.features 带同名标识声明支持; 任一侧缺席则整体回落单绑定
 *      行为(server 对旧 desktop 保持"跨 team 顶替"旧语义, 新 desktop 对
 *      旧 server 收起添加入口)。增量帧面:
 *        - bind.state(server -> desktop): 绑定全量快照(权威列表), 连接
 *          建立与任何绑定变化(新增/解除/被顶)后推送; 旧 desktop 不认识
 *          本类型, parse 拒收丢帧不断连。
 *        - bind.update 加可选 teamId: 事件帧按 team 定位(confirmed /
 *          revoked); 授权流早期(pending)团队未知, teamId 为 null。
 *        - bind.start 加可选 teamId: 给指定 team 重新授权时 pin 授权页;
 *          缺省 = 用户在 Slack 授权页自选(可绑任意新 team)。
 *        - bind.revoke 从空对象放宽为 { teamId?: string|null }: 带 team
 *          = 只解绑该 team; 空/缺省 = 解绑本设备全部(兼容老 desktop)。
 *          旧 server 对带 teamId 的帧 parse 拒收, 故 desktop 仅在 server
 *          声明 multi-team 后才发带 team 的形态。
 *        - prefs.set / prefs.state 条目 / tool.request 加可选 teamId:
 *          多绑定下偏好与网关工具的 team 归属消歧; 缺省语义 = 设备唯一
 *          绑定(多绑定时 server 拒绝猜测, 结构化报错)。
 *        - TaskSource 加 teamId / teamName: desktop 侧会话记住来源
 *          workspace(标题展示 + 工具调用默认 team)。
 *
 *   15. 生命周期通知偏好: hello.lifecycleAnnouncement 在每次建连时同步
 *      当前有效值,lifecycle.preference 在设置页切换时即时更新。server
 *      只有声明 HOOK_FEATURE_LIFECYCLE_ANNOUNCEMENT 后 desktop 才发送
 *      即时更新帧;旧 server 忽略 hello 新字段,保持既有通知行为。
 *
 *   19. Telegram 行为配置: provider.behavior.get / provider.behavior.set
 *      (desktop -> server) / provider.behavior.state(server -> desktop) ——
 *      当前仅 provider='telegram'。选择器**只认 bindingId**(不是
 *      provider.prefs.* 的 bindingId/scopeId 二选一): 行为配置(emoji 回应 /
 *      回复引用 / 群免 @ 白名单)在绑定成立前没有意义, 收窄为单选择器把
 *      "谁能读写它"的边界钉死在已确认的绑定上。set 的三个全局字段与
 *      groupActivation 共用同一套 patch 三态: 缺省(undefined)=不动、
 *      显式枚举值 = 写入 override(哪怕这个值刚好等于当前版本默认值也照写
 *      不落空 —— 用户的显式选择不能因为协议以后调整默认值而被悄悄改写)、
 *      显式 null = 清除 override、回落到当时版本的默认值。二者可同帧组合,
 *      但至少要有一项实际改动(null 也算一次真实改动)—— 空 patch 直接拒收
 *      (不同于 prefs.set, 这里没有"无副作用地静默 no-op"的容错空间)。
 *      state 携带的**始终是已解析的非空有效值**(不是原始 patch, 不会是
 *      null), 且 groupActivation 只列出偏离默认值('mention')的 chatId;
 *      bound=false 时 parse 强制整帧收敛为默认行为 + 空白名单(未绑定没有
 *      主体持有 per-chat 覆盖)。三个全局字段的默认值(DEFAULT_TELEGRAM_
 *      BEHAVIOR)与个人版桌面客户端出厂行为对齐: emojiReactions='minimal'、
 *      replyQuoteDm='off'、replyQuoteGroup='first'。见 Provider-neutral
 *      behavior 小节。
 *
 *   编号说明: 本文件头的条目号与 docs/slack-hook-protocol.md §1 的消息目录
 *      对齐(那份是正本)。中间的跳号是因为部分帧只在下方各自的类型旁说明 ——
 *      14 多 provider(provider.bind.* / provider.prefs.*, 见 Provider-neutral
 *      小节)、15 最近会话(QUERY_KINDS)、16 群消息中继(GroupMessagePayload)、
 *      17 上下线通知偏好(LifecyclePreferencePayload, 即上面那条)、19 见上。
 *
 *   18. 续跑: turn.reopen(desktop -> server) —— 一个已经以 turn.end 收口的
 *      任务, 在桌面端被用户续跑了, 把后续进展重新接回渠道里那条消息。
 *
 *      要解决的问题: turn.end(status=error)之后, 用户常在桌面端点错误横幅上
 *      的「重试」。那会在**同一个会话**里起一个新 turn(桌面端发的是一条隐藏
 *      续跑指令), 任务确实继续跑了, 但渠道那条消息永远停在失败上 —— 因为
 *      turn.progress / turn.end 都以 requestId 为键, 那一轮已经收口, 协议里
 *      也没有任何"会话级"通道能让 desktop 主动往那条消息写东西。用户看到的
 *      就是"点了重试也没反应"。
 *
 *      形态刻意用**新 requestId + reopenOf**, 而不是复用原 requestId:
 *        - server 侧幂等语义不用改(原 requestId 的 turn.end 仍是一次性的),
 *          只需把 reopenOf 指向的那条消息的位置(channel + ts)登记给新
 *          requestId, 之后的 turn.progress / turn.end 走既有代码路径;
 *        - task.cancel 能精确命中续跑轮(它带的是新 requestId);
 *        - 一次续跑再失败、再被续跑时天然形成链条, 每环都有自己的 id。
 *
 *      路由面**只含** turn.progress / turn.end / task.cancel, 刻意不含
 *      interaction.*: 续跑是用户在桌面端点出来的, 人就在桌面前, 那一轮里 agent
 *      的提问 / 计划审阅 / 权限审批由桌面本地交互面直接处理, 不绕回渠道。
 *
 *      server 侧约定:
 *        - 认不出 reopenOf(映射已过期 / 消息已删)时**静默忽略**整条帧, 并对
 *          随后到达的同 requestId 的 turn.progress / turn.end 一并忽略 ——
 *          回流失败只是回到"消息停在失败上"的现状, 不是错误, 不要报错刷屏;
 *          更一般地: 对**从未登记过**的 requestId 的 turn.progress / turn.end
 *          一律静默忽略, 不报错也不新建消息;
 *        - 认得出时把那条消息改回进行中态, 后续 progress 原地刷新、turn.end
 *          定稿。渠道里不新增消息(用户抱怨的正是那条消息不动);
 *        - 本帧必须幂等: 同一 (requestId, reopenOf) 重复登记同一个位置, 无副作用
 *          (断线重投时 desktop 可能重复发送);
 *        - 不需要为续跑 requestId 关联 interaction.* —— 那些帧不会带着它到来;
 *        - 收到一个已经绑定到别的任务的 requestId 时拒绝登记, 并把该 requestId
 *          整体隔离(后续 turn.progress / turn.end 一并忽略, 不得落到原有路由上);
 *        - **连接断开时必须收口该连接上所有"已 reopen 但没收到 turn.end"的消息**
 *          (恢复原终态或改写成「续跑中断」), 否则它们会永久停在假的"进行中"上,
 *          比本能力上线前更糟; 收口是权威的, desktop 不会在重连后补回该轮结果。
 *          但收口落笔时必须校验该消息仍归"被断开的那个连接 + 那次 reopen"所有,
 *          迟到的收口不得盖掉更新的一次 reopen 或已到达的新终态。
 *      desktop 侧约定:
 *        - 只在 server 于 welcome.features 宣告 HOOK_FEATURE_TURN_REOPEN 时
 *          才发本帧(旧 server 会 parse 拒收丢帧, 虽不断连但没有意义);
 *        - 只有"用户在桌面端显式续跑"才触发 —— 桌面端在同一会话里问的其它
 *          问题不回流, 否则渠道消息会被无关内容改写;
 *        - 记账只在进程内(app 重启后原 requestId 已随进程消失), 有 TTL;
 *        - 本帧必须排在该 turn 的任何 turn.progress / turn.end 之前, 包括"首个
 *          观察到的事件本身就是终态"的情形(否则先发的 turn.end 被当未知 id 丢弃,
 *          随后的 reopen 又把消息改成进行中, 就再没有终态帧能收口);
 *        - 续跑轮的 turn.progress / turn.end 一律直发, 不缓存也不在重连后补发 ——
 *          刻意偏离"断线重连 desktop 补发未送达 turn.end"的通用约定, 因为那条
 *          消息在断连瞬间已被 server 收口, 迟到的 turn.end 只会撞上被解绑的
 *          requestId 而丢弃, 反把"其实成功"显示成"续跑中断"。相应地, turn.end
 *          没发出去时不得再把这条消息线登记成可续跑。
 *
 *      requestId 命名空间: 续跑 requestId 由 desktop 生成、普通任务由 server
 *      生成, 却是同一张路由表的键(parse 只能校验非空且不等于 reopenOf), 所以
 *      desktop 必须用全局抗碰撞标识(UUID v4 或同等强度), server 以上面那条
 *      "拒绝并隔离已绑定 requestId"兜底。
 *
 *      已声明接受的降级: 连接在续跑轮跑完前断开时结果不回流 —— 断在装映射前是
 *      消息保持原失败态(与本能力上线前一致), 断在装映射后是 server 收口成原终态
 *      或「续跑中断」。两种都可在渠道重发。刻意不为此加 ack 往返: 回流是增强而非
 *      关键路径。注意"失败方向安全"依赖上面那条断连收口 —— 没有它, 可见状态会从
 *      "停在失败"退化成"永远进行中", 反而比不做回流更糟。
 */

/** 当前协议版本。信封 `v` 不等于本值的消息直接拒收。 */
export const HOOK_PROTOCOL_VERSION = 1;

/**
 * 单帧(JSON 序列化后)最大字符数。parse 对超长原始帧直接拒收 —— 纯粹是
 * 防 OOM 的粗防御, 不是业务限额。task.dispatch 可携带 base64 图片附件, 故取
 * 一个能容纳"几张聊天截图"的宽上限(48 MiB); 附件的精细限额(单图大小 /
 * 张数)由生产源头(provider)负责, 不依赖本值。非附件帧远小于此。
 */
export const HOOK_MAX_FRAME_CHARS = 48 * 1024 * 1024;

/** 消息类型全集(v1 七种 + v2 增量帧)。 */
export const HOOK_MESSAGE_TYPES = [
  'hello',
  'welcome',
  'ping',
  'pong',
  'task.dispatch',
  'task.ack',
  'turn.end',
  'turn.delivery',
  'turn.progress',
  'turn.reopen',
  'msg.op',
  'msg.op.result',
  'bind.start',
  'bind.update',
  'bind.revoke',
  'provider.bind.start',
  'provider.bind.cancel',
  'provider.bind.revoke',
  'provider.bind.update',
  'provider.bind.state',
  'query.request',
  'query.response',
  'task.cancel',
  'session.archive',
  'interaction.request',
  'interaction.decision',
  'interaction.cancel',
  'prefs.get',
  'prefs.set',
  'prefs.state',
  'provider.prefs.get',
  'provider.prefs.set',
  'provider.prefs.state',
  'tool.request',
  'tool.response',
  'bind.state',
  'group.message',
  'lifecycle.preference',
  'provider.behavior.get',
  'provider.behavior.set',
  'provider.behavior.state',
  'provider.commands.set',
] as const;

export type HookMessageType = (typeof HOOK_MESSAGE_TYPES)[number];

/**
 * 消息信封 —— 线上跑的每一帧都是这个形状。
 * `id` 是发送方生成的帧唯一标识(日志/去重用); 业务关联一律走 payload 里的
 * requestId, 不用 `id`。`ts` 是发送方时钟(unix ms), 仅供诊断, 不参与逻辑。
 */
export interface HookEnvelope<TType extends HookMessageType, TPayload> {
  v: number;
  type: TType;
  id: string;
  ts: number;
  payload: TPayload;
}

// ── 阶段 1: 连接与身份 ───────────────────────────────────────────────────────

/** Cosmetic status reactions in the current connection's platform-native format.
 * Client owns the palette; server owns lifecycle, cleanup and API fallbacks.
 * Limits: 64 chars per name, 1–16 processing variants, 1–64 expressive errors.
 */
export interface HookStatusReactions {
  queued: string;
  processing: readonly string[];
  error: string;
  expressiveError?: readonly string[];
}

/**
 * hello(desktop -> server): 建连后第一帧, 自报身份与能力。
 * 工作区别名映射变更后, desktop 重发 hello 即时生效(server 以最新一帧为准)。
 */
export interface HelloPayload {
  protocolVersion: number;
  /** desktop 设备稳定标识(多设备路由预留, v1 server 侧可只记录)。 */
  deviceId: string;
  deviceName: string;
  /** 本连接注册的工作区别名列表 —— server 只能派发列表内的别名。 */
  workspaces: string[];
  /**
   * 本连接的默认工作区别名(可选; 缺省 / null = 无默认, server 按各自既有
   * 规则决定, 通常落 HOOK_CHAT_WORKSPACE_ALIAS)。**必须是 workspaces 的成员**
   * (协议层校验) —— 默认值不能绕过「server 只能派发列表内的别名」这条约束。
   *
   * 动机: X 这类**一次交互只有一条公开消息**的渠道没有交互式选择面板(Slack
   * 有 Block Kit、Telegram 有 inline keyboard), 无处让用户挑目录, 于是所有
   * 任务都只能落在对话伪目录上、碰不到本地仓库。由 desktop 在握手时声明一个
   * 默认目录, 是不引入额外往返、也不占用正文字符的做法。
   *
   * 旧 server 校验器只查已知字段, 本字段安全透传(同 features 的兼容策略)。
   */
  defaultWorkspace?: string | null;
  /** 可用 agent 类型(如 'cc' / 'codex'), 供 server 侧校验 dispatch options。 */
  agents: string[];
  /**
   * desktop 侧能力标识(可选, 缺省 = 旧客户端无能力)。当前已定义:
   * HOOK_FEATURE_MULTI_TEAM —— 会消费 bind.state 快照与按 team 定位的
   * bind.update / prefs.state。老 server 校验器只查已知字段, 本字段安全透传。
   */
  features?: string[];
  /**
   * 是否由 Slack Bot 私信设备上下线通知。缺省表示旧客户端,server 按既有
   * 默认开启处理;新客户端始终显式发送当前有效值。
   */
  lifecycleAnnouncement?: boolean;
  /** Optional client palette. Old servers ignore it; absent means server defaults.
   * Re-hello replaces the declaration, including clearing it when omitted.
   */
  statusReactions?: HookStatusReactions;
}

/** welcome(server -> desktop): hello 的应答, 握手完成。 */
export interface WelcomePayload {
  serverName: string;
  /** server 侧启用的可选能力标识, v1 恒空数组, 预留。 */
  features: string[];
}

/** ping / pong: 心跳, 双向皆可发起, 收到 ping 必须回 pong。payload 恒空对象。 */
export type PingPayload = Record<string, never>;
export type PongPayload = Record<string, never>;

// ── 阶段 2: 派活 ─────────────────────────────────────────────────────────────

/**
 * dispatch 的可选 override。全部可空 —— 空值落到 desktop 连接配置的默认值。
 * permissionMode 语义: 仅对「新建 session」的任务生效 —— desktop 校验其属于
 * 目标 agent 的能力档位清单, 合法即用, 非法/缺省落 bypassPermissions;
 * 复用/接管已有会话时忽略(session meta 权威, 进行中的会话不受影响)。
 */
export interface TaskDispatchOptions {
  model?: string | null;
  permissionMode?: string | null;
  agentKind?: string | null;
  /** 思考强度档位(如 low/medium/high); 空 = desktop 按草稿默认落值。 */
  effort?: string | null;
}

/**
 * 入站附件(图片等), 随 dispatch 一起下发。base64 内联传输 —— 复用已建好、
 * 已鉴权的 WS 通道, 免去 desktop 再开 HTTP 拉取端点。desktop 侧解码落盘后
 * 以本地路径喂给 agent(maker 的 image content block 要 path 而非 base64)。
 * 精细限额(单图大小 / 张数)由 provider 在生产端把关, 见其实现。
 */
export interface TaskAttachment {
  /** 原文件名(落盘 / 提示用); 无则 desktop 按序号命名。 */
  name: string | null;
  /** MIME 类型(如 image/png)。 */
  mimeType: string;
  /** base64 编码的字节(不含 data: 前缀)。 */
  dataBase64: string;
}

/**
 * agent 多模态可消费的图片 MIME 白名单 —— 协议层的权威单一来源。
 * 与 desktop renderer 的 SUPPORTED_IMAGE_EXTS 一致, 也是 Claude / Codex vision
 * 实际接受的集合(png / jpeg / gif / webp)。provider 下载端与 desktop 落盘端
 * 都据此过滤: 一端宽一端窄会导致图片被下载/传输后在对端静默丢弃, 白费带宽还
 * 不告知用户。bmp / svg / heic / avif / tiff 等不在此列(上游 vendor API 不接受)。
 */
export const SUPPORTED_IMAGE_MIME_TYPES = [
  'image/png',
  'image/jpeg',
  'image/gif',
  'image/webp',
] as const;

/**
 * 判定 MIME 是否为 agent 可消费的图片类型(大小写 / 前后空白无关;
 * 常见别名 image/jpg 归一到 image/jpeg)。
 */
export function isSupportedImageMime(mime: string): boolean {
  const m = mime.trim().toLowerCase();
  if (m === 'image/jpg') return true;
  return (SUPPORTED_IMAGE_MIME_TYPES as readonly string[]).includes(m);
}

/**
 * 结构化 thread 上下文条目(来源 IM 的 thread 历史中的一条消息)。
 * desktop 据此渲染可折叠的 thread 上下文卡片, 不再依赖从 prompt
 * 文本里正则解析 <thread_context> 块。
 */
export interface ThreadContextEntry {
  /** 可选的平台消息身份与回复关系,不从正文推断。 */
  messageId?: string;
  replyToMessageId?: string | null;
  authorId?: string;
  author: string;
  text: string;
  /** 该条目是否为 bot 自身的回复(渲染时可视觉区分)。 */
  isBot?: boolean;
}

/**
 * 任务来源元数据 —— 告知 desktop 这条任务来自哪个 IM 平台及其上下文。
 * 字段全部可选(im 除外); 旧 server 不发时 desktop 降级为纯文本渲染。
 */
export interface TaskSource {
  /**
   * X 结构化组装标记:threadContext 按祖先到当前请求排列,末项对应
   * triggerMessageId / requesterId;userText 为完整请求本体。
   * 新客户端据此组装 prompt,缺失时继续使用服务端兼容 prompt。
   */
  xContext?: { requesterId: string; requesterName?: string; truncated: boolean };
  /** IM 平台标识(开放集合): 'slack' | 'feishu' | 'discord' | ... */
  im: string;
  /** 来源显示名(频道名 "#general"、群名等); null = 未知。 */
  channelName?: string | null;
  /**
   * (multi-team)来源 Slack workspace id / 显示名: desktop 存进 session
   * meta, 作会话标题前缀与网关工具调用的默认 team。老 server 不下发。
   */
  teamId?: string | null;
  teamName?: string | null;
  /** 结构化 thread 上下文; 省略或空数组 = 无 thread 历史。 */
  threadContext?: ThreadContextEntry[];
  /**
   * 触发本任务的 IM 消息 id(与 group.message.messageId 同一 id 空间)。
   * desktop 用它在本地群窗口中精确剔除"当前消息", 避免上下文与 prompt 重复。
   * 旧 server 不发 = null/缺省, desktop 降级为不剔重。
   */
  triggerMessageId?: string | null;
  /**
   * 用户 @ bot 的干净原文(UI 显示用) —— 不含 thread 上下文与 prompt 指引。
   * desktop 据此渲染任务卡片正文, 与发给 agent 的完整 prompt 彻底分离。
   */
  userText?: string;
}

/**
 * task.dispatch(server -> desktop): 派发一个任务。
 * 两种会话定位方式:
 *   - sessionId 为 null(默认): 按 externalKey 查映射, 有则复用、无则在
 *     workspace 别名对应目录下新建 —— 此时 workspace 必填。
 *   - sessionId 非 null(接管): 直接投进该已有 desktop session 并把
 *     externalKey 重绑到它; workspace 忽略(session 自带工作目录, 但其
 *     workingDir 必须落在本连接注册的别名路径内, 否则 rejected)。
 */
export interface TaskDispatchPayload {
  requestId: string;
  externalKey: string;
  /** 工作区别名; sessionId 为 null 时必填(非 null 字符串)。 */
  workspace: string | null;
  /** 接管目标 session; 普通流程恒 null。 */
  sessionId: string | null;
  prompt: string;
  options?: TaskDispatchOptions;
  /** 入站附件(可选); 省略或空数组 = 无附件, 纯文本任务。 */
  attachments?: TaskAttachment[];
  /** 任务来源元数据; 省略 = 来源未知, desktop 按纯文本处理。 */
  source?: TaskSource;
}

/** ack 三态。 */
export const TASK_ACK_RESULTS = ['accepted', 'queued', 'rejected'] as const;
export type TaskAckResult = (typeof TASK_ACK_RESULTS)[number];

/** rejected 的机器可读原因。 */
export const TASK_REJECT_REASONS = [
  /** workspace 别名未在本连接注册。 */
  'unknown_workspace',
  /** 接管目标 session 的工作目录不在本连接注册的别名路径内。 */
  'workspace_not_allowed',
  /** 接管目标 session 不存在。 */
  'session_not_found',
  /** desktop 侧 hook 功能已关闭(总开关或本连接开关)。 */
  'disabled',
  /** 参数非法(desktop 业务层校验不过, 区别于协议层直接拒收的坏帧)。 */
  'invalid',
] as const;
export type TaskRejectReason = (typeof TASK_REJECT_REASONS)[number];

/**
 * task.ack(desktop -> server): dispatch 的立即应答。
 * 字段联动约束(parse 强制):
 *   - reason 仅 rejected 时非 null;
 *   - queuePosition 仅 queued 时非 null(0 起, 非负整数);
 *   - sessionId 在 accepted / queued 时为目标 session id, rejected 时为 null。
 */
export interface TaskAckPayload {
  requestId: string;
  result: TaskAckResult;
  reason: TaskRejectReason | null;
  sessionId: string | null;
  queuePosition: number | null;
}

// ── 阶段 4: 交差 ─────────────────────────────────────────────────────────────

/** cancelled: task.cancel 中断收口(errorMessage 恒 null, finalText 可为已产出的部分文本)。 */
export const TURN_END_STATUSES = ['ok', 'error', 'cancelled'] as const;
export type TurnEndStatus = (typeof TURN_END_STATUSES)[number];

/** turn 的用量摘要。v1 只有耗时, 字段可空(拿不到就 null, 不编造)。 */
export interface TurnEndUsage {
  durationMs: number | null;
}

/**
 * turn.end(desktop -> server): 任务收口。
 * 收口时机以 maker-core 事件流的 done / terminal error 为准。
 * 字段联动约束(parse 强制): status 为 'ok' 时 errorMessage 必须为 null;
 * 为 'error' 时 errorMessage 必须为非空字符串。
 */
export interface TurnEndPayload {
  /** session-result-v1: a new result for the bound lane, not a dispatched/reopened request. */
  background?: true;
  requestId: string;
  externalKey: string;
  sessionId: string | null;
  status: TurnEndStatus;
  /** 该 turn 的最终文本(error 时可为空串)。 */
  finalText: string;
  errorMessage: string | null;
  usage: TurnEndUsage;
  /**
   * 出站附件(agent 产出的图片 / 文件, base64 内联) —— 与入站 attachments
   * 对称复用 TaskAttachment。desktop 侧从最终文本的 xdt-image / xdt-file
   * 引用与 tool_result 旁路收集并施加大小/数量限额(finalText 中对应引用
   * 已剥离/替换为提示); server 侧上传到渠道。省略或空数组 = 无附件。
   * 旧 server 收到未知字段静默忽略(校验器只查已知字段), 向后兼容。
   */
  attachments?: TaskAttachment[];
  /**
   * 客户端终稿发布结果(HOOK_FEATURE_TELEGRAM_FINAL_OPS)。缺席 = 客户端没发布过终稿,
   * 服务端照旧渲染。只适用于不带附件的轮次: 带附件时 desktop 不发布终稿、不带本字段,
   * 附件照常放在 attachments 里由服务端发送(服务端对带附件的 turn.end 也不认本字段)。
   */
  clientFinal?: TurnEndClientFinal;
}

/**
 * turn.delivery(server -> desktop): server 对普通 turn.end 的两阶段交付回执。
 *
 * accepted 表示 server 已经接管最终结果及其重试责任;delivered 表示渠道侧
 * 终态动作已完成;failed 表示 server 已停止重试。desktop 只有在双方协商
 * HOOK_FEATURE_TURN_DELIVERY 后才等待本帧,老 server 继续沿用 fire-and-forget。
 */
export const TURN_DELIVERY_STATES = ['accepted', 'retrying', 'delivered', 'failed'] as const;
export type TurnDeliveryState = (typeof TURN_DELIVERY_STATES)[number];

/** retrying / failed 回执的安全、结构化错误;不得携带上游响应体、凭证或用户内容。 */
export interface TurnDeliveryError {
  code: string;
  message: string;
  /** 原样重放同一个 turn.end 是否仍可能恢复;false 时 desktop 只提示,不重跑 Agent。 */
  retryable: boolean;
}

export interface TurnDeliveryPayload {
  requestId: string;
  state: TurnDeliveryState;
  /** 已发生的渠道发布尝试次数;accepted 为 0,其余状态至少为 1。 */
  attempt: number;
  /** 仅 retrying 为正的安全整数,表示 server 计划的下次尝试时刻(unix ms)。 */
  retryAt: number | null;
  /** retrying / failed 非 null;accepted / delivered 恒为 null,failed 的 retryable 必须为 false。 */
  error: TurnDeliveryError | null;
}

// ── 阶段 9(v2): 执行进度 ────────────────────────────────────────────────────

/**
 * turn.progress(desktop -> server): turn 执行中的渲染快照(见文件头第 9 条)。
 * text 是 desktop 合成好的完整 markdown 快照(过程区时间线 + 已产出的部分
 * 正文), server 侧不拼接、不累积 —— 每帧整体替换占位消息内容(latest-wins,
 * 丢帧无害)。desktop 侧负责节流(约 1.5s/帧)与长度控制。
 */
export interface TurnProgressPayload {
  requestId: string;
  /** 当前渲染快照(完整替换语义, 非增量)。 */
  text: string;
}

// ── 阶段 18(v2): 收口后的续跑 ───────────────────────────────────────────────

/**
 * turn.reopen(desktop -> server): 把一个已收口任务的续跑接回原消息
 * (见文件头第 18 条)。
 *
 * server 收到后把 reopenOf 那条消息的位置登记给 requestId, 之后 desktop 会用
 * **requestId**(不是 reopenOf)继续发 turn.progress 与 turn.end, 走既有路径。
 * 认不出 reopenOf 时静默忽略本帧与后续同 requestId 的帧。
 *
 * 路由面**只含** turn.progress / turn.end / task.cancel。刻意不含 interaction.*:
 * 续跑是用户在**桌面端**点出来的, 人就在桌面前, 那一轮里 agent 的提问 / 计划审阅 /
 * 权限审批由桌面本地交互面直接处理, 不绕回渠道 —— 所以 server 不会收到带续跑
 * requestId 的 interaction.request, 也不需要为它建立 thread 关联。(反过来若把交互
 * 推回渠道, 用户得离开正在操作的桌面端去渠道点按钮, 更绕。)
 *
 * 可靠性: 本帧可被重复发送, server 必须幂等 —— 同一 (requestId, reopenOf) 重复
 * 登记同一个位置, 无副作用。与之对称, server 对**从未登记过**的 requestId 的
 * turn.progress / turn.end 一律静默忽略: 不报错、不新建消息。
 *
 * 帧序: 本帧必须排在这一轮的**任何** turn.progress / turn.end 之前 —— 包括"首个
 * 观察到的事件本身就是终态"(例如立刻的凭证错误)。先发 turn.end 的话 server 会按
 * 未知 requestId 丢弃它, 随后的 reopen 又把消息改成进行中, 就再没有终态帧能收口。
 *
 * 孤儿收口(server 侧责任): 映射装上、消息已改成进行中之后, desktop 崩溃 / 重启
 * 不会补发任何帧(记账只在进程内)。所以**连接断开时 server 必须收口该连接上所有
 * "已 reopen 但未收到 turn.end"的消息** —— 恢复原终态或改写成一句"续跑中断"。
 * 少了这条, 可见状态会从"停在失败"退化成"永远进行中", 比不做回流更糟。收口落笔时
 * 必须校验该消息仍归"被断开的那个连接 + 那次 reopen"所有: desktop 可能毫秒级重连、
 * 用户也可能立刻再点一次重试, 迟到的收口不得盖掉更新的一次 reopen 或已到达的新终态。
 *
 * 断连即终局(desktop 侧对称责任): 续跑轮的 turn.progress / turn.end 一律直发,
 * **不缓存也不在重连后补发** —— 这刻意偏离"断线重连 desktop 补发未送达 turn.end"
 * 的通用约定, 因为那条消息在断连瞬间已被上面的收口改写, 迟到的 turn.end 只会撞上
 * 被解绑的 requestId 而丢弃, 反把"其实成功"显示成"续跑中断"。相应地, turn.end 没
 * 发出去时 desktop 不得再把这条消息线登记成可续跑(它的 reopenOf 已被解绑)。
 *
 * id 碰撞: 续跑 requestId 由 desktop 生成(须 UUID v4 或同等强度), 与 server 生成的
 * 普通 requestId 共用一张路由表。server 收到已绑定到别的任务的 requestId 时拒绝登记,
 * **并把该 requestId 整体隔离** —— 后续 turn.progress / turn.end 一并忽略。只拒本帧
 * 却继续按老路由收后续帧, 等于让续跑的进度与终态改写那个无关任务的消息。
 *
 * 已声明接受的降级: 连接在续跑轮跑完前断开时结果不回流 —— 断在装映射前是消息保持
 * 原失败态(与本能力上线前完全一致), 断在装映射后是 server 收口成原终态或"续跑中断"
 * (那一轮其实成功时, 渠道会偏保守地显示没成功, 而桌面端有正确结果)。两种情形用户都
 * 可在渠道重发。协议刻意不为此加 ack 往返: 回流是增强而非关键路径。注意这个"失败
 * 方向安全"的结论**依赖上面那条孤儿收口**。
 */
export interface TurnReopenPayload {
  /**
   * 续跑轮的新任务 id(后续 progress / end / cancel 都用它)。
   *
   * 必须**全局抗碰撞**(UUID v4 或同等强度), 不得用递增计数器或会话内序号: 普通
   * 任务的 requestId 由 server 生成、本字段由 desktop 生成, 两者是同一张生命周期
   * 路由表的键, 而 parse 只能校验"非空且不等于 reopenOf"。id 空间重叠时, 一次续跑
   * 可能覆盖掉某个无关在跑任务的路由。server 侧以"拒绝已绑定的 requestId"兜底。
   */
  requestId: string;
  /** 被续跑的那一轮的 requestId —— server 据此定位渠道里那条消息。 */
  reopenOf: string;
  /**
   * 渠道内标识(原样回传), 供日志与诊断关联。
   *
   * **不参与路由**: 定位那条消息的唯一依据是 reopenOf。刻意不允许用它兜底 ——
   * 两端独立实现(server 闭源、独立仓), 一端"映射过期就按 externalKey 找 thread"、
   * 另一端"映射过期就忽略", 同一次过期续跑会在一端改写消息、在另一端丢弃。
   */
  externalKey: string;
  /** 续跑发生在哪个会话(记录与调试用, 不参与路由)。 */
  sessionId: string | null;
  /**
   * 为什么被续跑。当前只有 'user-continued'(用户在桌面端显式点了续跑 / 重试)。
   * 开放集合: server 不认识的值按 'user-continued' 处理即可, 不要拒帧。
   */
  reason: string;
}

// ── 阶段 5(v2): 身份绑定 ────────────────────────────────────────────────────

/**
 * bind.start(desktop -> server): 发起「Slack 用户 ↔ 本设备」绑定。
 * 阶段 4 起绑定走 Sign in with Slack(OIDC): 新桌面端发**空对象** `{}`,
 * server 据连接身份签发授权链接经 bind.update(pending, authorizeUrl)回推。
 * 设备身份取连接 hello 的 deviceId, 不在本帧携带。
 *
 * email 字段仅为识别老客户端保留(@deprecated): 老桌面端仍按邮箱发起,
 * server 收到带 email 的 bind.start 即判定为旧版, 回 bind.update(failed)
 * 提示升级, 不再执行邮箱定位。
 */
export interface BindStartPayload {
  /** 仅授权本机通讯,绝不修改 Bot 接收设备。只能在 slack-communications 协商后发送。 */
  purpose?: 'communications';
  /** @deprecated 旧版邮箱绑定流字段; 新端不再发送, 仅用于 server 识别老客户端。 */
  email?: string;
  /**
   * (multi-team)重新授权指定 workspace 时 pin 授权页到该 team(server 在
   * 授权链接上带 team 参数); 缺省/null = 用户在授权页自选(添加新 team)。
   * 老 server 校验器不查本字段, 安全透传(它照常签发不 pin 的链接)。
   */
  teamId?: string | null;
}

/**
 * bind.update 状态机:
 *   none      未绑定(连接建立后 server 主动推一帧告知现状)
 *   pending   OIDC 授权链接已签发(authorizeUrl 非空), 等待用户在浏览器授权
 *   confirmed 绑定成立(slackUserId / slackUserName 非空)
 *   denied    用户在 Slack 授权页点了拒绝
 *   expired   授权超时(state 令牌过期)
 *   failed    流程失败(如老客户端、该 workspace 未安装本 app), message 携带原因
 *   revoked   绑定被解除(本设备主动 revoke, 或被同用户新设备顶掉)
 */
export const BIND_UPDATE_STATES = [
  'none',
  'pending',
  'confirmed',
  'denied',
  'expired',
  'failed',
  'revoked',
] as const;
export type BindUpdateState = (typeof BIND_UPDATE_STATES)[number];

/**
 * bind.update(server -> desktop): 绑定状态推送(bind.start 的应答 + 后续
 * 任何状态变化, 含连接建立时的现状同步与被新设备顶掉的通知)。
 * 字段联动(parse 强制): confirmed 时 slackUserId 非空; pending 时
 * authorizeUrl 非空(OIDC 授权链接); failed 时 message 非空。
 */
export interface BindUpdatePayload {
  /** 回放授权意图,防重连/重试将通讯授权误升级为 Bot 换绑。 */
  purpose?: 'communications';
  state: BindUpdateState;
  slackUserId: string | null;
  /** Slack 显示名(设置页展示「已绑定 @xxx」用), 拿不到可为 null。 */
  slackUserName: string | null;
  /** 人类可读补充说明(failed 原因 / revoked 缘由等)。 */
  message: string | null;
  /**
   * OIDC 授权链接(仅 state=pending 时非空): 桌面端用系统浏览器打开它,
   * 用户在 Slack 授权页确认后 server 回调完成绑定。其它状态省略或 null。
   */
  authorizeUrl?: string | null;
  /**
   * 结构化失败原因(仅 state=failed 时可选)。桌面端按它分支 UI, 不解析
   * message 文案(规则 9)。当前已定义:
   *   'not-installed' —— 用户授权的 Slack workspace 未安装本 App(SIWS 授权
   *   不要求安装, 但 bot 无 token 收发消息), 桌面端显示「安装 App」引导。
   * parse 侧只校验 string|null(未知值放行), 老客户端遇到新 reason 忽略即可。
   */
  reason?: string | null;
  /**
   * 按 workspace 定制的安装链接(仅 reason='not-installed' 时可选): 携带
   * team 参数, Slack 安装授权页会预选到用户刚授权的那个 workspace, 免手选。
   * 桌面端缺省(老 server)回退通用 /slack/install 链接。
   */
  installUrl?: string | null;
  /**
   * 绑定所在 Slack workspace 显示名(仅 state=confirmed 时可选下发, 取安装
   * 档案的 teamName): 设置页状态行展示「已绑定 @xxx(workspace)」。老 server
   * 不下发或档案缺名时为 null/缺省, 桌面端回退只显示用户名。
   */
  teamName?: string | null;
  /**
   * (multi-team)事件所属 Slack workspace id: confirmed / revoked 按 team
   * 定位到绑定列表的对应行; 授权流早期(pending / denied / expired)团队
   * 尚未确定, 为 null/缺省。老 server 不下发, 单绑定桌面端不依赖本字段。
   */
  teamId?: string | null;
}

/** bind.update.reason 已知值: 绑定的 Slack workspace 未安装本 App。 */
export const BIND_FAIL_REASON_NOT_INSTALLED = 'not-installed';

/** bind.update.reason 已知值(multi-team): 该绑定被同用户在另一台设备顶替。 */
export const BIND_FAIL_REASON_SUPERSEDED = 'superseded';

/**
 * bind.revoke(desktop -> server): 解除本设备绑定。
 * teamId 非空 = 只解绑该 workspace(multi-team); 空/缺省 = 解绑本设备全部
 * (兼容单绑定老 desktop 的"关开关即全解")。pendingOnly=true = 只作废
 * 进行中的授权尝试(pending 授权 / 等安装登记), 不触碰任何已确认绑定 ——
 * multi-team 下「取消添加 workspace」的通道(此时 teamId 忽略)。
 * ⚠ 旧 server 对带字段的帧 parse 拒收(它要求空对象), desktop 仅在
 * welcome.features 声明 multi-team 后才发非空形态。
 */
export interface BindRevokePayload {
  teamId?: string | null;
  pendingOnly?: boolean;
}

/**
 * bind.state(server -> desktop, multi-team): 本设备绑定全量快照。
 * 权威列表语义 —— 连接建立与任何绑定变化(新增 / 解除 / 被顶 / 撤权清理)
 * 后整体推送, desktop 以此对齐本地列表(bind.update 只承载过程事件)。
 * 仅对 hello.features 声明 multi-team 的连接下发; 旧 desktop 不认识本
 * 类型, parse 拒收丢帧不断连。
 */
export interface BindStateEntry {
  teamId: string;
  /** workspace 显示名(安装档案 teamName); 档案缺名时 null。 */
  teamName: string | null;
  slackUserId: string;
  slackUserName: string | null;
}

export interface BindStatePayload {
  bindings: BindStateEntry[];
  /** 设备通讯授权快照;缺省表示旧 server,不可由本地缓存推断授权。 */
  communications?: (BindStateEntry & { enabled: boolean })[];
}

// ── Provider-neutral binding (append-only v1) ───────────────────────────────

/**
 * IM providers supported by the shared Cindy relay.
 * Append-only: adding a value here is backward compatible because every
 * provider-specific frame family is gated behind a `provider:<id>` welcome
 * capability — an old peer that does not know the new id never negotiates it,
 * and its parse rejects stray frames without dropping the connection.
 */
export const HOOK_PROVIDERS = ['slack', 'telegram', 'x'] as const;
export type HookProvider = (typeof HOOK_PROVIDERS)[number];

/**
 * Provider binding states. A binding attempt moves monotonically from pending
 * through optional confirmation to confirmed, or one of the terminal states.
 */
export const PROVIDER_BIND_STATES = [
  'none',
  'pending',
  'awaiting_confirmation',
  'confirmed',
  'denied',
  'expired',
  'failed',
  'revoked',
  'superseded',
] as const;
export type ProviderBindState = (typeof PROVIDER_BIND_STATES)[number];

/** Known UI action hints. The wire remains open; consumers ignore unknown values. */
export const PROVIDER_BIND_ACTIONS = [
  'open_connect_url',
  'copy_connect_url',
  'cancel',
  'retry',
  'revoke',
  'open_provider',
  'add_to_group',
] as const;
export type KnownProviderBindAction = (typeof PROVIDER_BIND_ACTIONS)[number];
export type ProviderBindAction = string;

/** Start a provider-specific, one-time binding attempt for this device. */
export interface ProviderBindStartPayload {
  requestId: string;
  provider: HookProvider;
  /** Optional provider scope (for example a Slack team or Telegram bot id). */
  scopeId?: string | null;
}

/** Cancel exactly one in-flight binding attempt without touching a binding. */
export interface ProviderBindCancelPayload {
  requestId: string;
  provider: HookProvider;
  attemptId: string;
}

/** Revoke exactly one confirmed binding. */
export interface ProviderBindRevokePayload {
  requestId: string;
  provider: HookProvider;
  bindingId: string;
}

/**
 * Shared payload for provider.bind.update and provider.bind.state. update is an
 * event/reply; state is an authoritative point-in-time snapshot for one scope.
 * All nullable fields are explicit so an old value cannot survive a snapshot.
 */
export interface ProviderBindStatusPayload {
  provider: HookProvider;
  /** Request id being answered, or null for an unsolicited state push. */
  replyTo: string | null;
  state: ProviderBindState;
  attemptId: string | null;
  bindingId: string | null;
  principalId: string | null;
  principalName: string | null;
  scopeId: string | null;
  scopeName: string | null;
  /** One-time provider deep link; present only while state=pending. */
  connectUrl: string | null;
  /** Unix milliseconds; required for pending/awaiting_confirmation attempts. */
  expiresAt: number | null;
  /** Stable machine-readable reason; required for unsuccessful terminal states. */
  reason: string | null;
  /** Optional safe recovery/provider URL interpreted by the host application. */
  remediationUrl: string | null;
  actions: ProviderBindAction[];
}

export type ProviderBindUpdatePayload = ProviderBindStatusPayload;
export type ProviderBindStatePayload = ProviderBindStatusPayload;

// ── 阶段 6(v2): 实时问答 ────────────────────────────────────────────────────

/** 可查询的清单种类。 */
export const QUERY_KINDS = ['workspaces', 'models', 'sessions', 'session-new'] as const;
export type QueryKind = (typeof QUERY_KINDS)[number];

/**
 * query.request(server -> desktop): 实时拉取清单(/bind /model /effort 触发)。
 * queryId 由 server 生成, response 原样回传配对; server 侧自行做超时。
 */
export interface QueryRequestPayload {
  queryId: string;
  kind: QueryKind;
  /** kind=session-new: create and bind a blank task immediately for `/new`. */
  sessionNew?: {
    previousExternalKey: string;
    externalKey: string;
    workspace: string;
    options?: TaskDispatchOptions;
    source?: TaskSource;
  };
}

/**
 * 模型条目: efforts 为该模型支持的思考强度档位(可空数组 = 不支持调档)。
 * group 是目录分组 id(如 'gpt' / 'gpt-budget'): 骨折版与官方版 displayName
 * 故意同名、仅靠分组区分, server 渲染下拉时据此加区分后缀, 否则出现两个
 * 一模一样的 "GPT-5.5"(线上实撞)。可选 —— 旧桌面端不发, server 视为无分组。
 */
export interface QueryModelEntry {
  id: string;
  label: string;
  efforts: string[];
  defaultEffort: string | null;
  group?: string | null;
}

/**
 * 权限档条目(label = desktop capabilities 的 displayName, 原样透传,
 * 与模型 label 同风格 —— server 不做本地化映射, 避免档位集合演进时文案漂移)。
 */
export interface QueryPermissionModeEntry {
  id: string;
  label: string;
}

/**
 * 按 agent 分组的模型清单(kind=models 的响应体)。
 * permissionModes 缺席 = 旧版 desktop(不支持权限档下发), server 侧应隐藏
 * 权限选择 UI; 空数组 = 该 agent 无可选档位, 同样隐藏。
 */
export interface QueryAgentModels {
  agentKind: string;
  models: QueryModelEntry[];
  permissionModes?: QueryPermissionModeEntry[];
}

/** Privacy-minimised recent-session entry for the provider session picker. */
export interface QuerySessionEntry {
  id: string;
  title: string;
  /** Workspace alias only; local absolute paths are forbidden on this wire. */
  workspace: string;
  /** Unix milliseconds of the latest local activity. */
  lastActiveAt: number;
}

/**
 * query.response(desktop -> server): 问答应答。
 * ok=false 时 error 非空(desktop 侧取清单失败); ok=true 时按 kind 携带
 * workspaces 或 agents 之一(parse 强制)。
 */
export interface QueryResponsePayload {
  queryId: string;
  kind: QueryKind;
  ok: boolean;
  error: string | null;
  /** kind=workspaces 且 ok 时必填: 当前注册的工作区别名。 */
  workspaces?: string[];
  /** kind=models 且 ok 时必填: 按 agent 分组的可用模型与 effort 档位。 */
  agents?: QueryAgentModels[];
  /** kind=sessions 且 ok 时必填: at most 20 privacy-minimised entries. */
  sessions?: QuerySessionEntry[];
  /** kind=session-new 且 ok 时必填。 */
  sessionId?: string;
}

// ── 阶段 7(v2): 任务取消 ────────────────────────────────────────────────────

/**
 * task.cancel(server -> desktop): 中断在跑任务(/stop 触发)。
 * desktop 收到后中断对应 session 的当前 turn, 以 turn.end(cancelled) 收口;
 * requestId 未知 / 任务已收口时静默忽略(与 turn.end 的竞态由 server 侧
 * 幂等消化)。
 */
export interface TaskCancelPayload {
  requestId: string;
}

// ── 阶段 8(v2): 会话归档 ────────────────────────────────────────────────────

/**
 * session.archive(server -> desktop): 归档 externalKey 绑定的会话(私聊
 * /new 换代触发, 旧代会话不再显示在桌面端列表)。desktop 侧幂等: 无绑定、
 * 会话不存在或已归档时静默忽略。老版本 desktop 不认识本类型, parse 拒收
 * 丢帧不断连(见文件头「type 为开放集合」约定), 仅表现为旧会话留在列表。
 */
export interface SessionArchivePayload {
  externalKey: string;
}

// ── 阶段 10(v2): 执行中交互 ─────────────────────────────────────────────────

/** 单个交互卡按钮上限(Slack actions block 每块 5 个 x 分块, 取宽松上限)。 */
export const MAX_INTERACTION_BUTTONS = 24;

/**
 * 交互卡按钮。id 是 desktop 侧的决策映射键(server 原样回传, 不理解语义),
 * 同一张卡内唯一; 字符集限制: 不含 '|'(server 侧 value 复合编码分隔符)。
 */
export interface InteractionButton {
  id: string;
  label: string;
  /** 视觉样式(Slack 按钮 style; default = 无样式)。 */
  style: 'primary' | 'danger' | 'default';
}

/**
 * interaction.request(desktop -> server): turn 执行中 agent 发起的用户交互,
 * 以「标题 + markdown 正文 + 按钮组」的渠道无关卡片形式转发。server 渲染进
 * 该任务的回帖 thread, 按钮按压回 interaction.decision。
 * kind 是开放集合(当前 'ask_user_question' / 'plan_review'), server 只透传
 * 日志不理解语义 —— 新 kind 不需要 server 升级。
 */
export interface InteractionRequestPayload {
  /** 所属任务(server 据此定位回帖 thread 并校验归属)。 */
  requestId: string;
  /** 交互唯一标识(maker-core InteractionRequest.requestId), 决策配对键。 */
  interactionId: string;
  kind: string;
  title: string;
  /** markdown 正文(server 转渠道格式渲染); 可为空串。 */
  body: string;
  buttons: InteractionButton[];
}

/**
 * interaction.decision(server -> desktop): 用户按下交互卡按钮。
 * desktop 按 interactionId 配对挂起的交互, 用 buttonId 查自己登记的
 * 按钮->决策映射(语义不过网线)。迟到/未知的 decision 静默忽略。
 */
export interface InteractionDecisionPayload {
  requestId: string;
  interactionId: string;
  buttonId: string;
}

/**
 * interaction.cancel(desktop -> server): 交互已在 desktop 侧收口(任一端确认、
 * 超时按安全默认自决或 turn 结束), 通知 server 改写卡片(摘按钮 + reason 文案),
 * 防止用户对着死卡片按。幂等: server 找不到对应卡片时静默忽略。
 */
export interface InteractionCancelPayload {
  requestId: string;
  interactionId: string;
  /** 卡片改写文案(人类可读)。 */
  reason: string;
}

// ── 阶段 11(v2): 目录偏好远程读写 ──────────────────────────────────────────

/** prefs.get(desktop -> server): 拉取本设备绑定用户的全部目录偏好快照。 */
export interface PrefsGetPayload {
  /** desktop 生成的关联 id, prefs.state.replyTo 回显配对。 */
  requestId: string;
}

/** 单目录偏好条目(与 server user_prefs 行同形; slackUserId 不过网线)。 */
export interface WorkspacePrefsEntry {
  workspace: string;
  model: string | null;
  effort: string | null;
  agentKind: string | null;
  permissionMode: string | null;
  /**
   * (multi-team)偏好归属的 Slack workspace。多绑定设备的快照覆盖全部已绑
   * team, 桌面端按 teamId 分组编辑。老 server 不下发(单绑定语境无歧义)。
   */
  teamId?: string | null;
}

/**
 * prefs.set(desktop -> server): 部分更新某目录偏好(undefined 字段不动,
 * null 显式清空 —— 与 server setPrefs / dispatch options 同语义)。
 * server 只做 shape 校验, 不校验值合法性(值来自 desktop 自己的能力清单;
 * 过期值由 desktop 派发侧 defaults 兜底)。
 */
export interface PrefsSetPayload {
  requestId: string;
  workspace: string;
  model?: string | null;
  effort?: string | null;
  agentKind?: string | null;
  permissionMode?: string | null;
  /**
   * (multi-team)写入目标 team。缺省/null = 设备唯一绑定(多绑定时 server
   * 不猜测, 忽略写入并在应答快照中原样回放现状)。老 server 不查本字段。
   */
  teamId?: string | null;
}

/**
 * prefs.state(server -> desktop): 绑定用户的全量目录偏好快照。
 * replyTo 回显 get/set 的 requestId; 主动推送(/model 卡写入后)为 null。
 * 字段联动(parse 强制): bound=false 时 prefs 恒空数组(未绑定无偏好可言)。
 */
export interface PrefsStatePayload {
  replyTo: string | null;
  bound: boolean;
  prefs: WorkspacePrefsEntry[];
}

// ── Provider-neutral preferences (append-only v1) ──────────────────────────

/** Provider preference selector; exactly one of bindingId/scopeId is non-null. */
export interface ProviderPrefsSelector {
  provider: HookProvider;
  bindingId: string | null;
  scopeId: string | null;
}

export interface ProviderPrefsGetPayload extends ProviderPrefsSelector {
  requestId: string;
}

export interface ProviderPrefsSetPayload extends ProviderPrefsSelector {
  requestId: string;
  workspace: string;
  model?: string | null;
  effort?: string | null;
  agentKind?: string | null;
  permissionMode?: string | null;
}

/** Provider-neutral preference row (intentionally has no Slack teamId field). */
export interface ProviderWorkspacePrefsEntry {
  workspace: string;
  model: string | null;
  effort: string | null;
  agentKind: string | null;
  permissionMode: string | null;
}

export interface ProviderPrefsStatePayload extends ProviderPrefsSelector {
  replyTo: string | null;
  bound: boolean;
  prefs: ProviderWorkspacePrefsEntry[];
}

// ── Provider-neutral behavior (Telegram, append-only v1) ───────────────────
// 见文件头第 19 条。

/**
 * Providers this frame family currently understands. Deliberately its own
 * append-only list rather than reusing HookProvider: the field shapes below
 * (emoji reactions, reply-quote depth, a chat-id-keyed mention allowlist) are
 * Telegram-specific, not provider-neutral placeholders — adding Slack or X
 * here later requires a deliberate look at whether these exact fields still
 * make sense for that provider, not just a permissive type-level allowance.
 */
export const PROVIDER_BEHAVIOR_PROVIDERS = Object.freeze(['telegram'] as const);
export type ProviderBehaviorProvider = (typeof PROVIDER_BEHAVIOR_PROVIDERS)[number];

/** Emoji reaction verbosity on Telegram messages the bot sees/sends. */
export const TELEGRAM_EMOJI_REACTIONS = Object.freeze(['off', 'minimal', 'expressive'] as const);
export type TelegramEmojiReactions = (typeof TELEGRAM_EMOJI_REACTIONS)[number];

/** Whether a DM reply quotes the message it answers. */
export const TELEGRAM_REPLY_QUOTE_DM = Object.freeze(['off', 'first'] as const);
export type TelegramReplyQuoteDm = (typeof TELEGRAM_REPLY_QUOTE_DM)[number];

/** Whether a group reply quotes the message(s) it answers. */
export const TELEGRAM_REPLY_QUOTE_GROUP = Object.freeze(['off', 'first', 'all'] as const);
export type TelegramReplyQuoteGroup = (typeof TELEGRAM_REPLY_QUOTE_GROUP)[number];

/**
 * The only per-chat activation override this protocol carries: the bot
 * responds in that chat without requiring an @mention. The default behavior
 * ('mention' required) is expressed by the chat's *absence* from the map —
 * there is no 'mention' literal to write, only this one to set or clear.
 */
export const TELEGRAM_GROUP_ACTIVATION_ALWAYS = 'always';
export type TelegramGroupActivationOverride = typeof TELEGRAM_GROUP_ACTIVATION_ALWAYS;

/** The three global Telegram behavior switches, always present together. */
export interface TelegramBehaviorFields {
  emojiReactions: TelegramEmojiReactions;
  replyQuoteDm: TelegramReplyQuoteDm;
  replyQuoteGroup: TelegramReplyQuoteGroup;
}

/**
 * Baseline behavior for a binding that has never been configured, and the
 * value provider.behavior.state must report while bound=false (parse
 * enforced — see ProviderBehaviorStatePayload). Matches the personal-build
 * defaults (the shipped Telegram bot behavior before any override): emoji
 * reactions default to 'minimal', DM reply-quoting defaults off, and group
 * reply-quoting defaults to quoting the first message of a burst.
 */
export const DEFAULT_TELEGRAM_BEHAVIOR: Readonly<TelegramBehaviorFields> = Object.freeze({
  emojiReactions: 'minimal',
  replyQuoteDm: 'off',
  replyQuoteGroup: 'first',
});

/**
 * Selector for provider.behavior.* frames. Deliberately narrower than
 * ProviderPrefsSelector (which allows a scope-only selector before a binding
 * exists): every field here — the global switches and the per-chat allowlist
 * — is meaningless without a concrete bound principal (the allowlist's keys
 * are chats *that principal's bot* has seen), so there is nothing to
 * configure pre-binding. Requiring bindingId (not bindingId | scopeId) keeps
 * the owner boundary explicit: whoever holds the bindingId is the only party
 * allowed to read or write it.
 */
export interface ProviderBehaviorSelector {
  provider: ProviderBehaviorProvider;
  bindingId: string;
}

export interface ProviderBehaviorGetPayload extends ProviderBehaviorSelector {
  requestId: string;
}

/**
 * A single chat's activation-allowlist patch. `value: 'always'` adds the
 * override; `value: null` clears a previously-set override, falling back to
 * the default (mention required). Only one chat per set frame — batching is
 * just repeated set calls, which keeps each mutation independently
 * observable via the resulting provider.behavior.state.
 */
export interface ProviderBehaviorGroupActivationPatch {
  chatId: string;
  value: TelegramGroupActivationOverride | null;
}

/**
 * provider.behavior.set(desktop -> server): patch one bound Telegram
 * principal's behavior. Two independent, freely combinable patch axes:
 *   - the three global fields, each optional and each `enum | null`:
 *       - undefined = untouched (field omitted from the frame entirely);
 *       - an enum literal = set an **explicit override** to that value —
 *         written and persisted even when it happens to equal the current
 *         version default. This matters: a user who explicitly chose
 *         'minimal' must keep seeing 'minimal' even if a later protocol
 *         revision changes DEFAULT_TELEGRAM_BEHAVIOR.emojiReactions to
 *         something else. Explicit intent must survive a default-value
 *         change; only the user (or a future explicit clear) may remove it;
 *       - `null` = **clear** the override, falling back to whatever
 *         DEFAULT_TELEGRAM_BEHAVIOR carries for that field at resolve time.
 *     This is the same three-way shape as ProviderBehaviorGroupActivationPatch
 *     below (undefined/value/null), just applied to enum fields instead of
 *     a chat-id map entry.
 *   - groupActivation: one chat's allowlist patch or clear (see above).
 * parse rejects a frame with neither axis present — unlike prefs.set, a
 * silent no-op here would give the user no observable feedback that nothing
 * changed, so intent must be explicit. Note `null` on a global field still
 * counts as "an actual patch" for that at-least-one-patch requirement: it
 * is a real, observable clear action, not an omission.
 */
export interface ProviderBehaviorSetPayload extends ProviderBehaviorSelector {
  requestId: string;
  emojiReactions?: TelegramEmojiReactions | null;
  replyQuoteDm?: TelegramReplyQuoteDm | null;
  replyQuoteGroup?: TelegramReplyQuoteGroup | null;
  groupActivation?: ProviderBehaviorGroupActivationPatch;
}

/**
 * provider.behavior.state(server -> desktop): full effective snapshot for one
 * bound Telegram principal — reply to get/set (replyTo echoes requestId) or
 * an unsolicited push after some other client mutates it (replyTo null).
 * The three behavior fields are the *resolved* values (never a raw patch).
 * groupActivation lists only chats that deviate from the default — chats the
 * user never touched are implicitly 'mention' and are not enumerated. The
 * enclosing frame remains bounded by HOOK_MAX_FRAME_CHARS; the map itself has
 * no lower entry cap because every valid set mutation must remain representable
 * in a later authoritative state snapshot.
 * Field linkage (parse enforced): bound=false collapses the whole snapshot to
 * DEFAULT_TELEGRAM_BEHAVIOR and an empty groupActivation — there is no
 * principal to hold per-chat overrides for an unbound selector, so a stale
 * configured value cannot survive past the binding that set it.
 */
export interface ProviderBehaviorStatePayload
  extends ProviderBehaviorSelector, TelegramBehaviorFields {
  replyTo: string | null;
  bound: boolean;
  groupActivation: Record<string, TelegramGroupActivationOverride>;
}

// ── 阶段 12(v2): Slack 网关工具 ────────────────────────────────────────────

/**
 * welcome.features 能力标识: server 支持 tool.request / tool.response 帧族
 * (Slack 网关工具)。desktop 侧发 tool.request 前先查本标识, 缺席直接短路
 * 为 SERVER_TOO_OLD, 不打空炮。
 */
export const HOOK_FEATURE_SLACK_TOOLS = 'slack-tools';
/** 工具权限独立于 Bot 接收设备,支持 communications.set。 */
export const HOOK_FEATURE_SLACK_COMMUNICATIONS = 'slack-communications';

/**
 * 双向能力标识: 多 workspace 绑定(见文件头第 13 条)。desktop 在
 * hello.features 声明会消费 bind.state / 按 team 定位的帧; server 在
 * welcome.features 声明支持。任一侧缺席回落单绑定行为。
 */
export const HOOK_FEATURE_MULTI_TEAM = 'multi-team';

/** Both peers must advertise this before using provider.bind.* frames. */
export const HOOK_FEATURE_PROVIDER_BIND = 'provider-bind-v1';

/** Both peers must advertise this before using provider.prefs.* frames. */
export const HOOK_FEATURE_PROVIDER_PREFS = 'provider-prefs-v1';

/** Both peers must advertise this before using provider.behavior.* frames. */
export const HOOK_FEATURE_PROVIDER_BEHAVIOR = 'provider-behavior-v1';

/** Both peers must advertise this before query.kind=sessions is used. */
export const HOOK_FEATURE_SESSION_PICKER = 'session-picker-v1';

/** Both peers support immediate blank-task creation for provider `/new`. */
export const HOOK_FEATURE_SESSION_NEW = 'session-new-v1';

/** Server capability announcing that its provider registry enables Telegram. */
export const HOOK_FEATURE_PROVIDER_TELEGRAM = 'provider:telegram';

/** Server capability announcing that its provider registry enables X (Twitter). */
export const HOOK_FEATURE_PROVIDER_X = 'provider:x';

/**
 * server 支持 hello.lifecycleAnnouncement 与 lifecycle.preference,可由
 * desktop 设置页即时控制该设备的 Slack Bot 上下线私信。
 */
export const HOOK_FEATURE_LIFECYCLE_ANNOUNCEMENT = 'lifecycle-announcement-v1';

/** lifecycle.preference(desktop -> server): 即时更新本设备的通知偏好。 */
export interface LifecyclePreferencePayload {
  enabled: boolean;
}

/**
 * welcome.features 能力标识: server 支持 turn.reopen(见文件头第 18 条)——
 * 能把一条已收口消息重新挂到续跑轮的新 requestId 上。desktop 仅在本标识出现
 * 时才登记续跑记账并发帧; 缺席则维持旧行为(渠道消息停在失败上)。
 */
export const HOOK_FEATURE_TURN_REOPEN = 'turn-reopen-v1';
/** New messages for background execution in an existing IM-bound session. Excludes X. */
export const HOOK_FEATURE_SESSION_RESULT = 'session-result-v1';

/**
 * 双向能力标识:server 会在收到普通 turn.end 后回 turn.delivery,并以
 * accepted 明确接管重试责任。续跑轮仍遵循 turn-reopen 的“断连即终局”,
 * 不进入本回执与重放链路。
 */
export const HOOK_FEATURE_TURN_DELIVERY = 'turn-delivery-v1';

// ── 阶段 20: 消息操作动词(msg.op) —— 内容面上收客户端 ─────────────────────────

/**
 * 双向能力标识: 双方都宣告后, desktop 用 msg.op 直接驱动渠道消息形态,
 * server 退为**哑执行器**(只做 lane 授权、全局限速与 API 调用, 不解释内容)。
 *
 * 为什么要这条轴: 现有 turn.progress / turn.end 是按「turn 阶段」切的 ——
 * 客户端产文本快照、服务端决定它长什么样(分块、发还是编辑、卡片形态、
 * 表情、媒体组)。于是任何呈现改进都要协议 + 服务端 + 客户端三仓联发。
 * 正确的轴是**内容面(客户端) vs 投递面(服务端)**: 消息形态由客户端全权决定,
 * 服务端只保留多租户授权、跨租户共享 token 的限速预算、终稿必达与离线自治。
 *
 * 兼容: 缺席本标识时 desktop 继续走 turn.progress / turn.end 旧路径, 服务端
 * 保留旧渲染栈, 老客户端逐字节无感知。**仅 telegram provider 先行**——
 * Slack / X 的渲染路径不接入本动词集(它们的形态契约由 Dash 重构后的实现持有,
 * 不在本轴的搬迁范围)。
 */
export const HOOK_FEATURE_MESSAGE_OPS = 'msg-op-v1';

/** msg.op 的作用域: 服务端据此校验该设备是否有权操作这条 lane。 */
export interface MessageOpScope {
  /**
   * 目标渠道会话(与 task.dispatch 的 externalKey 同一命名空间)。
   *
   * **这是本动词集唯一的授权锚点, 也是唯一的寻址依据。** 服务端必须由它反查
   * 自己那份 lane 记录, 从记录里取实际的 chat / topic —— 不接受客户端直接指定
   * 目标聊天。否则一台被攻陷或有 bug 的桌面就能往任意 chat_id 发消息, 越过它
   * 自己 lane 的边界。lane 不存在或不属于该设备的绑定 principal 时一律拒绝执行。
   */
  externalKey: string;
}

/**
 * 一次消息操作的具体动作。
 *
 * 设计约束(与「哑执行器」互为定义):
 *   - 形态参数已经是**最终形态**: 文本是渲染好的正文, 分块由客户端切好,
 *     服务端不再分块、不再套模板、不再补文案;
 *   - 每个动作自带 `opId`(客户端生成, 全局唯一)。服务端按 opId 幂等:
 *     重复收到同一 opId 一律返回首次结果, 不重复调用 Bot API —— 这是断连
 *     重发下不产生重复消息的**唯一**依据(Telegram 没有发送端幂等键)。
 *
 * 服务端不变量(两条, 缺一即安全漏洞):
 *   1. **寻址**: 目标 chat / topic 只能由 `scope.externalKey` 反查服务端自己
 *      的 lane 记录得到, 不读客户端任何输入(见 MessageOpScope)。
 *   2. **归属**: `edit` / `delete` / `react` 引用的 messageId 必须经服务端核验
 *      确属该 lane —— 它只能是本 lane 先前 `send` 的产物, 或该 lane 收到的
 *      入站消息。少了这一条, 这套动词就是一个能编辑、删除、标记**任意**消息的
 *      后门: messageId 在 Telegram 里只是个自增序号, 猜得到。
 */
export type MessageOpAction =
  | {
      kind: 'send';
      /** 已渲染的最终正文(客户端已分块; 服务端不再切)。 */
      text: string;
      /** 回复锚点: 目标渠道的原生 message id。 */
      replyToMessageId?: string | null;
      /** 客户端决定的呈现档位; 服务端按能力降级但不改内容。 */
      tier?: 'rich' | 'html' | 'plain';
      silent?: boolean;
      /** 该消息挂的按钮(语义与形态都由客户端定, 服务端原样下发)。 */
      buttons?: MessageOpButton[][];
      /**
       * 渠道消息特效(Telegram `message_effect_id`), 客户端决定挂不挂、挂哪个;
       * 服务端原样透传。缺席 = 不挂。
       */
      effectId?: string;
    }
  | {
      kind: 'edit';
      messageId: string;
      text: string;
      tier?: 'rich' | 'html' | 'plain';
      /** 缺席 = 保留原键盘; 空数组 = 清空键盘(收口的卡片必须显式清)。 */
      buttons?: MessageOpButton[][];
    }
  | { kind: 'delete'; messageId: string }
  | {
      kind: 'react';
      targetMessageId: string;
      /** 空串 = 撤销该消息上本 bot 的表情。 */
      emoji: string;
      big?: boolean;
    }
  | { kind: 'typing' }
  | {
      kind: 'media';
      items: MessageOpMediaItem[];
      /** 2 张以上连续图片是否合成原生相册(客户端决定)。 */
      album?: boolean;
      replyToMessageId?: string | null;
    };

export interface MessageOpButton {
  /**
   * 客户端生成的回调 token; 服务端只做透传与一次性消费, 不解释语义。
   * `purpose: 'interaction-card'` 时它就是 interaction 的 buttonId: 服务端自己铸
   * callback_data 并记映射, 用户点按后照旧回 interaction.decision(buttonId=token)。
   */
  token: string;
  label: string;
}

export interface MessageOpMediaItem {
  name: string;
  mimeType: string;
  dataBase64: string;
  caption?: string;
}

/**
 * msg.op(desktop -> server): 驱动一次渠道消息操作。
 *
 * 服务端职责边界(哑执行器):
 *   1. 校验 scope.externalKey 落在该设备的绑定内(多租户授权, 不可下放客户端);
 *   2. 排进该 bot token 的全局限速队列, 尊重完整 retry_after(跨租户共享预算,
 *      必须中心化);
 *   3. 调用 Bot API, 按 opId 幂等;
 *   4. 回 msg.op.result 带上渠道 message id。
 * 除此之外**不解释内容**: 不分块、不套文案、不判断该发还是该编辑。
 */
export interface MessageOpPayload {
  /** 客户端生成的幂等键, 全局唯一; 重发同一 opId 不产生第二条消息。 */
  opId: string;
  /** 归属的 turn(用于日志关联与 lane 授权); 非 turn 语境可省略。 */
  requestId?: string;
  scope: MessageOpScope;
  action: MessageOpAction;
  /**
   * 这次操作在 turn 里承担什么角色(可选; 缺席 = 普通独立操作, 与本字段出现前
   * 的语义逐字相同)。见 MessageOpPurpose。
   */
  purpose?: MessageOpPurpose;
  /**
   * `purpose: 'turn-final'` 时必填(parse 强制): 这条是终稿的第几段(0 起)。
   * 0 是答案主体: 服务端按这一轮的回复引用策略挂触发消息(与服务端自己发终稿首段
   * 同一规则), 且它是续跑锚点的候选。其余 purpose 不得携带。
   */
  finalPart?: number;
  /** `purpose: 'interaction-card'` 时必填(parse 强制): 这张卡对应的 interactionId。 */
  interactionId?: string;
  /**
   * 只用于 `purpose: 'interaction-card'` 的 `edit`: 这是收口编辑(卡片已决 / 超时 /
   * 撤销)。服务端执行编辑后作废这张卡全部回调映射, 迟到的点按不再转成 decision。
   */
  interactionClosed?: boolean;
}

/**
 * msg.op 的角色标记。
 *
 * `'turn-progress'`: 驱动 `requestId` 那一轮的**进度消息**(客户端渲染的运行中
 * 过程消息)。仅在双方协商 HOOK_FEATURE_TELEGRAM_PROGRESS_OPS 后使用, 且必须带
 * `requestId`(parse 强制)。只用于 `send` / `edit`, `tier` 显式给 html / plain,
 * 不带按钮。服务端语义:
 *   - `send`: 核验 requestId 是该设备在 scope.externalKey 上**仍在运行**的一轮,
 *     把新建的消息登记为这一轮的进度消息(与旧 turn.progress 渲染登记的是同一个
 *     位置) —— 终稿仍由服务端按 turn.end 发布, 发布后照旧清理它(续跑轮: 原位
 *     修正旧终稿后清理本轮进度消息)。投递位置的副作用照旧由服务端负责: topic 由
 *     lane 记录取, `replyToMessageId` 缺席时按这一轮的「回复引用」策略挂到触发
 *     消息(含 `first` 档的消耗记账, 与旧进度消息逐字相同), `silent` 对应
 *     disable_notification;
 *   - `edit`: messageId 必须是这一轮登记过的进度消息;
 *   - 这一轮已收口 / 不认识 / 不属于该设备, 或这条 lane 的进度由服务端自己承载
 *     (私聊草稿 `TELEGRAM_DM_DRAFT_ENABLED`)时, 不调用 Bot API, 回
 *     `ok=false, errorCode=MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE`; 客户端据此
 *     停止本轮进度操作。
 *
 * `'turn-progress'` 也可用于 `delete`: 终稿落地后客户端尽力删掉本轮进度消息
 * (messageId 必须是这一轮登记过的进度消息; 服务端在 turn.end 收口时照旧兜底清理)。
 *
 * `'turn-final'`: 客户端发布 `requestId` 那一轮**成功**的终稿(HOOK_FEATURE_TELEGRAM_FINAL_OPS)。
 * 只用于 `send`(tier rich / html / plain), 必须带 `finalPart`; `finalPart=0` 是续跑锚点,
 * 只能是文字段。协议形状仍允许 `media`, 但服务端一律回 MESSAGE_OP_ERROR_UNSUPPORTED_PARAMETERS
 * —— 附件始终由服务端随 turn.end 发布, desktop 不发。服务端:
 *   - 核验这一轮仍在运行、属于该设备; turn.end 已到、不归该设备或私聊草稿模式(终稿随
 *     草稿通道由服务端发布)时回 MESSAGE_OP_ERROR_TURN_UNAVAILABLE;
 *   - 投递位置照旧由服务端决定(topic 取 lane; finalPart=0 按服务端终稿首段同一回复
 *     引用规则; 其余段不引用), 消息**会推送**(不带 disable_notification, 除非 silent);
 *   - 每条消息登记 botAuthored route(requestId 同一轮, 非 terminal), 并记为「客户端
 *     终稿段」—— 续跑锚点(terminal route)要等 turn.end 的 `clientFinal.complete`
 *     确认后才由服务端把 finalPart=0 那条提升上去(见 TurnEndPayload.clientFinal)。
 *
 * `'interaction-card'`: 客户端发布执行中交互卡(HOOK_FEATURE_TELEGRAM_CARD_OPS)。
 * 只用于 `send` / `edit`, 必须带 `interactionId`。正文与按钮布局全由客户端渲染;
 * 服务端:
 *   - 核验 requestId 是该设备仍在运行的一轮;
 *   - 投递位置沿用服务端现行规则: 私聊发到本 lane(按回复引用策略挂触发消息), 群 /
 *     topic 改投 owner 私聊并在正文前加服务端本地化的来源说明与原消息链接(HTML
 *     转义后前置; 这是投递面的注记, 不属于卡片内容);
 *   - 按钮: 每个 MessageOpButton.token 是 buttonId, 服务端铸 callback_data、记
 *     (requestId, interactionId, buttonId) 映射, 点按后照旧回 interaction.decision、
 *     清键盘、answerCallbackQuery; 回调映射的有效期与现行卡片相同;
 *   - `edit` 的 messageId 按 interactionId 记录核验(卡片可能已被改投 owner 私聊,
 *     不在本 lane 的 route 里); `interactionClosed: true` 时执行后作废回调映射;
 *   - 协商后客户端不再为这类卡发 interaction.request / interaction.cancel; 本轮
 *     turn.end 收口时服务端对仍未收口的客户端卡只作废回调、清键盘, 不改写正文。
 *
 * 幂等: 服务端按 opId + 内容指纹去重, **同一 opId 配不同内容**回
 * `MESSAGE_OP_ERROR_IDEMPOTENCY_CONFLICT`。所以回执未知时客户端必须原样重发
 * (同 opId 同正文), 不得沿用 opId 换正文。
 */
export type MessageOpPurpose = 'turn-progress' | 'turn-final' | 'interaction-card';

/*
 * msg.op.result.errorCode: 服务端**自己**判定的拒绝(未调用 Bot API, 或调用结果
 * 未知)。开放集合, 客户端只按码分支、不解析 error 文本; 不认识的码按"明确失败"
 * 处理。渠道 API 的拒绝不在这里, 走 channelErrorCode。
 */
/** 本轮进度不由客户端承载(私聊草稿 / 本轮已收口或不属于该设备)。客户端停止本轮进度 op。 */
export const MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE = 'PROGRESS_UNAVAILABLE';
/** 参数不在执行器支持范围内(契约错误)。客户端停止本轮同类 op, 不重试。 */
export const MESSAGE_OP_ERROR_UNSUPPORTED_PARAMETERS = 'UNSUPPORTED_PARAMETERS';
/** edit / delete 的 messageId 不属于该 lane / 该轮。客户端停止对这条消息的操作。 */
export const MESSAGE_OP_ERROR_MESSAGE_NOT_OWNED = 'MESSAGE_NOT_OWNED';
/** 设备的绑定已撤销或换代。客户端停止本轮 op。 */
export const MESSAGE_OP_ERROR_BINDING_REVOKED = 'BINDING_REVOKED';
/** 服务端限速队列拒收; 带 retryAfterMs, 客户端按它退避(与渠道 429 同处理)。 */
export const MESSAGE_OP_ERROR_RATE_LIMITED = 'RATE_LIMITED';
/** 同一 opId 配了不同内容。客户端的幂等记账出错, 按明确失败处理。 */
export const MESSAGE_OP_ERROR_IDEMPOTENCY_CONFLICT = 'IDEMPOTENCY_CONFLICT';
/** 服务端幂等记账已满, 拒收新操作(不淘汰旧回执)。明确未执行, 可换 opId 稍后再试。 */
export const MESSAGE_OP_ERROR_CAPACITY_REACHED = 'CAPACITY_REACHED';
/**
 * 已调用渠道 API 但拿不到确定结果(网络中断 / 5xx / 回执异常), 消息**可能已经落地**。
 * 客户端不得换 opId 重发同一内容: 只能原样重发同一 opId 对账。
 */
export const MESSAGE_OP_ERROR_OUTCOME_UNKNOWN = 'OUTCOME_UNKNOWN';
/** 渠道已执行但服务端登记失败(服务端已尽力撤回该消息)。明确失败, 可换 opId 重试。 */
export const MESSAGE_OP_ERROR_PERSIST_FAILED = 'PERSIST_FAILED';
/**
 * `turn-final` / `interaction-card`: 这一轮已收口(turn.end 已到)、不认识或不属于
 * 该设备。客户端停止本轮这类 op —— 终稿交回服务端按 turn.end 发布, 卡片交回
 * interaction.request 旧路径(本轮仍在跑时)。
 */
export const MESSAGE_OP_ERROR_TURN_UNAVAILABLE = 'TURN_UNAVAILABLE';

/**
 * 双向能力标识: 官方 Telegram 的运行中进度消息改由 desktop 渲染、经
 * `msg.op`(`purpose: 'turn-progress'`)驱动。必须与 HOOK_FEATURE_MESSAGE_OPS
 * 同时协商; 只在 telegram provider 的连接上声明。
 *
 * 协商后的分工(内容面在客户端, 投递面在服务端):
 *   - desktop 用与个人 bot 同一个过程载体与渲染(@cindy/im
 *     `startTelegramProgressCarrier` + `markdownToTelegramHtml`)生成 HTML, 首帧
 *     `send`、后续 `edit`; HTML 被拒(`channelErrorCode=400`)本地回落
 *     `tier: 'plain'`, `message is not modified` 视为成功, 429 按 `retryAfterMs`
 *     退避, 期间的新帧合并成最新一帧;
 *   - desktop **照发** turn.progress(服务端靠它续 turn lease), 但服务端**不再
 *     用它渲染**进度消息 —— 唯一例外是服务端仍自己承载进度的私聊草稿模式
 *     (此时进度 msg.op 回 PROGRESS_UNAVAILABLE, 服务端继续按 turn.progress 出草稿);
 *   - 终稿发布、进度消息清理、离线自治仍归服务端, 不随本能力改变。
 *
 * 任一侧缺席: desktop 只发 turn.progress, 服务端照旧渲染, 行为与本能力出现前
 * 逐字相同。
 */
export const HOOK_FEATURE_TELEGRAM_PROGRESS_OPS = 'telegram-progress-ops-v1';

/**
 * 双向能力标识: 官方 Telegram **成功轮次**的终稿由 desktop 用与个人 bot 同一套收口
 * (@cindy/im `startTelegramStreaming` 的 finalize: Rich → HTML → 纯文本、分块、落地后
 * 删进度消息)经 `msg.op`(`purpose: 'turn-final'`)发布。须与 HOOK_FEATURE_MESSAGE_OPS
 * 同时协商, 只在 telegram 连接上声明。
 *
 * **终稿必达不降级**: desktop 先把 turn.end 写进本地持久出箱, 再发布, 最后发 turn.end
 * 并用 `clientFinal` 说明结果。服务端只在 `clientFinal.complete === true` 时跳过自己
 * 渲染; 否则(未完成 / 缺席 / 重启后从出箱重放)删掉本轮已落地的客户端终稿段并照旧自己
 * 发布 —— 最坏是一次重新发布, 不会缺答案也不会两份并存。
 *
 * 只覆盖普通轮次、不带附件的 `status: 'ok'`。失败 / 取消 / 续跑轮(原位修正旧终稿)/
 * 正文恰为 NO_REPLY(ambient 判定在服务端)/ **带任何附件**时, desktop 不发 `turn-final`,
 * 由服务端按 turn.end 照旧处理; turn.end 带附件时服务端也不认 `clientFinal`(附件始终由
 * 服务端发送)。
 */
export const HOOK_FEATURE_TELEGRAM_FINAL_OPS = 'telegram-final-ops-v1';

/**
 * 双向能力标识: 官方 Telegram 执行中交互卡(ask / plan / 权限)由 desktop 用与个人 bot
 * 同一份卡片渲染(@cindy/im `layoutTelegramCard`: 标题 + markdown 正文 → HTML、正文上限、
 * 按钮成对排布)经 `msg.op`(`purpose: 'interaction-card'`)发布与收口; 按钮回调仍由
 * 服务端收入站并照旧回 interaction.decision。须与 HOOK_FEATURE_MESSAGE_OPS 同时协商。
 * 任一侧缺席: 走 interaction.request / interaction.cancel 旧路径, 服务端照旧渲染。
 */
export const HOOK_FEATURE_TELEGRAM_CARD_OPS = 'telegram-card-ops-v1';

/**
 * 双向能力标识: 官方 Telegram 的命令菜单以 desktop 的命令注册表为唯一真相源, 经
 * `provider.commands.set` 下发。任一侧缺席: 服务端照旧用自己的 TELEGRAM_COMMANDS。
 */
export const HOOK_FEATURE_TELEGRAM_COMMANDS = 'telegram-commands-v1';

/**
 * turn.end 的客户端终稿发布结果(只在协商 HOOK_FEATURE_TELEGRAM_FINAL_OPS、且 desktop
 * 尝试过 `turn-final` 时出现)。
 */
export interface TurnEndClientFinal {
  /**
   * true = 本轮全部终稿段都拿到了成功回执: 服务端不再渲染 finalText,
   * 把 finalPart=0 那条提升为续跑锚点(terminal route), 照常做收口副作用(群中继
   * —— 文本取本帧 finalText、消息 id 取锚点; 清理进度消息与未收口卡片; 终态表情;
   * inflight 移除)。
   * false = 发布没有完整确认: 服务端删掉本轮已登记的客户端终稿段(尽力), 再照旧自己发布。
   */
  complete: boolean;
}

/**
 * provider.commands.set(desktop -> server): 官方 Telegram 命令菜单
 * (HOOK_FEATURE_TELEGRAM_COMMANDS)。每次握手成功后发一次; 服务端**只存内存、不落库**,
 * 按 `{type:'chat', chat_id: principalId}` 作用域调用 setMyCommands。服务端只管理默认
 * 菜单与 zh / ja / ko, 每次全量重写(缺席的语言写空, 其它语言码含显式 'en' 忽略); 只有该
 * 设备当前仍协商本能力时才用它的菜单。服务端重启后到 desktop 重连前(以及设备离线期间)
 * 用服务端自己的默认菜单。服务端只校验形状与 Telegram 限制, 不改文案、不增删命令。
 */
export interface ProviderCommandsSetPayload {
  provider: 'telegram';
  /** 每个语言一份; languageCode=null 是不带 language_code 的默认菜单(必须有且仅有一份)。 */
  menus: TelegramCommandMenu[];
}

export interface TelegramCommandMenu {
  /** Telegram language_code(两位小写 ISO 639-1); null = 默认菜单。 */
  languageCode: string | null;
  /** 菜单顺序即展示顺序。command 1-32 位 [a-z0-9_]; description 1-256 字。至多 100 条。 */
  commands: Array<{ command: string; description: string }>;
}

/**
 * msg.op.result(server -> desktop): 一次消息操作的回执。
 *
 * `messageId` 是客户端做后续 edit / delete / react 的**唯一**依据 —— 没有它,
 * 整个动词集只能发不能改。失败时 `error` 说明原因; `retryAfterMs` 非空表示
 * 服务端限速队列建议的等待(客户端据此排后续 op, 不自行加固定上限)。
 */
export interface MessageOpResultPayload {
  opId: string;
  ok: boolean;
  /** send / media 成功时渠道返回的 message id(media 相册返回首条)。 */
  messageId?: string | null;
  /** 相册等一次产出多条时的完整 id 列表。 */
  messageIds?: string[];
  error?: string | null;
  retryAfterMs?: number | null;
  /**
   * 服务端自己判定的结构化拒绝码(开放集合; 缺席/null = 没有这类拒绝)。客户端只按
   * 码分支, 不解析 `error` 文本。已定义: MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE。
   */
  errorCode?: string | null;
  /**
   * 渠道 API 拒绝时的**原生**错误码(Telegram `error_code`, 如 400 / 429), 服务端
   * 原样透传、不翻译; 此时 `error` 为渠道原文 description。客户端据此做与个人 bot
   * 同判据的回落(HTML 被拒 400 → plain)。缺席/null = 不是渠道拒绝或老服务端。
   */
  channelErrorCode?: number | null;
}

/**
 * 内置「对话」伪工作目录的保留别名。desktop 恒把它放进 hello / query 的
 * workspaces 清单首位(绑定到它的任务以无项目目录的对话模式运行), 真实
 * 目录别名不许撞名(desktop 侧校验)。server 据此识别伪目录: 清单里只剩
 * 本别名(用户没配任何真实目录)时不走「单目录自动绑」捷径, 仍发选择卡
 * 让用户显式确认, 并提示去桌面端配置真实目录。
 */
export const HOOK_CHAT_WORKSPACE_ALIAS = 'chat';

/**
 * tool.request(desktop -> server): 调用 server 侧 Slack 网关工具。
 * tool 为开放集合(当前约定 'status' / 'listTools' / 'callTool'), server
 * 不认识的值回 UNKNOWN_TOOL 错误而非丢帧 —— 网关工具演进不需要协议升级。
 */
export interface ToolRequestPayload {
  /** desktop 生成的关联 id; tool.response.replyTo 回显配对。 */
  requestId: string;
  /** 网关工具名(开放集合)。 */
  tool: string;
  /** 工具参数(如 callTool 的 { name, arguments }); 省略 = 无参。 */
  args?: Record<string, unknown>;
  /**
   * (multi-team)以哪个 workspace 的绑定身份执行。缺省/null = 设备唯一
   * 绑定; 多绑定设备缺省时 server 拒绝猜测, 回结构化错误 AMBIGUOUS_TEAM
   * —— 以错误身份向错误 workspace 发消息是本帧族最重的串台风险(规则 9)。
   */
  teamId?: string | null;
}

/**
 * 网关工具的结构化错误。code 是机器可读错误码(如 NOT_BOUND / NO_USER_TOKEN /
 * UNKNOWN_TOOL / TOKEN_EXPIRED / RATE_LIMITED), desktop 按 code 分支提示,
 * message 仅人类可读补充 —— 两端都不得解析 message 做逻辑(规则 9)。
 */
export interface ToolErrorShape {
  code: string;
  message: string;
}

/**
 * tool.response(server -> desktop): tool.request 的应答。
 * 字段联动(parse 强制): ok=false 时 error 必须为非空 {code, message};
 * ok=true 时 error 必须缺席或 null(result 形状由具体工具约定, 协议不限)。
 */
export interface ToolResponsePayload {
  /** 回显 tool.request.requestId。 */
  replyTo: string;
  ok: boolean;
  /** ok=true 时的结果(任意 JSON; listTools/callTool 透传 MCP 结果语义)。 */
  result?: unknown;
  /** ok=false 时的结构化错误。 */
  error?: ToolErrorShape | null;
}

// ── 阶段 14: 群消息中继(group-relay-v1) ─────────────────────────────────────

/**
 * 双向能力标识: 群消息实时中继。desktop 在 hello.features 声明会消费
 * group.message 帧(本地维护群上下文窗口); server 在 welcome.features 声明
 * 支持。任一侧缺席则 server 不转发, desktop 无群上下文(引用注入不受影响)。
 *
 * 设计边界(2026-07-28 决策): 群聊内容**不得驻留在 server**(内存亦不允许),
 * server 收到群消息后对已声明本能力的成员桌面转发即弃; 滚动窗口、增量游标与
 * 上下文拼装全部在 desktop 本地完成 —— 与 Slack 通道「平台即存储」同构,
 * Telegram 无历史 API, 存储方为用户自己的设备。
 */
export const HOOK_FEATURE_GROUP_RELAY = 'group-relay-v1';

/**
 * group.message 接收方代际标识。双方同时声明后,server 必须按实际扇出目标
 * 填充 recipient,desktop 必须与当前 confirmed binding 精确匹配后才可入窗。
 * 这是独立能力而不是静默改写 group-relay-v1:旧帧没有可信接收方身份,
 * 新 desktop 对缺席本能力的 server 只能安全降级为不落群历史。
 */
export const HOOK_FEATURE_GROUP_RELAY_RECIPIENT = 'group-relay-recipient-v1';

/**
 * group.message 的发送者标识(display name 为主)。
 * id / username 均可选(旧生产端不发时省略, 向后兼容): 新生产端(阶段 19
 * 起, provider.behavior 需要按发送者匹配群白名单以外的场景)可附带平台
 * user id 与 @handle。二者按 Telegram 当前实际契约收紧校验(group.message
 * 本身仍是开放 provider 集合, 但这两个新字段目前只有 Telegram 生产端会填,
 * 形状即按 Telegram 定义; 未来若有其它 provider 要填这两个字段且形状不同,
 * 需要重新评估这里的校验, 而不是放宽成万能字符串):
 *   - id: Telegram 数字 user id 的规范十进制正整数字符串(无前导零,在 Bot API
 *     52-bit 范围内), 见 GROUP_MESSAGE_AUTHOR_ID_PATTERN;
 *   - username: Telegram @handle, 仅 [A-Za-z0-9_],1~32 位, 见
 *     GROUP_MESSAGE_AUTHOR_USERNAME_PATTERN。
 */
export interface GroupMessageAuthor {
  name: string;
  /** 是否为 bot(含 Cindy 自身出站回复的回流条目)。 */
  isBot?: boolean;
  /** Telegram 数字 user id 的规范十进制正整数字符串(52-bit 范围内); 拿不到时省略。 */
  id?: string;
  /** Telegram @handle(不含 @ 前缀, [A-Za-z0-9_]{1,32}); 拿不到时省略。 */
  username?: string;
}

/** server 针对单个 desktop 扇出 group.message 时的权威接收方绑定。 */
export interface GroupMessageRecipient {
  bindingId: string;
  principalId: string;
}

/**
 * group.message(server -> desktop): 把一条群消息实时转发给该群已知绑定
 * 成员的桌面, fire-and-forget(无 ack, 桌面离线即丢 —— 零驻留的固有代价)。
 * chatId/threadId/messageId 是反查 id: task.dispatch 的引用块与桌面窗口
 * 条目按同一组 id 关联, prompt 缺失上下文时 agent 可按 id 查本地窗口兜底。
 * 一次性凭证(如 Telegram 绑定深链 /start <token>)由 server 过滤, 不转发。
 */
export interface GroupMessageImageRef {
  fileId: string;
  name: string;
  mimeType: string;
  /** Recipient-bound proof for POST /telegram/group-image; never a bot token. */
  downloadToken?: string;
}

export interface GroupMessagePayload {
  /** IM 平台标识(开放集合, 当前 'telegram')。 */
  provider: string;
  /**
   * 本帧实际路由到的绑定代际;仅在双方协商
   * HOOK_FEATURE_GROUP_RELAY_RECIPIENT 后必填。旧生产端缺省以保持 wire 兼容。
   */
  recipient?: GroupMessageRecipient;
  chatId: string;
  /** forum topic / thread id; null = 主群流。 */
  threadId: string | null;
  messageId: string;
  /** 群显示名; null = 未知。 */
  chatName: string | null;
  author: GroupMessageAuthor;
  /** 正文(生产端截断后 ≤4k 字符; 可为空字符串, 如纯附件消息)。 */
  text: string;
  /** 附件文件名列表(仅名字, 不携带字节; 桌面窗口行内标注用)。 */
  fileNames?: string[];
  imageRefs?: GroupMessageImageRef[];
  /** 消息在 IM 平台的发送时刻(unix ms)。 */
  sentAt: number;
}

// ── 消息联合 ─────────────────────────────────────────────────────────────────

export type HookHelloMessage = HookEnvelope<'hello', HelloPayload>;
export type HookWelcomeMessage = HookEnvelope<'welcome', WelcomePayload>;
export type HookPingMessage = HookEnvelope<'ping', PingPayload>;
export type HookPongMessage = HookEnvelope<'pong', PongPayload>;
export type HookTaskDispatchMessage = HookEnvelope<'task.dispatch', TaskDispatchPayload>;
export type HookTaskAckMessage = HookEnvelope<'task.ack', TaskAckPayload>;
export type HookTurnEndMessage = HookEnvelope<'turn.end', TurnEndPayload>;
export type HookTurnDeliveryMessage = HookEnvelope<'turn.delivery', TurnDeliveryPayload>;
export type HookTurnProgressMessage = HookEnvelope<'turn.progress', TurnProgressPayload>;
export type HookMessageOpMessage = HookEnvelope<'msg.op', MessageOpPayload>;
export type HookMessageOpResultMessage = HookEnvelope<'msg.op.result', MessageOpResultPayload>;
export type HookTurnReopenMessage = HookEnvelope<'turn.reopen', TurnReopenPayload>;
export type HookBindStartMessage = HookEnvelope<'bind.start', BindStartPayload>;
export type HookBindUpdateMessage = HookEnvelope<'bind.update', BindUpdatePayload>;
export type HookBindRevokeMessage = HookEnvelope<'bind.revoke', BindRevokePayload>;
export type HookQueryRequestMessage = HookEnvelope<'query.request', QueryRequestPayload>;
export type HookQueryResponseMessage = HookEnvelope<'query.response', QueryResponsePayload>;
export type HookTaskCancelMessage = HookEnvelope<'task.cancel', TaskCancelPayload>;
export type HookSessionArchiveMessage = HookEnvelope<'session.archive', SessionArchivePayload>;
export type HookInteractionRequestMessage = HookEnvelope<
  'interaction.request',
  InteractionRequestPayload
>;
export type HookInteractionDecisionMessage = HookEnvelope<
  'interaction.decision',
  InteractionDecisionPayload
>;
export type HookInteractionCancelMessage = HookEnvelope<
  'interaction.cancel',
  InteractionCancelPayload
>;
export type HookPrefsGetMessage = HookEnvelope<'prefs.get', PrefsGetPayload>;
export type HookPrefsSetMessage = HookEnvelope<'prefs.set', PrefsSetPayload>;
export type HookPrefsStateMessage = HookEnvelope<'prefs.state', PrefsStatePayload>;
export type HookToolRequestMessage = HookEnvelope<'tool.request', ToolRequestPayload>;
export type HookToolResponseMessage = HookEnvelope<'tool.response', ToolResponsePayload>;
export type HookBindStateMessage = HookEnvelope<'bind.state', BindStatePayload>;
export type HookProviderBindStartMessage = HookEnvelope<
  'provider.bind.start',
  ProviderBindStartPayload
>;
export type HookProviderBindCancelMessage = HookEnvelope<
  'provider.bind.cancel',
  ProviderBindCancelPayload
>;
export type HookProviderBindRevokeMessage = HookEnvelope<
  'provider.bind.revoke',
  ProviderBindRevokePayload
>;
export type HookProviderBindUpdateMessage = HookEnvelope<
  'provider.bind.update',
  ProviderBindUpdatePayload
>;
export type HookProviderBindStateMessage = HookEnvelope<
  'provider.bind.state',
  ProviderBindStatePayload
>;
export type HookProviderPrefsGetMessage = HookEnvelope<
  'provider.prefs.get',
  ProviderPrefsGetPayload
>;
export type HookProviderPrefsSetMessage = HookEnvelope<
  'provider.prefs.set',
  ProviderPrefsSetPayload
>;
export type HookProviderPrefsStateMessage = HookEnvelope<
  'provider.prefs.state',
  ProviderPrefsStatePayload
>;
export type HookGroupMessageMessage = HookEnvelope<'group.message', GroupMessagePayload>;
export type HookLifecyclePreferenceMessage = HookEnvelope<
  'lifecycle.preference',
  LifecyclePreferencePayload
>;
export type HookProviderBehaviorGetMessage = HookEnvelope<
  'provider.behavior.get',
  ProviderBehaviorGetPayload
>;
export type HookProviderBehaviorSetMessage = HookEnvelope<
  'provider.behavior.set',
  ProviderBehaviorSetPayload
>;
export type HookProviderCommandsSetMessage = HookEnvelope<
  'provider.commands.set',
  ProviderCommandsSetPayload
>;
export type HookProviderBehaviorStateMessage = HookEnvelope<
  'provider.behavior.state',
  ProviderBehaviorStatePayload
>;

/** 全部合法消息的判别联合(按 `type` 判别)。 */
export type HookMessage =
  | HookHelloMessage
  | HookWelcomeMessage
  | HookPingMessage
  | HookPongMessage
  | HookTaskDispatchMessage
  | HookTaskAckMessage
  | HookTurnEndMessage
  | HookTurnDeliveryMessage
  | HookTurnProgressMessage
  | HookTurnReopenMessage
  | HookBindStartMessage
  | HookBindUpdateMessage
  | HookBindRevokeMessage
  | HookQueryRequestMessage
  | HookQueryResponseMessage
  | HookTaskCancelMessage
  | HookSessionArchiveMessage
  | HookInteractionRequestMessage
  | HookInteractionDecisionMessage
  | HookInteractionCancelMessage
  | HookPrefsGetMessage
  | HookPrefsSetMessage
  | HookPrefsStateMessage
  | HookToolRequestMessage
  | HookToolResponseMessage
  | HookBindStateMessage
  | HookProviderBindStartMessage
  | HookProviderBindCancelMessage
  | HookProviderBindRevokeMessage
  | HookProviderBindUpdateMessage
  | HookProviderBindStateMessage
  | HookProviderPrefsGetMessage
  | HookProviderPrefsSetMessage
  | HookProviderPrefsStateMessage
  | HookGroupMessageMessage
  | HookLifecyclePreferenceMessage
  | HookProviderBehaviorGetMessage
  | HookProviderBehaviorSetMessage
  | HookProviderBehaviorStateMessage
  | HookProviderCommandsSetMessage
  | HookMessageOpMessage
  | HookMessageOpResultMessage;

/** parseHookMessage 的结果 —— 不抛异常, 坏帧以 error 字符串描述具体原因。 */
export type HookParseResult = { ok: true; message: HookMessage } | { ok: false; error: string };