feat: relay-key 共用模块（三桥 + homeagent）

Sha256 clamp relay_key 过 160 字节上限，避免服务端 400
被 worker 当暂时失败让位，导致邮件驱动会话无本地 UI 静默挂死。

新增 relay_key.go / relay-key.js + 15 个纯函数测试。

plugins/pi-mail-bridge/lib/relay-key.js

@@ -0,0 +1,127 @@
+/**
+ * relay_key 长度收敛 —— 四个平台共用。
+ *
+ * ## 为什么需要它
+ *
+ * relay_key 是免配额通道的幂等键，服务端列宽 160 字节（超了返回 400）。
+ * 插件按「会话 id + 某个平台侧调用 id」拼这个键，平常七十来字节，很安全。
+ *
+ * 但生产上踩到一次：pi 会话里 bash 的 relay_key 突然超限，报文
+ * 「relay_key 过长（上限 160 字节）」。查真实会话文件后发现 toolCallId
+ * 有两种形态：
+ *
+ *   toolu_bdrk_01F6roEBHa8nic1mYiyLgNWK                  35 字节
+ *   toolu_bdrk_01FsWUWhEs4arnEWo44gqzLC~sig1:CAISoQIK…   437 ~ 13601 字节
+ *
+ * 启用 extended thinking 时 Bedrock 把**思考签名**拼进了 toolCallId。
+ * 同一条会话里两种形态混着出现，于是同一个 Agent 的权限询问随机成功随机失败。
+ *
+ * 后果不只是「这一次没送达」：那次失败被归入「暂时失败 → 让位给本地决策」，
+ * 而邮件驱动的 worker 没有 TUI，没有人可问 —— 那次 bash 调用**没有任何人
+ * 批准就执行了**。守卫形同虚设。
+ *
+ * ## 为什么用哈希而不是直接截断
+ *
+ * 直接截断会让两次不同的调用撞成同一个键（前缀相同后缀被切掉），
+ * 而这个键的全部意义是幂等：撞键意味着第二次询问被服务端当成重复请求丢掉。
+ * sha256 的碰撞概率可以忽略，且**同样的输入永远得到同样的输出** ——
+ * 这一点是必须的：插件重启后重放同一轮，必须算出同一个键。
+ *
+ * ## 为什么保留可读前缀
+ *
+ * 纯哈希在日志里没法看出是哪条会话。保留前缀让 `grep 会话id` 仍然有用。
+ * 前缀按**字节**截断并回退到字符边界 —— 键里可能有中文（邮件主题派生的键），
+ * 按字符数算会超字节上限，按字节硬切会切出半个字符。
+ */
+
+import { createHash } from 'node:crypto';
+
+/** 服务端 relay_key 列宽（字节）。与 gateway 侧 160 保持一致。 */
+export const RELAY_KEY_MAX_BYTES = 160;
+
+/** `:sha256:` + 64 位 hex */
+const HASH_SUFFIX_BYTES = 8 + 64;
+
+/**
+ * UTF-8 字节数。
+ *
+ * @param {string} s
+ * @returns {number}
+ */
+export function byteLength(s) {
+  return Buffer.byteLength(String(s ?? ''), 'utf8');
+}
+
+/**
+ * 按字节截断，回退到最近的字符边界（不产生半个字符）。
+ *
+ * @param {string} s
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+export function truncateToBytes(s, maxBytes) {
+  const str = String(s ?? '');
+  if (maxBytes <= 0) return '';
+  const buf = Buffer.from(str, 'utf8');
+  if (buf.length <= maxBytes) return str;
+
+  let end = maxBytes;
+  // UTF-8 续字节是 10xxxxxx。若第一个被丢掉的字节是续字节，
+  // 说明切点落在字符中间 —— 往前退到该字符的首字节之前。
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
+  return buf.subarray(0, end).toString('utf8');
+}
+
+/**
+ * 把 relay_key 收敛到服务端能接受的长度。
+ *
+ * 未超限时**原样返回** —— 这一点很重要：绝大多数键本来就合规，
+ * 改写它们会让插件升级前后算出不同的键，等于把已发出的询问变成新询问。
+ *
+ * @param {string} key 原始键
+ * @param {number} [limit] 上限字节数，默认 RELAY_KEY_MAX_BYTES
+ * @returns {string} 长度不超过 limit 的键
+ */
+export function clampRelayKey(key, limit = RELAY_KEY_MAX_BYTES) {
+  const raw = String(key ?? '');
+  if (byteLength(raw) <= limit) return raw;
+
+  const hash = createHash('sha256').update(raw, 'utf8').digest('hex');
+  const suffix = `:sha256:${hash}`;
+  // 上限小到装不下哈希时只留哈希（截断哈希仍然确定，只是碰撞面变大；
+  // 这条路径在真实配置下不会走到 —— 160 远大于 72）。
+  if (limit <= HASH_SUFFIX_BYTES) return truncateToBytes(hash, limit);
+
+  const prefix = truncateToBytes(raw, limit - HASH_SUFFIX_BYTES);
+  return `${prefix}${suffix}`;
+}
+
+/**
+ * 这次失败是不是「永远不会成功」。
+ *
+ * ## 为什么必须分类
+ *
+ * 插件在权限询问发送失败时有两条路：让位给平台本地决策，或当场 block。
+ * 原来除 409 之外一律当「暂时失败」让位 —— 而 400（请求本身不合法）
+ * 重试一万次也是 400。邮件驱动的会话**没有本地 UI**，让位等于让守卫消失：
+ * 生产实测一次 bash 就这样在无人批准的情况下执行了。
+ *
+ * ## 判据
+ *
+ * - 4xx（除 408 / 429）= 永久：请求本身有问题，重试不会变好
+ * - 408 / 429 = 暂时：超时与限流，等一会儿真的可能成功
+ * - 5xx = 暂时：服务端的问题
+ * - 无 status（网络层错误、DNS、连接被拒）= 暂时
+ *
+ * 401 归到永久：密钥无效要人去后台重新登记，不是等一等就好的事
+ * （本会话实测过一次 —— opencode 拿着已撤销的密钥重试了 18 小时）。
+ *
+ * @param {{status?: number}} err
+ * @returns {boolean} true = 永久失败，插件必须当场表态
+ */
+export function isPermanentFailure(err) {
+  const status = Number(err?.status);
+  if (!Number.isFinite(status) || status <= 0) return false; // 网络层错误 → 暂时
+  if (status === 408 || status === 429) return false;        // 超时 / 限流 → 暂时
+  return status >= 400 && status < 500;
+}