MailUI4Agents/plugins/opencode-mail-bridge/index.js

import { z } from "zod";
import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
import { randomBytes } from "node:crypto";
import { homedir } from "node:os";
import { join, dirname, basename } from "node:path";
// 自动转发去重的纯逻辑放在 lib/ 里：opencode 会把入口模块的每一个导出
// 都当成插件工厂，入口文件多导出一个东西就会 "Plugin export is not a function"。
import { snapshotOpencodeSessions } from "./lib/session-snapshot.js";
import { resolveWorkspaceCwd } from "./lib/workspace.js";
import { selectCatchup } from "./lib/catchup.js";
import {
  snapshotOpencodeModels,
  modelAttemptOrder,
  renderFailureReport,
} from "./lib/model-scope.js";
import {
  renderInbox,
  idsToMarkRead,
  formatSize,
  DEFAULT_INBOX_STATUS,
  DEFAULT_INBOX_LIMIT,
} from "./lib/inbox-format.js";
import {
  renderNameSuggestions,
  renderPathSuggestions,
  renderSessionSuggestions,
  renderParticipants,
  renderContacts,
  renderThread,
} from "./lib/discovery.js";
import {
  explicitSends,
  noteExplicitSend,
  shouldSkipAutoRelay,
} from "./lib/relay-dedup.js";

const GATEWAY_URL = process.env.AGENTMAIL_GATEWAY_URL || "http://127.0.0.1:8180";
const AGENT_NAME = process.env.AGENTMAIL_AGENT_NAME || "opencode";
// 收到邮件后自动开会话处理时使用的模型
const REPLY_PROVIDER = process.env.AGENTMAIL_REPLY_PROVIDER || "llmsproxy";
const REPLY_MODEL = process.env.AGENTMAIL_REPLY_MODEL || "AUTO";

// ─── 凭证 ───
//
// 优先用 Agent 密钥（Authorization: Bearer）。密钥来源按优先级：
//   1. AGENTMAIL_AGENT_KEY 环境变量（systemd 部署走这条）
//   2. ~/.agentmail/agent.key（首次安装时本地生成并落盘）
// 没有密钥时退回旧的 name/secret 方式，保证老配置不被这次改动打断。

const CONFIG_DIR = process.env.AGENTMAIL_CONFIG_DIR || join(homedir(), ".agentmail");
const KEY_FILE = join(CONFIG_DIR, "agent.key");
const CONFIG_FILE = join(CONFIG_DIR, "config.json");

const AGENT_SECRET = process.env.AGENTMAIL_AGENT_SECRET || "";

/** 读取本地密钥文件；不存在或损坏时返回 null。 */
function readLocalKey() {
  try {
    if (!existsSync(KEY_FILE)) return null;
    const raw = JSON.parse(readFileSync(KEY_FILE, "utf8"));
    return typeof raw?.key_token === "string" && raw.key_token ? raw.key_token : null;
  } catch {
    return null;
  }
}

/** 首次安装时本地生成密钥并落盘（0600）。 */
function generateLocalKey() {
  const token = randomBytes(32).toString("hex");
  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
  writeFileSync(
    KEY_FILE,
    JSON.stringify({ key_token: token, created_at: new Date().toISOString() }, null, 2),
    { mode: 0o600 }
  );
  console.error(`[mail-bridge] 已在 ${KEY_FILE} 生成本地密钥。`);
  console.error(`[mail-bridge] 该密钥需管理员在 AgentMail 后台登记后才能接入：`);
  console.error(`[mail-bridge]   ${token}`);
  return token;
}

/** 把 gateway 地址与密钥记到 config.json，便于换机时人工核对。 */
function saveConfig(extra) {
  try {
    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
    let cur = {};
    if (existsSync(CONFIG_FILE)) {
      try { cur = JSON.parse(readFileSync(CONFIG_FILE, "utf8")); } catch { /* 损坏就重写 */ }
    }
    writeFileSync(
      CONFIG_FILE,
      JSON.stringify({ ...cur, gateway_url: GATEWAY_URL, agent_name: AGENT_NAME, ...extra }, null, 2),
      { mode: 0o600 }
    );
  } catch (e) {
    console.error("[mail-bridge] 写 config.json 失败:", e?.message || e);
  }
}

// 当前生效的密钥：环境变量 > 本地文件 > 无（退回 name/secret）
let AGENT_KEY = process.env.AGENTMAIL_AGENT_KEY || readLocalKey() || "";

/** 认证头：有密钥走 Bearer，否则退回 name/secret。 */
function authHeaders() {
  if (AGENT_KEY) {
    return { Authorization: `Bearer ${AGENT_KEY}`, "X-Agent-Name": AGENT_NAME };
  }
  return { "X-Agent-Name": AGENT_NAME, "X-Agent-Secret": AGENT_SECRET };
}

// ─── HTTP ───

async function apiGet(path) {
  const res = await fetch(`${GATEWAY_URL}/api/v1${path}`, { headers: authHeaders() });
  if (!res.ok) throw new Error(`GET ${path} failed: ${res.status}`);
  return res.json();
}

