会话级 GitHub 令牌轮换

多用户服务可以为每个 session 注册 gitHubTokenProvider，在需要时获取用户令牌，而不是给整个 runtime 永久保存同一个用户 token。每个会话独立注册，可服务不同 GitHub host 与账户。

返回 token 与有效期

const session = await client.createSession({
    gitHubTokenProvider: async ({ host, sessionId, reason }) => {
        const token = await acquireGitHubToken({ host, sessionId, reason });
        return {
            kind: "token",
            accessToken: token.value,
            expiresIn: token.secondsRemaining,
        };
    },
});

acquireGitHubToken 是应用自己的凭据获取函数。expiresIn 必须是回调完成时仍剩余的正数秒数，不能无论实际过期时间都固定返回完整生命周期。

回调收到有效 GitHub host、session ID 和 reason，后者为 initial 或 refresh。只有云端会话尚未获得 ID 时，session ID 才缺省。不要同时设置会话静态 gitHubToken 与 token provider。

创建与恢复

runtime 在创建或恢复过程中执行 initial 获取。取消、回调异常、无效结果，或令牌不能提供稳定账户身份，都会使 create/resume 失败；不会回退到环境中的其他认证。

官方支持显式取消结果，但本页不猜测未展示的取消对象字段；按所用 SDK 类型定义返回。

何时刷新

会话建立后，runtime 在每次消费凭据的操作前异步检查。令牌剩余时间 1 小时或更少时请求 refresh；空闲会话不会持续后台刷新，要等下一次需要凭据的操作。

该机制不使用后台定时器，也不包含因请求被拒绝而自动重放、401/403 challenge 传播或权限提升。应用仍需设计取得新凭据、报告失败和用户重新认证的流程。

与其他 token 区分

这是 GitHub 用户身份的会话回调。BYOK 模型提供方使用 bearerTokenProvider；组织 installation token 使用 runtime 环境并通过重启更新，不能用这里的用户回调替代。参见认证与组织服务认证。