hiwork-core 0.0.38 → 0.0.39

package/lib/ai-router-client.js

@@ -1,4 +1,19 @@
 import { gatewayUserAgent } from "./user-agent.js";
+/** 模块级活动 sink：由宿主（index.ts）在 apply 时挂、在 effect 清理时摘。 */
+let sessionActivitySink;
+/** 挂载活动 sink（传 undefined 等价于清除，便于测试与宿主无处可摘时兜底）。 */
+export function setSessionActivitySink(sink) {
+    sessionActivitySink = sink;
+}
+/**
+ * 清除活动 sink，**仅当当前 sink 就是入参那一个**。
+ * HMR 会重挂同一个模块：旧 fiber 的清理回调可能在新的 sink 挂上之后才跑，
+ * 无条件清空会把新挂载的观察者一起摘掉（心跳与 401 汇聚会静默失效）。
+ */
+export function clearSessionActivitySink(sink) {
+    if (sessionActivitySink === sink)
+        sessionActivitySink = undefined;
+}
 /**
  * 读错误响应体里的结构化 `code`（读不到 → 空串）。
  *
@@ -18,6 +33,8 @@ async function knowledgeErrorCodeFromBody(res) {
 const AUTH_AUTHORIZE_PATH = '/api/auth/authorize';
 const AUTH_TOKEN_PATH = '/api/auth/token';
 const AUTH_SESSIONS_PATH = '/api/auth/sessions';
+/** refresh grant 静默重认证端点（M2 网关起；老网关无此路由回 404）。 */
+const AUTH_REFRESH_PATH = '/api/auth/refresh';
 /** 自助用量与成本端点（均挂在网关 /api/me 会话组下，鉴权由 SessionAuth 负责）。 */
 const ME_ANALYTICS_SUMMARY_PATH = '/api/me/analytics/summary';
 const ME_ANALYTICS_TRENDS_PATH = '/api/me/analytics/trends';
