@kukonce/dsh-loomy 0.0.0-stage → 0.3.1

package/src/panel/api.js

@@ -0,0 +1,661 @@
+/**
+ * Host HTTP surface for the Settings panel.
+ *
+ * Routes live under a top-level `/loomy` namespace — the same convention
+ * `dsh-host-open-in-app` uses with `/open-in-app` — deliberately outside `/api`,
+ * which the client-connection bridge owns as a prefix route. A prefix route under
+ * `/api` would be shadowed for every path the bridge also answers.
+ *
+ * Every route passes the connection trust fence first: only peers the running Web GUI
+ * already admits can read account state or start a login.
+ *
+ * Nothing here ever answers with a session string. The account table on disk holds
+ * them; every payload below goes through `accountView()`, which is the only shape
+ * that reaches the browser.
+ */
+
+import { createHash } from 'node:crypto'
+import { readFileSync, statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+import {
+  accountOf,
+  assertAccountId,
+  fetchUserInfo,
+  importDesktopAccount,
+  loginBySmsCode,
+  logoutRemote,
+  readAccounts,
+  removeAccount,
+  renameAccount,
+  sendSmsCode,
+  upsertAccount
+} from '../account/auth.js'
+import { describeSearchPaths, findDesktopSession } from '../account/desktop-session.js'
+import { anchorLedger, consumedOnDay, dailyGrantState, ensureDailyGrant, fetchCredits, grantedToday } from '../account/credits.js'
+import { loadCatalog, readCachedCatalog } from '../account/models.js'
+import { clearExpired, expiredInfo, sessionForId, withSession } from '../account/session.js'
+import { CLIENT_VERSION, GATEWAY_BASE_URL } from '../core/endpoints.js'
+import { localDayKey } from '../core/http.js'
+
+const API_PREFIX = '/loomy'
+const MAX_BODY_BYTES = 16 * 1024
+
+/**
+ * The plugin's artwork, resolved from the package root (this file lives in `src/panel/`).
+ *
+ * Resolved through `import.meta.url` rather than `process.cwd()`: the host may run from
+ * any directory, and a relative path here fails at request time, not at import time —
+ * which is exactly how a missing logo reaches a release unnoticed.
+ */
+const ICON_PATH = fileURLToPath(new URL('../../icon.png', import.meta.url))
+const MASK_PATH = fileURLToPath(new URL('../../icon-mask.png', import.meta.url))
+let iconBytes
+let maskBytes
+
+/**
+ * Which build of this file the running host actually loaded.
+ *
+ * A reload does not replace routes an earlier load registered — the host keeps serving
+ * the first registration it was given — so a panel talking to a stale instance answers
+ * `not found` on newer routes. Printing a content hash on mount makes the running build
+ * identifiable in the host log. A content hash rather than a timestamp: the host process
+ * may print in a different time zone than the file's mtime suggests.
+ */
+const CODE_STAMP = (() => {
+  try {
+    const self = fileURLToPath(import.meta.url)
+    const hash = createHash('sha256').update(readFileSync(self)).digest('hex').slice(0, 8)
+    return `api.js #${hash} (${statSync(self).mtime.toISOString().slice(0, 16)}Z)`
+  } catch {
+    return 'api.js (unidentified)'
+  }
+})()
+
+/** JSON answer with the two headers every panel payload needs. */
+function sendJson(res, status, payload) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  // Account state and balances are per-user and change under the panel's feet: a cached
+  // copy in the WebView would keep showing a balance the user just spent.
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(payload))
+}
+
+/** Collect a bounded JSON body; `undefined` when it is oversized or not a JSON object. */
+async function readJsonBody(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.byteLength
+    if (size > MAX_BODY_BYTES) return undefined
+    chunks.push(chunk)
+  }
+  if (size === 0) return {}
+  try {
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** `133****3805` — enough to tell two accounts apart, not enough to be a phone number. */
+function maskPhone(phone) {
+  const digits = String(phone ?? '').trim()
+  if (digits.length === 0) return ''
+  if (digits.length < 8) return '****'
+  return `${digits.slice(0, 3)}****${digits.slice(-4)}`
+}
+
+/** A number the panel can print; NaN must never reach the UI. */
+const finite = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0)
+
+/**
+ * The credit fields the panel shows, or `null` when nothing has been read yet.
+ *
+ * Kept narrow on purpose: the full `fetchCredits` answer also carries the invite code
+ * and the cycle bookkeeping, none of which the card renders, and every extra field is
+ * one more thing to widen by accident later.
+ */
+function creditsSummary(credits) {
+  if (credits === null || credits === undefined || typeof credits !== 'object') return null
+  return {
+    ok: credits.ok !== false,
+    balance: finite(credits.balance),
+    permanentBalance: finite(credits.permanentBalance),
+    dailyBalance: finite(credits.dailyBalance),
+    dailyQuota: finite(credits.dailyQuota),
+    dailyConsumed: finite(credits.dailyConsumed),
+    availableBalance: finite(credits.availableBalance),
+    dailyCycleDate: typeof credits.dailyCycleDate === 'string' ? credits.dailyCycleDate : '',
+    ...(typeof credits.error === 'string' ? { error: credits.error } : {})
+  }
+}
+
+/**
+ * One account as the panel may see it.
+ *
+ * The session is intentionally absent — this function is the boundary — and the phone
+ * arrives masked. Everything else is stored metadata or a count read from the catalog
+ * cache: no field here costs a network round trip, because `/state` is called on every
+ * panel open and after every action.
+ */
+function accountView(account, adapters) {
+  const cached = readCachedCatalog(account.id)
+  const grant = dailyGrantState(account.id)
+  const expired = expiredInfo(account.id)
+  const day = localDayKey()
+  return {
+    id: account.id,
+    label: account.label,
+    phone: maskPhone(account.phone),
+    userid: account.userid,
+    source: account.source,
+    loggedInAt: finite(account.loggedInAt),
+    signedIn: account.session.length > 0,
+    expired: expired !== undefined,
+    expiredAt: finite(expired?.at),
+    expiredReason: typeof expired?.reason === 'string' ? expired.reason : '',
+    provider: `@loomy/dsh-loomy/${account.id}`,
+    mounted: adapters[account.id] !== undefined,
+    models: Array.isArray(cached?.entries) ? cached.entries.length : 0,
+    modelsCachedAt: finite(cached?.savedAt),
+    // The grant ledger is the last recorded claim, not a live balance: it is what the
+    // panel needs to word the button ("今日已领取"), not what it prints as the balance.
+    dailyGrant: grant === undefined ? null : {
+      day: grant.day,
+      at: finite(grant.at),
+      granted: grant.granted === true,
+      balance: finite(grant.balance),
+      quota: finite(grant.quota),
+      reason: typeof grant.reason === 'string' ? grant.reason : '',
+      ...(typeof grant.error === 'string' ? { error: grant.error } : {})
+    },
+    grantedToday: grantedToday(account.id),
+    credits: grant === undefined ? null : creditsSummary(projectedCredits(grant, account.id, day)),
+    // Milliseconds, for clients that must judge staleness against one clock:
+    // Date.now() in the WebView can drift from this process by minutes.
+    serverNow: Date.now()
+  }
+}
+
+/**
+ * The ledger's claim-time pot minus what chat has spent since, as far as this
+ * process knows.
+ *
+ * The adapter books each turn's `points_consumed` into `usage.json` the moment the
+ * gateway's accounting frame arrives, so this projection tracks chatting in real
+ * time. It is still an estimate between sync points — a turn billed outside this
+ * process (onboarding tasks, another machine on the account) or a failed spend
+ * write is only corrected when the next claim re-reads the server. `spent` is
+ * clamped to the pot so a stale spend file can never push the display negative.
+ */
+function projectedCredits(grant, accountId, day) {
+  const pot = finite(grant.balance)
+  const spent = grant.day === day ? consumedOnDay(accountId, day) : 0
+  const remaining = Math.max(0, pot - Math.min(spent, pot))
+  return {
+    ok: grant.granted === true,
+    balance: grant.balance,
+    dailyBalance: remaining,
+    dailyQuota: grant.quota,
+    // The server's number for this is quota - dailyBalance; the same arithmetic here
+    // also counts what chat spent after the claim.
+    dailyConsumed: Math.max(0, finite(grant.quota) - remaining),
+    availableBalance: remaining,
+    dailyCycleDate: day,
+    ...(typeof grant.error === 'string' ? { error: grant.error } : {})
+  }
+}
+
+/**
+ * The model the picker should offer by default, from cached catalogs only.
+ *
+ * No network here: `/state` is on the panel's critical path, and a default model is a
+ * display detail that a stale answer still gets right.
+ */
+function defaultModelOf(adapters) {
+  for (const id of Object.keys(adapters)) {
+    const declared = adapters[id]?.defaultModel
+    if (typeof declared === 'string' && declared.length > 0) return declared
+    const entries = readCachedCatalog(id)?.entries
+    const preferred = Array.isArray(entries) ? entries.find((entry) => entry?.isDefault === true) : undefined
+    if (preferred !== undefined) return preferred.id
+  }
+  for (const id of Object.keys(adapters)) {
+    const entries = readCachedCatalog(id)?.entries
+    if (Array.isArray(entries) && entries.length > 0) return entries[0].id
+  }
+  return ''
+}
+
+/** Whether the Loomy desktop app has a session parked on this machine. */
+function desktopAvailable() {
+  try {
+    return findDesktopSession() !== undefined
+  } catch {
+    return false
+  }
+}
+
+/** The panel's full snapshot. */
+function statePayload(adapters) {
+  return {
+    accounts: readAccounts().map((account) => accountView(account, adapters)),
+    defaultModel: defaultModelOf(adapters),
+    gateway: GATEWAY_BASE_URL,
+    version: CLIENT_VERSION,
+    desktop: {
+      available: desktopAvailable(),
+      // The import button is a dead end on a machine that never ran Loomy, and its
+      // failure message has to name where the plugin looked.
+      paths: describeSearchPaths()
+    }
+  }
+}
+
+/** Map one catalog entry to the subset the panel renders. */
+function modelView(entry) {
+  return {
+    id: entry.id,
+    name: entry.name ?? entry.id,
+    // 'image' entries share the chat URL but 404 on it, so the panel lists them apart
+    // from the ones it offers for a conversation.
+    type: entry.type ?? 'chat',
+    chat: entry.type !== 'image',
+    protocol: entry.protocol,
+    contextLength: finite(entry.contextLength),
+    maxOutputTokens: finite(entry.maxOutputTokens),
+    input: Array.isArray(entry.input) ? entry.input : ['text'],
+    vision: entry.vision === true,
+    toolCalls: entry.toolCalls === true,
+    reasoning: entry.reasoning === true,
+    efforts: Array.isArray(entry.efforts) ? entry.efforts : [],
+    defaultEffort: typeof entry.defaultEffort === 'string' ? entry.defaultEffort : '',
+    isDefault: entry.isDefault === true
+  }
+}
+
+/**
+ * The live model catalog for one account.
+ *
+ * The mounted adapter wins when there is one: its list is the merged one the model
+ * picker reads, so the panel and the picker can never disagree about what is offered.
+ * The account-level catalog is the fallback for a composition where the adapter for
+ * this id is not mounted (an account added to config without a restart).
+ */
+async function modelsPayload(accountId, adapters, options = {}) {
+  const adapter = adapters[accountId]
+  if (adapter !== undefined && typeof adapter.models === 'function') {
+    if (options.refresh === true && typeof adapter.invalidateCatalog === 'function') adapter.invalidateCatalog()
+    const entries = await adapter.models()
+    return {
+      id: accountId,
+      source: typeof adapter.catalogSource === 'string' ? adapter.catalogSource : 'adapter',
+      // `catalogCachedAt` is what the WorkBuddy adapter calls it; this one calls its
+      // in-memory timestamp `catalogAt`. Both are read so neither adapter shape breaks
+      // the panel's "as of" line.
+      cachedAt: finite(adapter.catalogCachedAt ?? adapter.catalogAt),
+      models: (Array.isArray(entries) ? entries : []).map(modelView)
+    }
+  }
+  const { session } = sessionForId(accountId)
+  const catalog = await loadCatalog(accountId, session, { force: options.refresh === true })
+  return {
+    id: accountId,
+    source: catalog.source,
+    cachedAt: finite(catalog.savedAt),
+    models: (Array.isArray(catalog.entries) ? catalog.entries : []).map(modelView)
+  }
+}
+
+/**
+ * Validate an account id a route was handed, with an error the panel can show.
+ *
+ * An omitted id means "the account this panel is about", which for every caller so far
+ * is the first one in the table. Requiring it would make a single-account install pass
+ * an id on every request to say nothing — and the panel's own default fetch does not.
+ */
+function accountIdParam(raw) {
+  const value = String(raw ?? '').trim()
+  if (value.length === 0) {
+    const first = readAccounts()[0]
+    if (first === undefined) throw new Error('还没有登录任何 Loomy 账号')
+    return first.id
+  }
+  return assertAccountId(value)
+}
+
+/**
+ * Register the panel's routes. Call inside `ctx.inject(['webServer'], …)` so a
+ * composition without an HTTP carrier keeps the provider routes and the command.
+ *
+ * The second argument accepts either shape the plugin has been wired with: the bare
+ * adapter map (`{ [accountId]: adapter }`) or the host bundle
+ * `{ adapters, mountAccount, unmountAccount }`. Both were live at different points while
+ * this plugin was being written, and a mismatch fails only at the moment a route runs —
+ * so the normalization is here, once, rather than trusting the caller.
+ *
+ * @param {object} webCtx - host plugin context that carries `webServer`.
+ * @param {Record<string, object>|{ adapters: Record<string, object>, mountAccount?: Function, unmountAccount?: Function }} wiring - per-account LLM adapters, or the host bundle.
+ * @returns {() => void} the disposer the caller registers with `webCtx.effect`.
+ */
+export function registerLoomyApi(webCtx, wiring) {
+  const bundle = wiring !== null && typeof wiring === 'object' && typeof wiring.adapters === 'object' && wiring.adapters !== null
+    ? wiring
+    : { adapters: wiring ?? {} }
+  const catalogue = bundle.adapters
+  const mountAccount = typeof bundle.mountAccount === 'function' ? bundle.mountAccount : undefined
+  const unmountAccount = typeof bundle.unmountAccount === 'function' ? bundle.unmountAccount : undefined
+
+  /**
+   * The trust fence, identical to the one every other panel route in this host uses:
+   * ask the connection service whether it would reject this request, and let it answer
+   * with the status code it wants.
+   */
+  /**
+   * Mount the provider route for an account a route just created.
+   *
+   * Failures are logged and swallowed: the account is already stored at this point, so
+   * turning a mount problem into a login failure would make the user retry a login that
+   * in fact succeeded. The panel's `mounted` flag says the route is missing.
+   */
+  const mountSafely = (account) => {
+    if (mountAccount === undefined || account === undefined) return
+    if (catalogue[account.id] !== undefined) return
+    try {
+      mountAccount(account)
+    } catch (error) {
+      webCtx.logger?.warn?.(`[loomy] ${account.id}: 挂载 provider 路由失败 — ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
+  const rejected = (req, res) => {
+    const connection = webCtx.get('connection')
+    if (connection === undefined || typeof connection.requestRejection !== 'function') return false
+    const rejection = connection.requestRejection(req)
+    if (rejection === undefined) return false
+    res.statusCode = rejection
+    res.end()
+    return true
+  }
+
+  const handler = async (req, res) => {
+    const url = new URL(String(req.url ?? '/'), 'http://localhost')
+    const method = req.method ?? 'GET'
+    if (rejected(req, res)) return
+    const path = url.pathname
+
+    try {
+      if (path === `${API_PREFIX}/state` && method === 'GET') {
+        sendJson(res, 200, statePayload(catalogue))
+        return
+      }
+
+      // The packaged desktop app has no devtools, so the panel reports its load stages
+      // here and they land in the host log. That is how "the bundle never loaded" stays
+      // distinguishable from "loaded, but apply() threw".
+      if (path === `${API_PREFIX}/client-log` && method === 'POST') {
+        const body = await readJsonBody(req)
+        webCtx.logger?.info?.(`[loomy] client half: ${JSON.stringify(body ?? {})}`)
+        sendJson(res, 200, { ok: true })
+        return
+      }
+
+      /**
+       * The artwork, twice: the opaque mark for surfaces that want a fixed colour, and
+       * the alpha-only silhouette the panel paints through a CSS mask so one asset works
+       * in both themes.
+       */
+      if ((path === `${API_PREFIX}/icon.png` || path === `${API_PREFIX}/icon-mask.png`) && method === 'GET') {
+        const isMask = path.endsWith('icon-mask.png')
+        try {
+          if (isMask) maskBytes ??= await readFile(MASK_PATH)
+          else iconBytes ??= await readFile(ICON_PATH)
+          res.statusCode = 200
+          // Both assets are PNG (the encoder in scripts/ only writes PNG); serving one as
+          // image/webp would make the browser refuse to render it.
+          res.setHeader('content-type', 'image/png')
+          // The artwork never changes within a build, so it may be cached; the payloads
+          // above may not.
+          res.setHeader('cache-control', 'public, max-age=3600')
+          res.end(isMask ? maskBytes : iconBytes)
+        } catch {
+          // No artwork in this build is a 404, not an error: the panel renders without a
+          // logo rather than refusing to open.
+          res.statusCode = 404
+          res.end()
+        }
+        return
+      }
+
+      if (path === `${API_PREFIX}/models`) {
+        if (method !== 'GET') {
+          sendJson(res, 405, { error: 'method not allowed' })
+          return
+        }
+        try {
+          const id = accountIdParam(url.searchParams.get('id'))
+          const payload = await modelsPayload(id, catalogue, { refresh: url.searchParams.get('refresh') === '1' })
+          sendJson(res, 200, payload)
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+        return
+      }
+
+      if (path === `${API_PREFIX}/credits`) {
+        if (method !== 'GET') {
+          sendJson(res, 405, { error: 'method not allowed' })
+          return
+        }
+        try {
+          const id = accountIdParam(url.searchParams.get('id'))
+          // `fetchCredits` is the per-day idempotent first-login claim: reading the
+          // balance also renews the daily pot, so a balance refresh is never a wasted call.
+          const credits = await withSession(id, (session) => fetchCredits(session))
+          // Re-anchor the ledger from the live answer so the pill's projection agrees
+          // the moment the user has checked the real number against it.
+          anchorLedger(id, credits, '刷新积分')
+          sendJson(res, 200, {
+            id,
+            credits: creditsSummary(credits),
+            dailyGrant: dailyGrantState(id) ?? null,
+            grantedToday: grantedToday(id)
+          })
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+        return
+      }
+
+      /**
+       * The manual fallback for the daily 5000. The host claims on startup and at local
+       * midnight; this route exists because those timers cannot run while the app was
+       * closed across a day boundary, and because a failed automatic claim is invisible
+       * until somebody asks.
+       */
+      if (path === `${API_PREFIX}/credits/claim` && method === 'POST') {
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          sendJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const id = accountIdParam(body.id)
+          const outcome = await withSession(id, (session) => ensureDailyGrant(id, session, { force: true, reason: '手动' }))
+          webCtx.logger?.info?.(`[loomy] ${id}: 手动领取每日积分 ${outcome.granted === true ? '成功' : '未生效'}${outcome.error === undefined ? '' : `（${outcome.error}）`}`)
+          sendJson(res, 200, {
+            id,
+            granted: outcome.granted === true,
+            skipped: outcome.skipped === true,
+            credits: creditsSummary(outcome),
+            dailyGrant: dailyGrantState(id) ?? null,
+            grantedToday: grantedToday(id)
+          })
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+        return
+      }
+
+      if (path === `${API_PREFIX}/login/send` && method === 'POST') {
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          sendJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const result = await sendSmsCode(body.phone)
+          sendJson(res, 200, { phone: maskPhone(result.phone), msgid: result.msgid, expire: result.expire })
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+        return
+      }
+
+      /**
+       * Exchange the SMS code for a session. The answer is the stored account record —
+       * never the session string, not even masked.
+       */
+      if (path === `${API_PREFIX}/login/verify` && method === 'POST') {
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          sendJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const label = typeof body.label === 'string' ? body.label : ''
+          const loggedIn = await loginBySmsCode({ phone: body.phone, code: body.code, msgid: body.msgid, label })
+          const record = upsertAccount({
+            session: loggedIn.session,
+            userid: loggedIn.userid,
+            phone: loggedIn.phone,
+            label,
+            source: 'sms'
+          })
+          // The profile read only fills in a display name and a canonical phone; a
+          // failure here must not turn a successful login into an error.
+          try {
+            const info = await fetchUserInfo(loggedIn.session)
+            if (info.phone.length > 0 && info.phone !== record.phone) {
+              upsertAccount({
+                session: record.session,
+                userid: record.userid,
+                phone: info.phone,
+                label: record.label,
+                source: record.source
+              })
+            }
+          } catch {
+            // keep the login, lose the profile
+          }
+          clearExpired(record.id)
+          const stored = accountOf(record.id) ?? record
+          // The provider route is mounted per account, so a login has to create one now:
+          // otherwise the panel reports a working account that the model picker cannot
+          // offer until the host restarts.
+          mountSafely(stored)
+          webCtx.logger?.info?.(`[loomy] ${stored.id}: 短信登录成功（${maskPhone(stored.phone)}）`)
+          sendJson(res, 200, { account: accountView(stored, catalogue) })
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+        return
+      }
+
+      /** Adopt the login the Loomy desktop app already has on this machine. */
+      if (path === `${API_PREFIX}/login/import` && method === 'POST') {
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          sendJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const imported = await importDesktopAccount({ label: typeof body.label === 'string' ? body.label : '' })
+          clearExpired(imported.record.id)
+          mountSafely(imported.record)
+          webCtx.logger?.info?.(`[loomy] ${imported.record.id}: 已导入桌面端登录态（来自 ${imported.path}）`)
+          sendJson(res, 200, {
+            account: accountView(imported.record, catalogue),
+            // A filesystem location, not a credential: the panel prints it as the
+            // confirmation of where the session came from.
+            path: imported.path
+          })
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+        return
+      }
+
+      if (path === `${API_PREFIX}/logout` && method === 'POST') {
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          sendJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const id = accountIdParam(body.id)
+          const account = accountOf(id)
+          if (account === undefined) {
+            sendJson(res, 404, { error: `未找到账号 "${id}"` })
+            return
+          }
+          // Server-side retirement is best effort: a session the server already forgot is
+          // still a session this plugin should drop locally, and a network failure must
+          // not leave the user unable to sign out.
+          const remote = await logoutRemote(account.session)
+          removeAccount(id)
+          clearExpired(id)
+          // Retire the route too: leaving it registered would keep offering a provider
+          // whose session this plugin just deleted.
+          try {
+            unmountAccount?.(id)
+          } catch (error) {
+            webCtx.logger?.warn?.(`[loomy] ${id}: 卸载 provider 路由失败 — ${error instanceof Error ? error.message : String(error)}`)
+          }
+          webCtx.logger?.info?.(`[loomy] ${id}: 已退出登录（远端${remote.ok === true ? '已注销' : '未确认'}）`)
+          sendJson(res, 200, { id, removed: true, remote })
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+        return
+      }
+
+      /** Rename one account. The id stays: routes and cache files hang off it. */
+      if (path === `${API_PREFIX}/label` && method === 'POST') {
+        const body = await readJsonBody(req)
+        if (body === undefined) {
+          sendJson(res, 400, { error: 'invalid JSON body' })
+          return
+        }
+        try {
+          const id = accountIdParam(body.id)
+          const updated = renameAccount(id, typeof body.label === 'string' ? body.label : '')
+          if (updated === undefined) {
+            sendJson(res, 404, { error: `未找到账号 "${id}"` })
+            return
+          }
+          sendJson(res, 200, { account: accountView(updated, catalogue) })
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+        return
+      }
+
+      // Naming the path matters: the host keeps serving the *first* registration it got,
+      // so after a reload a request can still land on an older build that simply does not
+      // know the route.
+      webCtx.logger?.warn?.(`[loomy] 未匹配的面板请求 ${method} ${path}（当前挂载的是 ${CODE_STAMP}）`)
+      sendJson(res, 404, { error: 'not found' })
+    } catch (error) {
+      webCtx.logger?.warn?.(`[loomy] API ${method} ${path} failed — ${error instanceof Error ? error.message : String(error)}`)
+      if (!res.headersSent) sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  webCtx.logger?.info?.(`[loomy] 面板路由已挂载（${CODE_STAMP}）`)
+  return webCtx.webServer.register({ kind: 'prefix', path: API_PREFIX, handler })
+}