/**
 * 接管平台会话：从投递事件里取出「要投进哪条平台会话」并给出统一的失败话术。
 *
 * # 这件事是什么
 *
 * TUI 与邮箱是同一个 Agent 的**两个入口**，不是两套隔离的世界。人在平台界面上
 * 开的会话（opencode 的 session、DSH 的 agent、pi 的 .jsonl）早就被
 * session-snapshot 上报成候选，写信时能在补全里选中；此前投递侧没有这一跳，
 * 选中后只能得到 404 —— 候选列表在承诺一件做不到的事。
 *
 * 服务端在本侧建一条会话并记下 `platform_id`（「接管」），随后每次投递都在
 * 事件里带上 `platform_session_id`。插件看到它就去那条平台会话里接着谈，
 * **不新建** —— 新建会让人在界面上看不到这封邮件带来的对话，而那正是接管的目的。
 *
 * # 为什么这两个函数要三平台共用
 *
 * 字段名与失败话术是**对外契约**：字段名各写一遍，少个下划线就静默退化成
 * 「每封邮件新开一条会话」，而那个错误不报任何异常；话术各写一遍，同一个
 * 处境在三个平台上说三种话，模型学不到「该改用 .new」这个动作。
 *
 * 三平台的**接管机制**不共用（服务端持有会话 / 磁盘 replay / 文件 open 各不
 * 相同），只有这两件事共用。
 */

/**
 * 从投递事件里取出被接管的平台会话 id。
 *
 * @param {any} data new_mail / permission_decided 事件的 payload
 * @returns {string} 平台会话 id；空串 = 不是接管，照旧按邮件新开一条
 */
export function adoptedSessionID(data) {
  const raw = data?.platform_session_id;
  return typeof raw === 'string' ? raw.trim() : '';
}

/**
 * 平台侧那条会话已经不在了时的错误话术。
 *
 * 镜像是快照，可以过期：人可能已经在界面上删了那条会话。
 *
 * **不能退回「新建一条」**：那会让人在界面上看不到这封邮件带来的对话，
 * 而发件人以为投进去了。静默改语义比报错糟得多（与 N-8「404 后自动改用
 * .new 是禁止的」同一条原则）。
 *
 * 话术必须给出可执行的下一步：只说「不存在」的话，模型会原地重试同一个地址。
 *
 * @param {string} platformID
 * @param {string} [detail] 平台特有的补充说明，如「可能已在界面上删除」
 * @returns {string}
 */
export function adoptMissingMessage(platformID, detail = '可能已被删除') {
  return `平台会话 ${platformID} 已不存在（${detail}）。` +
    `请用 name@path.new 新开一条会话，或换一个仍然存在的会话别名。`;
}