dsh-magpie-connector 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.6.3 — 2026-11-04
+
+- **用上 Codex 重置卡（首个写操作）。** 卡片展开区里最早到期的那一项带「使用…」；周窗口（`7 days`）用量达到 **80%**、且读数新鲜时才可用。host 在准备和提交前各重新读一次该卡并独立校验，不信任浏览器的判断。
+- **只用最早到期的那张。** host 从刚读到的 `resets.each[]` 里挑 `until` 最早、仍可用的一张，把它的 `id` 记进票据；浏览器拿不到也指定不了 `id`。提交前那张已不在可用列表时直接拒绝，不会改用别的卡。
+- **两段确认 + 全插件单飞。** 「使用…」→ 60 秒一次性票据 → 对话框（账号、周用量、所选卡到期时间、不可撤销警告）→ 必须勾选才能提交。同一时刻只允许一个准备/消费；新的准备会作废旧票据。
+- **结果判定。** `reset` 成功并用刷新响应更新卡片；`nothing_to_reset`/`no_credit`/`already_redeemed` 各有文案；4xx（权限不足、409 并发、入口白名单拒绝）说明没花掉，可重来；网络错误/超时/5xx/无法解析一律按「结果不确定」锁定该账号到 host 重启，不自动重试。
+- **传输边界。** 白名单新增 `POST /magpie/quotas/codex-reset`，query 只允许且必须带 `user`、`credit`；其它组合在发出前拒绝。
+- **UI 对齐 subscriptions。** 重置折叠块的箭头从 16px 字符换成 12px SVG（间距 6px），展开条目缩进 18px 与标题文字对齐，行高 28px，「使用…」紧贴「完整重置」。
+- 修复 README（中/英）里 0.5.2 遗留的重复行。规范：`openspec/changes/magpie-codex-reset-redeem/`。
+- 部署提示：线上入口（Cloudflare + 自建 nginx 白名单）放行 `codex-reset` 之前，该功能会如实显示网关的 403/404，卡片与生成不受影响；gateway key 需具备完整权限（只读/受限 key 被网关拒绝）。
+
 ## 0.6.2 — 2026-11-03
 
 - **Accordion instead of an overlay.** Expanding the sidebar usage card no longer covers the session list: the detail grows in flow inside the same card and the list gives up height from the bottom (the list keeps its top anchor, so rows do not jump). No divider line; the card surface and shadow carry the separation.

package/README.md

@@ -25,8 +25,8 @@ English · [简体中文](README.zh.md)
 | **Grouped by upstream provider** (signature) | Works on stock DSH, no Host extension needed: the plugin registers one real provider route per gateway `owned_by` (`dsh-magpie-connector-claude`, `-codex`, `-opencode-go`, …; missing or invalid ownership goes to `-other`), so the official model picker shows `Magpie (Claude)`, `Magpie (Codex)`, `Magpie (Opencode-go)`, `Magpie (Other)` groups. Settings and usage cards use the same grouping, and a provider that only appears in usage is never dropped. |
 | **Line panel and latency** | Configured lines start collapsed; click a row header to edit it, and reorder/delete are always-visible DSH product-icon buttons with tooltips. Opening Settings measures every saved line with a parseable address once (parallel TCP connect time, ≤600ms per line, no HTTP, no credentials) and shows a 4-bar signal plus milliseconds; timeouts show a timeout reading and failures or older hosts degrade to a dash. Display-only: it never affects automatic line selection, is not persisted, and never polls. |
 | **Per-line Cloudflare Access** | Each line independently chooses Direct or Cloudflare Access. Access-enabled line requests carry the service token pair plus the bearer key; the token is never sent to a plain-HTTP line. |
-| **Read-only usage cards** | Each upstream account shows plan, expiry, window readings and, when the gateway provides them, its Codex reset credits: a folded `Usage limit resets · N available` line that expands to each credit with its expiry and how far off the soonest is (`expires in N days`); plans that hand out one kind per window show `2 five-hour · 1 weekly` in the summary instead. Cards are read once when settings open and only re-read when you press **Refresh** on that card; bars turn orange above 70% and red at 90%. |
-| **Read-only usage cards** | Each upstream account shows plan, expiry, window readings and Codex reset credits when the gateway provides them. Cards are read once when settings open and only re-read when you press **Refresh** on that card; bars turn orange above 70% and red at 90%. |
+| **Usage cards** | Each upstream account shows plan, expiry, window readings and, when the gateway provides them, its Codex reset credits: a folded `Usage limit resets · N available` line that expands to each credit with its expiry and how far off the soonest is (`expires in N days`); plans that hand out one kind per window show `2 five-hour · 1 weekly` in the summary instead. Cards are read once when settings open and only re-read when you press **Refresh** on that card; bars turn orange above 70% and red at 90%. |
+| **Use a Codex reset** (0.6.3) | The credit that expires first carries a **Use…** button. It stays inert until the account's weekly usage is at least 80% and the reading is fresh, and the host revalidates against a fresh gateway read before and after you confirm. Confirming spends one credit: a 60-second one-shot ticket, a dialog showing the account, weekly usage and expiry, and a box you must tick first. One reset runs at a time plugin-wide, a 4xx from the gateway means nothing was spent, and an unreadable answer locks that account until the host restarts (check Magpie, do not retry). Needs a full-access gateway key and, behind a self-hosted ingress, an allowlist entry for `POST /magpie/quotas/codex-reset`. |
 | **Sidebar usage card** (0.6.0) | Settings → Magpie has a 「Sidebar usage」 switch (host setting, default off) and an auto-refresh interval (minutes, `0` = off, default 5). When on, a dense card sits above Settings: one weekly (`7 days`) row per upstream with its reading and bar, at most five rows with the rest scrolling inside and a overflow chevron when more exist, and one refresh for the whole card. Clicking the header row toggles an in-flow detail list (every window, reset time/chances, balance, error) that shrinks the session list instead of covering it; in rail mode a single Magpie icon opens the same content as a 320px popover. Reads reuse the existing usage endpoint with a 60s cache; only the configured interval polls, silently and paused while the page is hidden. |
 | **Model visibility and default effort** | Per provider, leave visibility untouched to follow the gateway catalog, or save an explicit allowlist so new models stay hidden. Per model, save a default reasoning effort; DSH applies it on the next request. |
 | **Per-session fast mode** | Models advertising the `priority` service tier get a standard/fast switch next to the composer. The choice is per session and in host memory only; it adds `service_tier: "priority"` to requests. |
