hiwork-core 0.0.38 → 0.0.39

package/lib/knowledge-config.js

@@ -45,6 +45,7 @@
  * 本模块不 import cordis 运行时：provide 走结构化的 {@link KnowledgeConfigContext} 端口，
  * 调用方（index.ts）传真实 ctx；单测直接伪造。
  */
+import { TtlCache } from "./ttl-cache.js";
 import { PKG_VERSION } from "./version.js";
 /** cordis 服务名（hiwork-knowledge 的 Host 半边按此名 `ctx.get` 探测）。 */
 export const HIWORK_KNOWLEDGE_SERVICE = 'hiworkKnowledge';
@@ -188,11 +189,12 @@ function reasonOfStatus(status) {
         return 'unreachable';
     return 'error';
 }
-/** 视图投影 + 5 分钟内存缓存（无状态依赖，只有一条内存缓存）。 */
+/** 视图投影 + 5 分钟内存缓存（无状态依赖，只有两条会话绑定的 TTL 缓存）。 */
 class KnowledgeConfigProvider {
     deps;
-    cached;
-    tokenCached;
+    configCache = new TtlCache({ ttlMs: KNOWLEDGE_CONFIG_TTL_MS });
+    // 令牌缓存比配置缓存短 30s（KNOWLEDGE_TOKEN_CACHE_TTL_MS 已扣掉余量，见其注释）。
+    tokenCache = new TtlCache({ ttlMs: KNOWLEDGE_TOKEN_CACHE_TTL_MS });
     constructor(deps) {
         this.deps = deps;
     }
@@ -208,9 +210,10 @@ class KnowledgeConfigProvider {
         }
         if (!sessionCookie)
             return failure('unauthenticated');
-        const hit = this.tokenCached;
-        if (!force && hit?.sessionCookie === sessionCookie && this.now() - hit.at < KNOWLEDGE_TOKEN_CACHE_TTL_MS) {
-            return hit.view;
+        if (!force) {
+            const hit = this.tokenCache.get(sessionCookie, this.now());
+            if (hit !== undefined)
+                return hit;
         }
         const gateway = this.deps.gateway();
         if (!gateway)
@@ -238,7 +241,7 @@ class KnowledgeConfigProvider {
                 return id ? [{ id, name: textOrUndefined(obj['name']) ?? '' }] : [];
             }).filter(item => knowledgeBaseIds.includes(item.id)) : [];
             const view = { ok: true, token, audience, knowledgeBaseIds, knowledgeBases };
-            this.tokenCached = { sessionCookie, view, at: this.now() };
+            this.tokenCache.put(sessionCookie, view, this.now());
             return view;
         }
         catch (error) {
@@ -263,10 +266,9 @@ class KnowledgeConfigProvider {
         if (sessionCookie === undefined || sessionCookie === '')
             return failure('unauthenticated');
         if (!force) {
-            const hit = this.cached;
-            if (hit !== undefined && hit.sessionCookie === sessionCookie && this.now() - hit.at < KNOWLEDGE_CONFIG_TTL_MS) {
-                return hit.view;
-            }
+            const hit = this.configCache.get(sessionCookie, this.now());
+            if (hit !== undefined)
+                return hit;
         }
         const gateway = this.deps.gateway();
         // 没有网关地址 = 还没完成登录（baseURL 是登录时写下的），与网络不通归同一档。
@@ -297,7 +299,7 @@ class KnowledgeConfigProvider {
             return failure('error');
         }
         // 只缓存成功结果：拉不到时下一次调用重新出网（一次抖动不该锁住一个 TTL）。
-        this.cached = { sessionCookie, view, at: this.now() };
+        this.configCache.put(sessionCookie, view, this.now());
         return view;
     }
     now() {

package/lib/memory-config.js

@@ -32,6 +32,7 @@
  * 本模块不 import cordis 运行时：provide 走结构化的 {@link MemoryConfigContext} 端口，
  * 调用方（index.ts）传真实 ctx；单测直接伪造。
  */
+import { TtlCache } from "./ttl-cache.js";
 import { PKG_VERSION } from "./version.js";
 /** cordis 服务名（hiwork-memory 的 Host 半边按此名 `ctx.get` 探测）。 */
 export const HIWORK_MEMORY_SERVICE = 'hiworkMemory';
@@ -145,10 +146,10 @@ function reasonOfStatus(status) {
         return 'unreachable';
     return 'error';
 }
-/** 视图投影 + 5 分钟内存缓存（无状态依赖，只有一条内存缓存）。 */
+/** 视图投影 + 5 分钟内存缓存（无状态依赖，只有一条会话绑定的 TTL 缓存）。 */
 class MemoryConfigProvider {
     deps;
-    cached;
+    cache = new TtlCache({ ttlMs: MEMORY_CONFIG_TTL_MS });
     constructor(deps) {
         this.deps = deps;
     }
@@ -166,10 +167,9 @@ class MemoryConfigProvider {
         if (sessionCookie === undefined || sessionCookie === '')
             return failure('unauthenticated');
         if (!force) {
-            const hit = this.cached;
-            if (hit !== undefined && hit.sessionCookie === sessionCookie && this.now() - hit.at < MEMORY_CONFIG_TTL_MS) {
-                return hit.view;
-            }
+            const hit = this.cache.get(sessionCookie, this.now());
+            if (hit !== undefined)
+                return hit;
         }
         const gateway = this.deps.gateway();
         // 没有网关地址 = 还没完成登录（baseURL 是登录时写下的），与网络不通归同一档。
@@ -200,7 +200,7 @@ class MemoryConfigProvider {
             return failure('error');
         }
         // 只缓存成功结果：拉不到时下一次调用重新出网（一次抖动不该锁住一个 TTL）。
-        this.cached = { sessionCookie, view, at: this.now() };
+        this.cache.put(sessionCookie, view, this.now());
         return view;
     }
     now() {

package/lib/orchestration.js

@@ -1,6 +1,6 @@
 import { GatewayError } from "./ai-router-client.js";
 import { NO_BASE_URL_ERROR, resolveDeviceInfo, startBrowserLogin } from "./browser-login.js";
-import { API_KEY_REF, SESSION_REF, PENDING_PASSWORD_REF, REMEMBERED_PASSWORD_REF, buildPiAiProviderProfiles, computeModelIds, computeRouteModels, } from "./provision.js";
+import { API_KEY_REF, SESSION_REF, REFRESH_TOKEN_REF, PENDING_PASSWORD_REF, REMEMBERED_PASSWORD_REF, buildPiAiProviderProfiles, computeModelIds, computeRouteModels, } from "./provision.js";
 import { computeBudgets, computeKeys, provisionSession, toLoginError, } from "./provision-session.js";
 // 端口契约与供给尾部现居 src/provision-session.ts（供 browser-login.ts 共用且避免循环依赖）；
 // 此处原样再导出，保持既有导入面（index.ts / 测试）不变。
@@ -23,14 +23,21 @@ export async function runLogin(opts) {
         // 表单回退也上报设备信息（网关记录登录设备）；设备未知时 resolveDeviceInfo 会生成，
         // 任何情况下都不得因设备信息让登录失败。
         const device = await resolveDeviceInfo(opts.credentials);
-        const { sessionCookie, user } = await opts.gateway.login(pending.username, password.value, device);
+        const { sessionCookie, user, sessionExpiresAt, refreshToken } = await opts.gateway.login(pending.username, password.value, device);
         await opts.credentials.set(SESSION_REF, sessionCookie);
+        // grant 必须与会话同批落盘：新登录成功却没拿到 grant（老网关）时要清掉残留的旧值，
+        // 否则上一次登录/上一个账号的 grant 会与新会话并存（会话已换、可续期的还是旧账号）。
+        if (refreshToken === undefined)
+            await opts.credentials.unset(REFRESH_TOKEN_REF).catch(() => { });
+        else
+            await opts.credentials.set(REFRESH_TOKEN_REF, refreshToken);
         await provisionSession({
             ...opts,
             baseURL,
             sessionCookie,
             user,
             username: pending.username,
+            sessionExpiresAt,
             requestUnset: ['pendingLogin'],
             onApiKeyWritten: async () => {
                 if (opts.value.rememberPassword === true)
@@ -57,8 +64,17 @@ export async function runLogin(opts) {
         return loginError;
     }
 }
-/** 用已存会话刷新模型列表。 */
+/** 用已存会话刷新模型列表（会话过期时先试 refresh grant 静默重认证，再回落记住密码/登录门）。 */
 export async function runRefresh(opts) {
+    return refreshWith(opts, false);
+}
+/**
+ * `runRefresh` 的实现体。`grantRetried` 是**内部标志**：只有本函数在「refresh grant 换到新会话、
+ * 带新 SESSION_REF 重跑供给」时置 true；公共入口 `runRefresh` 永远传 false，外部无法传入，
+ * 因此一次刷新里 grant 路径最多走一次——第二次仍 SESSION_EXPIRED 时直接回落到既有链路
+ * （记住密码重登 / 清会话开登录门），不会用同一个 grant 打转。
+ */
+async function refreshWith(opts, grantRetried) {
     const baseURL = opts.value.baseURL;
     if (baseURL === undefined) {
         await opts.state.patch({ unset: ['refreshRequest'] });
@@ -97,6 +113,34 @@ export async function runRefresh(opts) {
     }
     catch (error) {
         const refreshError = toLoginError(error, '无法连接网关，请检查 baseURL 或网络');
+        if (refreshError.code === 'SESSION_EXPIRED' && !grantRetried) {
+            // 会话过期先试 refresh grant（M2 网关）：成功即拿到新会话与轮换后的 grant，重跑一次供给。
+            const grant = await opts.credentials.resolve(REFRESH_TOKEN_REF).catch(() => undefined);
+            if (grant !== undefined && grant.value !== '') {
+                try {
+                    const renewed = await opts.gateway.refreshSession(grant.value);
+                    await opts.credentials.set(SESSION_REF, renewed.sessionCookie);
+                    // 轮换：新 grant 落盘；响应没回 token（已消费）时清掉，绝不留下可能已被作废的旧值。
+                    if (renewed.refreshToken === undefined)
+                        await opts.credentials.unset(REFRESH_TOKEN_REF).catch(() => { });
+                    else
+                        await opts.credentials.set(REFRESH_TOKEN_REF, renewed.refreshToken);
+                    // 新会话的绝对寿命只在网关给了 expires_at 时更新；没给就保留旧估计，不用编造值。
+                    if (renewed.sessionExpiresAt !== undefined) {
+                        await opts.state.patch({ set: { sessionExpiresAt: renewed.sessionExpiresAt } });
+                    }
+                    return refreshWith(opts, true);
+                }
+                catch (grantError) {
+                    // 只有「grant 明确作废」才丢弃本地值：400（失效/已轮换）= 该 grant 没用了；
+                    // 404 = 老网关没有这条路由，静默弃用。其余（网络/5xx）保留 grant，下次再试。
+                    const code = grantError instanceof GatewayError ? grantError.code : undefined;
+                    if (code === 'REFRESH_GRANT_INVALID' || code === 'REFRESH_GRANT_ABSENT') {
+                        await opts.credentials.unset(REFRESH_TOKEN_REF).catch(() => { });
+                    }
+                }
+            }
+        }
         if (refreshError.code === 'SESSION_EXPIRED' && opts.value.rememberPassword === true && opts.value.username !== undefined) {
             const remembered = await opts.credentials.resolve(REMEMBERED_PASSWORD_REF).catch(() => undefined);
             if (remembered !== undefined) {
@@ -124,6 +168,7 @@ export async function runLogout(opts) {
     }
     await opts.credentials.unset(API_KEY_REF).catch(() => { });
     await opts.credentials.unset(SESSION_REF).catch(() => { });
+    await opts.credentials.unset(REFRESH_TOKEN_REF).catch(() => { });
     await opts.credentials.unset(PENDING_PASSWORD_REF).catch(() => { });
     await opts.credentials.unset(REMEMBERED_PASSWORD_REF).catch(() => { });
     await opts.piAi.applyAiRouterProfiles(null);
@@ -131,6 +176,8 @@ export async function runLogout(opts) {
         unset: [
             'pendingLogin', 'refreshRequest', 'logoutRequest', 'browserLoginRequest', 'browserLogin',
             'username', 'displayName', 'lastLogin', 'lastError', 'keyId', 'budgets', 'keys',
+            // 会话寿命随会话一起清空：残留的旧 expiresAt 会让保活决策基于已失效的会话。
+            'sessionExpiresAt',
         ],
     });
 }

package/lib/provision-session.js

@@ -70,6 +70,7 @@ export async function provisionSession(opts) {
     const displayName = opts.user.display_name?.trim() || undefined;
     const set = {
         ...(opts.username === undefined ? {} : { username: opts.username }),
+        ...(opts.sessionExpiresAt === undefined ? {} : { sessionExpiresAt: opts.sessionExpiresAt }),
         ...(displayName === undefined ? {} : { displayName }),
         lastLogin: {
             at: new Date().toISOString(),

package/lib/provision.js

@@ -6,6 +6,11 @@ export const SESSION_REF = 'AI_ROUTER_SESSION';
 export const PENDING_PASSWORD_REF = 'AI_ROUTER_PENDING_PASSWORD';
 /** 勾选“记住密码”后保存的凭据 ref（由 credentials provider 加密存储）。 */
 export const REMEMBERED_PASSWORD_REF = 'AI_ROUTER_REMEMBERED_PASSWORD';
+/**
+ * 网关 refresh grant 的凭据 ref 名（M2 起 login/token 响应下发，登出/换新时清理）。
+ * 仅供 `runRefresh` 的静默重认证使用：绝不出现在状态或日志里，老网关没有它时静默弃用。
+ */
+export const REFRESH_TOKEN_REF = 'AI_ROUTER_REFRESH_TOKEN';
 /**
  * 注册到 llm-pi-ai 的协议路由表：路由名 → pi-ai 协议。
  * 网关按「入站协议 + 模型」匹配模型映射（internal/service/provider_service.go），

package/lib/session-fanout.js

@@ -0,0 +1,29 @@
+/**
+ * 会话供给成功后的联动刷新（spec §4.2）。
+ *
+ * 会话刚建立 / 刚续上时，**按人 + 按会话**下发的派生清单必须立刻对齐一次：client policy、
+ * 受管 MCP、受管技能、工作台应用。这些清单各自的 30 分钟（策略是 6 小时）预热只保证
+ * 「最迟那么久之后」收敛；换了账号、会话重建、或长期挂机后重新登录，旧清单在预热窗口内
+ * 就是错的。所以供给成功是一条事件，而不是等下一个定时器。
+ *
+ * 这里把「四件事依次触发」收成一个纯函数：任一 handler 抛异常只记日志、不影响其余
+ * ——刷新是尽力而为的旁路，绝不能反过来把登录 / 续期主链路带崩。
+ */
+export function buildSessionFanout(handlers) {
+    const entries = [
+        ['client policy', handlers.onPolicyRefresh],
+        ['managed mcp', handlers.onManagedMcpRefresh],
+        ['managed skills', handlers.onManagedSkillsRefresh],
+        ['workbench', handlers.onWorkbenchRefresh],
+    ];
+    return () => {
+        for (const [label, run] of entries) {
+            try {
+                run();
+            }
+            catch (error) {
+                handlers.log?.(`hiwork-core: 会话联动刷新「${label}」失败（${error instanceof Error ? error.name : typeof error}）`);
+            }
+        }
+    };
+}

package/lib/session-supervisor.js

@@ -0,0 +1,156 @@
+import { GatewayError } from "./ai-router-client.js";
+/**
+ * 会话心跳保活（spec §4.1b）。
+ *
+ * 网关会话是**服务端滑动续期**的：任意已认证请求在剩余寿命 < TTL/2 时会被续满。但桌面端
+ * 长时间挂机（不点任何功能）就不会发出任何已认证请求，续期永远不会触发，24h 后会话必过期。
+ * 本模块用一个兜底定时器（每小时醒一次），在「近期没有任何已认证请求成功」且「会话可能快
+ * 到期」时主动打一个轻量会话请求，把会话按住。
+ *
+ * 寿命预算：客户端不一定知道服务端真实 TTL（旧网关的 Set-Cookie 不带过期属性、`/api/auth/token`
+ * 与表单登录也不回 expires_at），所以用 {@link SESSION_TTL_ASSUMPTION_MS}（24h，与服务端缺省
+ * `session.duration` 一致）作为**安全上界**估算：只要在「剩余不足假定寿命一半」时打一次心跳，
+ * 服务端就一定会把它续满。新网关在带会话的成功响应里下发 `X-Session-Expires-At`，
+ * 心跳响应也可能带精确寿命——这些值先进内存估计（{@link SessionSupervisor.noteAuthedSuccess}），
+ * 用来判定「还要不要打心跳」；只有心跳成功才写 settings（热路径零写入）。
+ *
+ * 只读端口 + 单向动作：本模块不持有任何凭据、不写日志里的会话值；会话已失效（401）的恢复
+ * 动作由调用方经 401 汇聚接线（Task A3），这里只记中文日志、绝不向宿主抛。
+ */
+/** 假定会话总寿命（服务端 `session.duration` 缺省 24h；滑动续期的安全上界）。 */
+export const SESSION_TTL_ASSUMPTION_MS = 24 * 60 * 60_000;
+/** 心跳兜底检查间隔（1h）。 */
+export const SESSION_CHECK_INTERVAL_MS = 60 * 60_000;
+/**
+ * 会话恢复的冷却窗口（60s）：多通道并发 401（voice / usage / MCP …）只触发一次恢复，
+ * 且恢复动作本身（写 refreshRequest → 静默重登或开登录门）不会在窗口内被反复排队。
+ */
+export const SESSION_RECOVERY_COOLDOWN_MS = 60_000;
+export class SessionSupervisor {
+    deps;
+    timer;
+    /** 上次「已知会话存活」的时刻；undefined = 本进程内还没确认过（重启后的首次检查照打）。 */
+    lastAuthedSuccessAt;
+    /**
+     * 最近一次带会话成功响应里 `X-Session-Expires-At` 给出的**内存**寿命估计（原样时刻串）。
+     * 只活在内存里——热路径绝不写 settings（Review Focus 5），只有心跳成功才落盘。
+     */
+    lastHeaderExpiresAt;
+    /** 恢复请求是否在途（单飞去抖）。 */
+    recoveryInFlight = false;
+    /** 上次触发恢复的时刻（冷却窗口基准）。 */
+    lastRecoveryAt;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 开始兜底检查；重复调用不叠加定时器。 */
+    start() {
+        if (this.timer !== undefined)
+            return;
+        this.timer = setInterval(() => { void this.wake(); }, SESSION_CHECK_INTERVAL_MS);
+        this.timer.unref?.();
+    }
+    /** 停止兜底检查（调用后零活动）。 */
+    stop() {
+        if (this.timer === undefined)
+            return;
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /**
+     * 带会话的请求成功 → 记活动时间（由 ai-router-client 的活动汇聚驱动）。
+     * `expiresAt` 为响应头 `X-Session-Expires-At` 给出的会话寿命：**只更新内存估计**，
+     * 绝不在此写 settings——热路径上每个成功请求都写盘会打爆设置面（Review Focus 5）。
+     * 不可解析的值直接丢弃（当作没给），不覆盖既有估计。
+     */
+    noteAuthedSuccess(expiresAt) {
+        this.lastAuthedSuccessAt = this.now();
+        if (expiresAt !== undefined && !Number.isNaN(Date.parse(expiresAt)))
+            this.lastHeaderExpiresAt = expiresAt;
+    }
+    /**
+     * 带会话的请求收到 401 → 去抖后触发一次会话恢复。
+     * 去抖有两层：`recoveryInFlight`（单飞，覆盖「恢复请求还没落地，同刻又来了 5 条 401」）
+     * 与 `SESSION_RECOVERY_COOLDOWN_MS` 冷却（覆盖恢复完成后短时间内的余波 401）。
+     * 恢复失败只记日志——apply 后写入面需要几秒才就绪，那一侧的失败不该惊动宿主。
+     */
+    reportAuthed401(source) {
+        if (this.recoveryInFlight)
+            return;
+        const now = this.now();
+        if (this.lastRecoveryAt !== undefined && now - this.lastRecoveryAt < SESSION_RECOVERY_COOLDOWN_MS)
+            return;
+        this.recoveryInFlight = true;
+        this.lastRecoveryAt = now;
+        void this.deps.requestRecovery()
+            .catch(() => { this.log(`hiwork-core: 会话恢复触发失败（来源 ${source}），等待下个 401 或心跳重试`); })
+            .finally(() => { this.recoveryInFlight = false; });
+    }
+    now() {
+        return this.deps.now?.() ?? Date.now();
+    }
+    log(message) {
+        this.deps.log?.(message);
+    }
+    /**
+     * 一次兜底检查。判定顺序（早退即不发请求）：
+     * 无会话 / 无 baseURL → 返回；距上次已认证成功不足 TTL/2 → 返回；
+     * 已知剩余寿命 > TTL/2 → 返回；否则 ping。
+     * 寿命未知也 ping——重启后的首次检查即校验会话是否还活着。
+     * 「已知剩余寿命」取 settings 值与内存估计（响应头）的**较大者**：头值只会更晚更准，
+     * 用较大者才不会因为 settings 里的旧估算偏早而白打心跳。
+     */
+    async wake() {
+        try {
+            const session = await this.deps.getSession();
+            if (session === undefined || session === '')
+                return;
+            if (this.deps.getBaseURL() === undefined)
+                return;
+            const now = this.now();
+            if (this.lastAuthedSuccessAt !== undefined && now - this.lastAuthedSuccessAt < SESSION_TTL_ASSUMPTION_MS / 2)
+                return;
+            const knownExpiresAtMs = this.knownExpiresAtMs();
+            if (knownExpiresAtMs !== undefined && knownExpiresAtMs - now > SESSION_TTL_ASSUMPTION_MS / 2)
+                return;
+            let pinged;
+            try {
+                pinged = await this.deps.ping(session);
+            }
+            catch (error) {
+                // 会话失效（401）与网络异常一律不抛：前者交给 401 汇聚触发恢复，后者下个周期再试。
+                const expired = error instanceof GatewayError && error.code === 'SESSION_EXPIRED';
+                this.log(expired
+                    ? 'hiwork-core: 会话心跳发现会话已失效，等待 401 汇聚触发恢复'
+                    : 'hiwork-core: 会话心跳请求失败，将在下个周期重试');
+                return;
+            }
+            // 服务端已按滑动续期处理本次请求；能拿到精确寿命就用它，否则按安全上界估算回写。
+            const pingedExpiresAt = pinged?.expiresAt;
+            const pingedMs = pingedExpiresAt === undefined ? Number.NaN : Date.parse(pingedExpiresAt);
+            const nextExpiresAt = pingedExpiresAt === undefined || Number.isNaN(pingedMs)
+                ? new Date(this.now() + SESSION_TTL_ASSUMPTION_MS).toISOString()
+                : pingedExpiresAt;
+            try {
+                await this.deps.patchSessionExpiresAt(nextExpiresAt);
+            }
+            catch {
+                this.log('hiwork-core: 会话心跳成功但寿命回写失败，将在下个周期重试');
+            }
+        }
+        catch {
+            // 读取端口（凭据存储 / 设置面）抛异常也不得打断定时器或惊动宿主。
+            this.log('hiwork-core: 会话心跳检查失败，将在下个周期重试');
+        }
+    }
+    /**
+     * 已知的会话到期时刻（epoch ms）：settings 值与内存头值里**有效且较晚**的那个；
+     * 两者都没有（或都不可解析）返回 undefined = 寿命未知。
+     */
+    knownExpiresAtMs() {
+        const values = [this.deps.getSessionExpiresAt(), this.lastHeaderExpiresAt]
+            .map((iso) => (iso === undefined ? Number.NaN : Date.parse(iso)))
+            .filter((ms) => !Number.isNaN(ms));
+        return values.length === 0 ? undefined : Math.max(...values);
+    }
+}

package/lib/ttl-cache.js

@@ -0,0 +1,45 @@
+/**
+ * 会话绑定的 TTL 缓存原语（spec §4.4）。
+ *
+ * knowledge / memory / image / usage 各自手写过一遍「会话配 TTL」的内存缓存，语义已经
+ * 开始漂移。原语只做三件事，把「成功才 put、失败不 put、force 旁路」留给调用方：
+ *  - 值与**会话键**绑定：读别人的会话键一定 miss（换账号绝不串号）；
+ *  - 命中条件是 `now - putAt < ttlMs`（严格小于，与既有实现逐字一致）；
+ *  - `invalidate` 支持全清与单键清理。
+ *
+ * **只保留一条条目**（不是每个键一条）：这与迁移前的既有实现逐字等价——写入新会话的
+ * 缓存会顶掉旧会话那条。这条语义被 knowledge 的既有测试钉着（换账号再换回来必须重新
+ * 出网），也是「一次只服务一个登录账号」的诚实表达，故不改成 Map。
+ *
+ * 余量（skew）不在这里做：不同调用方的提前量不同（如 knowledge 令牌要扣 30s），
+ * 由调用方在 `ttlMs` 里自己扣——原语只认一个 TTL，不猜语义。
+ */
+export class TtlCache {
+    ttlMs;
+    entry;
+    constructor(opts) {
+        this.ttlMs = opts.ttlMs;
+    }
+    /** 命中返回缓存值；会话键不同或已到期返回 undefined。`now` 可注入（缺省 Date.now）。 */
+    get(sessionKey, now = Date.now()) {
+        const hit = this.entry;
+        if (hit === undefined || hit.sessionKey !== sessionKey)
+            return undefined;
+        if (now - hit.at >= this.ttlMs)
+            return undefined;
+        return hit.value;
+    }
+    /** 写入/覆盖缓存（新会话键会顶掉旧会话那条）。 */
+    put(sessionKey, value, now = Date.now()) {
+        this.entry = { sessionKey, value, at: now };
+    }
+    /** 清掉指定会话键的条目（不影响别的键，虽然只会存在一条）；不传参数则清空。 */
+    invalidate(sessionKey) {
+        if (sessionKey === undefined) {
+            this.entry = undefined;
+            return;
+        }
+        if (this.entry?.sessionKey === sessionKey)
+            this.entry = undefined;
+    }
+}

package/lib/types/ai-router-client.d.ts

@@ -1,4 +1,25 @@
 import type { DeviceSession, LoginErrorCode } from './types.ts';
+/**
+ * 带会话请求的活动事件（spec §4.1b/c）：成功 = 会话仍然活着，401 = 会话已失效。
+ * 这是「隐式心跳」与「401 统一汇聚」的唯一信号源——**只带 kind 与会话寿命，不带任何请求细节**
+ * （URL / 响应体 / cookie 都不外传），避免凭据经观察者泄漏到日志。
+ * success 的 `expiresAt` 是响应头 `X-Session-Expires-At`（网关 C5 起下发）解析出的会话绝对
+ * 寿命（原样透传服务端时刻串）；头缺失或不可解析时该字段不出现。
+ */
+export type SessionActivityEvent = {
+    kind: 'success';
+    expiresAt?: string;
+} | {
+    kind: 'unauthorized';
+};
+/** 挂载活动 sink（传 undefined 等价于清除，便于测试与宿主无处可摘时兜底）。 */
+export declare function setSessionActivitySink(sink: ((event: SessionActivityEvent) => void) | undefined): void;
+/**
+ * 清除活动 sink，**仅当当前 sink 就是入参那一个**。
+ * HMR 会重挂同一个模块：旧 fiber 的清理回调可能在新的 sink 挂上之后才跑，
+ * 无条件清空会把新挂载的观察者一起摘掉（心跳与 401 汇聚会静默失效）。
+ */
+export declare function clearSessionActivitySink(sink: (event: SessionActivityEvent) => void): void;
 /**
  * 生图的单次请求超时（**按网关下发的预算算**，不是常量）。
  *
@@ -585,10 +606,16 @@ export interface GatewayClient {
      * 表单登录（loginMode=form 的回退路径）。
      * `device` 为可选设备信息：已知时随请求上报 `X-HiWork-*` 头（供网关记录登录设备），
      * 未知则不发——**设备信息缺失绝不能让登录失败**。
+     * `sessionExpiresAt`：从 Set-Cookie 的 `Expires`/`Max-Age` 解析出的会话绝对寿命（ISO），
+     * 旧网关不下发过期属性时为 undefined（调用方按假定寿命估算）。
+     * `refreshToken`：M2 网关下发的 refresh grant（非空字符串才收）；老网关缺失时为 undefined，
+     * 此时调用方要清掉本地残留的旧 grant。
      */
     login(username: string, password: string, device?: DeviceIdentity): Promise<{
         sessionCookie: string;
         user: GatewayUser;
+        sessionExpiresAt?: string;
+        refreshToken?: string;
     }>;
     /**
      * 浏览器授权登录：用一次性 code + PKCE verifier 换取会话（返回形状与 login 一致）。
@@ -601,6 +628,19 @@ export interface GatewayClient {
     }): Promise<{
         sessionCookie: string;
         user: GatewayUser;
+        sessionExpiresAt?: string;
+        refreshToken?: string;
+    }>;
+    /**
+     * 用 refresh grant 换一份新会话（M2 网关的静默重认证）。**不调用它做探测**：
+     * 老网关（没有 `/api/auth/refresh`）会回 404，调用方按 `REFRESH_GRANT_ABSENT` 静默弃用本地 grant。
+     * 成功后本地必须落盘新的 `sessionCookie` 与轮换后的 `refreshToken`（响应没回 token 时清除）。
+     */
+    refreshSession(refreshToken: string): Promise<{
+        sessionCookie: string;
+        user: GatewayUser;
+        sessionExpiresAt?: string;
+        refreshToken?: string;
     }>;
     /** 当前账号的登录设备列表。 */
     listSessions(sessionCookie: string): Promise<DeviceSession[]>;
@@ -666,6 +706,8 @@ export declare class AiRouterClient implements GatewayClient {
     login(username: string, password: string, device?: DeviceIdentity): Promise<{
         sessionCookie: string;
         user: GatewayUser;
+        sessionExpiresAt?: string;
+        refreshToken?: string;
     }>;
     /**
      * POST /api/auth/token：用一次性 code + PKCE verifier 换取会话。
@@ -679,6 +721,25 @@ export declare class AiRouterClient implements GatewayClient {
     }): Promise<{
         sessionCookie: string;
         user: GatewayUser;
+        sessionExpiresAt?: string;
+        refreshToken?: string;
+    }>;
+    /**
+     * POST /api/auth/refresh：用 refresh grant 换一份新会话（M2 网关的静默重认证）。
+     *
+     * 拒绝语义必须分开，调用方据此决定「弃用 grant」还是「保留待重试」：
+     *  - 400 = grant 无效（过期 / 已被轮换 / 复用检测拒绝）→ `REFRESH_GRANT_INVALID`，本地作废；
+     *  - 404 = 老网关根本没有这条路由 → `REFRESH_GRANT_ABSENT`，本地作废且**静默降级**；
+     *  - 其余非 2xx（5xx / 反代错误页）与网络层异常 → `GATEWAY_UNREACHABLE`，grant 保留，
+     *    下次 SESSION_EXPIRED 再试。
+     *
+     * 任何日志/异常信息都不得包含 refresh_token / session_id 明文。
+     */
+    refreshSession(refreshToken: string): Promise<{
+        sessionCookie: string;
+        user: GatewayUser;
+        sessionExpiresAt?: string;
+        refreshToken?: string;
     }>;
     /** GET /api/auth/sessions：当前账号的登录设备列表。 */
     listSessions(sessionCookie: string): Promise<DeviceSession[]>;
@@ -966,3 +1027,16 @@ export declare function deviceHeaders(device?: DeviceIdentity): Record<string, s
  * 旧运行时回退 get('set-cookie') 时可能拿到逗号合并串，故分隔符同时接受 `,` 与 `;`。
  */
 export declare function extractSessionId(headers: Headers): string | undefined;
+/**
+ * 从 Set-Cookie 解析会话过期时间（ISO 串；解析不出返回 undefined）。
+ * 与 {@link extractSessionId} 同源遍历全部 Set-Cookie，但只认 `session_id` 那一节里的
+ * `Expires=`（绝对时刻，`Date.parse`，NaN 弃用）或 `Max-Age=`（相对秒数，now + 秒）；
+ * 两者都有优先 `Expires`——服务端给的是权威时刻，Max-Age 只是保守回退。
+ * 旧网关可能两个属性都不带（网关契约尚未下发过期信息），此时返回 undefined，
+ * 由调用方的「按假定寿命估算」路径接手，绝不在这里抛错或猜一个假值。
+ *
+ * 旧运行时回退 `get('set-cookie')` 会拿到逗号合并串，故先按「逗号 + cookie 名=」切节：
+ * `Expires` 的日期串里也有逗号，但逗号后面不是 `name=`，不会被误切。
+ * `now` 可注入以便测试（默认 `Date.now()`）。
+ */
+export declare function parseSessionCookieExpiry(headers: Headers, now?: number): string | undefined;

package/lib/types/client/types.d.ts

@@ -1,11 +1,17 @@
 /** 稳定错误码，供 settings card 分支渲染。 */
-export type LoginErrorCode = 'AUTH_FAILED' | 'RATE_LIMITED' | 'GATEWAY_UNREACHABLE' | 'NO_KEY_ASSIGNED' | 'SESSION_EXPIRED' | 'KEY_DISABLED' | 'KEY_INVALID' | 'NOT_FOUND'
+export type LoginErrorCode = 'AUTH_FAILED' | 'RATE_LIMITED' | 'GATEWAY_UNREACHABLE' | 'NO_KEY_ASSIGNED' | 'SESSION_EXPIRED'
+/** 400：grant 失效 / 已被轮换复用 / 已过期——该 grant 作废，回落记住密码。 */
+ | 'REFRESH_GRANT_INVALID'
+/** 404：老网关没有 `/api/auth/refresh`——静默弃用本地 grant，用户无感知。 */
+ | 'REFRESH_GRANT_ABSENT' | 'KEY_DISABLED' | 'KEY_INVALID' | 'NOT_FOUND'
 /** 该分配已被管理员撤销（或从未属于当前账号）：取断言时 404。 */
  | 'MCP_ASSIGNMENT_GONE'
 /** 服务或分配已停用（或被改成了不可下发的凭证方式）：取断言时 409。 */
  | 'MCP_NOT_DELIVERABLE'
 /** 本部署未配置断言签名私钥（`mcp.assertion_key`）：取断言时 503。 */
  | 'MCP_ASSERTION_DISABLED'
+/** 断言签发频率超限（服务端按用户 60 次/分限流）：取断言时 429，下一轮同步会自动重试。 */
+ | 'MCP_ASSERTION_RATE_LIMITED'
 /** 该分配已被管理员撤销（或从未属于当前账号）：取包体时 404。 */
  | 'SKILL_ASSIGNMENT_GONE'
 /** 本部署未启用技能下发：取包体时 503。 */

package/lib/types/client-policy.d.ts

@@ -2,9 +2,11 @@
  * 客户端版本策略（spec §6）：`GET /api/client/policy` 的免登录只读拉取。
  *
  * 网关返回的是**最终判定**（`loginMode` 等），插件只做投影不做策略逻辑，因此管理端
- * 调整 `client.login_mode` 后重启插件即生效，无需发版（spec §6.1）。
+ * 调整 `client.login_mode` 后无需重启插件、无需发版：由 {@link createClientPolicyPoller}
+ * 每 6 小时重拉一次（对齐服务端 `Cache-Control: max-age=300` 的注释预期），失败按
+ * 1min → 10min → 1h 阶梯退避重试，紧急止血策略（如 `login_mode=form`）由此能到达在线客户端。
  *
- * 本模块只负责「拉 + 严格解析」，投影与 fail-open 缺省由 `src/index.ts` 的
+ * 本模块只负责「拉 + 严格解析 + 轮询节律」，投影与 fail-open 缺省由 `src/index.ts` 的
  * `projectLoginMode` 完成：**非 200 / 非 JSON / 枚举非法 / 超时 / 网络异常一律返回
  * undefined**，调用方据此回退 `DEFAULT_LOGIN_MODE`，绝不把用户锁在门外（spec §5.4 / §6.4）。
  */
@@ -57,3 +59,29 @@ export declare function buildClientPolicyURL(opts: FetchClientPolicyOptions): st
  * 不记录响应原文——策略接口当前无敏感字段，但保持与其他网关调用一致的日志纪律。
  */
 export declare function fetchClientPolicy(opts: FetchClientPolicyOptions): Promise<ClientPolicy | undefined>;
+/** 策略轮询间隔（6h，对齐服务端 `Cache-Control: max-age=300` 的注释预期）。 */
+export declare const CLIENT_POLICY_POLL_INTERVAL_MS: number;
+/**
+ * 失败退避阶梯（1min → 10min → 1h），末档封顶循环。
+ * 退避只影响「多久后重试」，不影响已经投影好的策略值——失败时保留上一轮结果。
+ */
+export declare const CLIENT_POLICY_RETRY_DELAYS_MS: readonly [60000, number, number];
+export interface ClientPolicyPoller {
+    /** 请求一次拉取：**当前没有排程**（也没在跑）时立即发起，否则什么都不做。 */
+    trigger(): void;
+    /** 停止轮询并清掉已排程的定时器（调用后零回调）。 */
+    dispose(): void;
+}
+/**
+ * 自排程的策略轮询器（不用 setInterval：每轮的间隔由上一轮结果决定）。
+ *  - `attempt` 返回 true（成功拉到并投影）→ 6h 后再来；
+ *  - 返回 false 或抛异常 → 按 {@link CLIENT_POLICY_RETRY_DELAYS_MS} 退避，末档封顶循环；
+ *  - 任意一次成功把退避档归零（下一次失败重新从 1min 起步）；
+ *  - 定时器 `unref`，不拖住进程退出；`trigger()` 幂等（已排程/在飞时是 no-op），
+ *    让宿主 200ms 消费循环可以无脑反复调用。
+ */
+export declare function createClientPolicyPoller(deps: {
+    /** 发起一次拉取并投影；成功返回 true。baseURL 未配置时返回 false。 */
+    attempt: () => Promise<boolean>;
+    log?: (message: string) => void;
+}): ClientPolicyPoller;