@ilaomianyang/dsh-memory-graph 0.10.4 → 0.12.0

package/src/turns.js

@@ -0,0 +1,265 @@
+/**
+ * Turn assembly: live events and a replayed session file go through one reducer.
+ *
+ * Two things must never be implemented twice. First, what counts as a message a
+ * person actually typed — the harness pushes runtime snapshots, skill catalogs,
+ * sampled time and compaction checkpoints down the same channel, sometimes
+ * tagged `user`. Second, the truncation and redaction applied before anything
+ * touches disk. If the live listener and the history importer had separate
+ * copies of either, they would drift and the drift would be silent: a leaked
+ * snapshot on one side, a lost message on the other.
+ *
+ * So the filter lives here. The callers only decide *when* a turn is closed and
+ * *what timestamp* its episode carries.
+ */
+import { nowIso } from './vault.js'
+
+/** Assistant text is context, not the record; a handful of parts is plenty. */
+const MAX_ASSISTANT_PARTS = 6
+
+function collectText(node, depth = 0, seen = new Set(), out = []) {
+  if (node === null || node === undefined || depth > 4) return out
+  if (typeof node === 'string') return out
+  if (Array.isArray(node)) {
+    for (const item of node) collectText(item, depth + 1, seen, out)
+    return out
+  }
+  if (typeof node !== 'object') return out
+  if (seen.has(node)) return out
+  seen.add(node)
+
+  if (node.type === 'text' && typeof node.text === 'string') {
+    out.push(node.text)
+    return out
+  }
+  for (const key of ['content', 'message', 'text', 'parts', 'blocks']) {
+    if (key in node) collectText(node[key], depth + 1, seen, out)
+  }
+  return out
+}
+
+export function eventText(event) {
+  const parts = collectText(event?.data)
+  return parts.join('\n').replace(/\n{3,}/g, '\n\n').trim()
+}
+
+export function truncate(text, max) {
+  const value = String(text ?? '').trim()
+  if (value.length <= max) return value
+  return `${value.slice(0, max)}…`
+}
+
+/**
+ * Delimited harness blocks come off before any pattern is consulted.
+ *
+ * They are the one kind of injection whose extent is knowable, so removing them
+ * keeps the person's own words when a real message happens to carry one — the
+ * alternative (dropping the whole message) loses the part that was worth
+ * keeping. Undelimited blocks (a runtime snapshot) are handled by the patterns.
+ */
+export function stripInjectedBlocks(text) {
+  return String(text ?? '')
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+/** The project a session belongs to: the last segment of the cwd it started in. */
+export function projectOf(session, fallback) {
+  const cwd = session?.header?.cwd ?? session?.meta?.cwd ?? session?.cwd
+  if (typeof cwd === 'string' && cwd.trim() !== '') {
+    // Both separators, whatever platform this is running on: the path comes from
+    // the session header, which may well have been written on the other OS.
+    const parts = cwd.replace(/[\\/]+$/, '').split(/[\\/]/)
+    const base = parts[parts.length - 1] ?? ''
+    if (base !== '') return base
+  }
+  return fallback
+}
+
+/** The same shape as vault's nowIso(), for an arbitrary instant. */
+export function isoAt(ms) {
+  const d = new Date(ms)
+  const pad = (n) => String(n).padStart(2, '0')
+  const offset = -d.getTimezoneOffset()
+  const sign = offset >= 0 ? '+' : '-'
+  const abs = Math.abs(offset)
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+    `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}` +
+    `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`
+  )
+}
+
+/**
+ * Feed it events in order; it hands back finished episodes.
+ *
+ * `push()` returns an array because one event can close two turns: a user
+ * message that arrives while the previous turn never closed flushes that one
+ * first, then opens the next.
+ */
+export function createTurnAssembler({ cfg, redactor }) {
+  const buffers = new Map()
+
+  // Both the switch and the skip list are editable while the plugin runs (they
+  // are `.volatile()` in the schema), so neither is baked in here: the switch is
+  // read per event, and the compiled rules are rebuilt only when the list's text
+  // actually changes — a `new RegExp` on every token would be pure waste.
+  let skipKey
+  let skipRules = []
+
+  function compiledSkipRules() {
+    const list = cfg.capture.skipPatterns ?? []
+    const key = list.join('\u0000')
+    if (key !== skipKey) {
+      skipKey = key
+      skipRules = list.flatMap((pattern) => {
+        try {
+          return [new RegExp(pattern, 'i')]
+        } catch {
+          return []
+        }
+      })
+    }
+    return skipRules
+  }
+
+  /** True when the "user" side is really a harness injection, not a person typing. */
+  const injected = (text) => text !== '' && compiledSkipRules().some((re) => re.test(text))
+
+  function openBuffer(sessionId, project) {
+    let buffer = buffers.get(sessionId)
+    if (!buffer) {
+      buffer = {
+        project: project ?? cfg.defaultProject,
+        user: '',
+        assistant: [],
+        tools: 0,
+        turn: null,
+        at: null,
+      }
+      buffers.set(sessionId, buffer)
+    }
+    return buffer
+  }
+
+  function finish(sessionId, at) {
+    const buffer = buffers.get(sessionId)
+    if (!buffer) return null
+    buffers.delete(sessionId)
+
+    const toolCount = buffer.tools
+    const user = truncate(buffer.user, cfg.capture.userChars)
+    const assistant = truncate(buffer.assistant.join('\n'), cfg.capture.assistantChars)
+
+    // Every episode is anchored to something the user actually said. A turn with
+    // no user side is context noise, and one too short to mean anything — such as
+    // "ok" — would only fill the vault with lines the extractor cannot use.
+    if (user === '' || user.length + assistant.length < cfg.capture.minChars) return null
+
+    // The turn's own clock when the log carries one (a replayed session, or a
+    // turn flushed a minute late), otherwise now: the timeline should say when
+    // it happened, not when it was written down.
+    const stamp = at ?? buffer.at
+    const when = typeof stamp === 'string' ? stamp : stamp === null || stamp === undefined ? nowIso() : isoAt(stamp)
+
+    return {
+      t: when,
+      project: buffer.project,
+      session: sessionId,
+      turn: buffer.turn,
+      user: redactor.redact(user).text,
+      assistant: redactor.redact(assistant).text,
+      ...(cfg.capture.includeToolOutput && toolCount > 0 ? { tools: toolCount } : {}),
+    }
+  }
+
+  return {
+    /**
+     * @param {{sessionId: string, project?: string, event: object}} input
+     * @returns {object[]} episodes that are finished and ready to append
+     */
+    push({ sessionId, project, event }) {
+      if (!cfg.capture.enabled) return []
+      const type = event?.type
+      const at = Number.isFinite(event?.time) ? event.time : null
+      const done = []
+
+      if (type === 'turn/end') {
+        const buffer = buffers.get(sessionId)
+        if (!buffer) return done
+        if (typeof event?.data?.turn === 'number') buffer.turn = event.data.turn
+        const episode = finish(sessionId, at)
+        if (episode) done.push(episode)
+        return done
+      }
+
+      if (type !== 'user/message' && type !== 'assistant/message' && type !== 'tool/result') return done
+
+      if (type === 'user/message') {
+        // The harness delivers runtime snapshots, skill catalogs, sampled time,
+        // approval notices and compaction checkpoints through the same channel as
+        // the person typing — and not always with a telling `source.kind`: a real
+        // runtime snapshot has arrived here tagged `user` (it was captured as if
+        // the person had typed it). So provenance can only *add* a skip, never
+        // veto the patterns; both are consulted, and delimited blocks come off
+        // first so a message that merely carried a reminder keeps its own words.
+        const kind = event?.data?.source?.kind
+        const text = stripInjectedBlocks(eventText(event))
+        const synthetic = (typeof kind === 'string' && kind !== 'user') || text === '' || injected(text)
+        if (synthetic) return done
+
+        const open = buffers.get(sessionId)
+        if (open && (open.user !== '' || open.assistant.length > 0)) {
+          // A turn that never closed (interrupted, or an older harness): keep it.
+          const episode = finish(sessionId, at)
+          if (episode) done.push(episode)
+        }
+
+        const buffer = openBuffer(sessionId, project)
+        buffer.user = text
+        buffer.turn = typeof event?.data?.turn === 'number' ? event.data.turn : buffer.turn
+        if (at !== null) buffer.at = at
+        return done
+      }
+
+      const buffer = openBuffer(sessionId, project)
+      if (at !== null) buffer.at = at
+
+      if (type === 'assistant/message') {
+        const text = eventText(event)
+        if (text !== '' && buffer.assistant.length < MAX_ASSISTANT_PARTS) buffer.assistant.push(text)
+        if (typeof event?.data?.turn === 'number') buffer.turn = event.data.turn
+        return done
+      }
+
+      buffer.tools += 1
+      return done
+    },
+
+    /** Close one session's open turn. Returns the episode, or null if it was noise. */
+    flush(sessionId, at) {
+      return finish(sessionId, at ?? undefined)
+    },
+
+    /** Close every open turn (shutdown, or the end of a replayed file). */
+    flushAll(at) {
+      const out = []
+      for (const sessionId of [...buffers.keys()]) {
+        const episode = finish(sessionId, at ?? undefined)
+        if (episode) out.push(episode)
+      }
+      return out
+    },
+
+    /** True when this session has an open turn — a hint for the timer bookkeeping. */
+    isOpen(sessionId) {
+      return buffers.has(sessionId)
+    },
+
+    forget(sessionId) {
+      buffers.delete(sessionId)
+    },
+  }
+}