@@ -71,7 +71,7 @@ Need another method — custom headers, mTLS, another zero-trust gateway? **Issu
 - **Only silence ends a stream.** Headers, SSE events and heartbeats all count as liveness; 300 seconds without any data ends the request with `TIMEOUT` (message contains `MAGPIE_STREAM_TIMEOUT`). Long reasoning survives as long as the gateway keeps the stream alive.
 - **Connection changes do not abort work.** A new address or key immediately hides the old catalog and cards, but generations already prepared or running finish with their captured address and key. User cancellation and plugin disposal still stop them.
 - **The transport is deliberately narrow.** Host requests go through a private `undici` dispatcher straight to the configured gateway, never through a global proxy dispatcher. Redirects are rejected; only `GET /models`, `POST /responses`, `POST /chat/completions`, `GET /magpie/quotas/cards` and `POST /magpie/quotas/refresh` are allowed; Magpie GUI `/api/*` management endpoints are never called. Provider egress proxies belong in Magpie.
-- **Not supported:** `stop` sequences fail before any network access (`MAGPIE_STOP_UNSUPPORTED`) because Magpie cannot preserve them across every upstream translation. Usage cards and Codex reset credits are display-only; the plugin never calls account-management or reset endpoints.
+- **Not supported:** `stop` sequences fail before any network access (`MAGPIE_STOP_UNSUPPORTED`) because Magpie cannot preserve them across every upstream translation. Usage cards are read-only. Spending a Codex reset is the plugin's only write to a Magpie account: it is manual, two-step, limited to the credit that expires first, and it never touches account-management endpoints.
 - **Secrets stay out of responses and logs.** Gateway-reflected text is redacted with the current key before it can reach the settings API or logs. Files are written `0600`; the settings API reports only `configured` / `writable`.
 - **The interface follows the DSH UI language.** Since 0.5.0 the settings page and the speed menu ship English and Chinese dictionaries and render in the active DSH language (`ctx.locale`); before 0.5.0 the copy was Chinese-only. A host without a locale service (or a unit test) falls back to the Chinese reference set, so stored settings and behaviour are untouched.
 

package/README.zh.md

@@ -23,8 +23,8 @@
 | **按上游 provider 分组**（特色） | 原版 DSH 即可使用，无需 Host 扩展：插件按网关 `owned_by` 为每个归属注册一个真实 provider route（`dsh-magpie-connector-claude`、`-codex`、`-opencode-go` 等；缺失或不合法归入 `-other`），官方模型选择器因此显示 `Magpie (Claude)`、`Magpie (Codex)`、`Magpie (Opencode-go)`、`Magpie (Other)` 分组。设置页和用量卡片使用同一套分组，只出现在用量里的 provider 也不会被丢弃。 |
 | **线路面板与延迟** | 已配置的线路默认全部收起，点行头部展开编辑；上移 / 下移 / 删除是常驻的 DSH 产品图标按钮（带 tooltip）。打开设置页对每条已保存且地址可解析的线路做一次 TCP 建连测速（并行、单条 ≤600ms、不发 HTTP、不带凭据），用 4 格信号条 + 毫秒显示；超时显示「超时」，旧版宿主或失败显示「—」。只展示当时的网络质量，不参与自动选线、不持久化、不轮询。 |
 | **按线路的 Cloudflare Access** | 每条线路可单独选择「直连」或「Cloudflare Access」。启用后该线路的请求带上服务令牌两项并保留 bearer key；服务令牌永远不会发往明文 HTTP 线路。 |
-| **只读用量卡片** | 每个上游账号展示计划、到期时间、各窗口读数和 Codex 重置卡（网关提供时）：折叠行「用量限制重置 · 可用 N 次」，展开逐张看到期时间与最早一张还剩多久（`N 天后过期`）；按窗口发放的计划摘要显示「5 小时 N 次 · 每周 M 次」。打开设置页只读一次，之后只有点单张卡片的「刷新」才会重新读取；用量条超过 70% 变橙、达到 90% 变红。 |
-| **只读用量卡片** | 每个上游账号展示计划、到期时间、各窗口读数和 Codex 重置次数（网关提供时）。打开设置页只读一次，之后只有点单张卡片的「刷新」才会重新读取；用量条超过 70% 变橙、达到 90% 变红。 |
+| **用量卡片** | 每个上游账号展示计划、到期时间、各窗口读数和 Codex 重置卡（网关提供时）：折叠行「用量限制重置 · 可用 N 次」，展开逐张看到期时间与最早一张还剩多久（`N 天后过期`）；按窗口发放的计划摘要显示「5 小时 N 次 · 每周 M 次」。打开设置页只读一次，之后只有点单张卡片的「刷新」才会重新读取；用量条超过 70% 变橙、达到 90% 变红。 |
+| **使用 Codex 重置卡**（0.6.3） | 最早到期的那张带「使用…」按钮。周用量 ≥ 80% 且读数新鲜时才可点；确认前后 host 都会重新读一次网关再校验。确认会消耗一次额度：60 秒一次性票据 + 对话框（账号、周用量、到期时间），必须先勾选才能提交。全插件同一时刻只允许一个；网关 4xx 说明没花掉；应答无法解析时该账号锁定到 host 重启（先去 Magpie 核对，不要重试）。需要完整权限的 gateway key；自建入口还需为 `POST /magpie/quotas/codex-reset` 放行。 |
 | **侧栏额度卡**（0.6.0） | 设置 → Magpie 新增「侧边栏额度」开关（host 持久化，默认关闭）与自动刷新间隔（分钟，`0` = 关闭，默认 5）。打开后左侧栏底部常驻一张密集卡片：每个上游一行周窗口（`7 days`）读数与进度条，最多 5 行、多出的在卡内滚动并显示溢出箭头，整张卡只有一个刷新。点标题行在手风琴里展开每个上游的全部窗口、重置时间/机会、余额与错误，占列表高度而不是盖住列表；侧栏收起时只剩一个 Magpie icon，点开是 320px 浮层。读取复用现有用量接口，客户端 60s 缓存，只有配置的间隔会静默轮询，页面隐藏时暂停。 |
 | **模型可见性与默认 effort** | 每个 provider 不设置可见性时跟随网关目录；保存过选择后只显示勾选项，新上架模型默认隐藏。每个模型可保存一个默认推理 effort，DSH 在下一次请求应用。 |
 | **会话级快速档** | 网关声明 `priority` 服务档的模型，输入框旁会出现标准/快速切换。选择按会话保存在 host 内存，快速档会给请求带上 `service_tier: "priority"`。 |

