@genee/omp-opsx-addon 0.1.0

package/lib/agent-defs.ts

@@ -0,0 +1,291 @@
+export const ADDON_VERSION = '0.1.0';
+
+const MARKER = '<!-- @genee/omp-opsx-addon -->';
+
+const CODE_REVIEWER_MD = (model?: string) => `---
+name: code-reviewer
+description: OpenSpec 代码审查 agent，审查代码实现并执行全局验证
+tools: read, bash, glob, grep${model ? `\nmodel: ${model}` : ''}
+---
+
+你是一位资深代码审查员。你根据 OpenSpec 提案和设计文档审查代码实现，并在审阅的同时执行最后一次全局验证。
+
+## 启动
+1. 从 prompt 或上下文确定要审查的变更
+2. 读取 proposal、design 和 tasks 文件
+3. 运行 \`git diff HEAD~1\` 或 \`git diff --stat\` 查看改动
+
+## 审查维度
+1. **规范遵循**：是否精确实现了 proposal/design/tasks 定义的内容？有无缺失或偏离？
+2. **代码质量**：可读性、可维护性、模式一致性。代码异味、死代码、不必要的复杂性？
+3. **健壮性**：错误处理、边界情况、输入验证
+4. **安全性**：注入缺陷、授权问题、敏感数据暴露
+
+## 全局验证（交付前最后一道质量门）
+coder 已在其改动面完成自验证；你的验证是 maker-checker 的兜底确认，与代码审查同轮执行：
+- **Tier 1 – 环境完整性（必需）**：依赖安装、typecheck、lint
+- **Tier 2 – 冒烟测试（必需）**：运行项目现有测试套件（\`bun test\`/\`npm test\` 等）
+- **Tier 3 – E2E（可选）**：变更涉及用户可见行为时运行 E2E
+
+## 输出格式
+\`\`\`markdown
+## 审查: <change-name>
+
+**结论:** APPROVE | REQUEST_CHANGES | BLOCKED
+**轮次:** 第 N 次审查
+
+### 规范遵循
+- [x] 需求 1: <状态> / - [ ] 需求 N: <差距>
+
+### 关键问题 (必须修复)
+<P0/P1 列表，或 "无">
+
+### 改进建议 (可选修复)
+<P2+ 列表，或 "无">
+
+### 总结
+<1-2 句整体评估>
+
+### 全局验证
+- [x] / - [ ] Tier 1 环境完整性: <通过/失败项>
+- [x] / - [ ] Tier 2 冒烟测试: <通过/失败项>
+- [x] / - [ ] Tier 3 E2E（如适用）: <通过/失败或 N/A>
+- 验证失败项（按严重度）：<P0/P1 已并入关键问题；P2+ 告警，不阻塞通过>
+\`\`\`
+
+## 结论与上报
+你是审查员，**只审查、不改代码**。如实报告，由主 agent 决定是否委派 coder 修复。
+- **APPROVE** → 报告通过
+- **REQUEST_CHANGES + P0/P1** → 返回问题列表，由主 agent 委派 coder 修复
+- **REQUEST_CHANGES + 仅 P2+** → 视为通过，建议可选
+- **BLOCKED** → 说明原因，由用户决策
+- 全局验证失败项按严重度并入结论：P0/P1 → 关键问题（必须修复）；P2 级验证告警 → 改进建议，不阻塞通过
+${MARKER}
+`;
+const PROPOSAL_REVIEWER_MD = (model?: string) => `---
+name: proposal-reviewer
+description: OpenSpec 提案审查 agent，审查提案质量
+tools: read, bash, glob, grep${model ? `\nmodel: ${model}` : ''}
+---
+
+你是一位资深需求审查员。你审查 OpenSpec 提案的完整性和质量。
+
+## 启动
+1. 从 prompt 或上下文确定要审查的提案名称
+2. 读取 proposal.md、design.md（如果存在）
+
+## 审查维度
+1. **完整性**：Why/What/Capabilities/Impact 是否齐全？有无缺失章节？
+2. **需求清晰度**：描述是否清晰无歧义？实现方能否据此执行？
+3. **设计合理性**：方案是否实际可行？有无明显错漏或矛盾？
+4. **Budget 合理性**：Token 预算估算是否与工作范围匹配？
+5. **任务可执行性**：tasks.md 任务粒度是否合适？可独立交付？
+
+## 输出格式
+\`\`\`markdown
+## 提案审查: <change-name>
+
+**结论:** APPROVE | REQUEST_CHANGES | BLOCKED
+**轮次:** 第 N 次审查
+
+### 完整性
+- [x] / - [ ] <章节>：<状态>
+
+### 关键问题 (必须修复)
+<P0/P1 列表，或 "无">
+
+### 改进建议 (可选修复)
+<P2+ 列表，或 "无">
+
+### 总结
+<1-2 句整体评估>
+\`\`\`
+
+## 结论与上报
+- **APPROVE** → 提案通过
+- **REQUEST_CHANGES + P0/P1** → 返回问题列表，由主 agent 委派 planner 修复
+- **REQUEST_CHANGES + 仅 P2+** → 视为通过，建议可选
+- **BLOCKED** → 说明原因，由用户决策
+${MARKER}
+`;
+
+const CODER_MD = (model?: string) => `---
+name: coder
+description: OpenSpec 变更实现 agent，同步 tasks.md 进度
+tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: ${model}` : ''}
+skill: openspec-apply-change
+---
+
+你是一个快速、专注的代码实现 agent。你从 prompt 和对话上下文推断要做什么。
+
+## 启动：确定任务
+0. 加载技能：用 Skill tool 读取 skill://openspec-apply-change 并遵循其流程
+1. 若 prompt 提到变更名称或能推断：读取 \`openspec/changes/<name>/tasks.md\`、\`proposal.md\`、\`design.md\` 并实现未完成任务
+2. 若无名称：运行 \`openspec list --json\`；单个用其，多个或无则停止并询问
+3. 通用编码请求：从 prompt 理解需求直接实现
+
+## 实现规则
+- 写代码前先读现有代码；匹配项目风格和模式
+- 完成任务后在 tasks.md 标记：\`- [ ]\` → \`- [x]\`
+- 每轮结束时根据实际进度更新 tasks.md，确保提案状态与代码一致
+- 代码全部完成后将所有未完成项标记为 \`- [x]\`，在 ACTION 报告中说明变更已全部实现
+- 不修改 \`proposal.md\`、\`design.md\` 或 \`.openspec.yaml\`
+- 直接用 read/write/edit/bash 等内置工具实现；不要尝试调用 task 二次委派。
+## 验证（交付门槛）
+- 交付前必须跑过 **scoped 到本次改动面** 的 lint、typecheck 与针对性单测（proposal 约定的测试必须通过）；任一未通过不得交付，先修到通过再标记 ACTION: REVIEW_REQUIRED。
+- 项目级全量校验（全仓库 lint/typecheck/\`bun test\`）不属于自验证门槛：若失败可归因于并发 sibling 的半成品改动（与本改动无关），把失败连同「已排查与本改动无关」的证据作为上下文上报（交付摘要中注明），不要被其阻塞；最终由 code-reviewer 的全局验证兜底确认。
+
+## 协作流程（由你编排）
+1. **完成实现后**：向主 agent 报告，由主 agent 决定是否委派审查
+2. **收到审查反馈（P0/P1）**：反馈统一由 code-reviewer 回传（含全局验证失败）；用 read/edit/bash 修复后重新标记 ACTION: REVIEW_REQUIRED
+3. **轮次上限**：最多 3 轮（含首次实现与修复）；仍无法解决则 STATUS: blocked
+
+## 输出格式
+向主 agent 报告时以以下格式结尾：
+\`\`\`
+---
+ACTION: REVIEW_REQUIRED
+CHANGE: <change-name 或 "general">
+STATUS: success | partial | blocked
+SESSION: <session_name>（仅 STATUS: blocked 且需 resume 时填写）
+TASKS: N/M complete
+FILES: <逗号分隔的修改/创建文件列表>
+---
+\`\`\`
+收到 Review 反馈后，修复 P0/P1，输出中增加「本轮修复」章节；修复完成且需再审时 ACTION 仍为 REVIEW_REQUIRED。
+${MARKER}
+`;
+
+const PLANNER_MD = (model?: string) => `---
+name: planner
+description: OpenSpec 提案规划 agent
+tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: ${model}` : ''}\nskill: openspec-propose
+---
+
+你是一个 OpenSpec 提案规划 agent。负责创建和更新 OpenSpec 变更提案文档。
+
+## 启动：确定任务
+1. 加载技能：用 Skill tool 读取 skill://openspec-propose 并遵循其流程
+2. 若 prompt 提到变更名称或能推断：读取 \`openspec/changes/<name>/\` 下已有文件，根据需求创建或更新 proposal/design/tasks
+3. 若无名称：从 prompt 理解需求，确定名称并创建新变更目录
+4. 若提到使用 skill（如 openspec-propose）：用 Skill tool 加载并执行
+
+## 工作范围
+- **只负责提案文档**：proposal.md、design.md、tasks.md、specs/（openspec/changes/ 目录下）
+- 直接用内置工具；不要尝试调用 task 二次委派。
+
+## 提案拆分
+- 接大需求先评估契约边界:能拆则拆成多个小变更,先输出拆分建议(契约边界+提案清单)待主 agent 确认后再开写。
+- 纲领/roadmap change 只做层级管理(阶段/依赖/验收口径),不含实现细节。
+
+## Budget 估算
+
+在 proposal.md 末尾输出 \`## Budget Estimate\` 章节。Budget 必须覆盖**完整编排流程**的全部 agent 消耗（planner → proposal-reviewer → coder → code-reviewer + 可能的修复轮次），不只是提案撰写。
+
+### 快速公式
+\`总额 = (涉及文件数 × 80K + 固定编排开销 120K) × 轮次系数\`
+
+- **涉及文件数**：需修改或新建的源文件数量（不含 proposal/design/tasks 等提案文档本身）
+- **固定编排开销**：120K tokens（planner 30K + proposal-reviewer 20K + code-reviewer(审查+全局验证) 30K + 主 agent 委派及缓冲 40K）
+- **轮次系数**：预期 1 轮 = 1.0，2 轮 = 1.3，3 轮 = 1.5
+
+### 输出格式
+\`\`\`
+## Budget Estimate
+- 涉及文件数: &lt;F&gt;
+- 预计审查轮次: &lt;R&gt;
+- 预计实现 token: &lt;F × 80K × R&gt;K
+- 预计审查 token: &lt;R × 25K&gt;K
+- 编排固定开销: 120K
+- 建议 /goal budget: &lt;总额&gt;K tokens
+\`\`\`
+
+### 参考示例
+- 3 个文件、1 轮 → (240 + 120) × 1.0 = 360 → \`建议 /goal budget: 360K tokens\`
+- 8 个文件、2 轮 → (640 + 120) × 1.3 = 988 → \`建议 /goal budget: 990K tokens\`
+- 单文件修复、1 轮 → (80 + 120) × 1.0 = 200 → \`建议 /goal budget: 200K tokens\`
+
+## 输出
+完成后列出所有创建或修改的文件及变更名称。
+
+${MARKER}
+`;
+
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+type Status = 'unchanged' | 'created' | 'updated' | 'conflict';
+
+async function agentStatus(file: string, want: string): Promise<Status> {
+    if (!existsSync(file)) return 'created';
+    try {
+        const have = await readFile(file, 'utf-8');
+        if (have === want) return 'unchanged';
+        return have.includes(MARKER) ? 'updated' : 'conflict';
+    } catch {
+        return 'conflict';
+    }
+}
+
+export async function installAgents(
+    projectDir: string,
+    coderModel?: string,
+    reviewerModel?: string,
+    plannerModel?: string,
+    proposalReviewerModel?: string,
+): Promise<{ status: Status; conflicts: string[] }> {
+    const agentsDir = join(projectDir, '.omp', 'agents');
+    if (!existsSync(agentsDir)) await mkdir(agentsDir, { recursive: true });
+
+    const coderWant = CODER_MD(coderModel?.trim() || undefined);
+    const codeReviewerWant = CODE_REVIEWER_MD(reviewerModel?.trim() || undefined);
+    const plannerWant = PLANNER_MD(plannerModel?.trim() || undefined);
+    const proposalReviewerWant = PROPOSAL_REVIEWER_MD(proposalReviewerModel?.trim() || undefined);
+
+    const coderPath = join(agentsDir, 'coder.md');
+    const codeReviewerPath = join(agentsDir, 'code-reviewer.md');
+    const plannerPath = join(agentsDir, 'planner.md');
+    const proposalReviewerPath = join(agentsDir, 'proposal-reviewer.md');
+    const versionFile = join(agentsDir, '.addon-version');
+
+    const [coderStat, codeReviewerStat, plannerStat, proposalReviewerStat] = await Promise.all([
+        agentStatus(coderPath, coderWant),
+        agentStatus(codeReviewerPath, codeReviewerWant),
+        agentStatus(plannerPath, plannerWant),
+        agentStatus(proposalReviewerPath, proposalReviewerWant),
+    ]);
+
+    const conflicts: string[] = [];
+    const writes: Promise<void>[] = [];
+
+    for (const [path, stat, content] of [
+        [coderPath, coderStat, coderWant],
+        [codeReviewerPath, codeReviewerStat, codeReviewerWant],
+        [plannerPath, plannerStat, plannerWant],
+        [proposalReviewerPath, proposalReviewerStat, proposalReviewerWant],
+    ] as const) {
+        if (stat === 'conflict') {
+            conflicts.push(path.replace(agentsDir + '/', ''));
+        } else if (stat === 'created' || stat === 'updated') {
+            writes.push(writeFile(path, content, 'utf-8'));
+        }
+    }
+
+    if (
+        coderStat !== 'conflict' &&
+        codeReviewerStat !== 'conflict' &&
+        plannerStat !== 'conflict' &&
+        proposalReviewerStat !== 'conflict'
+    ) {
+        writes.push(writeFile(versionFile, ADDON_VERSION, 'utf-8'));
+    }
+
+    await Promise.all(writes);
+
+    const statuses = [coderStat, codeReviewerStat, plannerStat, proposalReviewerStat];
+    if (statuses.includes('conflict')) return { status: 'conflict', conflicts };
+    if (statuses.includes('created')) return { status: 'created', conflicts };
+    if (statuses.includes('updated')) return { status: 'updated', conflicts };
+    return { status: 'unchanged', conflicts };
+}

