@qthinker/opencode-deepseek-search 0.3.0 → 0.3.2

package/src/gui/index.tsx

@@ -40,9 +40,14 @@ export default Plugin.define({
     // `status` takes a required first argument: plain JSON Schema degrades the
     // input type to `unknown`, and the host validates the payload against the
     // method's object schema, so an omitted input is rejected as invalid.
-    async function refresh() {
+    //
+    // `force` asks the server to re-probe the account balance instead of serving
+    // the cache; only the panel's refresh button spends that request. The
+    // `changed` event sends `{}` exactly — an older server rejects unknown input
+    // properties, so a stray `force: false` would break it.
+    async function refresh(force = false) {
       try {
-        const next = readStatus(await rpc.status({}))
+        const next = readStatus(await rpc.status(force ? { force: true } : {}))
         if (next) {
           setStatus(next)
           setError(undefined)
@@ -68,13 +73,14 @@ export default Plugin.define({
       }
     }
 
-    // Mirrors the TUI card: no status or a stale error rereads, otherwise
-    // switch. A missing key still allows releasing the takeover (the shared
-    // model hides the button only where there is genuinely nothing to do).
+    // Mirrors the TUI card: no status or a stale error rereads (a retry is a
+    // user action, so it also re-probes the balance), otherwise switch. A
+    // missing key still allows releasing the takeover (the shared model hides
+    // the button only where there is genuinely nothing to do).
     function toggle() {
       const current = status()
       if (!current || error()) {
-        void refresh()
+        void refresh(true)
         return
       }
       void applyMode(current.mode === "deepseek" ? "native" : "deepseek")
@@ -91,7 +97,7 @@ export default Plugin.define({
           error={error()}
           busy={busy()}
           onToggle={toggle}
-          onRefresh={() => void refresh()}
+          onRefresh={(force) => void refresh(force)}
         />
       ),
     })

package/src/gui/panel.tsx

@@ -4,15 +4,20 @@ import type { JSX } from "solid-js"
 import { For, Show, createMemo, onCleanup, onMount } from "solid-js"
 import { usePlugin } from "@opencode/plugin/gui"
 import { t, type Key } from "../i18n/index.ts"
-import type { SearchStatus } from "../rpc.ts"
-import { sidebarRows, type SidebarRows } from "../status-view.ts"
+import type { BalanceStatus, Language, SearchStatus } from "../rpc.ts"
+import { CURRENCY_SYMBOL, sidebarRows, type SidebarRows } from "../status-view.ts"
 
 export interface DeepSeekPanelProps {
   readonly status: SearchStatus | undefined
   readonly error: string | undefined
   readonly busy: boolean
   readonly onToggle: () => void
-  readonly onRefresh: () => void
+  /**
+   * `force` re-probes the server's balance cache; only a user action (the
+   * refresh button) may set it. The 10s poll timer calls it bare, so the
+   * automatic path keeps sending `{}` and never bypasses the server TTL.
+   */
+  readonly onRefresh: (force?: boolean) => void
 }
 
 type Tone = SidebarRows["tone"]
@@ -67,6 +72,20 @@ function help(action: string, mono: string): JSX.Element {
   )
 }
 
+/**
+ * The balance tooltip carries the granted/topped-up split, because those are the
+ * two numbers behind the total. It is skipped when only one component is
+ * non-zero: there it would just restate the total. The currency code rides
+ * along only for USD, whose `$` needs no introduction.
+ */
+function balanceTip(balance: BalanceStatus, language: Language): string | undefined {
+  const hasGranted = Number.parseFloat(balance.grantedBalance) > 0
+  const hasTopped = Number.parseFloat(balance.toppedUpBalance) > 0
+  if (!hasGranted || !hasTopped) return undefined
+  const text = t(language, "balance.breakdown", { granted: balance.grantedBalance, topped: balance.toppedUpBalance })
+  return balance.currency === "USD" ? `${text} (USD)` : text
+}
+
 export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
   const ctx = usePlugin()
   // The desktop plugin has no forced locale: the server resolves one and carries
@@ -77,6 +96,18 @@ export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
   const ink = createMemo(() => INK[ctx.appearance.mode()])
   const mono = () => ctx.appearance.font("mono")
 
+  /**
+   * The account block mirrors the view model's own emit condition (enabled or
+   * native mode), so `rows().lines` ends with the balance row exactly when
+   * this is defined and the usage table must stop before it. The block renders
+   * from the structured payload, not from re-parsing the line.
+   */
+  const balance = createMemo<BalanceStatus | undefined>(() => {
+    const account = props.status?.balance
+    if (account === undefined || (rows().tone !== "on" && rows().tone !== "off")) return undefined
+    return account
+  })
+
   // Cross-half `changed` delivery is the one runtime behaviour this repo cannot
   // verify, so the panel rereads on its own timer while it is mounted — the same
   // fallback the TUI sidebar uses.
@@ -94,14 +125,14 @@ export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
       }}
     >
       <header style={{ display: "flex", "align-items": "flex-start", gap: "8px" }}>
-        <span aria-hidden="true" style={{ "flex-shrink": 0, "font-size": "10px", "line-height": "20px", "font-weight": 700, color: ink()[rows().tone] }}>
+        <span aria-hidden="true" style={{ "flex-shrink": 0, "font-size": "12px", "line-height": "20px", width: "12px", "text-align": "center", "font-weight": 700, color: ink()[rows().tone] }}>
           {GLYPH[rows().tone]}
         </span>
         <h2 aria-live="polite" style={{ flex: 1, "min-width": 0, margin: 0, "font-size": "13px", "font-weight": 600, "line-height": "20px", "overflow-wrap": "anywhere" }}>
           {headline(rows().title, ink()[rows().tone])}
         </h2>
         <ctx.ui.Tooltip value={t(language(), "panel.tooltip.refresh")} placement="bottom">
-          <ctx.ui.IconButton icon="refresh" label={t(language(), "panel.tooltip.refresh")} size="small" onClick={props.onRefresh} />
+          <ctx.ui.IconButton icon="refresh" label={t(language(), "panel.tooltip.refresh")} size="small" onClick={() => props.onRefresh(true)} />
         </ctx.ui.Tooltip>
       </header>
 
@@ -116,31 +147,66 @@ export function DeepSeekPanel(props: DeepSeekPanelProps): JSX.Element {
         )
       ) : (
         <dl style={{ margin: "16px 0 0", "border-top": `1px solid ${ink().rule}`, "border-bottom": `1px solid ${ink().rule}` }}>
-          <For each={rows().lines}>
+          <For each={balance() !== undefined ? rows().lines.slice(0, -1) : rows().lines}>
             {(line, index) => {
               const parts = splitLine(line)
               return (
                 <div style={{ display: "flex", "align-items": "baseline", gap: "12px", padding: "10px 0", "border-top": index() > 0 ? `1px solid ${ink().rule}` : undefined }}>
-                  <dt style={{ "flex-shrink": 0, "font-size": "11px", "letter-spacing": "0.08em", "line-height": "1.9", opacity: 0.62 }}>
+                  <dt style={{ "flex-shrink": 0, "font-size": "11px", "letter-spacing": /^[\x20-\x7E]+$/.test(parts.label) ? "0.08em" : undefined, "line-height": "1.9", opacity: 0.62 }}>
                     {parts.label}
                   </dt>
                   <dd style={{
                     margin: 0, "margin-left": "auto", "min-width": 0, display: "flex", "flex-wrap": "wrap", "justify-content": "flex-end",
-                    "column-gap": "6px", "row-gap": "2px", "font-family": mono(), "font-size": "13px", "line-height": "1.55",
+                    "column-gap": "10px", "row-gap": "2px", "font-family": mono(), "font-size": "13px", "line-height": "1.55",
                     "font-variant-numeric": "tabular-nums", "text-align": "right",
                   }}>
                     <For each={parts.chunks}>
-                      {(chunk, i) => (
-                        <span style={{ "min-width": 0, "overflow-wrap": "anywhere", "font-weight": chunk.startsWith("¥") ? 500 : 400, opacity: chunk.startsWith("¥") ? 1 : 0.8 }}>
-                          {chunk}{i() < parts.chunks.length - 1 ? " ·" : ""}
-                        </span>
-                      )}
+                      {(chunk) => {
+                        // A money chunk must never wrap apart from its digits, and
+                        // it is the only chunk that reads at full weight.
+                        const money = /^[¥$]/.test(chunk)
+                        return (
+                          <span style={{ "min-width": 0, "overflow-wrap": "anywhere", "font-weight": money ? 500 : 400, opacity: money ? 1 : 0.8, "flex-shrink": money ? 0 : undefined }}>
+                            {chunk}
+                          </span>
+                        )
+                      }}
                     </For>
                   </dd>
                 </div>
               )
             }}
           </For>
+          {/* The account block closes the table like a receipt: the usage rows
+              above are local estimates for this machine, the balance under them
+              is the authoritative amount still on the account. */}
+          <Show when={balance()} keyed>
+            {(account) => {
+              const label = t(language(), "balance.label")
+              const tip = balanceTip(account, language())
+              const amount = (
+                <dd style={{
+                  margin: 0, "margin-left": "auto", "font-family": mono(), "font-size": "14px", "line-height": "1.55",
+                  "font-variant-numeric": "tabular-nums", "text-align": "right", "font-weight": 500, "flex-shrink": 0,
+                  color: account.isAvailable ? undefined : ink().warn,
+                }}>
+                  {CURRENCY_SYMBOL[account.currency] ?? ""}{account.totalBalance}
+                </dd>
+              )
+              return (
+                <div style={{ display: "flex", "align-items": "baseline", gap: "12px", padding: "10px 0 4px", "border-top": `1px solid ${ink().rule}` }}>
+                  <dt style={{ "flex-shrink": 0, "font-size": "11px", "letter-spacing": /^[\x20-\x7E]+$/.test(label) ? "0.08em" : undefined, "line-height": "1.9", opacity: 0.62 }}>
+                    {label}
+                  </dt>
+                  {tip !== undefined ? (
+                    <ctx.ui.Tooltip value={tip} placement="bottom">{amount}</ctx.ui.Tooltip>
+                  ) : (
+                    amount
+                  )}
+                </div>
+              )
+            }}
+          </Show>
         </dl>
       )}
 

package/src/i18n/en.ts

@@ -85,6 +85,10 @@ export const en = {
   "usage.label.total": "Total",
   "usage.summary.line": "Search {search} · Fetch {fetch} · empty/failed {skipped} · {cost}",
 
+  // ---------- account balance (the card row and the desktop tooltip) ----------
+  "balance.label": "Balance",
+  "balance.breakdown": "Granted {granted} · Topped up {topped}",
+
   // ---------- errors ----------
   "error.missingKey":
     "DeepSeek API key is not configured. Set the DEEPSEEK_API_KEY environment variable " +
@@ -131,17 +135,32 @@ export type Messages = Record<Key, string>
  * Usage-row ladder, richest first. Each entry is a complete row, so nothing is
  * ever left dangling and no number is ever cut from its unit. `{label}` is the
  * localized period label; `Search`/`Fetch` stay English in every language.
+ *
+ * Order is by what the row is worth, then by width, so it runs strictly
+ * descending (36/33/25/17/11 columns for a typical fixture). The amount
+ * outranks the words and the counters: the old ladder kept a wider words-only
+ * row and hid the cost until 36 columns, which is the number this card exists
+ * for, so those two rungs are gone. The amount-only row (which carries no count
+ * at all) is composed in `status-view.ts` and tried just before the last rung —
+ * an amount is worth more than a lone counter, but the ladder itself only holds
+ * rows that carry counts.
  */
 export const enUsageForms: readonly string[] = [
   "{label}  Search {search}  Fetch {fetch}  {cost}",
   "{label} Search {search} Fetch {fetch} {cost}",
-  "{label}  Search {search}  Fetch {fetch}",
-  "{label} Search {search} Fetch {fetch}",
   "{label}  {search}S  {fetch}F  {cost}",
   "{label}  {search}S  {fetch}F",
-  "{label}  {search}S",
+  "{label} {search}S",
 ]
 
+/**
+ * Balance-row ladder, verbose first: the terminal takes the compact form when
+ * the verbose one does not fit, a surface with an unbounded budget (the desktop)
+ * always reads the first. `{amount}` already carries the currency symbol — the
+ * view model composes it, because only it knows the currency code.
+ */
+export const enBalanceForms: readonly string[] = ["Balance {amount}", "Bal. {amount}"]
+
 /** Missing-key hint ladder, richest first. The env var name is always present. */
 export const enHintForms: readonly string[] = [
   "Set DEEPSEEK_API_KEY and restart",

package/src/i18n/index.ts

@@ -6,9 +6,9 @@
 // plugin or host imports, so every runtime can load this module.
 
 import { isLanguage, type Language } from "../rpc.ts"
-import { en, enHintForms, enUsageForms, type Key, type Messages } from "./en.ts"
-import { ja, jaHintForms, jaUsageForms } from "./ja.ts"
-import { zh, zhHintForms, zhUsageForms } from "./zh.ts"
+import { en, enBalanceForms, enHintForms, enUsageForms, type Key, type Messages } from "./en.ts"
+import { ja, jaBalanceForms, jaHintForms, jaUsageForms } from "./ja.ts"
+import { zh, zhBalanceForms, zhHintForms, zhUsageForms } from "./zh.ts"
 
 export type { Key, Messages }
 
@@ -19,12 +19,14 @@ export interface LocalePack {
   readonly usageForms: readonly string[]
   /** Missing-key hint ladder, richest first. */
   readonly hintForms: readonly string[]
+  /** Balance-row ladder, verbose first; `{amount}` carries the currency symbol. */
+  readonly balanceForms: readonly string[]
 }
 
 const PACKS: Readonly<Record<Language, LocalePack>> = {
-  en: { messages: en, usageForms: enUsageForms, hintForms: enHintForms },
-  ja: { messages: ja, usageForms: jaUsageForms, hintForms: jaHintForms },
-  "zh-CN": { messages: zh, usageForms: zhUsageForms, hintForms: zhHintForms },
+  en: { messages: en, usageForms: enUsageForms, hintForms: enHintForms, balanceForms: enBalanceForms },
+  ja: { messages: ja, usageForms: jaUsageForms, hintForms: jaHintForms, balanceForms: jaBalanceForms },
+  "zh-CN": { messages: zh, usageForms: zhUsageForms, hintForms: zhHintForms, balanceForms: zhBalanceForms },
 }
 
 export function pack(language: Language): LocalePack {

package/src/i18n/ja.ts

@@ -83,6 +83,10 @@ export const ja = {
   "usage.label.total": "合計",
   "usage.summary.line": "検索 {search} · 取得 {fetch} · 空/失敗 {skipped} · {cost}",
 
+  // ---------- アカウント残高（カードの行とデスクトップのツールチップ） ----------
+  "balance.label": "残高",
+  "balance.breakdown": "付与 {granted} · チャージ {topped}",
+
   // ---------- エラー ----------
   "error.missingKey":
     "DeepSeek APIキーが未設定です。環境変数 DEEPSEEK_API_KEY を設定してください" +
@@ -118,17 +122,22 @@ export const ja = {
   "error.fetch.truncated": "[DeepSeek Fetch 切り詰め] 元の本文は {raw} 文字で、上限 {max} 文字を超えています。先頭 {max} 文字のみ保持しました。",
 } satisfies Messages
 
-/** 使用量行の階段：完全な行から最も短い行まで。各段は単体で完結する。 */
+/**
+ * 使用量行の階段：価値の高い順、同じ価値なら幅の広い順。各段は単体で完結する。
+ * 金額は語や回数より上位なので、金額を含まない「語だけ」の段は廃止した。金額だけの
+ * 行は件数を持たないため status-view.ts 側で組み立て、最後の 1 段の直前に試す。
+ */
 export const jaUsageForms: readonly string[] = [
   "{label}  Search {search}  Fetch {fetch}  {cost}",
   "{label} Search {search} Fetch {fetch} {cost}",
-  "{label}  Search {search}  Fetch {fetch}",
-  "{label} Search {search} Fetch {fetch}",
   "{label}  {search}S  {fetch}F  {cost}",
   "{label}  {search}S  {fetch}F",
-  "{label}  {search}S",
+  "{label} {search}S",
 ]
 
+/** 残高行の階段：完全な形が先。`{amount}` は通貨記号込み。 */
+export const jaBalanceForms: readonly string[] = ["残高 {amount}"]
+
 /** APIキー未設定のヒント階段：最後の段でも何を設定するかは残る。 */
 export const jaHintForms: readonly string[] = [
   "DEEPSEEK_API_KEY を設定して再起動",

package/src/i18n/zh.ts

@@ -81,6 +81,10 @@ export const zh = {
   "usage.label.total": "累计",
   "usage.summary.line": "搜索 {search} · 抓取 {fetch} · 空/失 {skipped} · {cost}",
 
+  // ---------- 账户余额（卡片行与桌面端浮动提示） ----------
+  "balance.label": "余额",
+  "balance.breakdown": "赠金 {granted} · 充值 {topped}",
+
   // ---------- 错误信息 ----------
   "error.missingKey":
     "未配置 DeepSeek API Key：请设置环境变量 DEEPSEEK_API_KEY" +
@@ -113,17 +117,23 @@ export const zh = {
   "error.fetch.truncated": "[DeepSeek Fetch 截断提示] 原文共 {raw} 字符，超出上限 {max}，此处仅保留前 {max} 字符。",
 } satisfies Messages
 
-/** 用量行阶梯：从最完整到最紧凑；每一条都是完整的一行。 */
+/**
+ * 用量行阶梯：按价值从高到低排列，同等价值再按宽度从宽到窄；每一条都是完整的一行。
+ * 金额优先于文字与计数，因此删掉了不带金额的“纯文字”档——旧阶梯会为了更宽的
+ * 纯文字行而把金额藏到 36 列。只带金额的一行不含计数，改由 status-view.ts 组装，
+ * 并在最后一档之前尝试。
+ */
 export const zhUsageForms: readonly string[] = [
   "{label}  Search {search}  Fetch {fetch}  {cost}",
   "{label} Search {search} Fetch {fetch} {cost}",
-  "{label}  Search {search}  Fetch {fetch}",
-  "{label} Search {search} Fetch {fetch}",
   "{label}  {search}S  {fetch}F  {cost}",
   "{label}  {search}S  {fetch}F",
-  "{label}  {search}S",
+  "{label} {search}S",
 ]
 
+/** 余额行阶梯：完整写法在前；`{amount}` 已含货币符号。 */
+export const zhBalanceForms: readonly string[] = ["余额 {amount}"]
+
 /** 缺 key 提示阶梯：最后一档仍然指明要设置什么。 */
 export const zhHintForms: readonly string[] = [
   "设置 DEEPSEEK_API_KEY 后重启",

package/src/index.ts

@@ -16,6 +16,7 @@ import { Plugin } from "@opencode/plugin"
 import type { Result as ToolResult, ToolContext } from "@opencode/plugin/promise/tool"
 import type { RpcRegistration } from "@opencode/plugin/promise/rpc"
 import {
+  deepseekBalance,
   deepseekFetch,
   deepseekSearch,
   formatSearchResults,
@@ -25,7 +26,7 @@ import {
   type SearchResult,
 } from "./deepseek.ts"
 import { resolveLanguage, t } from "./i18n/index.ts"
-import { DeepSeekRpc, type ModeSwitchResult, type SearchStatus } from "./rpc.ts"
+import { DeepSeekRpc, type BalanceRead, type ModeSwitchResult, type SearchStatus } from "./rpc.ts"
 import {
   USAGE_KEY,
   applyTally,
@@ -375,13 +376,52 @@ export default Plugin.define({
       })
     })
 
+    // ---------- account balance cache ----------
+    // The sidebars poll `status`, so the balance is cached for a minute: at most
+    // one upstream probe per TTL, shared by every caller. Failures keep the last
+    // good snapshot and back off instead of retrying on every poll.
+    const BALANCE_TTL_MS = 60_000
+    let balanceCache: { value: BalanceRead; at: number } | undefined
+    let balanceInFlight: Promise<void> | undefined
+    let lastBalanceAttemptAt = 0
+    // Never rejects: the balance is decoration on `status`, not a feature that
+    // may break it, so every failure is swallowed here.
+    const refreshBalance = (force: boolean): Promise<void> => {
+      if (!apiKey) return Promise.resolve()
+      if (balanceInFlight) return balanceInFlight
+      const startedAt = Date.now()
+      if (!force) {
+        if (balanceCache && startedAt - balanceCache.at < BALANCE_TTL_MS) return Promise.resolve()
+        if (startedAt - lastBalanceAttemptAt < BALANCE_TTL_MS) return Promise.resolve()
+      }
+      lastBalanceAttemptAt = startedAt
+      const run = (async (): Promise<void> => {
+        try {
+          const value = await deepseekBalance(apiKey, language)
+          balanceCache = { value, at: Date.now() }
+          notifyChanged()
+        } catch {
+          /* keep the previous snapshot */
+        } finally {
+          balanceInFlight = undefined
+        }
+      })()
+      balanceInFlight = run
+      return run
+    }
+
     // ---------- RPC contract (TUI / desktop sidebars) ----------
     // Both sidebars read `status` and call `setMode`; nothing else crosses the
     // process boundary, so the plugin's state stays the single source of truth.
     rpcRegistration = await ctx.rpc.register(DeepSeekRpc, {
       // Reads through `withLedger` so it observes the same serialized chain.
-      status: async (): Promise<SearchStatus> =>
-        withLedger((ledger): SearchStatus => {
+      status: async (input: unknown): Promise<SearchStatus> => {
+        // A manual refresh (the sidebar's refresh button) may ask for a fresh
+        // probe; timer paths send `{}` so old servers still accept the input.
+        const force = (input as { force?: unknown } | undefined)?.force === true
+        // Kicked, not awaited: `status` must stay fast even when the probe hangs.
+        void refreshBalance(force)
+        return withLedger((ledger): SearchStatus => {
           const todayKey = dayKey()
           return {
             mode,
@@ -398,8 +438,12 @@ export default Plugin.define({
               month: sumDays(ledger, (k) => k.startsWith(todayKey.slice(0, 7))),
               total: sumDays(ledger, () => true),
             },
+            // Absent until the first successful probe; `fetchedAt` is stamped by
+            // the cache, so clients can render staleness.
+            balance: balanceCache ? { ...balanceCache.value, fetchedAt: balanceCache.at } : undefined,
           }
-        }),
+        })
+      },
       // The input is plain JSON Schema, hence `unknown`: report, never throw.
       setMode: async (input: unknown): Promise<ModeSwitchResult> => {
         const parsed = readModeAction(input)

package/src/rpc.ts

@@ -38,11 +38,36 @@ const USAGE_COUNTS_SCHEMA = {
   additionalProperties: false,
 } as const
 
+// Account balance snapshot in `status.balance`. `currency` deliberately has no
+// enum: a value the server could not normalize must not fail the whole payload
+// at output-schema validation time.
+const BALANCE_SCHEMA = {
+  type: "object",
+  properties: {
+    isAvailable: { type: "boolean" },
+    currency: { type: "string" },
+    totalBalance: { type: "string" },
+    grantedBalance: { type: "string" },
+    toppedUpBalance: { type: "string" },
+    fetchedAt: { type: "number" },
+  },
+  required: ["isAvailable", "currency", "totalBalance", "grantedBalance", "toppedUpBalance", "fetchedAt"],
+  additionalProperties: false,
+} as const
+
 export const DeepSeekRpc = {
   id: DEEPSEEK_RPC_ID,
   methods: {
     status: {
-      input: { type: "object", properties: {}, additionalProperties: false },
+      input: {
+        type: "object",
+        properties: {
+          // Only a manual refresh sends `{ force: true }`; timer paths MUST send
+          // `{}`, because older servers reject unknown input properties.
+          force: { type: "boolean" },
+        },
+        additionalProperties: false,
+      },
       output: {
         type: "object",
         properties: {
@@ -67,6 +92,9 @@ export const DeepSeekRpc = {
             required: ["today", "month", "total"],
             additionalProperties: false,
           },
+          // Optional like `counts`: absent while the first probe is in flight, on
+          // servers without the endpoint, or when the API key is missing.
+          balance: BALANCE_SCHEMA,
         },
         required: ["mode", "source", "patched", "hasKey", "pricePerThousand", "today", "month", "total"],
         additionalProperties: false,
@@ -107,6 +135,24 @@ export interface UsageCounts {
   costMicro: number
 }
 
+/**
+ * DeepSeek account balance as reported by `GET /user/balance`.
+ *
+ * `fetchedAt` is epoch milliseconds attached by the server when it caches the
+ * snapshot, so sidebars can show staleness without trusting client clocks.
+ */
+export interface BalanceStatus {
+  isAvailable: boolean
+  currency: string
+  totalBalance: string
+  grantedBalance: string
+  toppedUpBalance: string
+  fetchedAt: number
+}
+
+/** The wire shape of a balance probe, before the cache stamps `fetchedAt`. */
+export type BalanceRead = Omit<BalanceStatus, "fetchedAt">
+
 export interface SearchStatus {
   mode: "deepseek" | "native"
   source: "override" | "config"
@@ -124,6 +170,8 @@ export interface SearchStatus {
   language: Language
   /** Structured counters, so each surface can format for its own width. Optional for older servers. */
   counts?: { today: UsageCounts; month: UsageCounts; total: UsageCounts }
+  /** Last cached balance probe. Absent until the first successful fetch. */
+  balance?: BalanceStatus
 }
 
 export interface ModeSwitchResult {
@@ -151,10 +199,23 @@ function readUsageCounts(value: unknown): UsageCounts | undefined {
   return { search, fetch, empty, failed, costMicro } as UsageCounts
 }
 
+/** Strict read of a cached balance snapshot: all six fields, currency normalized. */
+function readBalance(value: unknown): BalanceStatus | undefined {
+  if (!isRecord(value)) return undefined
+  const { isAvailable, currency, totalBalance, grantedBalance, toppedUpBalance, fetchedAt } = value
+  if (typeof isAvailable !== "boolean") return undefined
+  if (currency !== "CNY" && currency !== "USD") return undefined
+  for (const text of [totalBalance, grantedBalance, toppedUpBalance]) {
+    if (typeof text !== "string" || text.length === 0) return undefined
+  }
+  if (typeof fetchedAt !== "number" || !Number.isFinite(fetchedAt) || fetchedAt < 0) return undefined
+  return { isAvailable, currency, totalBalance, grantedBalance, toppedUpBalance, fetchedAt } as BalanceStatus
+}
+
 /** Defensive read of an RPC `status` result. Never throws. */
 export function readStatus(raw: unknown): SearchStatus | undefined {
   if (!isRecord(raw)) return undefined
-  const { mode, source, patched, hasKey, pricePerThousand, today, month, total, language, counts } = raw
+  const { mode, source, patched, hasKey, pricePerThousand, today, month, total, language, counts, balance } = raw
   if (!isMode(mode)) return undefined
   if (source !== "override" && source !== "config") return undefined
   if (typeof patched !== "boolean" || typeof hasKey !== "boolean") return undefined
@@ -180,6 +241,10 @@ export function readStatus(raw: unknown): SearchStatus | undefined {
     const totalCounts = readUsageCounts(counts.total)
     if (todayCounts && monthCounts && totalCounts) status.counts = { today: todayCounts, month: monthCounts, total: totalCounts }
   }
+  // A missing balance stays absent (no probe yet, no key, older server); a
+  // malformed one is dropped without failing the rest of the payload.
+  const balanceStatus = readBalance(balance)
+  if (balanceStatus) status.balance = balanceStatus
   return status
 }