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

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

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

plugins/homeagent-mail-bridge/relay_key.go

@@ -0,0 +1,111 @@
+package main
+
+// relay_key 长度收敛 —— 三个 Node 插件里 `lib/relay-key.js` 的 Go 对应物。
+//
+// **不能共用那个文件**（homeagent 是 Go 子进程插件），但语义必须一致 ——
+// 因此这里把那边的注释与判据原样搬过来，`relay_key_test.go` 逐条钉住。
+//
+// # 为什么需要它
+//
+// 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。
+// 同一条会话里两种形态混着出现，于是权限询问随机成功随机失败。
+//
+// homeagent 侧的键目前都是自己拼的（"homeagent:" + mailID），长度可控。
+// 但 mailID 来自 Gateway、replyTo 来自邮件头，都不是本地常量 —— 而
+// 「这个值一直很短」正是 pi 侧那次事故的前提假设。
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"net/http"
+)
+
+// RelayKeyMaxBytes 服务端 relay_key 列宽（字节）。与 gateway 侧 160 保持一致。
+const RelayKeyMaxBytes = 160
+
+// hashSuffixBytes = len(":sha256:") + 64 位 hex
+const hashSuffixBytes = 8 + 64
+
+// truncateToBytes 按字节截断，回退到最近的字符边界（不产生半个字符）。
+//
+// Go 的 string 是 UTF-8 字节序列，直接 s[:n] 会切出无效字节。
+// 键里可能有中文（邮件主题派生的键），按 rune 数算会超字节上限，
+// 按字节硬切会切出半个字符。
+func truncateToBytes(s string, maxBytes int) string {
+	if maxBytes <= 0 {
+		return ""
+	}
+	if len(s) <= maxBytes {
+		return s
+	}
+	end := maxBytes
+	// UTF-8 续字节是 10xxxxxx。若切点落在字符中间，往前退到该字符首字节之前。
+	for end > 0 && s[end]&0xc0 == 0x80 {
+		end--
+	}
+	return s[:end]
+}
+
+// ClampRelayKey 把 relay_key 收敛到服务端能接受的长度。
+//
+// 未超限时**原样返回** —— 这一点很重要：绝大多数键本来就合规，
+// 改写它们会让插件升级前后算出不同的键，等于把已发出的询问变成新询问。
+//
+// 超限时用 sha256 而不是直接截断：直接截断会让两次不同的调用撞成同一个键
+// （前缀相同后缀被切掉），而这个键的全部意义是幂等 —— 撞键意味着第二次
+// 询问被服务端当成重复请求丢掉。保留可读前缀让日志里 grep 会话 id 仍然有用。
+func ClampRelayKey(key string) string {
+	return clampRelayKeyTo(key, RelayKeyMaxBytes)
+}
+
+func clampRelayKeyTo(key string, limit int) string {
+	if len(key) <= limit {
+		return key
+	}
+	sum := sha256.Sum256([]byte(key))
+	hash := hex.EncodeToString(sum[:])
+	// 上限小到装不下哈希时只留哈希（截断哈希仍然确定，只是碰撞面变大；
+	// 这条路径在真实配置下不会走到 —— 160 远大于 72）。
+	if limit <= hashSuffixBytes {
+		return truncateToBytes(hash, limit)
+	}
+	return fmt.Sprintf("%s:sha256:%s", truncateToBytes(key, limit-hashSuffixBytes), hash)
+}
+
+// IsPermanentFailure 这次失败是不是「永远不会成功」。
+//
+// # 为什么必须分类
+//
+// 插件在请求失败时有两条路：重试/让位，或当场表态。原来除 409 之外
+// 一律当「暂时失败」—— 而 400（请求本身不合法）重试一万次也是 400。
+// 邮件驱动的会话没有本地 UI，让位等于让守卫消失。
+//
+// # 判据
+//
+//   - 4xx（除 408 / 429）= 永久：请求本身有问题，重试不会变好
+//   - 408 / 429 = 暂时：超时与限流，等一会儿真的可能成功
+//   - 5xx = 暂时：服务端的问题
+//   - status <= 0（网络层错误、DNS、连接被拒）= 暂时
+//
+// 401 归到永久：密钥无效要人去后台重新登记，不是等一等就好的事
+// （实测过一次 —— opencode 拿着已撤销的密钥重试了 18 小时，2690 次 401）。
+func IsPermanentFailure(status int) bool {
+	if status <= 0 {
+		return false
+	}
+	if status == http.StatusRequestTimeout || status == http.StatusTooManyRequests {
+		return false
+	}
+	return status >= 400 && status < 500
+}