package/lib/client/SettingsPage.d.ts

@@ -16,3 +16,11 @@ export declare function MagpieSettings({ api }: {
 }): import("react").DetailedReactHTMLElement<{
     className: string;
 }, HTMLElement>;
+/**
+ * Why the host or the gateway said no, in the page's words. The host's codes are
+ * fixed strings; anything else falls back to its (already redacted) message.
+ */
+export declare function resetErrorText(response: {
+    status: number;
+    body: unknown;
+}): string;

package/lib/client/SettingsPage.js

@@ -6,7 +6,7 @@ import { settingsCss } from './styles.js';
 import { UsageCard } from './UsageCard.js';
 import { t } from './locales.js';
 import { DEFAULT_REFRESH_MINUTES, MAX_REFRESH_MINUTES, setSidebarPreference } from './sidebar-preference.js';
-import { cacheIds, cardKey, checkDiff, checkSignature, formatTime, parseCards, parseCheck, providerOrder, readTime, sameTarget, } from './view-model.js';
+import { cacheIds, cardKey, checkDiff, checkSignature, formatTime, parseCards, parseCheck, parseResetOutcome, parseResetTicket, providerOrder, readTime, resetAccount, sameTarget, } from './view-model.js';
 /**
  * Magpie settings section: connection (with an advanced access mode), then
  * per-provider groups (model visibility, DSH-side default effort, read-only
@@ -72,6 +72,11 @@ export function MagpieSettings({ api }) {
     const [usageAlert, setUsageAlert] = useState('');
     const [savingSettings, setSavingSettings] = useState(false);
     const [latency, setLatency] = useState({ phase: 'idle' });
+    const [resetConfirm, setResetConfirm] = useState();
+    const [resetBusyKey, setResetBusyKey] = useState();
+    const [resetConsuming, setResetConsuming] = useState(false);
+    const [resetAcknowledged, setResetAcknowledged] = useState(false);
+    const [resetStatuses, setResetStatuses] = useState({});
     const settingsRef = useRef(undefined);
     const settingsVersion = useRef(0);
     const settingsLock = useRef(false);
@@ -268,8 +273,7 @@ export function MagpieSettings({ api }) {
     };
     const groups = settings?.groups ?? [];
     const cardList = cards?.cards ?? [];
-    const busy = refreshing !== undefined;
-    // Catalog first, then an all-provider usage read: the only bulk refresh left, for when no card exists yet.
+    const busy = refreshing !== undefined; // Catalog first, then an all-provider usage read: the only bulk refresh left, for when no card exists yet.
     const fetchAll = async () => {
         const result = await mutateSettings({ resync: true });
         if (result?.view)
@@ -280,6 +284,85 @@ export function MagpieSettings({ api }) {
         }
     };
     const groupNote = (provider) => noteScope === provider ? { notice, alert: usageAlert } : {};
+    const setResetStatus = (key, status) => setResetStatuses(current => {
+        const next = { ...current };
+        if (status === undefined)
+            delete next[key];
+        else
+            next[key] = status;
+        return next;
+    });
+    /**
+     * Prepare a reset: the host re-reads the card, revalidates the guard and hands
+     * back a one-shot ticket. Nothing is spent until the dialog is confirmed.
+     */
+    const startReset = async (card) => {
+        const account = resetAccount(card);
+        if (!account || resetBusyKey !== undefined || resetConsuming)
+            return;
+        const key = cardKey(card);
+        setResetBusyKey(key);
+        setResetStatus(key, undefined);
+        try {
+            const response = await api({ method: 'POST', path: 'reset', body: { action: 'prepare', provider: 'codex', user: account } });
+            const ticket = isOk(response) ? parseResetTicket(response.body) : undefined;
+            if (!ticket) {
+                setResetStatus(key, { text: resetErrorText(response), tone: 'error' });
+                return;
+            }
+            setResetAcknowledged(false);
+            setResetConfirm({ card, ...ticket });
+        }
+        catch {
+            setResetStatus(key, { text: t('resetUseReadFailed'), tone: 'error' });
+        }
+        finally {
+            setResetBusyKey(undefined);
+        }
+    };
+    /** Spend the prepared credit. Every answer is reported where the button was. */
+    const confirmReset = async () => {
+        if (!resetConfirm || !resetAcknowledged || resetConsuming)
+            return;
+        const key = cardKey(resetConfirm.card);
+        setResetConsuming(true);
+        try {
+            const response = await api({ method: 'POST', path: 'reset', body: { action: 'consume', ticket: resetConfirm.ticket } });
+            const outcome = parseResetOutcome(response.body);
+            if (!isOk(response) || !outcome) {
+                setResetStatus(key, { text: resetErrorText(response), tone: response.status === 502 ? 'warn' : 'error' });
+                return;
+            }
+            if (outcome.outcome === 'reset') {
+                if (outcome.cards)
+                    setCards(parseCards({ status: 'ok', cards: outcome.cards }, 200));
+                setResetStatus(key, {
+                    text: outcome.windows === undefined ? t('resetUseSuccess') : `${t('resetUseSuccess')} · ${t('resetUseResetCode', { windows: outcome.windows })}`,
+                    tone: 'ok',
+                });
+            }
+            else if (outcome.outcome === 'uncertain')
+                setResetStatus(key, { text: t('resetUseUncertain'), tone: 'warn' });
+            else if (outcome.outcome === 'unconsumed')
+                setResetStatus(key, { text: t('resetUseUnconsumed', { reason: outcome.error ?? '' }), tone: 'error' });
+            else if (outcome.outcome === 'kept')
+                setResetStatus(key, { text: t('resetUseKept'), tone: 'ok' });
+            else if (outcome.outcome === 'no-credit')
+                setResetStatus(key, { text: t('resetUseNoCredit'), tone: 'error' });
+            else if (outcome.outcome === 'already')
+                setResetStatus(key, { text: t('resetUseAlready'), tone: 'error' });
+            else
+                setResetStatus(key, { text: t('resetUseUnknown', { code: outcome.code ?? '' }), tone: 'warn' });
+        }
+        catch {
+            // The browser gave up before the host answered: the spend may have happened.
+            setResetStatus(key, { text: t('resetUseUncertain'), tone: 'warn' });
+        }
+        finally {
+            setResetConsuming(false);
+            setResetConfirm(undefined);
+        }
+    };
     return h('div', { className: 'dmg-settings' }, h('style', null, settingsCss), h('p', { className: 'dmg-intro' }, t('intro')), settingsError ? h('p', { className: 'dmg-error', role: 'alert' }, t('settingsReadFailed', { error: settingsError })) : null, settings ? h(Connection, { settings, saving: savingSettings, mutateSettings, api, latency, onRefreshLatency: (lineId) => { void readLatency(lineId); },
         usage: h(UsageStatus, { cards, busy, ...(noteScope === undefined ? { notice, alert: usageAlert } : {}), onFetchAll: () => { void fetchAll(); }, saving: savingSettings }) })
         : settingsError ? null : h('p', { role: 'status', className: 'dmg-hint' }, t('readingSettings')), settings ? h(SidebarUsagePreference, { settings, saving: savingSettings, mutateSettings }) : null, ...providerOrder(groups, cardList).map(provider => h(ProviderGroup, {
@@ -288,8 +371,15 @@ export function MagpieSettings({ api }) {
         settings,
         cards: cardList.filter(c => c.provider === provider),
         busy, saving: savingSettings, mutateSettings, ...groupNote(provider),
+        resetBusyKey, resetStatuses,
+        onReset: (card) => { void startReset(card); },
         onRefresh: (card) => { void refresh({ provider: card.provider, ...(card.user !== undefined ? { user: card.user } : {}) }); },
-    })));
+    })), h(ResetDialog, {
+        confirm: resetConfirm, acknowledged: resetAcknowledged, busy: resetConsuming,
+        onAcknowledge: setResetAcknowledged,
+        onCancel: () => { setResetConfirm(undefined); setResetAcknowledged(false); },
+        onConfirm: () => { void confirmReset(); },
+    }));
 }
 /** What to tell the user after a 2xx refresh: unchanged read times, or a still-empty cold start. */
 function noticeAfter(target, before, next) {
@@ -328,6 +418,42 @@ function UsageStatus({ cards, busy, saving, notice, alert, onFetchAll }) {
         return null;
     return h('div', { className: 'dmg-usage', 'data-usage-state': state, 'aria-label': t('usageLabel') }, ...lines, canFetch ? h('div', { className: 'dmg-row' }, h('button', { type: 'button', className: 'dmg-button', disabled: busy || saving, onClick: onFetchAll }, t('fetchModelsAndUsage'))) : null);
 }
+/**
+ * Why the host or the gateway said no, in the page's words. The host's codes are
+ * fixed strings; anything else falls back to its (already redacted) message.
+ */
+export function resetErrorText(response) {
+    const reason = response.body?.error;
+    const code = typeof reason === 'string' ? reason : '';
+    if (code === 'MAGPIE_RESET_BUSY')
+        return t('resetUseBusy');
+    if (code === 'MAGPIE_RESET_UNCERTAIN' || code.startsWith('MAGPIE_RESET_UNCERTAIN:'))
+        return t('resetUseUncertain');
+    if (code === 'MAGPIE_RESET_GUARD')
+        return t('resetUseGuard');
+    if (code === 'MAGPIE_RESET_UNAVAILABLE' || code === 'MAGPIE_RESET_CREDIT_GONE')
+        return t('resetUseUnavailable');
+    if (code === 'MAGPIE_RESET_REFRESH')
+        return t('resetUseRefresh');
+    if (code === 'MAGPIE_RESET_TICKET_INVALID')
+        return t('resetUseTicketInvalid');
+    if (code === 'MAGPIE_RESET_TICKET_EXPIRED')
+        return t('resetUseTicketExpired');
+    if (code.startsWith('MAGPIE_RESET_READ_FAILED'))
+        return t('resetUseReadFailed');
+    return failureText(response);
+}
+/**
+ * The confirmation of an irreversible spend. Rendered as an open `<dialog>` inside
+ * a backdrop: the shell has no modal service, and a plain element keeps the page
+ * testable without `showModal`. The confirm button stays inert until the box is ticked.
+ */
+function ResetDialog({ confirm, acknowledged, busy, onAcknowledge, onCancel, onConfirm }) {
+    if (!confirm)
+        return null;
+    const { card } = confirm;
+    return h('div', { className: 'dmg-modal-backdrop', 'data-reset-dialog': '' }, h('dialog', { open: true, className: 'dmg-modal', 'aria-labelledby': 'dmg-reset-title' }, h('h3', { id: 'dmg-reset-title' }, t('resetUseConfirmTitle')), h('p', { className: 'dmg-hint', 'data-reset-account': '' }, `${t('resetUseAccount')}：${card.user ?? ''}`), confirm.weeklyUsedPercent === undefined ? null : h('p', { className: 'dmg-hint', 'data-reset-weekly': '' }, `${t('resetUseWeekly')} ${Math.round(confirm.weeklyUsedPercent)}%`), confirm.creditExpiresAt === undefined ? null : h('p', { className: 'dmg-hint', 'data-reset-credit': '' }, t('resetCreditExpires', { date: formatTime(confirm.creditExpiresAt) })), h('p', { className: 'dmg-warn' }, t('resetUseWarning')), h('label', { className: 'dmg-check-row' }, h('input', { type: 'checkbox', checked: acknowledged, 'data-reset-acknowledge': '', onChange: (e) => onAcknowledge(e.target.checked) }), h('span', null, t('resetUseAcknowledge'))), h('div', { className: 'dmg-row' }, h('button', { type: 'button', className: 'dmg-button', onClick: onCancel }, t('cancel')), h('button', { type: 'button', className: 'dmg-button', 'data-reset-confirm': '', disabled: !acknowledged || busy, onClick: onConfirm }, busy ? t('resetUseConfirming') : t('resetUseConfirm')))));
+}
 async function postSettings(api, body) {
     try {
         const response = await api({ method: 'POST', path: 'settings', body });
@@ -595,7 +721,7 @@ function SyncStatus({ settings }) {
     const registration = settings.routeRegistrationError;
     return h('div', { className: 'dmg-meta', 'data-sync': '' }, settings.lastSyncAt ? h('p', null, t('modelsCount', { n: count }), h('time', { dateTime: settings.lastSyncAt }, formatTime(settings.lastSyncAt))) : null, settings.lastSyncError ? h('p', { className: 'dmg-error' }, t('syncFailed', { kind: settings.lastSyncErrorKind ? t('syncFailedKind', { kind: t(SYNC_KIND[settings.lastSyncErrorKind] ?? 'syncKindHttp') }) : '', error: settings.lastSyncError })) : null, registration ? h('p', { className: 'dmg-error', role: 'alert' }, t('routeRegistrationFailed', { code: registration.code, route: registration.route ? `, ${registration.route}` : '' })) : null, settings.knownOwnersReset ? h('p', { className: 'dmg-hint' }, t('ownersReset')) : null, settings.ownerLimitReached ? h('p', { className: 'dmg-hint' }, t('ownerLimitReached', { list: rejected.join(t('listSeparator')) })) : null);
 }
-function ProviderGroup({ provider, group, settings, cards, busy, saving, mutateSettings, onRefresh, notice, alert }) {
+function ProviderGroup({ provider, group, settings, cards, busy, saving, mutateSettings, onRefresh, onReset, resetBusyKey, resetStatuses, notice, alert }) {
     const [error, setError] = useState('');
     const saved = settings?.visibleModels ?? {};
     const following = !Object.hasOwn(saved, provider);
@@ -629,7 +755,12 @@ function ProviderGroup({ provider, group, settings, cards, busy, saving, mutateS
         effort: settings?.defaultEfforts?.[model.id],
         onVisible: (visible) => setVisible(model, visible),
         onEffort: (effort) => { void post({ defaultEffort: { model: model.id, effort } }); },
-    }))) : null, cards.length ? h('div', { className: 'dmg-cards' }, ...cards.map(card => h(UsageCard, { key: cardKey(card), card, busy, onRefresh: () => onRefresh(card) }))) : null, notice === 'not-reread' ? h('p', { className: 'dmg-hint', role: 'status' }, t('notReread')) : null, alert ? h('p', { className: 'dmg-error', role: 'alert', 'data-usage-alert': '' }, alert) : null, error ? h('p', { className: 'dmg-error', role: 'alert' }, error) : null);
+    }))) : null, cards.length ? h('div', { className: 'dmg-cards' }, ...cards.map(card => h(UsageCard, {
+        key: cardKey(card), card, busy, disabled: saving,
+        resetBusy: resetBusyKey === cardKey(card),
+        ...(resetStatuses?.[cardKey(card)] === undefined ? {} : { resetStatus: resetStatuses[cardKey(card)] }),
+        onRefresh: () => onRefresh(card), onReset: () => onReset(card),
+    }))) : null, notice === 'not-reread' ? h('p', { className: 'dmg-hint', role: 'status' }, t('notReread')) : null, alert ? h('p', { className: 'dmg-error', role: 'alert', 'data-usage-alert': '' }, alert) : null, error ? h('p', { className: 'dmg-error', role: 'alert' }, error) : null);
 }
 function ModelLine({ model, visible, effort, disabled, onVisible, onEffort }) {
     const efforts = model.efforts ?? [];

package/lib/client/UsageCard.d.ts

@@ -1,10 +1,17 @@
 import { type Card } from './view-model.js';
 /** Bar colour: ≤70% normal (blue), above 70 and below 90 warn (orange), 90% and above high (red). */
 export declare const usageLevel: (used: number) => "high" | "normal" | "warn";
-export declare function UsageCard({ card, busy, onRefresh }: {
+export declare function UsageCard({ card, busy, onRefresh, disabled, resetBusy, resetStatus, onReset }: {
     card: Card;
     busy: boolean;
     onRefresh: () => void;
+    disabled?: boolean;
+    resetBusy?: boolean;
+    resetStatus?: {
+        text: string;
+        tone: 'ok' | 'error' | 'warn';
+    };
+    onReset?: (card: Card) => void;
 }): import("react").DetailedReactHTMLElement<{
     className: string;
     'data-card': string;

package/lib/client/UsageCard.js

@@ -1,10 +1,10 @@
 import { createElement as h } from 'react';
-import { expiryHint, formatTime, readTime, windowReading } from './view-model.js';
+import { expiryHint, formatTime, readTime, resetAccount, resetBlock, windowReading } from './view-model.js';
 import { t } from './locales.js';
 /**
- * One read-only usage card. Every gateway string is a React text child (never
- * HTML), absent fields are omitted, and the only control is "刷新" — there is
- * deliberately no reset action (the Codex reset credits are display-only).
+ * One usage card. Every gateway string is a React text child (never HTML),
+ * absent fields are omitted. The only controls are "刷新" and — on a card whose
+ * resets the host marked redeemable — "使用…" on the credit that expires first.
  */
 const time = (raw) => h('time', { dateTime: raw }, formatTime(raw));
 /** A reset credit's expiry: the localized instant, "expires …", in one machine-readable `<time>`. */
@@ -18,6 +18,8 @@ const inline = (nodes) => nodes.flatMap((node, index) => index === 0 ? [node] :
 const windowLabel = (window) => window === 'fiveHour' ? t('resetWindowFiveHour') : window === 'weekly' ? t('resetWindowWeekly') : undefined;
 /** Bar colour: ≤70% normal (blue), above 70 and below 90 warn (orange), 90% and above high (red). */
 export const usageLevel = (used) => used >= 90 ? 'high' : used > 70 ? 'warn' : 'normal';
+/** The reset area's disclosure arrow: a 12px glyph, so the unfolded rows line up with the title text. */
+const ResetChevron = () => h('svg', { className: 'dmg-reset-chevron', 'aria-hidden': true, width: 12, height: 12, viewBox: '0 0 16 16' }, h('path', { d: 'm6 3 5 5-5 5', fill: 'none', stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round', strokeLinejoin: 'round' }));
 function WindowRow({ window }) {
     const reading = windowReading(window);
     const showReset = reading !== undefined && window.unlimited !== true && !present(window.display) && present(window.resetsAt);
@@ -38,28 +40,50 @@ function resetCount(resets) {
         : null;
 }
 /** One reset credit: which kind it is, when it runs out and, for the soonest, how far off that is. */
-function resetItem(item, soonest, key) {
+function resetItem(item, soonest, key, action) {
     const at = item.until;
     const hint = present(at) && soonest !== undefined && Date.parse(at) === soonest ? expiryHint(at) : undefined;
-    return h('div', { className: 'dmg-reset-item', 'data-reset-item': '', key }, h('span', null, windowLabel(item.window) ?? t('resetCreditFull')), h('span', null, present(at) ? expiryTime(at) : t('resetCreditExpiryUnknown'), hint === undefined ? null : [' · ', hint]));
+    return h('div', { className: 'dmg-reset-item', 'data-reset-item': '', key }, h('span', { className: 'dmg-reset-kind' }, h('span', null, windowLabel(item.window) ?? t('resetCreditFull')), action === undefined ? null : action), h('span', { className: 'dmg-reset-when' }, present(at) ? expiryTime(at) : t('resetCreditExpiryUnknown'), hint === undefined ? null : [' · ', hint]));
+}
+/** The "use" button of one credit: disabled state is explained on hover, never silently inert. */
+function resetButton(card, busy, blocked, onReset) {
+    const reason = resetBlock(card);
+    const label = busy ? t('resetUseChecking') : t('resetUseButton');
+    const title = busy ? t('resetUseChecking') : reason === 'guard' ? t('resetUseGuard') : reason === 'refresh' ? t('resetUseRefresh') : reason === 'restart' ? t('resetUseRestart') : t('resetUseReady');
+    const inactive = busy || blocked || reason !== undefined;
+    return h('button', {
+        type: 'button', className: 'dmg-reset-use', 'data-reset-use': '', 'aria-disabled': inactive ? 'true' : 'false', title,
+        ...(inactive ? {} : { 'data-ready': '' }),
+        onClick: () => { if (!inactive)
+            onReset?.(); },
+    }, label);
 }
 /**
  * The card's reset credits, folded like the subscriptions plugin does: the count
- * on the summary line, every credit and its expiry when opened. Read-only —
- * spending a credit is not offered here.
+ * on the summary line, every credit and its expiry when opened, and the use
+ * action on the credit that runs out first.
  */
-function ResetLine({ resets }) {
+function ResetLine({ card, resets, busy, blocked, onReset }) {
     const each = resets.each ?? [];
     const items = each.length ? each : present(resets.until) ? [{ until: resets.until }] : [];
     const times = items.flatMap(item => { const at = present(item.until) ? Date.parse(item.until) : NaN; return Number.isNaN(at) ? [] : [at]; });
-    // The soonest credit carries the relative hint; it is the one worth not wasting.
+    // The soonest credit carries the relative hint and the use action; it is the one worth not wasting.
     const soonest = times.length ? Math.min(...times) : undefined;
     const count = resetCount(resets);
     if (count === null && items.length === 0)
         return null;
-    return h('details', { className: 'dmg-resets', 'data-field': 'resets' }, h('summary', null, h('span', { className: 'dmg-chevron', 'aria-hidden': true }, '▸'), h('span', null, t('resetCreditsTitle')), count === null ? null : h('span', { className: 'dmg-resets-count' }, count)), items.length ? h('div', { className: 'dmg-reset-items' }, ...items.map((item, index) => resetItem(item, soonest, `reset-${index}`))) : null);
+    // The host marks the card, but the premise is also checked here: only a named Codex
+    // account can be spent for, and without that there is nothing to send.
+    const actionable = resets.redeemable === true && resetAccount(card) !== undefined && onReset !== undefined;
+    return h('details', { className: 'dmg-resets', 'data-field': 'resets' }, h('summary', null, h('span', { className: 'dmg-reset-chevron-slot', 'aria-hidden': true }, h(ResetChevron, null)), h('span', null, t('resetCreditsTitle')), count === null ? null : h('span', { className: 'dmg-resets-count' }, count)), items.length ? h('div', { className: 'dmg-reset-items' }, ...items.map((item, index) => {
+        const at = present(item.until) ? Date.parse(item.until) : NaN;
+        // A credit with no expiry never runs out, so every credit ties; the first one
+        // then stands in for "soonest" instead of leaving the card without an action.
+        const isSoonest = soonest === undefined ? index === 0 : !Number.isNaN(at) && at === soonest;
+        return resetItem(item, soonest, `reset-${index}`, actionable && isSoonest ? resetButton(card, busy, blocked, () => onReset(card)) : undefined);
+    })) : null);
 }
-export function UsageCard({ card, busy, onRefresh }) {
+export function UsageCard({ card, busy, onRefresh, disabled, resetBusy, resetStatus, onReset }) {
     const read = readTime(card);
     const facts = [
         present(card.user) && fact('user', t('usageUser'), card.user),
@@ -70,5 +94,5 @@ export function UsageCard({ card, busy, onRefresh }) {
         present(read) && fact('readAt', card.asOf !== undefined ? t('usageReadAtStale') : t('usageReadAt'), time(read)),
     ].filter(Boolean);
     const resets = card.resets;
-    return h('article', { className: 'dmg-card', 'data-card': '' }, h('div', { className: 'dmg-card-title' }, h('strong', null, present(card.name) ? card.name : card.provider), h('button', { type: 'button', className: 'dmg-button', disabled: busy, onClick: onRefresh }, t('refresh'))), facts.length ? h('div', { className: 'dmg-facts' }, ...facts) : null, ...(card.windows ?? []).map((window, index) => h(WindowRow, { key: `window-${index}`, window })), resets ? h(ResetLine, { resets }) : null, present(card.error) ? h('p', { className: 'dmg-error', 'data-field': 'error', role: 'alert' }, card.error) : null);
+    return h('article', { className: 'dmg-card', 'data-card': '' }, h('div', { className: 'dmg-card-title' }, h('strong', null, present(card.name) ? card.name : card.provider), h('button', { type: 'button', className: 'dmg-button', disabled: busy || disabled === true, onClick: onRefresh }, t('refresh'))), facts.length ? h('div', { className: 'dmg-facts' }, ...facts) : null, ...(card.windows ?? []).map((window, index) => h(WindowRow, { key: `window-${index}`, window })), resets ? h(ResetLine, { resets, card, busy: resetBusy === true, blocked: disabled === true, onReset }) : null, resetStatus ? h('p', { className: resetStatus.tone === 'error' ? 'dmg-error' : resetStatus.tone === 'warn' ? 'dmg-warn' : 'dmg-ok', role: resetStatus.tone === 'error' ? 'alert' : 'status', 'data-reset-status': resetStatus.tone }, resetStatus.text) : null, present(card.error) ? h('p', { className: 'dmg-error', 'data-field': 'error', role: 'alert' }, card.error) : null);
 }

package/lib/client/api.d.ts

@@ -3,7 +3,7 @@
  * `/api/dsh-magpie-connector/`. Responses are bare JSON; errors are non-2xx with
  * `{error: string}`. Injected so tests replace it without touching `fetch`.
  */
-export type Resource = 'settings' | 'cards' | 'speed' | 'line-check' | 'latency';
+export type Resource = 'settings' | 'cards' | 'speed' | 'line-check' | 'latency' | 'reset';
 export interface ApiRequest {
     method: 'GET' | 'POST';
     path: Resource;

package/lib/client/api.js

@@ -1,9 +1,15 @@
 const TIMEOUT_MS = 30_000;
+/**
+ * Spending a reset outlives the generic budget: the host waits up to 45s for the
+ * gateway, which itself may spend 20s and then re-read the account for 15s. The
+ * browser must not give up first — a timeout here reads as "outcome unknown".
+ */
+const RESET_TIMEOUT_MS = 60_000;
 export function createFetchApi(base = '/api/dsh-magpie-connector/') {
     return async ({ method, path, query, body }) => {
         const search = query ? `?${new URLSearchParams(query).toString()}` : '';
         const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        const timer = setTimeout(() => controller.abort(), path === 'reset' ? RESET_TIMEOUT_MS : TIMEOUT_MS);
         try {
             const response = await fetch(`${base}${path}${search}`, {
                 method,

package/lib/client/locales.d.ts

@@ -37,6 +37,7 @@ export declare const en: {
     refreshModels: string;
     modelsRefreshed: string;
     save: string;
+    cancel: string;
     saving: string;
     addLine: string;
     addBackupLine: string;
@@ -147,6 +148,32 @@ export declare const en: {
     resetExpired: string;
     resetInHours: string;
     resetInDays: string;
+    resetUseButton: string;
+    resetUseChecking: string;
+    resetUseConfirming: string;
+    resetUseGuard: string;
+    resetUseRefresh: string;
+    resetUseRestart: string;
+    resetUseReady: string;
+    resetUseConfirmTitle: string;
+    resetUseWarning: string;
+    resetUseAcknowledge: string;
+    resetUseConfirm: string;
+    resetUseSuccess: string;
+    resetUseKept: string;
+    resetUseNoCredit: string;
+    resetUseAlready: string;
+    resetUseUnknown: string;
+    resetUseUnconsumed: string;
+    resetUseUncertain: string;
+    resetUseBusy: string;
+    resetUseTicketInvalid: string;
+    resetUseTicketExpired: string;
+    resetUseUnavailable: string;
+    resetUseReadFailed: string;
+    resetUseAccount: string;
+    resetUseWeekly: string;
+    resetUseResetCode: string;
     yes: string;
     no: string;
     unlimited: string;

package/lib/client/locales.js

@@ -37,6 +37,7 @@ export const en = {
     refreshModels: 'Refresh model list',
     modelsRefreshed: 'Model list refreshed',
     save: 'Save',
+    cancel: 'Cancel',
     saving: 'Saving…',
     addLine: 'Add line',
     addBackupLine: 'Add backup line',
@@ -147,6 +148,32 @@ export const en = {
     resetExpired: 'expired',
     resetInHours: 'in {n}h',
     resetInDays: 'in {n}d',
+    resetUseButton: 'Use…',
+    resetUseChecking: 'Checking…',
+    resetUseConfirming: 'Spending…',
+    resetUseGuard: 'You can use this reset once weekly usage reaches 80%.',
+    resetUseRefresh: 'Refresh usage to confirm the current limits and reset availability.',
+    resetUseRestart: 'Reset details are missing. Refresh usage and try again.',
+    resetUseReady: 'Spend the reset that expires first. This needs confirmation.',
+    resetUseConfirmTitle: 'Confirm a full reset',
+    resetUseWarning: 'This spends one reset and restarts the weekly and 5-hour limits. It cannot be undone, and this confirmation expires in 60 seconds.',
+    resetUseAcknowledge: 'I understand that one reset will be spent.',
+    resetUseConfirm: 'Spend one reset',
+    resetUseSuccess: 'Reset confirmed. Usage refreshed.',
+    resetUseKept: 'Nothing needed resetting, so no reset was spent.',
+    resetUseNoCredit: 'This account has no reset left.',
+    resetUseAlready: 'That reset was already used.',
+    resetUseUnknown: 'The gateway reported “{code}”.',
+    resetUseUnconsumed: 'The gateway did not run the reset: {reason}',
+    resetUseUncertain: 'The outcome could not be confirmed. Check the account in Magpie before trying again — do not retry or restart to get around this.',
+    resetUseBusy: 'Another reset is already in progress. Wait for it to finish.',
+    resetUseTicketInvalid: 'That confirmation is no longer valid. Start again.',
+    resetUseTicketExpired: 'That confirmation expired. Start again.',
+    resetUseUnavailable: 'That reset is no longer available. Refresh and try again.',
+    resetUseReadFailed: 'Could not read fresh usage, so no reset was submitted.',
+    resetUseAccount: 'Account',
+    resetUseWeekly: 'Weekly usage',
+    resetUseResetCode: '{windows} windows restarted',
     yes: 'Yes',
     no: 'No',
     unlimited: 'Unlimited',
@@ -193,6 +220,7 @@ export const zh = {
     refreshModels: '刷新模型列表',
     modelsRefreshed: '已刷新模型列表',
     save: '保存',
+    cancel: '取消',
     saving: '保存中…',
     addLine: '添加线路',
     addBackupLine: '添加备用线路',
@@ -303,6 +331,32 @@ export const zh = {
     resetExpired: '已过期',
     resetInHours: '{n} 小时后过期',
     resetInDays: '{n} 天后过期',
+    resetUseButton: '使用…',
+    resetUseChecking: '正在检查…',
+    resetUseConfirming: '正在提交…',
+    resetUseGuard: '每周用量达到 80% 后才可使用此重置。',
+    resetUseRefresh: '请刷新用量，确认当前限额与重置可用性。',
+    resetUseRestart: '缺少重置详情。请刷新用量后重试。',
+    resetUseReady: '使用最早到期的这张重置，操作前需要确认。',
+    resetUseConfirmTitle: '确认完整重置',
+    resetUseWarning: '将消耗一次重置额度，重置每周与 5 小时限额。无法撤销，确认 60 秒后失效。',
+    resetUseAcknowledge: '我理解将消耗一次额度。',
+    resetUseConfirm: '消耗一次重置',
+    resetUseSuccess: '重置已确认，用量已刷新。',
+    resetUseKept: '没有需要重置的窗口，额度未消耗。',
+    resetUseNoCredit: '该账号已没有可用的重置额度。',
+    resetUseAlready: '这张重置已被使用。',
+    resetUseUnknown: '网关返回了「{code}」。',
+    resetUseUnconsumed: '网关没有执行重置：{reason}',
+    resetUseUncertain: '结果无法确认。请先在 Magpie 核对账号状态再试，不要依靠重试或重启绕过。',
+    resetUseBusy: '已有重置操作在进行，请等它完成。',
+    resetUseTicketInvalid: '确认已失效，请重新开始。',
+    resetUseTicketExpired: '确认已过期，请重新开始。',
+    resetUseUnavailable: '这张重置已不可用，请刷新后重试。',
+    resetUseReadFailed: '无法读取最新用量，未提交重置。',
+    resetUseAccount: '账号',
+    resetUseWeekly: '每周用量',
+    resetUseResetCode: '{windows} 个窗口已重置',
     yes: '是',
     no: '否',
     unlimited: '无限',

package/lib/client/styles.js

@@ -45,12 +45,24 @@ export const settingsCss = `
 .dmg-resets>summary{display:flex;align-items:center;gap:6px;cursor:pointer;list-style:none;color:var(--dsw-alias-label-secondary)}
 .dmg-resets>summary::-webkit-details-marker{display:none}
 .dmg-resets>summary:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px;border-radius:8px}
-.dmg-resets[open]>summary .dmg-chevron{transform:rotate(90deg)}
+.dmg-reset-chevron-slot{display:inline-flex;flex:none;width:12px;height:12px;align-items:center;justify-content:center;color:var(--dsw-alias-label-tertiary);transition:transform 100ms ease}
+.dmg-resets[open]>summary .dmg-reset-chevron-slot{transform:rotate(90deg)}
 .dmg-resets-count{margin-left:auto;color:var(--dsw-alias-label-tertiary);white-space:nowrap}
 .dmg-reset-items{display:flex;flex-direction:column;gap:2px;margin-top:6px;padding-left:18px}
-.dmg-reset-item{display:flex;align-items:baseline;justify-content:space-between;gap:12px;min-height:20px;color:var(--dsw-alias-label-tertiary)}
-.dmg-reset-item>span:first-child{color:var(--dsw-alias-label-secondary)}
+.dmg-reset-item{display:flex;align-items:center;justify-content:space-between;gap:12px;min-height:28px;color:var(--dsw-alias-label-tertiary)}
+.dmg-reset-kind{display:inline-flex;align-items:center;gap:8px;flex:none;color:var(--dsw-alias-label-secondary)}
+.dmg-reset-when{margin-left:auto;text-align:right}
+.dmg-reset-use{height:22px;min-height:22px;padding:0 7px;border:.5px solid var(--dsw-alias-border-l4);border-radius:8px;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit;font-size:12px;line-height:1;cursor:pointer;white-space:nowrap}
+.dmg-reset-use:hover[data-ready]{background:var(--dsw-alias-interactive-bg-hover)}
+.dmg-reset-use[aria-disabled=true]{opacity:.4;cursor:not-allowed}
+.dmg-reset-use:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}
 .dmg-reset-item time{color:var(--dsw-alias-label-tertiary)}
+.dmg-warn{color:var(--dsw-alias-state-warn-primary);font-size:12px;overflow-wrap:anywhere}
+.dmg-modal-backdrop{position:fixed;inset:0;z-index:30;display:flex;align-items:center;justify-content:center;padding:24px;background:var(--dsw-alias-bg-mask-1,#0006)}
+.dmg-modal{position:static;display:flex;flex-direction:column;gap:8px;max-width:420px;width:100%;padding:16px 18px;border:.5px solid var(--dsw-alias-border-l4);border-radius:16px;background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);font-size:13px;line-height:1.5}
+.dmg-modal h3{margin:0;font-size:14px;font-weight:500}
+.dmg-check-row{display:flex;align-items:flex-start;gap:8px;font-size:12px;color:var(--dsw-alias-label-secondary)}
+.dmg-check-row input{margin:2px 0 0}
 .dmg-models{display:flex;flex-direction:column}
 .dmg-model{display:flex;align-items:center;gap:8px;padding:6px 0;border-top:.5px solid var(--dsw-alias-border-l2)}
 .dmg-model label{display:flex;align-items:center;gap:6px;min-width:0;flex:1}