async function apiPost(path, body) {
  const res = await fetch(`${GATEWAY_URL}/api/v1${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...authHeaders() },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) throw new Error(data.error || `POST ${path} failed: ${res.status}`);
  return data;
}

// 把 opencode 侧的会话标题/slug 回写到 AgentMail。
// opencode 会在首轮对话后由模型生成会话标题，并配一个短 slug（如 jolly-cactus）——
// 不在 AgentMail 侧另造一套命名，平台那边叫什么，这边的 session_alias 就叫什么。
async function syncSessionNaming(mailSessionID, { alias, title }) {
  if (!mailSessionID) return null;
  if (!alias && !title) return null;
  try {
    const res = await apiPost(`/sessions/${mailSessionID}/sync`, {
      alias: alias || "",
      title: title || "",
    });
    return res;
  } catch (e) {
    // 同步是后台润色，失败不该影响邮件主流程，但必须留痕
    console.error("[mail-bridge] 会话命名同步失败:", e?.message || e);
    return null;
  }
}

// ─── Tools（直接用 zod 定义，不依赖 @opencode-ai/plugin） ───

const sendMailTool = {
  description: "发送邮件。三维地址 name@path.session：省略 session 投递到默认会话，.new 强制新建会话，.具体别名 必须是已存在的会话（否则无法送达）。回复来信请传 reply_to。",
  args: {
    to: z.string().describe("收件人：name / name@path（默认会话）/ name@path.new（新建）/ name@path.别名（已有会话）"),
    subject: z.string().describe("邮件主题"),
    body: z.string().describe("邮件正文（Markdown）"),
    cc: z.string().optional().describe("抄送，逗号分隔多个三维地址"),
    reply_to: z.string().optional().describe("回复某封邮件时传其 mail_id，回信会落回同一会话"),
    session_alias: z.string().optional().describe("仅在用 .new 新建会话时生效：给新会话命名，之后可用 name@path.<别名> 续谈。别名全局唯一，不可含 . / @ 空白，不可为 new"),
    attachment_ids: z.array(z.string()).optional().describe("附件 ID 列表，先用 upload_attachment 上传取得"),
    propose_alias: z.string()
      .optional()
      .describe(
        "建议把当前会话改名成这个别名（例如摸清问题后从 witty-planet 改成 fix-login-leak）。" +
        "这只是建议：别名是人的寻址入口，实际改名由用户在界面上确认。不可含 . / @ 空白，不可为 new"
      ),
    propose_reason: z.string().optional().describe("改名理由，一句话，展示给用户看"),
  },
  // context 带 sessionID：用它记下「模型这一轮亲手发过信」，
  // 让 session.idle 的自动转发让位，避免同一件事发两封。
  async execute(args, context) {
    // 改名建议以 HTML 注释形式附在正文末尾，由网关解析后剥离。
    // 选注释而不是自造标记：react-markdown 不解析 raw HTML，
    // 万一网关没剥掉，它在页面上也只是一行不显眼的转义文本而非破版内容。
    let body = args.body;
    if (args.propose_alias) {
      const esc = (v) => String(v).replace(/"/g, "");  // 双引号是标记的定界符
      const reason = args.propose_reason ? ` reason="${esc(args.propose_reason)}"` : "";
      body += `\n\n<!-- agentmail:rename-session alias="${esc(args.propose_alias)}"${reason} -->`;
    }

    const result = await apiPost("/mail/send", {
      to: args.to,
      subject: args.subject,
      body,
      cc: args.cc || "",
      reply_to: args.reply_to || "",
      session_alias: args.session_alias || "",
      attachment_ids: args.attachment_ids || [],
    });

    // 发成功后才记：失败的调用不该压掉自动转发 ——
    // 那种情况下模型的结论还没送出去，自动转发正是兜底
    noteExplicitSend(context?.sessionID, args.to, args.reply_to);
    const alias = result.session_alias
      ? `，会话别名 ${result.session_alias}（续谈可用 ${args.to.split(".")[0]}.${result.session_alias}）`
      : "";
    // 本任务的剩余往返必须回给模型：不然它只能撞到 403 才知道额度用完。
    // 注意这是【这条线索】的预算，不是 Agent 的终身额度 ——
    // 换一个任务就是另一份预算。
    const budget =
      typeof result.budget_remaining === "number"
        ? `\n本任务剩余 ${result.budget_remaining}/${result.budget_max} 个来回。` +
          (result.budget_remaining <= 1
            ? "预算即将用尽，请尽快给出结论；自动转发的总结不占预算。"
            : "")
        : "";
    // 回传规范化后的别名：Agent 提的名字可能含非法字符被改写过
    const proposed = result.rename_proposed
      ? `\n已向用户提议把会话改名为 ${result.rename_proposed}，等待其确认。`
      : "";
    return `已发送。Mail ID: ${result.mail_id}，Session: ${result.session_id}${alias}${budget}${proposed}`;
  },
};

const forwardMailTool = {
  description:
    "转发一封邮件给新的收件人（引用原文）。与回复不同：回复落回原会话，转发按目标地址另行定位会话。" +
    "只能转发自己参与过的邮件。",
  args: {
    mail_id: z.string().describe("要转发的邮件 ID（从 read_inbox 获得）"),
    to: z.string().describe("新收件人的三维地址"),
    comment: z.string().optional().describe("转发说明，置于引用原文之前"),
    cc: z.string().optional().describe("抄送，逗号分隔多个三维地址"),
    subject: z.string().optional().describe("自定义主题；留空则自动加 Fwd: 前缀"),
    session_alias: z.string().optional().describe("仅在目标地址以 .new 结尾时生效：给新会话命名"),
  },
  async execute(args) {
    const result = await apiPost(`/mail/${args.mail_id}/forward`, {
      to: args.to,
      comment: args.comment || "",
      cc: args.cc || "",
      subject: args.subject || "",
      session_alias: args.session_alias || "",
    });
    return `已转发。新 Mail ID: ${result.mail_id}，Session: ${result.session_id}`;
  },
};

const readInboxTool = {
  description: "查阅收件箱中的邮件。收到新邮件通知后应立即调用此工具。",
  args: {
    filter: z.enum(["unread", "all"]).optional().describe("过滤条件，默认 unread"),
    limit: z.number().optional().describe("返回数量，默认 5"),
  },
  async execute(args) {
    const filter = args.filter || DEFAULT_INBOX_STATUS;
    const limit = args.limit || DEFAULT_INBOX_LIMIT;
    const data = await apiGet(`/mail/inbox?status=${filter}&limit=${limit}`);

    // 渲染与已读策略放 lib/inbox-format.js：它们与平台 SDK 无关，
    // 各平台插件必须一致（见该文件里每条规则对应的错误行为）。
    //
    // 传 AGENT_NAME 是为了让渲染能判定「我是收件人还是抄送方」并给出
    // 可投递地址 —— 不传的话模型只能从抄送行里抄一个 `.new`，而那是
    // 一次性的，回过去只会再建一条平行会话。
    const listed = renderInbox(data.mails, 200, AGENT_NAME);

    const ids = idsToMarkRead(args.filter, data.mails);
    if (ids.length) {
      // 标记失败不该让 read_inbox 失败 —— 正文已经取到了，
      // 代价只是下次会重复看到，比丢掉这次读取轻。
      apiPost("/mail/read", { mail_ids: ids }).catch(e =>
        console.error("[mail-bridge] 标记已读失败:", e?.message || e)
      );
    }
    return listed;
  },
};

const uploadAttachmentTool = {
  description:
    "上传本地文件作为邮件附件，返回 attachment_id。" +
    "拿到 id 后在 send_mail 的 attachment_ids 里带上，附件才会随邮件发出。" +
    "未随邮件发出的附件 24 小时后自动清理。",
  args: {
    path: z.string().describe("要上传的本地文件绝对路径"),
    filename: z.string().optional().describe("自定义展示文件名，默认取路径的最后一段"),
  },
  async execute(args) {
    const filePath = args.path;
    let stat;
    try {
      stat = statSync(filePath);
    } catch {
      return `文件不存在或不可读: ${filePath}`;
    }
    if (!stat.isFile()) return `不是普通文件: ${filePath}`;

    const name = args.filename || basename(filePath);
    // Node 的 Blob 需要完整读入内存。附件上限 25MB，一次性读入可接受；
    // 若将来放宽上限，这里要换成流式 multipart。
    const buf = readFileSync(filePath);
    const form = new FormData();
    form.append("file", new Blob([buf]), name);

    const res = await fetch(`${GATEWAY_URL}/api/v1/attachments`, {
      method: "POST",
      headers: authHeaders(), // 不设 Content-Type，交给 FormData 自己带 boundary
      body: form,
    });
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new Error(data.error || `上传失败: ${res.status}`);

    const a = data.attachment;
    return `已上传 ${a.filename}（${formatSize(a.size_bytes)}）。attachment_id: ${a.attachment_id}\n` +
      `在 send_mail 的 attachment_ids 里带上这个 id 才会随邮件发出。`;
  },
};

const downloadAttachmentTool = {
  description: "下载邮件附件到本地文件。attachment_id 从 read_inbox 的附件清单里取。",
  args: {
    attachment_id: z.string().describe("附件 ID"),
    save_to: z.string().describe("保存到的本地绝对路径"),
  },
  async execute(args) {
    const res = await fetch(`${GATEWAY_URL}/api/v1/attachments/${args.attachment_id}`, {
      headers: authHeaders(),
    });
    if (!res.ok) {
      const data = await res.json().catch(() => ({}));
      throw new Error(data.error || `下载失败: ${res.status}`);
    }
    const buf = Buffer.from(await res.arrayBuffer());
    mkdirSync(dirname(args.save_to), { recursive: true });
    writeFileSync(args.save_to, buf);
    return `已保存到 ${args.save_to}（${formatSize(buf.length)}）`;
  },
};

// ─── 寻址发现工具（读 Agent 侧只读端点）───
//
// 在这一组之前，send_mail 的 to 是个只能靠记忆拼写的自由文本字段。人类侧
// 从来不是这样：三段式输入框逐段查候选。Agent 只能猜，而猜错不报错 ——
// 生产上 dsh 猜了 `opencode@/home`，投递成功，但那不是 opencode 的工作目录，
// 那个错误路径静默变成了新会话的 workspace。
//
// 渲染逻辑在 lib/discovery.js（与平台 SDK 无关，三平台共用）。

const suggestAddressTool = {
  description:
    "查询可用的收件人地址，用于精准发信。分三段逐步查：不带参数给候选收件人名；" +
    "带 name 给它可用的工作目录；name+path 都带则给该目录下可续谈的会话别名与现成地址。" +
    "**发信前应先用它确认地址**，不要凭记忆拼写 —— 拼错不会报错，只会投到别的会话。",
  args: {
    name: z.string().optional().describe("收件人名；留空则列出所有候选收件人"),
    path: z.string().optional().describe("工作目录；与 name 同时给出才列会话"),
  },
  async execute(args) {
    const name = (args.name || "").trim();
    const path = (args.path || "").trim();
    const qs = new URLSearchParams();
    if (name) qs.set("name", name);
    if (path) qs.set("path", path);
    const data = await apiGet(`/agent/contacts/suggest?${qs.toString()}`);

    // 按服务端回的 kind 分派，而不是按本地参数判断：省略 path 与传空串在
    // 服务端是同一个意思，但「哪一段该渲染成什么」只有服务端知道。
    switch (data?.kind) {
      case "name":
        return renderNameSuggestions(data.suggestions);
      case "path":
        return renderPathSuggestions(data.suggestions, name);
      default:
        return renderSessionSuggestions(data, name, path);
    }
  },
};

const listContactsTool = {
  description:
    "列出自己参与过的全部会话及各自的可投递地址、未读数、剩余往返预算。" +
    "用于回答「我还有什么没处理」以及「上次跟某人聊的那条线索地址是什么」。",
  args: {
    limit: z.number().optional().describe("最多列出多少条，默认 20"),
  },
  async execute(args) {
    const data = await apiGet("/agent/contacts");
    return renderContacts(data, args.limit || 20);
  },
};

const sessionParticipantsTool = {
  description:
    "列出某条会话的全部参与方（发件人/收件人/抄送方）及各自的可投递地址，" +
    "并标出谁还没回应。**要回给抄收方或向第三方转达时先用它拿地址**。",
  args: {
    session_id: z.string().describe("会话 ID（read_inbox 未直接给出时可从 read_thread 或新邮件通知取得）"),
  },
  async execute(args) {
    const data = await apiGet(`/agent/sessions/${args.session_id}/participants`);
    return renderParticipants(data);
  },
};

const readThreadTool = {
  description:
    "查看一封邮件所在线索的完整往来（谁回了谁、谁还没回）。多方抄送协作时" +
    "用它确认别人已经说了什么，避免重复提问或重复汇报。",
  args: {
    mail_id: z.string().describe("线索中任一封邮件的 ID"),
    offset: z.number().optional().describe("分页偏移，续取时传上次返回的 next_offset"),
  },
  async execute(args) {
    const qs = args.offset ? `?offset=${args.offset}` : "";
    const data = await apiGet(`/agent/mail/${args.mail_id}/thread${qs}`);
    return renderThread(data, AGENT_NAME);
  },
};

const readMailTool = {
  description:
    "读一封邮件的完整内容，含收件人、抄送清单、附件与每个参与方的可投递地址。" +
    "收件箱只给摘要；要回给抄收方就得先看清这封信发给了谁。",
  args: {
    mail_id: z.string().describe("邮件 ID"),
  },
  async execute(args) {
    const data = await apiGet(`/agent/mail/${args.mail_id}`);
    const m = data?.mail || {};
    const lines = [
      `发件人: ${m.from_name || "?"}`,
      `收件人: ${m.to_name || "?"}${m.to_workspace ? "@" + m.to_workspace : ""}`,
      `主题: ${m.subject || "(无主题)"}`,
      `会话: #${data.session_alias || "未命名"}（session_id: ${m.session_id || "?"}）`,
    ];
    if (Array.isArray(m.cc_list) && m.cc_list.length) {
      lines.push(`抄送: ${m.cc_list.map(c => c?.raw || c?.name).join("、")}`);
    }
    if (Array.isArray(m.attachments) && m.attachments.length) {
      lines.push(
        `附件: ${m.attachments
          .map(a => `${a.filename}（${formatSize(a.size_bytes)}, id=${a.attachment_id}）`)
          .join("、")}`
      );
    }
    lines.push("", m.body || "(空正文)", "");
    // 参与方地址由服务端拼好（session 位已是真实别名，不是 .new）
    if (Array.isArray(data.participants) && data.participants.length) {
      lines.push(
        "可投递地址: " +
          data.participants
            .filter(p => p.address && p.name !== AGENT_NAME)
            .map(p => `${p.address}（${p.role}）`)
            .join("、")
      );
    }
    if (data.reply_address) {
      lines.push(`回信给发件人用 ${data.reply_address}，或传 reply_to=${m.mail_id}。`);
    }
    return lines.join("\n");
  },
};