package/lib/change-scanner.ts

@@ -0,0 +1,72 @@
+import { readFile, readdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { countTaskCheckboxes } from './openspec-tasks.js';
+
+export type ChangeStatus = 'ready' | 'doing' | 'done';
+
+export interface ChangeInfo {
+    name: string;
+    status: ChangeStatus;
+    completed: number;
+    total: number;
+}
+
+function inferStatus(completed: number, total: number): ChangeStatus {
+    if (total === 0) return 'ready';
+    if (completed === total) return 'done';
+    return 'doing';
+}
+
+export async function scanChanges(directory: string, statusFilter?: ChangeStatus): Promise<ChangeInfo[]> {
+    const changesDir = join(directory, 'openspec', 'changes');
+    if (!existsSync(changesDir)) return [];
+
+    let names: string[];
+    try {
+        const entries = await readdir(changesDir, { withFileTypes: true });
+        names = entries
+            .filter((e) => e.isDirectory() && e.name !== 'archive')
+            .map((e) => e.name)
+            .sort();
+    } catch {
+        return [];
+    }
+
+    const results: ChangeInfo[] = [];
+    for (const name of names) {
+        const tasksPath = join(changesDir, name, 'tasks.md');
+        if (!existsSync(tasksPath)) {
+            results.push({ name, status: 'ready', completed: 0, total: 0 });
+            continue;
+        }
+        try {
+            const content = await readFile(tasksPath, 'utf-8');
+            const { completed, total } = countTaskCheckboxes(content);
+            results.push({ name, status: inferStatus(completed, total), completed, total });
+        } catch {
+            results.push({ name, status: 'ready', completed: 0, total: 0 });
+        }
+    }
+    if (statusFilter) return results.filter((r) => r.status === statusFilter);
+    return results;
+}
+
+export function createCachedScanner(ttlMs = 30_000, clock: () => number = Date.now) {
+    let cache: { dir: string; filter?: ChangeStatus; result: ChangeInfo[]; expiresAt: number } | null = null;
+
+    return {
+        async scanChanges(directory: string, statusFilter?: ChangeStatus): Promise<ChangeInfo[]> {
+            const now = clock();
+            if (cache && cache.dir === directory && cache.filter === statusFilter && now < cache.expiresAt) {
+                return cache.result;
+            }
+            const result = await scanChanges(directory, statusFilter);
+            cache = { dir: directory, filter: statusFilter, result, expiresAt: now + ttlMs };
+            return result;
+        },
+        invalidate() {
+            cache = null;
+        },
+    };
+}

package/lib/cursor-auth.ts

@@ -0,0 +1,230 @@
+/**
+ * Cursor IDE credential resolution for usage fetch.
+ *
+ * Cascade (local-only, no network for presence probes):
+ *   1. CURSOR_ACCESS_TOKEN env
+ *   2. Cursor IDE state.vscdb → cursorAuth/accessToken
+ *   3. In-process refreshed token (after oauth/token)
+ *
+ * The state DB is always opened read-only and never written.
+ */
+
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { Database } from 'bun:sqlite';
+
+export const CURSOR_OAUTH_CLIENT_ID = 'KbZUR41cY7W6zRSdpSUJ7I7mLYBKOCmB';
+export const CURSOR_TOKEN_URL = 'https://api2.cursor.sh/oauth/token';
+
+export interface CursorTokenStore {
+    accessToken?: string;
+    refreshToken?: string;
+    membershipType?: string;
+}
+
+export type CursorTokenReader = (dbPath: string) => CursorTokenStore | null;
+
+/** Process-memory access token from a successful refresh (not persisted). */
+let memoryAccessToken: string | undefined;
+
+let tokenReader: CursorTokenReader = defaultReadTokensFromDb;
+/** When set, overrides filesystem discovery of state.vscdb (tests). */
+let stateDbPathOverride: string | null | undefined;
+
+/** Test seam: replace the SQLite reader. Pass `null` to restore the default. */
+export function _setTokenReaderForTest(reader: CursorTokenReader | null): void {
+    tokenReader = reader ?? defaultReadTokensFromDb;
+}
+
+/** Test seam: force a db path (`null` = pretend missing; `undefined` = restore). */
+export function _setStateDbPathForTest(path: string | null | undefined): void {
+    stateDbPathOverride = path;
+}
+
+/** Test seam: clear / seed the in-process refreshed token. */
+export function _setMemoryAccessTokenForTest(token: string | undefined): void {
+    memoryAccessToken = token;
+}
+
+/** Cross-platform path to Cursor's globalStorage state.vscdb, or null if missing. */
+export function defaultStateDbPath(env: NodeJS.ProcessEnv = process.env, home = homedir()): string | null {
+    if (stateDbPathOverride !== undefined) return stateDbPathOverride;
+    const platform = process.platform;
+    let candidate: string;
+    if (platform === 'darwin') {
+        candidate = join(home, 'Library', 'Application Support', 'Cursor', 'User', 'globalStorage', 'state.vscdb');
+    } else if (platform === 'win32') {
+        const appData = env.APPDATA?.trim() || join(home, 'AppData', 'Roaming');
+        candidate = join(appData, 'Cursor', 'User', 'globalStorage', 'state.vscdb');
+    } else {
+        const xdg = env.XDG_CONFIG_HOME?.trim() || join(home, '.config');
+        candidate = join(xdg, 'Cursor', 'User', 'globalStorage', 'state.vscdb');
+    }
+    return existsSync(candidate) ? candidate : null;
+}
+
+function decodeJwtPayload(token: string): Record<string, unknown> | null {
+    try {
+        const part = token.split('.')[1];
+        if (!part) return null;
+        const padded = part + '='.repeat((4 - (part.length % 4)) % 4);
+        const json = Buffer.from(padded, 'base64url').toString('utf8');
+        return JSON.parse(json) as Record<string, unknown>;
+    } catch {
+        return null;
+    }
+}
+
+/** True when the JWT `exp` claim is in the past. Non-JWTs are treated as not expired. */
+export function isJwtExpired(token: string, nowMs: number = Date.now()): boolean {
+    const payload = decodeJwtPayload(token);
+    const exp = payload?.exp;
+    if (typeof exp !== 'number' || !Number.isFinite(exp)) return false;
+    return exp * 1000 <= nowMs;
+}
+
+function defaultReadTokensFromDb(dbPath: string): CursorTokenStore | null {
+    try {
+        const db = new Database(dbPath, { readonly: true });
+        try {
+            const row = (key: string): string | undefined => {
+                const r = db.query('SELECT value FROM ItemTable WHERE key = ?').get(key) as
+                    | { value?: unknown }
+                    | null
+                    | undefined;
+                if (!r || r.value == null) return undefined;
+                const v = r.value;
+                return typeof v === 'string' ? v : Buffer.isBuffer(v) ? v.toString('utf8') : String(v);
+            };
+            const accessToken = row('cursorAuth/accessToken')?.trim() || undefined;
+            const refreshToken = row('cursorAuth/refreshToken')?.trim() || undefined;
+            const membershipType = row('cursorAuth/stripeMembershipType')?.trim() || undefined;
+            if (!accessToken && !refreshToken) return null;
+            return { accessToken, refreshToken, membershipType };
+        } finally {
+            db.close();
+        }
+    } catch {
+        return null;
+    }
+}
+
+function readStore(env: NodeJS.ProcessEnv = process.env): CursorTokenStore {
+    const fromEnvAccess = env.CURSOR_ACCESS_TOKEN?.trim() || undefined;
+    const fromEnvRefresh = env.CURSOR_REFRESH_TOKEN?.trim() || undefined;
+    const dbPath = defaultStateDbPath(env);
+    const fromDb = dbPath ? tokenReader(dbPath) : null;
+    return {
+        accessToken: fromEnvAccess || memoryAccessToken || fromDb?.accessToken,
+        refreshToken: fromEnvRefresh || fromDb?.refreshToken,
+        membershipType: fromDb?.membershipType,
+    };
+}
+
+/**
+ * Sync, local-only probe — MUST NOT hit the network.
+ * True when env/IDE/memory can supply an access token string.
+ */
+export function cursorCredentialsPresent(env: NodeJS.ProcessEnv = process.env): boolean {
+    if (env.CURSOR_ACCESS_TOKEN?.trim()) return true;
+    if (memoryAccessToken?.trim()) return true;
+    const dbPath = defaultStateDbPath(env);
+    if (!dbPath) return false;
+    const store = tokenReader(dbPath);
+    return Boolean(store?.accessToken?.trim());
+}
+
+export interface ResolvedCursorAuth {
+    accessToken: string;
+    refreshToken?: string;
+    membershipType?: string;
+    /** True when the access token came from CURSOR_ACCESS_TOKEN. */
+    fromEnv: boolean;
+}
+
+/**
+ * Resolve an access token for usage fetch. May refresh once if the JWT is expired
+ * and a refresh token is available. Never writes back to the IDE DB.
+ */
+export async function resolveCursorAccessToken(opts?: {
+    env?: NodeJS.ProcessEnv;
+    nowMs?: number;
+    fetchImpl?: typeof fetch;
+    /** When true, force a refresh attempt even if the access token looks unexpired. */
+    forceRefresh?: boolean;
+}): Promise<ResolvedCursorAuth | null> {
+    const env = opts?.env ?? process.env;
+    const nowMs = opts?.nowMs ?? Date.now();
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+
+    const fromEnv = Boolean(env.CURSOR_ACCESS_TOKEN?.trim());
+    const store = readStore(env);
+    const access = store.accessToken?.trim() || undefined;
+    const refresh = store.refreshToken?.trim() || undefined;
+
+    if (access && !opts?.forceRefresh && !isJwtExpired(access, nowMs)) {
+        return {
+            accessToken: access,
+            refreshToken: refresh,
+            membershipType: store.membershipType,
+            fromEnv,
+        };
+    }
+
+    if (refresh) {
+        const next = await refreshCursorAccessToken(refresh, fetchImpl);
+        if (next) {
+            memoryAccessToken = next;
+            return {
+                accessToken: next,
+                refreshToken: refresh,
+                membershipType: store.membershipType,
+                fromEnv: false,
+            };
+        }
+    }
+
+    // Fall back to a still-present (possibly expired) access token so the caller
+    // can attempt the usage request and refresh on 401 — but only if we have one.
+    if (access) {
+        return {
+            accessToken: access,
+            refreshToken: refresh,
+            membershipType: store.membershipType,
+            fromEnv,
+        };
+    }
+    return null;
+}
+
+/**
+ * Exchange a refresh token for a new access token.
+ * Returns null on failure or when the server signals logout.
+ */
+export async function refreshCursorAccessToken(
+    refreshToken: string,
+    fetchImpl: typeof fetch = fetch,
+): Promise<string | null> {
+    try {
+        const res = await fetchImpl(CURSOR_TOKEN_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify({
+                grant_type: 'refresh_token',
+                client_id: CURSOR_OAUTH_CLIENT_ID,
+                refresh_token: refreshToken,
+            }),
+        });
+        if (!res.ok) return null;
+        const body = (await res.json()) as {
+            access_token?: string;
+            shouldLogout?: boolean;
+        };
+        if (body.shouldLogout) return null;
+        const next = body.access_token?.trim();
+        return next || null;
+    } catch {
+        return null;
+    }
+}