package/src/update.js

@@ -0,0 +1,406 @@
+/**
+ * Self-update: notice that a newer version exists, then let one decision install it.
+ *
+ * Two halves, deliberately separated.
+ *
+ * *Checking* is a single `GET <registry>/<name>/latest` — no query string, no
+ * body, nothing about the vault or the user in it — compared against the version
+ * this module is running. The answer is cached in the vault (`.update-state.json`)
+ * for `update.checkEveryHours`, so a page load does not turn into a request storm
+ * and an offline machine just keeps the last answer.
+ *
+ * *Installing* goes through the host's own `pluginManager.installBundle`, the same
+ * pnpm path `dsh plugin` uses, so the plugin does not invent a second way to move
+ * packages around and the profile's registry configuration is respected.
+ *
+ * The one thing that must not happen is a development checkout updating itself:
+ * under a `link:` install "install the newest version" would replace the user's
+ * working tree with a registry tarball. That is refused, and the refusal is
+ * reported as a fact about the installation rather than as an error.
+ */
+import fsp from 'node:fs/promises'
+
+import { paths } from './config.js'
+
+export const UPDATE_PATH = '/api/memory-graph.update'
+export const PACKAGE_NAME = '@ilaomianyang/dsh-memory-graph'
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org'
+const REQUEST_TIMEOUT_MS = 8000
+/** A GET younger than this is answered from the cache even when the caller asks. */
+const FRESH_MS = 60 * 1000
+
+/**
+ * The version this code is, read from its own manifest.
+ *
+ * Not a constant: a release bump must not need a second place to be edited, and
+ * the file is right there next to `src/`. A missing or unreadable manifest is not
+ * fatal — the plugin keeps working and simply cannot compare versions.
+ */
+export async function readOwnVersion(url = new URL('../package.json', import.meta.url)) {
+  try {
+    const manifest = JSON.parse(await fsp.readFile(url, 'utf8'))
+    return typeof manifest?.version === 'string' ? manifest.version : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Compare two dotted versions: -1, 0, 1.
+ *
+ * Deliberately small rather than a semver dependency: the only consumers are a
+ * published version and a registry dist-tag, both plain `x.y.z`. A prerelease
+ * (`1.0.0-beta.1`) sorts below its release, which is the one rule worth keeping.
+ */
+export function compareVersions(left, right) {
+  const parse = (text) => {
+    const [core, pre = ''] = String(text ?? '').trim().replace(/^v/u, '').split('-', 2)
+    const nums = core.split('.').map((part) => {
+      const value = Number.parseInt(part, 10)
+      return Number.isFinite(value) ? value : 0
+    })
+    while (nums.length < 3) nums.push(0)
+    return { nums: nums.slice(0, 3), pre }
+  }
+  const a = parse(left)
+  const b = parse(right)
+  for (let i = 0; i < 3; i += 1) {
+    if (a.nums[i] !== b.nums[i]) return a.nums[i] < b.nums[i] ? -1 : 1
+  }
+  if (a.pre === b.pre) return 0
+  // A prerelease is older than the release it precedes; two prereleases compare
+  // as text, which is wrong in theory and unreachable for this package.
+  if (a.pre === '') return 1
+  if (b.pre === '') return -1
+  return a.pre < b.pre ? -1 : 1
+}
+
+/**
+ * What the registry says the newest version is.
+ *
+ * `latest` as a dist-tag, not "the highest version ever published": a dist-tag is
+ * what `npm install` would give you, and it is what a person means by "the newest
+ * version".
+ */
+export async function fetchLatestVersion({ registry, name = PACKAGE_NAME, timeoutMs = REQUEST_TIMEOUT_MS, fetchFn } = {}) {
+  const base = String(registry || DEFAULT_REGISTRY).replace(/\/+$/u, '')
+  const url = `${base}/${name.replace('/', '%2f')}/latest`
+  const doFetch = fetchFn ?? globalThis.fetch
+  if (typeof doFetch !== 'function') throw new Error('这个运行时没有 fetch，查不了新版本 · fetch is unavailable in this runtime')
+  const init = { headers: { accept: 'application/json' } }
+  if (typeof AbortSignal?.timeout === 'function') init.signal = AbortSignal.timeout(timeoutMs)
+  const response = await doFetch(url, init)
+  if (!response?.ok) throw new Error(`registry ${base} answered ${response?.status ?? 'nothing'} · 注册表 ${base} 返回 ${response?.status ?? '无响应'}`)
+  const body = await response.json()
+  const version = typeof body?.version === 'string' ? body.version : ''
+  if (version === '') throw new Error(`registry ${base} returned no version · 注册表 ${base} 没有返回版本号`)
+  return { version, registry: base, name: body?.name ?? name }
+}
+
+function isoAt(ms) {
+  const date = new Date(ms)
+  const pad = (value) => String(Math.abs(value)).padStart(2, '0')
+  const offset = -date.getTimezoneOffset()
+  const sign = offset >= 0 ? '+' : '-'
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}${sign}${pad(Math.trunc(offset / 60))}:${pad(offset % 60)}`
+}
+
+/**
+ * How this plugin is installed, as far as the update decision is concerned.
+ *
+ * `link:` and `file:` are a working copy (this repository, in development): a
+ * registry install would overwrite it, so an update is refused rather than
+ * attempted. Anything else — including "cannot tell" — is treated the same way:
+ * not updatable until the host itself says the package came from a registry.
+ */
+export function installKindOf(bundles, name = PACKAGE_NAME) {
+  if (!Array.isArray(bundles)) return 'unknown'
+  const mine = bundles.find((bundle) => bundle?.name === name)
+  if (!mine) return 'unknown'
+  const spec = String(mine?.installTarget?.spec ?? '')
+  const source = String(mine?.source ?? '')
+  if (/^(link|file|workspace):/u.test(spec) || /^(link|file|workspace):/u.test(source)) return 'link'
+  if (mine.availability === 'profile' && spec !== '') return 'registry'
+  return 'unknown'
+}
+
+/**
+ * The checker. One instance per activation, shared by the route, the startup
+ * check and `memory_stats`.
+ */
+export function createUpdateChecker({ cfg, log = () => {}, getPluginManager, getName = () => PACKAGE_NAME, now = () => Date.now(), readVersion = readOwnVersion, fetchFn } = {}) {
+  let current = null
+  let cached = null
+  let busy = false
+  let lastError = null
+  let loading = null
+
+  const settings = () => cfg?.update ?? {}
+  const stateFile = () => (cfg?.vaultDir ? paths(String(cfg.vaultDir)).updateState : null)
+
+  async function version() {
+    if (current === null) current = await readVersion()
+    return current
+  }
+
+  async function loadCache() {
+    if (cached !== null) return cached
+    cached = { checkedAt: null, latest: null, registry: null, error: null }
+    const file = stateFile()
+    if (file === null) return cached
+    try {
+      const parsed = JSON.parse(await fsp.readFile(file, 'utf8'))
+      const at = Number(parsed?.checkedAtMs)
+      cached = {
+        checkedAt: Number.isFinite(at) && at > 0 ? at : null,
+        latest: typeof parsed?.latest === 'string' ? parsed.latest : null,
+        registry: typeof parsed?.registry === 'string' ? parsed.registry : null,
+        error: typeof parsed?.error === 'string' ? parsed.error : null,
+      }
+    } catch {
+      // A missing or broken cache is the normal first run, not a failure.
+    }
+    return cached
+  }
+
+  async function saveCache(next) {
+    cached = next
+    const file = stateFile()
+    if (file === null) return
+    try {
+      await fsp.mkdir(String(cfg.vaultDir), { recursive: true })
+      await fsp.writeFile(
+        file,
+        `${JSON.stringify({ checkedAtMs: next.checkedAt, latest: next.latest, registry: next.registry, error: next.error }, null, 2)}\n`,
+        'utf8',
+      )
+    } catch (error) {
+      log('warn', `自动更新：没能记下检查结果 · update: could not write the check cache: ${error?.message ?? error}`)
+    }
+  }
+
+  async function registryOf() {
+    const configured = String(settings().registry || '')
+    if (configured !== '') return configured
+    try {
+      const manager = getPluginManager?.()
+      const resolved = typeof manager?.registries === 'function' ? await manager.registries() : null
+      if (typeof resolved?.registry === 'string' && resolved.registry !== '') return resolved.registry
+    } catch {
+      // No plugin manager, or a profile that will not say: npm's own registry.
+    }
+    return DEFAULT_REGISTRY
+  }
+
+  async function refresh() {
+    const at = now()
+    const own = await version()
+    try {
+      const found = await fetchLatestVersion({ registry: await registryOf(), fetchFn })
+      const next = { checkedAt: at, latest: found.version, registry: found.registry, error: null }
+      await saveCache(next)
+      lastError = null
+      log('info', `自动更新：最新版本 ${found.version}，当前 ${own ?? '未知'}`)
+      return next
+    } catch (error) {
+      // Keep the previous answer and its timestamp: an offline machine should not
+      // forget what it knew, and a failed check must not look like "up to date".
+      const previous = await loadCache()
+      lastError = String(error?.message ?? error)
+      await saveCache({ ...previous, error: lastError })
+      log('warn', `自动更新：查不到新版本 · update: could not reach the registry: ${lastError}`)
+      return { ...previous, error: lastError }
+    }
+  }
+
+  async function ensureFresh(force = false) {
+    const cache = await loadCache()
+    const ttl = Math.max(1, Number(settings().checkEveryHours ?? 12)) * 3600 * 1000
+    const age = cache.checkedAt === null ? Number.POSITIVE_INFINITY : now() - cache.checkedAt
+    if (force && age >= FRESH_MS) return refresh()
+    if (age < ttl) return cache
+    if (loading !== null) return loading
+    loading = refresh().finally(() => {
+      loading = null
+    })
+    return loading
+  }
+
+  async function installKind() {
+    try {
+      const manager = getPluginManager?.()
+      if (typeof manager?.listBundles !== 'function') return 'unknown'
+      return installKindOf(await manager.listBundles(), getName())
+    } catch {
+      return 'unknown'
+    }
+  }
+
+  /** The shape the Settings page and the tests read. */
+  async function status({ force = false } = {}) {
+    const own = await version()
+    if (settings().enabled === false) {
+      return {
+        ok: true,
+        current: own,
+        latest: null,
+        behind: false,
+        canCheck: false,
+        canInstall: false,
+        installKind: 'unknown',
+        checkedAt: null,
+        registry: await registryOf(),
+        busy,
+        message: '自动检查更新已在设置里关掉 · update checks are off',
+        error: null,
+      }
+    }
+    const cache = await ensureFresh(force)
+    const kind = await installKind()
+    const behind = own !== null && cache.latest !== null ? compareVersions(cache.latest, own) > 0 : false
+    const canInstall = behind && kind === 'registry' && !busy
+    let message = null
+    if (cache.error !== null && cache.latest === null) message = `查不到新版本 · could not check: ${cache.error}`
+    else if (cache.latest === null) message = null
+    else if (behind) message = `有新版本 ${cache.latest} · ${own ?? '?'} → ${cache.latest}`
+    else message = `已是最新版本 ${own ?? cache.latest}`
+    if (behind && kind === 'link') message = `${message}；当前是本地 link: 安装，不能自动更新`
+    return {
+      ok: true,
+      current: own,
+      latest: cache.latest,
+      behind,
+      canCheck: true,
+      canInstall,
+      installKind: kind,
+      checkedAt: cache.checkedAt === null ? null : isoAt(cache.checkedAt),
+      registry: cache.registry ?? (await registryOf()),
+      busy,
+      message,
+      error: cache.error,
+    }
+  }
+
+  /**
+   * Install the newest version through the host.
+   *
+   * Refusals are returned, not thrown: every one of them is something a person
+   * needs to read (development install, nothing to update, no plugin manager),
+   * and the difference between "refused" and "failed" is worth keeping.
+   */
+  async function install() {
+    if (busy) return { ok: false, applied: false, application: 'failed', version: null, message: '已经有一次更新在跑 · an update is already running', error: null }
+    const state = await status({ force: true })
+    if (state.error !== null && state.latest === null) {
+      return { ok: false, applied: false, application: 'failed', version: null, message: `查不到新版本，装不了 · could not check: ${state.error}`, error: state.error }
+    }
+    if (!state.behind) {
+      return { ok: false, applied: false, application: 'failed', version: state.current, message: `已经是最新版本 ${state.current ?? ''} · already up to date`, error: null }
+    }
+    if (state.installKind === 'link') {
+      return {
+        ok: false,
+        applied: false,
+        application: 'failed',
+        version: state.latest,
+        message: '当前不是从 npm 安装的（link: 本地安装），自动更新会覆盖你的开发目录，已拒绝 · this is a link: install, so updating would overwrite the working copy',
+        error: null,
+      }
+    }
+    const manager = getPluginManager?.()
+    if (typeof manager?.installBundle !== 'function') {
+      return { ok: false, applied: false, application: 'failed', version: state.latest, message: '宿主没有提供 pluginManager，装不了 · the host exposes no pluginManager', error: null }
+    }
+    busy = true
+    try {
+      const spec = `${getName()}@${state.latest}`
+      log('info', `自动更新：正在安装 ${spec}`)
+      const result = await manager.installBundle(spec, { enabled: true })
+      const application = String(result?.application ?? 'failed')
+      const applied = application === 'applied' || application === 'restart-required'
+      if (applied) {
+        // The running code is now a version older than the one on disk; forget the
+        // cache so the next status is honest about what is installed.
+        cached = null
+      }
+      const message = applied
+        ? application === 'restart-required'
+          ? `已安装 ${state.latest}，需要重启 Harness 生效 · installed, restart the harness to apply`
+          : `已更新到 ${state.latest} · updated to ${state.latest}`
+        : `更新没有成功：${result?.error?.diagnostic ?? result?.error?.code ?? application} · update did not apply`
+      log(applied ? 'info' : 'warn', `自动更新：${message}`)
+      return {
+        ok: applied,
+        applied,
+        application,
+        version: applied ? (result?.version ?? state.latest) : state.latest,
+        message,
+        error: applied ? null : String(result?.error?.diagnostic ?? result?.error?.code ?? ''),
+      }
+    } catch (error) {
+      const message = String(error?.message ?? error)
+      log('warn', `自动更新：安装失败 · update install failed: ${message}`)
+      return { ok: false, applied: false, application: 'failed', version: state.latest, message: `安装失败：${message}`, error: message }
+    } finally {
+      busy = false
+    }
+  }
+
+  /** Startup hook: check once, and install only when that was asked for. */
+  async function onStart() {
+    if (settings().enabled === false) return null
+    try {
+      const state = await status()
+      if (state.behind && settings().autoInstall === true && state.installKind === 'registry') {
+        return await install()
+      }
+      return state
+    } catch (error) {
+      log('warn', `自动更新：启动检查失败 · update: startup check failed: ${error?.message ?? error}`)
+      return null
+    }
+  }
+
+  return { status, install, onStart, version, peek: () => ({ current, latest: cached?.latest ?? null, checkedAt: cached?.checkedAt ?? null, busy }), lastError: () => lastError }
+}
+
+/**
+ * The route. One path, two methods: GET answers "am I behind?", POST answers
+ * "then update" — and POST is the only verb that can touch the installation, so a
+ * page load or a prefetch can never do it by accident.
+ */
+export function createUpdateHandler({ getChecker }) {
+  return async function handle(request) {
+    const checker = getChecker()
+    if (!checker) {
+      return new Response(JSON.stringify({ ok: false, error: '更新检查还没有就绪 · the update checker is not ready' }), {
+        status: 503,
+        headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+      })
+    }
+    try {
+      if ((request?.method ?? 'GET').toUpperCase() === 'POST') {
+        const result = await checker.install()
+        // 200 when it landed, 409 when it was refused (a link: install, nothing to
+        // update, no plugin manager). "Refused" and "failed" are both non-2xx on
+        // purpose: neither should look like a version change to a caller.
+        return new Response(JSON.stringify(result), {
+          status: result.ok ? 200 : 409,
+          headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+        })
+      }
+      const url = new URL(request?.url ?? 'http://localhost/')
+      const force = url.searchParams.get('force') === '1'
+      const state = await checker.status({ force })
+      return new Response(JSON.stringify(state), {
+        status: 200,
+        headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+      })
+    } catch (error) {
+      return new Response(JSON.stringify({ ok: false, error: `更新检查失败：${error?.message ?? error}` }), {
+        status: 500,
+        headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+      })
+    }
+  }
+}