// 平台原生权限询问 → 邮件。
//
// **不作为工具暴露给模型**：opencode 自己就有权限机制（permission.ask 钩子 /
// permission.updated 事件），模型该做的是正常调工具，由 harness 决定要不要问人。
// 让模型主动调一个 request_permission 工具是把 harness 的职责推给模型 ——
// 它可能忘了调，也可能在不需要时乱调，而真正被 opencode 拦下的那次询问反而没人看见。
//
// relay_key 用 opencode 的 permission.id 做幂等键：permission.updated 会重复触发，
// 插件重连也会重放，没有它同一次询问会生成好几封邮件。
async function relayPermission({ question, options, context, relayKey }) {
  return apiPost("/permission/request", {
    question,
    options: options && options.length ? options : ["同意", "拒绝"],
    context: context || "",
    relay_key: relayKey || "",
  });
}

const connectToServerTool = {
  description:
    "连接到 AgentMail Gateway：登记本机密钥并完成注册。首次安装或换了 Gateway 地址时调用。" +
    "密钥若未在后台登记过，此处会返回需要登记的密钥全文。",
  args: {
    gateway_url: z.string().optional().describe("Gateway 地址，如 https://mail.example.com；省略则用当前配置"),
    key_token: z.string().optional().describe("管理员签发的 Agent 密钥；省略则用本地密钥（不存在时自动生成）"),
  },
  async execute(args) {
    if (args.key_token) {
      AGENT_KEY = args.key_token.trim();
      // 管理员给的密钥落盘，重启后仍然可用
      mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
      writeFileSync(
        KEY_FILE,
        JSON.stringify({ key_token: AGENT_KEY, created_at: new Date().toISOString() }, null, 2),
        { mode: 0o600 }
      );
    } else if (!AGENT_KEY) {
      AGENT_KEY = generateLocalKey();
    }

    const url = (args.gateway_url || GATEWAY_URL).replace(/\/+$/, "");
    const res = await fetch(`${url}/api/v1/agent/register`, {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${AGENT_KEY}` },
      body: JSON.stringify({ name: AGENT_NAME, workspaces: [], platform: "opencode" }),
    });
    const data = await res.json().catch(() => ({}));

    if (!res.ok) {
      // 密钥没登记是最常见的失败，直接把要登记的值给出来，省一轮来回
      return [
        `连接失败（HTTP ${res.status}）：${data.error || "未知错误"}`,
        ``,
        `若提示密钥无效，请让管理员在 AgentMail 后台「Agent 密钥」中登记：`,
        AGENT_KEY,
        ``,
        `密钥文件：${KEY_FILE}`,
      ].join("\n");
    }

    saveConfig({ gateway_url: url, registered_at: new Date().toISOString() });
    return `已连接 ${url}，注册为 ${data.agent_name || AGENT_NAME}。`;
  },
};

// ─── SSE ───

let sseAbort = null;

function startSSE(onEvent) {
  if (sseAbort) sseAbort.abort();
  sseAbort = new AbortController();

  const reconnect = () => {
    if (sseAbort?.signal.aborted) return;

    fetch(`${GATEWAY_URL}/api/v1/events/stream`, {
      headers: authHeaders(),
      signal: sseAbort.signal,
    }).then((res) => {
      const reader = res.body?.getReader();
      if (!reader) return;
      const decoder = new TextDecoder();
      let buf = "";

      const read = () => {
        reader.read().then(({ done, value }) => {
          if (done) { setTimeout(reconnect, 3000); return; }
          buf += decoder.decode(value, { stream: true });
          const lines = buf.split("\n");
          buf = lines.pop() || "";
          let evt = "", data = "";
          for (const line of lines) {
            if (line.startsWith("event: ")) evt = line.slice(7).trim();
            else if (line.startsWith("data: ")) data = line.slice(6);
            else if (line === "" && evt) {
              try { onEvent(evt, JSON.parse(data)); } catch {}
              evt = ""; data = "";
            }
          }
          read();
        }).catch(() => setTimeout(reconnect, 5000));
      };
      read();
    }).catch(() => setTimeout(reconnect, 5000));
  };

  reconnect();
}

// ─── Plugin ───

// AgentMail 会话 ↔ opencode 会话的绑定。
// 网关已经根据三维地址的 session 位完成了「复用默认 / 新建 / 具名必须存在」的判定，
// 推送过来的 session_id 就是那个判定结果；插件只负责忠实映射，不自己决定开不开新会话。
const sessionMap = new Map(); // agentmail session_id -> opencode session id
const reverseMap = new Map(); // opencode session id -> agentmail session_id（供 event 钩子回写命名）
const syncedTitles = new Map(); // opencode session id -> 已回写过的标题（去重，避免 session.updated 刷屏）

// 权限询问的双向定位。
//
// opencode 的 permission.id 与 AgentMail 的 mail_id 是两个 id 空间：
// 转出去时要记住 permission 属于哪个会话（回信地址从那里来），
// 人类决策回来时要用 permission.id 去回复 opencode。
// 服务端会把 relay_key 随决策事件回传，所以插件重启丢了内存映射也能续上。
const pendingPermissions = new Map(); // permission.id -> { sessionID, callID }

// 每个会话「上一次转出去的最后一条 assistant 消息」，避免 session.idle 重复触发时重发。
// 服务端另有 relay_key 幂等兜底，这里只是少打一次网关。
const relayedSummaries = new Map(); // opencode session id -> assistant message id

// 收到邮件后建立的会话，才需要在 idle 时把总结转回去。
// 用户在 TUI 里自己开的会话不该被搬进邮件系统。
const mailDrivenSessions = new Set(); // opencode session id

// 管理员在配置页划定的可用模型范围（按优先级）。随心跳响应更新。
// 空数组 = 不限定，回退到环境变量或平台默认。
let allowedModels = [];

async function resolveSessionForMail(client, directory, data, kind) {
  const mailSessionID = data.session_id;
  const bound = mailSessionID ? sessionMap.get(mailSessionID) : undefined;
  if (bound) return { sessionID: bound, reused: true };

  // 工作目录取**寻址里的 path 位**，而不是插件启动时那个固定的 directory。
  //
  // 三维地址 name@path.session 的 path 就是「希望它在哪儿干活」。用固定的
  // directory 会让所有邮件会话都挤在同一个目录里，与地址写的完全无关；
  // 而 opencode 按 directory 归属项目，写错了会话就归到别的项目下。
  //
  // 校验逻辑与 DSH 侧共用（lib/workspace.js）：目录不存在时不创建、
  // 拒绝相对路径。opencode 的兜底是插件启动时的 directory。
  const { cwd: wantDir, grouped } = resolveWorkspaceCwd(data.to_workspace, directory);
  if (!grouped && data.to_workspace) {
    console.error(
      `[mail-bridge] 工作目录 ${data.to_workspace} 不可用，回退到 ${wantDir || "(平台默认)"}`);
  }

  // 故意不传 title：opencode 只在标题缺省时才让模型按首轮对话生成摘要标题，
  // 传了占位标题就等于掐掉平台自己的命名机制。标题稍后由 session.updated 事件回写。
  const created = await client.session.create({
    query: wantDir ? { directory: wantDir } : undefined,
  });
  const session = created?.data ?? created;
  const sessionID = session?.id;
  if (!sessionID) throw new Error("session.create 未返回 id");

  if (mailSessionID) {
    sessionMap.set(mailSessionID, sessionID);
    reverseMap.set(sessionID, mailSessionID);
    mailDrivenSessions.add(sessionID);

    // slug 在创建时就有（如 nimble-lagoon），立即作为寻址别名回写；
    // 标题要等模型生成，走 session.updated 事件。
    if (session.slug) {
      syncSessionNaming(mailSessionID, { alias: session.slug }).then((res) => {
        if (res?.alias) console.error(`[mail-bridge] 别名同步 ${sessionID} -> ${res.alias}`);
      });
    }
  }
  return { sessionID, reused: false };
}

// 把本轮的最终总结转成邮件发回给对方。
//
// **不消耗配额**（基本原则：配额约束的是模型的自主发信，不是 harness 的转发）：
// 模型已经把话说完了，插件只是把它搬到邮件里。对搬运收费会导致配额用尽时
// Agent 连交代都做不了 —— 而那正是最需要它说话的时刻。
//
// 触发点是 session.idle：opencode 在一轮跑完（不再有工具调用与生成）时发这个事件，
// 此刻的最后一条 assistant 消息就是本轮结论。
// 不用 message.updated：那会在流式生成过程中反复触发，转出去的是半截话。
async function relaySummary(client, directory, sessionID) {
  const mailSessionID = reverseMap.get(sessionID);
  if (!mailSessionID) return null;              // 不是邮件驱动的会话，不碰
  if (!mailDrivenSessions.has(sessionID)) return null;

  // 取最后一条 assistant 文本消息
  const listed = await client.session.messages({
    path: { id: sessionID },
    query: directory ? { directory } : undefined,
  });
  const msgs = listed?.data ?? listed ?? [];
  let last = null;
  for (let i = msgs.length - 1; i >= 0; i--) {
    const m = msgs[i];
    if (m?.info?.role !== "assistant") continue;
    // 未完成的消息（还在生成/被中断）不转：转出去是半截话
    if (!m.info.time?.completed) continue;
    const text = (m.parts || [])
      .filter(p => p.type === "text" && !p.synthetic && !p.ignored && p.text)
      .map(p => p.text)
      .join("\n")
      .trim();
    if (text) { last = { id: m.info.id, text }; }
    break;
  }
  if (!last) return null;

  // 本地去重（服务端另有 relay_key 幂等兜底，这里只是少打一次网关）
  if (relayedSummaries.get(sessionID) === last.id) return null;

  // 回信地址：这轮是谁发起的就回给谁。取该会话最近一封来信的发件人。
  const ctx = mailContexts.get(mailSessionID);
  if (!ctx?.replyTo) return null;

  // 模型这一轮已经亲手回过这条线索 → 不再自动转发。
  //
  // 否则收件箱里会出现两封说同一件事的邮件（生产实测：311 字节与 342 字节各一封，
  // 其中带附件的那封才是模型真正想发的）。判定看两点：
  //   - 收件人同名：它已经跟这个人说过了
  //   - reply_to 相同：它已经回过这封信了
  // relay_key 的幂等管不了这个 —— 那个键保证「同一条消息不转两次」，
  // 而这里是「模型已经自己发过了」。
  if (shouldSkipAutoRelay(explicitSends.get(sessionID), ctx.replyTo, ctx.mailID)) {
    explicitSends.delete(sessionID);
    relayedSummaries.set(sessionID, last.id); // 记下这条已「处理」，别下次 idle 又转
    console.error(`[mail-bridge] 本轮模型已主动回信 ${ctx.replyTo}，跳过自动转发`);
    return null;
  }

  const res = await apiPost("/mail/send", {
    to: ctx.replyTo,
    subject: ctx.subject ? `Re: ${stripRe(ctx.subject)}` : "本轮工作总结",
    body: last.text,
    reply_to: ctx.mailID || "",
    // relay + relay_key：走免配额通道，并以 assistant message id 保证只转一次
    relay: "summary",
    relay_key: last.id,
  });
  relayedSummaries.set(sessionID, last.id);
  explicitSends.delete(sessionID); // 一轮结束，窗口关闭
  return res;
}

/** 去掉已有的 Re: 前缀，避免 Re: Re: Re: 叠加。 */
function stripRe(subject) {
  return String(subject).replace(/^(\s*Re:\s*)+/i, "");
}

// 每个 AgentMail 会话最近一封来信的上下文，用于决定总结回给谁。
// 一个会话里可能来过多封信，回最近那封（reply_to 指向它，回信才落回同一线索）。
const mailContexts = new Map(); // agentmail session_id -> { replyTo, subject, mailID }

// relaySummary 需要 client/directory，而 event 钩子拿不到它们
// （只在插件初始化时给一次）。插件启动时把它们闭包进来。
let relaySummaryRef = async () => null;

// 人类决策回来 → 回复 opencode 的原生权限询问。
//
// 决策语义映射回 opencode 的三态：
//   同意     → once   （仅这一次）
//   一直同意 → always （后续同类不再问）
//   拒绝     → reject
//
// relay_key（= opencode 的 permission.id）由服务端随决策事件回传，
// 所以插件重启丢了 pendingPermissions 也能续上 —— 这个映射不能只存在内存里。
async function replyPermission(client, directory, data) {
  const permID = data.relay_key || "";
  if (!permID) {
    // 没有上游 id 说明这条权限请求不是插件转发的（例如模型直接调过老的
    // request_permission，或历史数据）。此时没有可回复的 opencode permission，
    // 只能把结论作为一段话送进会话。
    return deliverMail(client, directory, data, "permission");
  }

  const pending = pendingPermissions.get(permID);
  const sessionID = pending?.sessionID || sessionMap.get(data.session_id || "");
  if (!sessionID) {
    console.error(`[mail-bridge] 权限 ${permID} 找不到对应会话，跳过`);
    return null;
  }

  const decision = String(data.decision || "");
  const response =
    decision === "一直同意" || decision === "always" ? "always" :
    decision === "拒绝" || decision === "reject" ? "reject" : "once";

  await client.postSessionIdPermissionsPermissionId({
    path: { id: sessionID, permissionID: permID },
    query: directory ? { directory } : undefined,
    body: { response },
  });
  pendingPermissions.delete(permID);
  console.error(`[mail-bridge] 权限 ${permID} -> ${response}（决策人 ${data.decided_by || "?"}）`);
  return { sessionID };
}

// 把一封来信投递给对应的 opencode 会话（已绑定则续谈，未绑定则新开）。
async function deliverMail(client, directory, data, kind) {
  const { sessionID, reused } = await resolveSessionForMail(client, directory, data, kind);

  // 新一轮开始：清掉上一轮「模型主动发过信」的记录。
  // 不清的话，上一轮亲手回过信会永久压掉这个会话之后所有的自动转发。
  explicitSends.delete(sessionID);

  // 记住这轮该回给谁：idle 时 relaySummary 靠它决定收件人与 reply_to。
  // 一个会话里可能来过多封信，只保留最近那封 —— 回信要落回最新的线索。
  if (kind === "mail" && data.session_id) {
    mailContexts.set(data.session_id, {
      replyTo: data.from_name || "",
      subject: data.subject || "",
      mailID: data.mail_id || "",
    });
  }

  const text = kind === "permission"
    ? `你之前发起的权限请求已有结论：${data.decision}（决策人：${data.decided_by || "用户"}）。请据此继续后续工作。`
    : [
        reused ? `本会话收到一封新邮件（AgentMail 续谈）。` : `你收到一封新邮件（AgentMail）。`,
        ``,
        `发件人：${data.from_name || "unknown"}`,
        `主题：${data.subject || "(无主题)"}`,
        `邮件 ID：${data.mail_id || "unknown"}`,
        `身份：你是 ${AGENT_NAME}`,
        ``,
        `请先调用 read_inbox 读取完整正文（附带附件清单，如有附件可用 download_attachment 取回），然后处理其中的请求。`,
        ``,
        `**回信不用你自己发**：你把本轮工作做完、把结论正常说出来就行，`,
        `插件会在这一轮结束时自动把你最后那段话作为回信发回给 ${data.from_name || "发件人"}（不消耗你的发信配额）。`,
        `只有在需要主动联系其他人、或要带附件时才调用 send_mail。`,
      ].join("\n");

  // 按管理员划定的范围逐个尝试，全部失败才回一封说明失败原因的邮件。
  //
  // 必须发那封信：模型一次都没跑起来时会话里没有任何 assistant 消息，
  // 自动转发因此什么也不会发 —— 发件人只会看到邮件发出去后再无音讯。
  //
  // **promptAsync 返回不代表模型跑起来了**（名字里的 Async 就是这个意思）：
  // 无效 provider 的失败通过 `session.error` 事件到达，而不是它的 reject。
  // 因此只包 try/catch 的话第二个模型永远不会被试到 —— 用 awaitFirstTurn 等结论。
  const attempts = modelAttemptOrder(allowedModels, {
    provider: REPLY_PROVIDER,
    model: REPLY_MODEL,
  });
  const failures = [];

  for (const route of attempts) {
    const label = route ? `${route.provider}/${route.model}` : "(平台默认)";
    const watching = awaitFirstTurn(sessionID);
    try {
      await client.session.promptAsync({
        path: { id: sessionID },
        query: directory ? { directory } : undefined,
        body: {
          // route 为 undefined 表示不指定模型，交给平台自己选
          ...(route ? { model: { providerID: route.provider, modelID: route.model } } : {}),
          parts: [{ type: "text", text }],
        },
      });
    } catch (e) {
      // 同步就被拒（参数非法、会话不存在等）
      watching.cancel();
      failures.push({ ...(route ?? {}), error: e?.message || String(e) });
      console.error(`[mail-bridge] 模型 ${label} 提交失败:`, e?.message || e);
      continue;
    }

    const outcome = await watching.result;
    if (outcome.ok) {
      if (failures.length > 0) {
        console.error(`[mail-bridge] ${label} 成功（前 ${failures.length} 个失败）`);
      }
      return { sessionID, reused };
    }
    failures.push({ ...(route ?? {}), error: outcome.error });
    console.error(`[mail-bridge] 模型 ${label} 失败:`, outcome.error);
  }

  // 全部失败：把原因作为邮件回给发件人。走免配额通道 ——
  // 这是插件的故障报告，不是模型的自主发信。
  if (kind === "mail" && data.from_name) {
    try {
      await apiPost("/mail/send", {
        to: data.from_name,
        subject: `处理失败: ${data.subject || "(无主题)"}`,
        body: renderFailureReport(failures, data.subject),
        reply_to: data.mail_id || "",
        relay: "summary",
        relay_key: `model-failure:${data.mail_id || sessionID}`,
      });
      console.error(`[mail-bridge] 已回报模型调用失败给 ${data.from_name}`);
    } catch (e) {
      console.error("[mail-bridge] 失败回报也发不出去:", e?.message || e);
    }
  }
  throw new Error(
    `划定范围内的 ${failures.length} 个模型全部失败：` +
    failures.map(f => f.error).join(" | "));
}

// ─── 首轮结果观察 ───
//
// opencode 的事件是通过插件的 event 钩子进来的，而 deliverMail 在钩子之外，
// 因此这里用一个「等待者」表：event 钩子看到 session.error / session.idle 时
// 唤醒对应会话的等待者。
const turnWatchers = new Map(); // sessionID -> { resolve, timer }

/**
 * 等这个会话的首轮跑起来或失败。
 *
 * 超时按「成功」处理：模型可能只是很慢（首 token 前要装载上下文），
 * 把慢当成失败会在换模型的同时把已经在跑的那一轮丢掉。
 *
 * @param {string} sessionID opencode 会话 id
 * @param {number} timeoutMs 判定窗口
 */
function awaitFirstTurn(sessionID, timeoutMs = 60000) {
  let settle;
  const result = new Promise(res => { settle = res; });
  const finish = (r) => {
    const w = turnWatchers.get(sessionID);
    if (!w) return;
    clearTimeout(w.timer);
    turnWatchers.delete(sessionID);
    w.resolve(r);
  };
  const timer = setTimeout(() => finish({ ok: true }), timeoutMs);
  turnWatchers.set(sessionID, { resolve: settle, timer });
  return {
    result,
    cancel: () => finish({ ok: true }),
  };
}

/** event 钩子调用：这个会话的首轮有结论了。 */
function settleFirstTurn(sessionID, outcome) {
  const w = turnWatchers.get(sessionID);
  if (!w) return false;
  clearTimeout(w.timer);
  turnWatchers.delete(sessionID);
  w.resolve(outcome);
  return true;
}

export default async function mailBridge(input) {
  const { client, directory } = input;

  // 注册 Agent。无密钥也无 secret 时先本地生成一把密钥，
  // 等管理员在后台登记后即可接入（无需重装插件）。
  if (!AGENT_KEY && !AGENT_SECRET) {
    AGENT_KEY = generateLocalKey();
  }
  try {
    await apiPost("/agent/register", {
      name: AGENT_NAME,
      secret: AGENT_KEY ? "" : AGENT_SECRET,
      workspaces: [],
      platform: "opencode",
    });
    saveConfig({ registered_at: new Date().toISOString() });
    console.error(
      `[mail-bridge] 已接入 ${GATEWAY_URL}，身份 ${AGENT_NAME}` +
        `（${AGENT_KEY ? "密钥认证" : "name/secret 认证"}）。`
    );
  } catch (e) {
    // 密钥未登记时这里会报「密钥无效」——必须说清楚该做什么，
    // 否则用户只看到一句 401 不知道要拿密钥去后台登记。
    console.error("[mail-bridge] 注册失败:", e?.message);
    if (AGENT_KEY) {
      console.error(`[mail-bridge] 若提示密钥无效，请让管理员在 AgentMail 后台登记这把密钥（见 ${KEY_FILE}）。`);
    }
  }

  // event 钩子里拿不到 client/directory（它们只在插件初始化时给），
  // 所以用一个闭包把 relaySummary 需要的两个参数固定下来。
  relaySummaryRef = (sid) => relaySummary(client, directory, sid);

  // 心跳。保活、取待处理邮件数，并上报平台侧的会话快照。
  //
  // 额度属于具体任务（会话），不属于 Agent，所以这里没有「剩余额度」可报。
  // 剩余往返随每次发信响应的 budget_remaining 回传，在那里才有意义。
  //
  // 会话快照解决的是「工作区下的历史会话在补全里选不到」：Gateway 只看得见
  // 邮件驱动的那部分，人直接在 opencode 界面上开的会话它一无所知。
  // 让插件上报而不是让 Gateway 反向拉取 —— 当前架构是单向的，
  // 反向拉取需要 Gateway 保存各平台的地址与凭证。
  async function reportSessions() {
    try {
      const listed = await client.session.list({
        query: directory ? { directory } : undefined,
      });
      const sessions = listed?.data ?? listed ?? [];
      return snapshotOpencodeSessions(sessions, (id) => mailDrivenSessions.has(id));
    } catch (e) {
      // 拉不到列表就**省略**该字段，而不是传空数组：
      // 空数组的语义是「平台侧确实一条会话都没有」，会把服务端的镜像抹掉。
      console.error("[mail-bridge] 会话列表读取失败:", e?.message || e);
      return undefined;
    }
  }

  // 模型目录：随心跳上报，让配置页看到的清单跟着平台的实际状态走。
  //
  // 只在注册时报一次的话目录会静静变陈（换 provider 配置、上游上下线、
  // 换 API key 都会让它失准），管理员会选中一个平台其实调不到的模型，
  // 而失败要到真发邮件时才暴露。
  async function reportModels() {
    try {
      const cfg = await client.config.providers();
      return snapshotOpencodeModels(cfg?.data ?? cfg);
    } catch (e) {
      // 拉不到就**省略**该字段，而不是传空数组：
      // 空数组的语义是「平台确实一个模型都拿不到」，会把配置页清成空白。
      console.error("[mail-bridge] 模型目录读取失败:", e?.message || e);
      return undefined;
    }
  }

  // 已经投过的 mail_id。心跳与 SSE 建连之间有个窗口：那期间到的邮件
  // 既在 pending_mails 里、也会被 SSE 推一次 —— 不去重就会投两遍。
  const deliveredMails = new Set();

  /**
   * 补投离线期间积压的未读邮件。
   *
   * SSE 只推连上之后的事件，插件重启前发来的邮件不会再推一次。
   * 不补的话那封邮件永远躺在收件箱里，而发件人以为 Agent 收到了。
   */
  async function catchUp(pending) {
    if (!pending) return;
    try {
      const box = await apiGet("/mail/inbox?status=unread&limit=20");
      const tasks = selectCatchup(box?.mails ?? box, deliveredMails);
      if (tasks.length === 0) return;
      console.error(`[mail-bridge] 补投 ${tasks.length} 封离线期间的邮件（共 ${pending} 封未读）`);
      // 串行：每封都要起一轮模型，并发放出去等于对上游打 N 个并发请求
      for (const ev of tasks) {
        // 逐封再查一次：拉收件箱和逐封投递之间 SSE 可能已经投过其中某封
        // （selectCatchup 只在拉完那一刻去过重）
        if (deliveredMails.has(ev.mail_id)) continue;
        deliveredMails.add(ev.mail_id);
        try {
          await deliverMail(client, directory, ev, "mail");
        } catch (e) {
          console.error(`[mail-bridge] 补投 ${ev.mail_id} 失败:`, e?.message || e);
        }
      }
    } catch (e) {
      console.error("[mail-bridge] 补投失败:", e?.message || e);
    }
  }

  let caughtUp = false;

  const beat = async () => {
    const [platform_sessions, models] = await Promise.all([
      reportSessions(),
      reportModels(),
    ]);
    const body = {};
    if (platform_sessions) body.platform_sessions = platform_sessions;
    if (models) body.models = models;
    try {
      const res = await apiPost("/agent/heartbeat", body);
      // 生效的模型范围随心跳响应回传：管理员在配置页改了范围后，
      // 插件最多一个周期（30 秒）就能看到新值，不需要重启。
      if (Array.isArray(res?.allowed_models)) allowedModels = res.allowed_models;
      // 只在首个成功的心跳后补投一次：之后的积压都由 SSE 覆盖，
      // 每轮心跳都补的话会把「模型正在处理中、尚未标已读」的邮件重复投递。
      if (!caughtUp) {
        caughtUp = true;
        await catchUp(res?.pending_mails);
      }
    } catch {
      // 心跳失败不报错：网络抖动很常见，下一轮会补上。
      // 真的持续连不上时 Gateway 会把它判成离线，那才是可见的信号。
    }
  };
  beat();
  const heartbeat = setInterval(beat, 30000);

  startSSE((type, data) => {
    // 人类决策了一条权限请求 → 回复 opencode 的原生 permission，让它自己恢复执行。
    // 这条路径不走 deliverMail：opencode 的权限机制会在收到回复后继续原来的工具调用，
    // 再往会话里塞一段「你的请求已批准」的文字只会干扰它。
    if (type === "permission_decision") {
      replyPermission(client, directory, data).catch((e) => {
        console.error("[mail-bridge] 权限决策回传失败:", e?.message || e);
      });
      return;
    }

    if (type !== "new_mail") return;
    if (data?.mail_id) deliveredMails.add(data.mail_id);
    deliverMail(client, directory, data, "mail")
      .then(({ sessionID, reused }) => {
        console.error(`[mail-bridge] ${type} -> ${reused ? "续谈" : "新会话"} ${sessionID}`);
      })
      .catch((e) => {
        // 失败必须可见，否则邮件会静默丢失
        console.error(`[mail-bridge] ${type} 处理失败:`, e?.message || e);
      });
  });

  process.on("SIGINT", () => {
    clearInterval(heartbeat);
    if (sseAbort) sseAbort.abort();
  });

  return {
    // 平台原生的权限询问 → 转成邮件问人。
    //
    // 这是 harness 的职责，不该让模型自己调一个 request_permission 工具：
    // 模型可能忘了调，也可能在不需要时乱调，而真正被 opencode 拦下的那次询问反而没人看见。
    //
    // 钩子里只**记下**待决策项并转出邮件，status 保持 "ask" —— 不在这里阻塞等人回复：
    // permission.ask 是同步钩子，卡在这里会把整个 opencode 请求挂住。
    // 人类决策通过 SSE 回来后，再用 SDK 回复这条 permission。
    async "permission.ask"(input, output) {
      if (!mailDrivenSessions.has(input.sessionID)) return; // 非邮件驱动的会话不接管
      const mailSessionID = reverseMap.get(input.sessionID);
      if (!mailSessionID) return;

      pendingPermissions.set(input.id, {
        sessionID: input.sessionID,
        callID: input.callID || "",
      });

      try {
        // opencode 的权限语义是三态，映射成人类看得懂的选项：
        // 「同意」= once（仅这次），「一直同意」= always（后续同类不再问），「拒绝」= reject
        await relayPermission({
          question: input.title || `请求执行 ${input.type}`,
          options: ["同意", "一直同意", "拒绝"],
          context: [
            `类型：${input.type}`,
            input.pattern ? `目标：${Array.isArray(input.pattern) ? input.pattern.join(", ") : input.pattern}` : "",
            Object.keys(input.metadata || {}).length
              ? "\n```json\n" + JSON.stringify(input.metadata, null, 2) + "\n```"
              : "",
          ].filter(Boolean).join("\n"),
          relayKey: input.id,
        });
        console.error(`[mail-bridge] 权限询问已转邮件 ${input.id}（${input.type}）`);
      } catch (e) {
        // 转不出去就别让 opencode 挂在那儿等：保持 ask 让本地机制接管（TUI 弹窗）
        console.error("[mail-bridge] 权限询问转发失败:", e?.message || e);
        pendingPermissions.delete(input.id);
        return;
      }
      output.status = "ask";
    },

    async event({ event }) {
      // 1) opencode 生成/更新会话标题时，把标题与 slug 回写成 AgentMail 的会话命名。
      //    首轮对话结束后 opencode 才由模型定标题，所以只能靠事件而非创建时刻拿到。
      if (event?.type === "session.updated") {
        const info = event.properties?.info;
        if (!info?.id) return;

        const mailSessionID = reverseMap.get(info.id);
        if (!mailSessionID) return; // 不是邮件驱动的会话，不碰

        // "New session - <时间>" 是 opencode 的占位标题，等模型生成真摘要再回写
        const title = typeof info.title === "string" ? info.title : "";
        if (!title || title.startsWith("New session")) return;

        // 同一标题只回写一次，避免 session.updated 高频触发时反复打网关
        if (syncedTitles.get(info.id) === title) return;
        syncedTitles.set(info.id, title);

        const res = await syncSessionNaming(mailSessionID, { alias: info.slug || "", title });
        if (res) {
          console.error(`[mail-bridge] 会话命名同步 ${info.id} -> alias=${res.alias || "-"} title=${res.title || "-"}`);
        }
        return;
      }

      // 2) 一轮跑完 → 把最后那段话作为回信转出去（不消耗配额）。
      //    用 session.idle 而不是 message.updated：后者在流式生成中反复触发，
      //    转出去的会是半截话。
      // 1.5) 模型调用出错 → 唤醒等待者，让 deliverMail 换下一个模型。
      //      promptAsync 已经返回过了，失败只能从这里得知。
      if (event?.type === "session.error") {
        const sid = event.properties?.sessionID;
        const err = event.properties?.error;
        const msg = err?.data?.message || err?.name || JSON.stringify(err ?? {});
        if (sid && settleFirstTurn(sid, { ok: false, error: msg })) {
          return; // 正在降级尝试中，不当作一次普通故障
        }
        if (sid && mailDrivenSessions.has(sid)) {
          console.error(`[mail-bridge] 会话 ${sid} 出错:`, msg);
        }
        return;
      }

      if (event?.type === "session.idle") {
        const sid = event.properties?.sessionID;
        // 首轮跑到 idle = 这一路走通了（哪怕没产出文本）
        if (sid) settleFirstTurn(sid, { ok: true });
        if (!sid || !mailDrivenSessions.has(sid)) return;
        try {
          const res = await relaySummaryRef(sid);
          if (res?.mail_id) {
            console.error(`[mail-bridge] 总结已回信 ${res.mail_id}（不计配额）`);
          }
        } catch (e) {
          console.error("[mail-bridge] 总结回信失败:", e?.message || e);
        }
        return;
      }

      // 3) 权限被本地机制（TUI）处理掉时，清掉待决策记录，
      //    免得之后邮件决策回来又去回复一条已经结案的 permission。
      if (event?.type === "permission.replied") {
        const pid = event.properties?.permissionID;
        if (pid) pendingPermissions.delete(pid);
        return;
      }
    },

    tool: {
      send_mail: sendMailTool,
      read_inbox: readInboxTool,
      read_mail: readMailTool,
      forward_mail: forwardMailTool,
      upload_attachment: uploadAttachmentTool,
      download_attachment: downloadAttachmentTool,
      connect_to_server: connectToServerTool,
      // 寻址发现：让模型选地址而不是拼地址
      suggest_address: suggestAddressTool,
      list_contacts: listContactsTool,
      session_participants: sessionParticipantsTool,
      read_thread: readThreadTool,
    },
  };
}