@@ -254,8 +271,22 @@ export class AiRouterClient {
             throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
         if (sid === undefined)
             throw new GatewayError('GATEWAY_UNREACHABLE', '网关登录成功但未返回会话 Cookie', res.status);
-        const user = await res.json();
-        return { sessionCookie: `session_id=${sid}`, user };
+        // 表单登录响应体带 expires_at（网关 C5 起）与 refresh_token（M2 起）：前者优先于 Set-Cookie
+        // 的过期属性，两者都没有（旧网关）时留空，由调用方的「按假定寿命估算」路径接手。
+        // 两个字段都从 user 上摘掉（refresh_token 是密钥，绝不能混进 GatewayUser 被当作展示字段）。
+        const { expires_at: rawExpiresAt, refresh_token: rawRefreshToken, ...user } = await res.json();
+        const bodyExpiresAt = typeof rawExpiresAt === 'string' && !Number.isNaN(Date.parse(rawExpiresAt))
+            ? rawExpiresAt
+            : undefined;
+        const sessionExpiresAt = bodyExpiresAt ?? parseSessionCookieExpiry(res.headers);
+        // grant 只收「字符串且非空」：空串/非字符串一律当老网关没给，调用方据此清陈旧 grant。
+        const refreshToken = typeof rawRefreshToken === 'string' && rawRefreshToken !== '' ? rawRefreshToken : undefined;
+        return {
+            sessionCookie: `session_id=${sid}`,
+            user,
+            ...(sessionExpiresAt === undefined ? {} : { sessionExpiresAt }),
+            ...(refreshToken === undefined ? {} : { refreshToken }),
+        };
     }
     /**
      * POST /api/auth/token：用一次性 code + PKCE verifier 换取会话。
@@ -282,7 +313,62 @@ export class AiRouterClient {
         if (data === undefined || data.session_id === undefined || data.session_id === '') {
             throw new GatewayError('GATEWAY_UNREACHABLE', '网关兑换成功但未返回会话标识', res.status);
         }
-        return { sessionCookie: `session_id=${data.session_id}`, user: data.user };
+        // 服务端已回 expires_at（spec §4.1a）；只收「字符串且可解析」的值，原样保留服务端给的
+        // 时刻串，坏值当未知交给估算路径。
+        const rawExpiresAt = typeof data.expires_at === 'string' ? data.expires_at : undefined;
+        const sessionExpiresAt = rawExpiresAt !== undefined && !Number.isNaN(Date.parse(rawExpiresAt))
+            ? rawExpiresAt
+            : undefined;
+        // grant 同样「字符串非空才收」（M2 起下发；老网关缺失即 undefined）。
+        const refreshToken = typeof data.refresh_token === 'string' && data.refresh_token !== '' ? data.refresh_token : undefined;
+        return {
+            sessionCookie: `session_id=${data.session_id}`,
+            user: data.user,
+            ...(sessionExpiresAt === undefined ? {} : { sessionExpiresAt }),
+            ...(refreshToken === undefined ? {} : { refreshToken }),
+        };
+    }
+    /**
+     * 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 明文。
+     */
+    async refreshSession(refreshToken) {
+        const res = await this.requestOrUnreachable(AUTH_REFRESH_PATH, {
+            method: 'POST',
+            body: { refresh_token: refreshToken },
+        });
+        if (res.status === 400)
+            throw new GatewayError('REFRESH_GRANT_INVALID', '登录已过期，请重新登录', 400);
+        if (res.status === 404)
+            throw new GatewayError('REFRESH_GRANT_ABSENT', '网关不支持静默续期', 404);
+        if (!res.ok)
+            throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
+        // 与 exchangeCode 同理用 readJson（不把响应片段带进异常信息）。
+        const data = await readJson(res);
+        // 响应体优先取 session_id（契约字段）；网关只下发 Set-Cookie 时回落解析 Cookie，
+        // 两处都没有才算契约违约（与 login 的判据一致）。
+        const sid = typeof data?.session_id === 'string' && data.session_id !== '' ? data.session_id : extractSessionId(res.headers);
+        if (data === undefined || data.user === undefined || sid === undefined) {
+            throw new GatewayError('GATEWAY_UNREACHABLE', '网关续期成功但未返回会话标识', res.status);
+        }
+        const rawExpiresAt = typeof data.expires_at === 'string' ? data.expires_at : undefined;
+        const sessionExpiresAt = rawExpiresAt !== undefined && !Number.isNaN(Date.parse(rawExpiresAt))
+            ? rawExpiresAt
+            : undefined;
+        const rotated = typeof data.refresh_token === 'string' && data.refresh_token !== '' ? data.refresh_token : undefined;
+        return {
+            sessionCookie: `session_id=${sid}`,
+            user: data.user,
+            ...(sessionExpiresAt === undefined ? {} : { sessionExpiresAt }),
+            ...(rotated === undefined ? {} : { refreshToken: rotated }),
+        };
     }
     /** GET /api/auth/sessions：当前账号的登录设备列表。 */
     async listSessions(sessionCookie) {
@@ -551,6 +637,11 @@ export class AiRouterClient {
         if (res.status === 503) {
             throw new GatewayError('MCP_ASSERTION_DISABLED', '本部署未启用 MCP 断言签发，请联系管理员', 503);
         }
+        // 429：服务端限流（每用户 60 次/分）。与其余拒绝不同，这不是终局——调用方（MCP 同步）
+        // 吞掉单条失败等下一轮即可，故给独立 code 让消费方能区分「等一会」与「找管理员」。
+        if (res.status === 429) {
+            throw new GatewayError('MCP_ASSERTION_RATE_LIMITED', '断言签发过于频繁，稍后自动重试', 429);
+        }
         if (!res.ok)
             throw new GatewayError('GATEWAY_UNREACHABLE', `网关返回错误（HTTP ${res.status}）`, res.status);
         return await parseMeJson(res);
@@ -969,7 +1060,26 @@ export class AiRouterClient {
         }
         else if (opts.body !== undefined)
             init.body = JSON.stringify(opts.body);
-        return fetch(`${this.baseURL}${path}`, init);
+        const res = await fetch(`${this.baseURL}${path}`, init);
+        // 只有「带会话的请求」才产生活动信号：登录/兑换等尚无会话的请求不参与心跳与恢复。
+        if (opts.sessionCookie !== undefined) {
+            try {
+                if (res.status === 401)
+                    sessionActivitySink?.({ kind: 'unauthorized' });
+                else if (res.ok) {
+                    // 响应头带会话绝对寿命（网关 C5 起）：透传给宿主更新内存估计；不可解析当缺失。
+                    const headerExpiresAt = res.headers.get('x-session-expires-at');
+                    const expiresAt = headerExpiresAt !== null && !Number.isNaN(Date.parse(headerExpiresAt))
+                        ? headerExpiresAt
+                        : undefined;
+                    sessionActivitySink?.(expiresAt === undefined ? { kind: 'success' } : { kind: 'success', expiresAt });
+                }
+            }
+            catch {
+                // sink 是外部注入的观察者：它的异常绝不能影响请求结果本身。
+            }
+        }
+        return res;
     }
 }
 /**
@@ -1038,6 +1148,44 @@ export function extractSessionId(headers) {
     }
     return 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 function parseSessionCookieExpiry(headers, now = Date.now()) {
+    const raws = typeof headers.getSetCookie === 'function'
+        ? headers.getSetCookie()
+        : [headers.get('set-cookie')].filter((raw) => raw !== null);
+    for (const raw of raws) {
+        for (const section of raw.split(/,\s*(?=[!#$%&'*+\-.^_`|~0-9A-Za-z]+=)/)) {
+            if (!/(?:^|;\s*)session_id=/.test(section))
+                continue;
+            const expires = /;\s*Expires=([^;]+)/i.exec(section);
+            const expiresRaw = expires?.[1];
+            if (expiresRaw !== undefined) {
+                const ms = Date.parse(expiresRaw);
+                if (!Number.isNaN(ms))
+                    return new Date(ms).toISOString();
+            }
+            const maxAge = /;\s*Max-Age=(-?\d+)/i.exec(section);
+            if (maxAge !== null) {
+                const seconds = Number(maxAge[1]);
+                if (Number.isFinite(seconds))
+                    return new Date(now + seconds * 1000).toISOString();
+            }
+            return undefined;
+        }
+    }
+    return undefined;
+}
 /** 读取 JSON 响应体：解析失败返回 undefined（不抛错、不记录原文，避免敏感字段进日志）。 */
 async function readJson(res) {
     try {

package/lib/browser-login.js

@@ -15,7 +15,7 @@ import { hostname } from 'node:os';
 import { buildAuthorizeURL } from "./ai-router-client.js";
 // 供给尾部与端口契约在 provision-session.ts（该模块不反向 import 本文件，无循环依赖）。
 import { provisionSession, toLoginError, } from "./provision-session.js";
-import { SESSION_REF } from "./provision.js";
+import { REFRESH_TOKEN_REF, SESSION_REF } from "./provision.js";
 import { PKG_VERSION } from "./version.js";
 /** 待完成授权请求的有效期：超过 10 分钟的回调一律拒绝（授权页/一次性 code 早已失效）。 */
 export const BROWSER_LOGIN_TTL_MS = 10 * 60 * 1000;
@@ -241,12 +241,18 @@ export async function completeBrowserLogin(input, opts) {
         const baseURL = opts.value.baseURL;
         if (baseURL === undefined || baseURL === '')
             return await failBrowserLogin(opts.state, NO_BASE_URL_ERROR, log);
-        const { sessionCookie, user } = await opts.gateway.exchangeCode({
+        const { sessionCookie, user, sessionExpiresAt, refreshToken } = await opts.gateway.exchangeCode({
             code: input.code,
             codeVerifier: pending.codeVerifier,
             deviceId: pending.deviceId,
         });
         await opts.credentials.set(SESSION_REF, sessionCookie);
+        // 与表单登录同批落盘（浏览器授权是主登录面，缺了这一步静默续期对它永远无效）：
+        // 有 grant 即写，老网关没给则清掉残留旧值（防上一个账号的 grant 与新会话并存）。
+        if (refreshToken === undefined)
+            await opts.credentials.unset(REFRESH_TOKEN_REF).catch(() => { });
+        else
+            await opts.credentials.set(REFRESH_TOKEN_REF, refreshToken);
         const username = typeof user.username === 'string' && user.username.trim() !== '' ? user.username.trim() : undefined;
         await provisionSession({
             gateway: opts.gateway,
@@ -258,6 +264,7 @@ export async function completeBrowserLogin(input, opts) {
             sessionCookie,
             user,
             username,
+            sessionExpiresAt,
             requestUnset: ['browserLoginRequest', 'browserLogin'],
             ...(opts.defaultModel === undefined ? {} : { defaultModel: opts.defaultModel }),
             ...(opts.ensureWorkspace === undefined ? {} : { ensureWorkspace: opts.ensureWorkspace }),

package/lib/client-policy.js

@@ -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）。
  */
@@ -92,3 +94,76 @@ export async function fetchClientPolicy(opts) {
         return undefined;
     }
 }
+/** 策略轮询间隔（6h，对齐服务端 `Cache-Control: max-age=300` 的注释预期）。 */
+export const CLIENT_POLICY_POLL_INTERVAL_MS = 6 * 60 * 60_000;
+/**
+ * 失败退避阶梯（1min → 10min → 1h），末档封顶循环。
+ * 退避只影响「多久后重试」，不影响已经投影好的策略值——失败时保留上一轮结果。
+ */
+export const CLIENT_POLICY_RETRY_DELAYS_MS = [60_000, 10 * 60_000, 60 * 60_000];
+/**
+ * 自排程的策略轮询器（不用 setInterval：每轮的间隔由上一轮结果决定）。
+ *  - `attempt` 返回 true（成功拉到并投影）→ 6h 后再来；
+ *  - 返回 false 或抛异常 → 按 {@link CLIENT_POLICY_RETRY_DELAYS_MS} 退避，末档封顶循环；
+ *  - 任意一次成功把退避档归零（下一次失败重新从 1min 起步）；
+ *  - 定时器 `unref`，不拖住进程退出；`trigger()` 幂等（已排程/在飞时是 no-op），
+ *    让宿主 200ms 消费循环可以无脑反复调用。
+ */
+export function createClientPolicyPoller(deps) {
+    let timer;
+    let disposed = false;
+    let running = false;
+    let retryIndex = 0;
+    const schedule = (delayMs) => {
+        if (disposed)
+            return;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            void run();
+        }, delayMs);
+        timer.unref?.();
+    };
+    const run = async () => {
+        if (disposed || running)
+            return;
+        running = true;
+        let ok = false;
+        try {
+            ok = await deps.attempt();
+        }
+        catch {
+            // attempt 的实现方约定「不抛」，但轮询器不能因此死掉：异常一律视同失败。
+            ok = false;
+        }
+        finally {
+            running = false;
+        }
+        if (disposed)
+            return;
+        if (ok) {
+            retryIndex = 0;
+            schedule(CLIENT_POLICY_POLL_INTERVAL_MS);
+            return;
+        }
+        const delay = CLIENT_POLICY_RETRY_DELAYS_MS[Math.min(retryIndex, CLIENT_POLICY_RETRY_DELAYS_MS.length - 1)];
+        retryIndex += 1;
+        deps.log?.(`hiwork-core: 客户端策略拉取失败，${Math.round(delay / 1000)}s 后重试`);
+        schedule(delay);
+    };
+    return {
+        trigger: () => {
+            if (disposed || running || timer !== undefined)
+                return;
+            void run();
+        },
+        dispose: () => {
+            disposed = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+    };
+}