@thewaifu/dsh-bot 1.1.1

package/src/host/turns.js

@@ -0,0 +1,388 @@
+// Turns: what each Bot Session is doing now (for its mascot), which turns another Bot
+// triggered, the waiters and inboxes of group rounds, and routing a finished turn's reply.
+//
+// Turn tracking: which turns were triggered by another Bot, and what they said.
+import { REFERENCE_KIND, REPLY_KIND, SOURCE_KIND } from './constants.js'
+import { textOf } from './text.js'
+import { reminderText } from './schedules.js'
+
+// A failed turn's `LlmFailure`, kept to what can be shown and logged. Like DSH's own
+// error row, an AUTH failure loses its message: providers may echo part of the key.
+export function turnFailure(error) {
+  const code = typeof error?.code === 'string' && error.code !== '' ? error.code : 'UNKNOWN'
+  const message = code === 'AUTH' || typeof error?.message !== 'string' ? '' : error.message.trim().slice(0, 500)
+  return {
+    code,
+    message,
+    ...(typeof error?.status === 'number' ? { status: error.status } : {}),
+    ...(typeof error?.requestId === 'string' ? { requestId: error.requestId } : {}),
+  }
+}
+
+export const failureLine = failure => `${failure.code}${failure.status ? ` ${failure.status}` : ''}${failure.message ? `: ${failure.message.slice(0, 200)}` : ''}`
+
+// A group's own Session never reaches a model, so the snapshot DSH prepared there
+// rides with the user's queued message to the members who answer it.
+export function attachReference(queued, source, text) {
+  const post = queued?.findLast(item => item.botId === undefined && item.kickoff !== true)
+  if (post === undefined || text === '') return
+  const labels = (Array.isArray(source?.references) ? source.references : [])
+    .map(reference => reference?.label).filter(label => typeof label === 'string' && label !== '')
+  post.references = [...(post.references ?? []), { labels, text }]
+}
+
+export function install(rt) {
+  const { ctx, state } = rt
+
+  /** @type {Map<string, {turn?:number, pending?:any, info?:any, texts:string[], opened?:boolean, joined?:{info:any, from:number}[]}>} */
+  const live = new Map()
+  /** @type {Map<string, {sessionId:string, resolve:(text:string|null)=>void, fail:(failure:any)=>void, touch:()=>void, approval:()=>void}>} member turn waiters keyed by exchange id */
+  const roomWaiters = new Map()
+  /** @type {Map<string, {roomId:string, replies:any[], members:string[], speaking:string|null}>} */
+  const roomProgress = new Map()
+  /** @type {Map<string, {text:string, botId?:string, name?:string, reportBack?:boolean, hop?:number, kickoff?:boolean, references?:{labels:string[], text:string}[]}[]>} messages a room's next relay posts */
+  const roomInbox = new Map()
+  const queueRoomMessage = (roomId, item) => roomInbox.set(roomId, [...(roomInbox.get(roomId) ?? []), item])
+  // Member turns of a group round the user stopped: what they end with stays out of the group.
+  const stoppedRoomTurns = new Set()
+
+  // A stopped round stops the member work it started: the turn that answers it, or the
+  // delivery still waiting for the member's Session. An earlier turn there keeps going.
+  // An exchange whose turn already ended stays in the set, so it is bounded.
+  const STOPPED_KEPT = 200
+  async function stopRoomTurn(sessionId, exchangeId) {
+    stoppedRoomTurns.add(exchangeId)
+    if (stoppedRoomTurns.size > STOPPED_KEPT) stoppedRoomTurns.delete(stoppedRoomTurns.values().next().value)
+    const agent = await rt.resolveAgent(sessionId).catch(() => undefined)
+    if (agent === undefined) return
+    const entry = live.get(sessionId)
+    if (entry?.turn !== undefined && entry.info?.exchangeId === exchangeId) {
+      agent.cancel({ kind: 'hook', reason: 'ds-bot/stopped' })
+      return
+    }
+    for (const message of [...(agent.inbox?.nextStep ?? []), ...(agent.inbox?.nextTurn ?? [])]) {
+      if (message.source?.exchangeId === exchangeId && agent.inbox.remove(message.id)) stoppedRoomTurns.delete(exchangeId)
+    }
+  }
+
+  const liveOf = id => {
+    let entry = live.get(id)
+    if (entry === undefined) live.set(id, entry = { texts: [] })
+    return entry
+  }
+
+  // What each running Bot is doing right now, for its mascot. Process-local: it is
+  // rebuilt from live events and never saved.
+  /** @type {Record<string, string>} */
+  let activity = {}
+  const activityOf = (tool) => {
+    if (/^(message_bot|stop_bot|create_bot|update_bot|create_group|update_group|delete_group|post_to_group)$/.test(tool)) return 'sending'
+    if (tool === 'group_relay') return 'orbit'
+    if (/search|fetch|browse|browser|read|grep|glob|list/i.test(tool)) return 'searching'
+    return 'working'
+  }
+  const setActivity = (id, value) => {
+    if (activity[id] === value) return
+    const next = { ...activity }
+    if (value === undefined) delete next[id]
+    else next[id] = value
+    activity = next
+  }
+
+  const markExchangeTurn = (sessionId, turn) => {
+    const turns = state.exchangeTurns[sessionId] ??= []
+    if (!turns.includes(turn)) {
+      turns.push(turn)
+      if (turns.length > 400) turns.splice(0, turns.length - 400)
+      void rt.save().catch(() => {})
+    }
+  }
+  const unmarkExchangeTurn = (sessionId, turn) => {
+    const turns = state.exchangeTurns[sessionId] ?? []
+    if (!turns.includes(turn)) return
+    state.exchangeTurns[sessionId] = turns.filter(other => other !== turn)
+    void rt.save().catch(() => {})
+  }
+
+  // A request whose audience is the user is answered in the recipient's own chat: that
+  // turn stays visible there and its reply is not routed back to the sender.
+  const answersUser = info => info.role === 'request' && info.audience === 'user'
+  // Roles whose turn owes the sender a reply: a 'stopped' notice asks the Bot to
+  // acknowledge, exactly like a request.
+  const expectsReply = info => info.role === 'request' || info.role === 'stopped'
+
+  // A group Session is hidden as a whole, so its turns need no marking. A handoff
+  // package that only opens a part is acknowledged with a fixed line, also hidden.
+  const claimTrigger = (sessionId, entry, info) => {
+    entry.info = info
+    // A turn that was stopped for a part switch brings its joined requests along.
+    if (Array.isArray(info.joined) && info.joined.length > 0) {
+      entry.joined = info.joined.filter(item => item?.info !== undefined && item.info !== null)
+    }
+    if (rt.groupOwners.has(sessionId)) return
+    if ((expectsReply(info) && !answersUser(info)) || info.role === 'room' || (info.role === 'handoff' && info.resume !== true)) {
+      markExchangeTurn(sessionId, entry.turn)
+    }
+  }
+
+  // Activity is tracked per Session; a Bot's mascot shows its own chat's, else a group's.
+  const activityView = () => {
+    const merged = {}
+    for (const [id, value] of Object.entries(activity)) {
+      if (!rt.groupOwners.has(id)) merged[rt.chatOwners.get(id) ?? id] = value
+    }
+    for (const [id, value] of Object.entries(activity)) {
+      const owner = rt.groupOwners.get(id)
+      if (owner !== undefined) merged[owner.botId] ??= value
+    }
+    // A Bot writing its handoff note is thinking.
+    for (const job of rt.switchJobs()) {
+      if (job.roomId === undefined) merged[job.botId] = 'thinking'
+      else merged[job.botId] ??= 'thinking'
+    }
+    for (const approval of rt.approvalsView?.() ?? []) merged[approval.botId] = 'alert'
+    return merged
+  }
+
+  // Per Bot, the turn it is running and its current tool; its own chat wins over a group.
+  const workView = () => {
+    const bots = {}
+    for (const [id, entry] of live) {
+      if (entry.turn === undefined) continue
+      const owner = rt.groupOwners.get(id)
+      const botId = owner?.botId ?? rt.chatOwners.get(id)
+      if (botId === undefined || (owner !== undefined && bots[botId] !== undefined)) continue
+      bots[botId] = { since: entry.since, ...(entry.tool ? { tool: entry.tool } : {}), ...(owner ? { roomId: owner.roomId } : {}) }
+    }
+    return bots
+  }
+
+  // What a running tool call is about, for an approval card: its own description and
+  // the command, path or address it acts on.
+  const callDetail = (sessionId, callId) => {
+    let args
+    try { args = JSON.parse(live.get(sessionId)?.calls?.get(callId) ?? '{}') } catch { args = {} }
+    const first = keys => keys.map(key => args?.[key]).find(value => typeof value === 'string' && value.trim() !== '')
+    const text = first(['description', 'justification'])
+    const code = first(['command', 'cmd', 'file_path', 'path', 'url', 'query'])
+    return { ...(text ? { text: text.trim().slice(0, 300) } : {}), ...(code ? { code: code.trim().slice(0, 400) } : {}) }
+  }
+
+  // Where a Session speaks, for the diagnostics log.
+  const placeOf = (id) => {
+    const room = rt.roomOf(rt.groupOwners.get(id)?.roomId) ?? rt.roomOf(id)
+    return room ? `group "${room.name}"` : 'own chat'
+  }
+  const noteTurnFailure = (id, failure) => {
+    rt.noteFailure({
+      source: 'turn',
+      text: failure.message || 'the model call failed',
+      code: failure.code,
+      status: failure.status,
+      requestId: failure.requestId,
+      bot: rt.botOf(rt.selfOf(id))?.name ?? (rt.roomOf(id) ? undefined : 'unknown Bot'),
+      where: placeOf(id),
+      sessionId: id,
+    })
+  }
+
+  ctx.on('session/event', (session, event) => {
+    const id = session?.id
+    if (id === undefined) return
+    if (!rt.isBotSession(id) && !rt.roomOf(id)) return
+    const entry = liveOf(id)
+    if (rt.groupOwners.has(id)) rt.touchRoomTurn?.(id)
+    switch (event.type) {
+      case 'tool/call': {
+        const name = String(event.data?.name ?? '')
+        setActivity(id, name === 'ask_user' ? undefined : activityOf(name))
+        entry.tool = name
+        if (typeof event.data?.callId === 'string') (entry.calls ??= new Map()).set(event.data.callId, String(event.data.arguments ?? ''))
+        break
+      }
+      case 'tool/result':
+        if (entry.turn !== undefined) setActivity(id, 'thinking')
+        entry.tool = undefined
+        entry.calls?.delete(event.data?.callId)
+        break
+      case 'turn/start':
+        setActivity(id, 'thinking')
+        entry.turn = event.data.turn
+        entry.since = event.time ?? Date.now()
+        entry.texts = []
+        entry.info = undefined
+        // A turn turned away before its first step may end without a turn/end.
+        entry.switched = false
+        entry.answers = false
+        entry.opened = false
+        entry.joined = []
+        if (entry.pending !== undefined) {
+          claimTrigger(id, entry, entry.pending)
+          entry.pending = undefined
+        }
+        break
+      case 'user/message': {
+        const source = event.data?.source
+        // A message that shares a step with a bare handoff package is what the turn
+        // answers, so the turn is not a hidden acknowledgement.
+        const bare = info => info?.handoff === true && info.resume !== true
+        // Whether the turn was already opened by an earlier message decides what a
+        // Bot relay that lands inside it may claim: the first message of a turn
+        // still claims it as today, a later one only joins it.
+        const opened = entry.opened === true
+        if (entry.turn !== undefined && !bare(source)
+          && (source?.kind === 'user' || source?.kind === REPLY_KIND || source?.kind === 'schedule' || source?.kind === SOURCE_KIND)) {
+          entry.opened = true
+        }
+        if (entry.turn !== undefined && (source?.kind === 'user' || source?.kind === REPLY_KIND || source?.kind === SOURCE_KIND)) {
+          if (bare(source)) {
+            if (entry.answers) break
+          } else {
+            entry.answers = true
+            if (bare(entry.info)) {
+              unmarkExchangeTurn(id, entry.turn)
+              entry.info = undefined
+            }
+          }
+        }
+        if (source?.kind === SOURCE_KIND && source.role === 'post' && rt.roomOf(id)) {
+          queueRoomMessage(id, {
+            text: textOf(event.data.content).replace(/^\[Group post from [^\]]*\]\n?/, ''),
+            botId: source.senderSessionId,
+            name: source.senderName,
+            reportBack: source.reportBack === true,
+            hop: source.hop ?? 0,
+            ...(source.late ? { late: true } : {}),
+            ...(source.quiet ? { quiet: true } : {}),
+            ...(source.failed ? { failed: source.failed } : {}),
+          })
+        } else if (source?.kind === SOURCE_KIND && source.role === 'kickoff' && rt.roomOf(id)) {
+          queueRoomMessage(id, { text: '', kickoff: true })
+        } else if (source?.kind === SOURCE_KIND) {
+          if (entry.turn === undefined) entry.pending = source
+          else if (!opened) claimTrigger(id, entry, source)
+          else if (expectsReply(source) && !answersUser(source)
+            && source.exchangeId !== entry.info?.exchangeId
+            && !(entry.joined ?? []).some(joined => joined.info.exchangeId === source.exchangeId)) {
+            // A request that lands inside a running turn steers that work but is
+            // answered in a hidden turn of its own once the work is done, so the
+            // sender never gets the turn's text. A failed-switch resume message
+            // re-sends the trigger's own source; the same exchangeId must not join twice.
+            const text = textOf(event.data.content).replace(/^\[[^\]\n]*\]\n?/, '')
+            entry.joined = [...(entry.joined ?? []), { info: source, text }]
+          }
+          // A mid-turn relay that owes no reply only informs the turn: it neither
+          // claims the running turn nor queues as the next one's trigger.
+        } else if (source?.kind === 'schedule' && rt.roomOf(id)) {
+          // A group's scheduled task reaches the group as the user's message.
+          queueRoomMessage(id, { text: reminderText(textOf(event.data.content)) })
+        } else if (source?.kind === REFERENCE_KIND && rt.roomOf(id)) {
+          attachReference(roomInbox.get(id), source, textOf(event.data.content))
+        } else if (source?.kind === 'user' || source?.kind === REPLY_KIND) {
+          if (rt.roomOf(id) && source.kind === 'user') {
+            const images = (Array.isArray(event.data.content) ? event.data.content : [])
+              .filter(block => block?.type === 'image' && !block.offloaded).map(block => block.attachment)
+            queueRoomMessage(id, { text: textOf(event.data.content), ...(images.length > 0 ? { images } : {}) })
+          }
+          const own = rt.chatOwners.get(id)
+          if (own !== undefined) rt.dropKickoff(own)
+          // Any user message answers or supersedes the open question card.
+          if (state.questions[id] !== undefined) {
+            delete state.questions[id]
+            void rt.save().catch(() => {})
+          }
+        }
+        break
+      }
+      case 'assistant/message': {
+        const text = textOf(event.data?.message?.content)
+        if (text !== '') entry.texts.push(text)
+        break
+      }
+      case 'turn/end': {
+        setActivity(id, undefined)
+        const info = entry.info
+        const joined = entry.joined ?? []
+        const texts = entry.texts
+        // A turn stopped for a switch goes on in the next part, which answers instead.
+        const switched = entry.switched === true
+        entry.turn = undefined
+        entry.info = undefined
+        entry.texts = []
+        entry.switched = false
+        entry.joined = []
+        entry.since = undefined
+        entry.tool = undefined
+        entry.calls = undefined
+        const reason = event.data?.reason
+        const failure = reason?.kind === 'error' && !switched ? turnFailure(reason.error) : undefined
+        if (failure !== undefined) noteTurnFailure(id, failure)
+        if (switched) break
+        // Whoever the turn answers gets the same three-way rule: a failure notice,
+        // the turn's text (or a stopped-before-answer line), or nothing.
+        const answer = (source, reply) => {
+          if (!expectsReply(source) || answersUser(source)) return
+          const name = rt.botOf(rt.selfOf(id))?.name ?? 'The other Bot'
+          if (failure !== undefined) {
+            // The sender was told a reply comes later; without this it would wait forever.
+            void rt.deliver({
+              fromId: rt.selfOf(id),
+              toId: source.senderSessionId,
+              text: `${name} could not answer your message: its model call failed (${failureLine(failure)}). Tell the user if it matters; do not retry right away.`,
+              role: 'reply',
+              hop: (source.hop ?? 0) + 1,
+              replyTo: source.exchangeId,
+            }).catch(error => rt.warn('ds-bot: failure notice delivery failed: %s', error))
+          } else if (reply !== '' || reason?.kind === 'aborted') {
+            // A turn stopped before it could answer still owes the sender a line,
+            // or it would wait forever for a reply that never comes.
+            void rt.deliver({
+              fromId: rt.selfOf(id),
+              toId: source.senderSessionId,
+              text: reply !== '' ? reply : `${name} was stopped before it could answer your message.`,
+              role: 'reply',
+              hop: (source.hop ?? 0) + 1,
+              replyTo: source.exchangeId,
+            }).catch(error => rt.warn('ds-bot: reply delivery failed: %s', error))
+          }
+        }
+        if (info?.role === 'room') {
+          const waiter = roomWaiters.get(info.exchangeId)
+          roomWaiters.delete(info.exchangeId)
+          const stopped = stoppedRoomTurns.delete(info.exchangeId)
+          if (waiter !== undefined) {
+            if (failure !== undefined) waiter.fail(failure)
+            else waiter.resolve(reason?.kind === 'aborted' ? null : texts.join('\n\n').trim())
+          } else if (!stopped && reason?.kind !== 'aborted') {
+            // The round moved on without this member; how its turn ends still reaches the group.
+            if (failure !== undefined) void rt.lateRoomFailure?.(id, info, failure)
+            else void rt.lateRoomReply?.(id, info, texts.join('\n\n').trim())
+          }
+        } else if (info !== undefined) {
+          answer(info, texts.join('\n\n').trim())
+        }
+        for (const request of joined) {
+          // A failed or stopped turn closes the request like any other; a finished
+          // one hands it back to the Bot to answer next.
+          if (failure !== undefined || reason?.kind === 'aborted') {
+            answer(request.info, '')
+            continue
+          }
+          void rt.deliver({
+            fromId: request.info.senderSessionId,
+            toId: rt.selfOf(id),
+            sessionId: id,
+            text: request.text,
+            role: 'request',
+            hop: request.info.hop ?? 0,
+            exchangeId: request.info.exchangeId,
+            deferred: true,
+          }).catch(error => rt.warn('ds-bot: deferred request delivery failed: %s', error))
+        }
+        break
+      }
+    }
+  })
+
+  Object.assign(rt, { live, liveOf, roomWaiters, roomProgress, roomInbox, activityView, workView, callDetail, stopRoomTurn })
+}

package/src/host/update.js

@@ -0,0 +1,237 @@
+// Updates: compare this package's version with the newest release where it was
+// installed from (the npm registry, or a GitHub tag for a versioned git install)
+// and, when the user asks, reinstall it through DSH's plugin manager. A new version
+// runs from the next DSH start. A linked or local checkout is never offered one.
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const PKG = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+export const OFFICIAL_REGISTRY = 'https://registry.npmjs.org/'
+export const MIRROR_REGISTRY = 'https://registry.npmmirror.com/'
+// Every window that opens asks; within this long the last answer stands.
+export const CHECK_TTL_MS = 10 * 60_000
+export const FETCH_TIMEOUT_MS = 8000
+// The first check waits until the host has settled its own start.
+const STARTUP_DELAY_MS = 15_000
+const VERSION = /^v?(\d+\.\d+\.\d+(?:-[\w.]+)?)(?:\+[\w.]+)?$/
+
+/** A release version without its `v` and build metadata, or null. */
+export const cleanVersion = value => VERSION.exec(String(value ?? '').trim())?.[1] ?? null
+
+/** Whether version `a` is newer than `b` (semver order, prereleases before their release). */
+export function newer(a, b) {
+  const parse = (value) => {
+    const [core, pre] = (cleanVersion(value) ?? '0.0.0').split(/-(.*)/s)
+    return { nums: core.split('.').map(Number), pre: pre ?? null }
+  }
+  const x = parse(a)
+  const y = parse(b)
+  for (let index = 0; index < 3; index++) if (x.nums[index] !== y.nums[index]) return x.nums[index] > y.nums[index]
+  if (x.pre === y.pre) return false
+  if (x.pre === null) return true
+  if (y.pre === null) return false
+  return x.pre.localeCompare(y.pre, 'en', { numeric: true }) > 0
+}
+
+/**
+ * How the profile installed this package, from the plugin manager's `source` spec:
+ * `registry` (name@range), `git` (with `owner`, `repo`, the version `ref` and the
+ * other fragment parts when it pins a GitHub tag), `path` (link:, file: or a folder),
+ * `tarball`, or `unknown`.
+ */
+export function sourceOf(spec) {
+  const text = typeof spec === 'string' ? spec.trim() : ''
+  if (text === '') return { kind: 'unknown' }
+  if (/^(link|file):/i.test(text) || /^([a-z]:[\\/]|[\\/]|~|\.)/i.test(text)) return { kind: 'path' }
+  const github = /^(?:github:|git\+https:\/\/github\.com\/|https:\/\/github\.com\/|git@github\.com:)?([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:#(.*))?$/i.exec(text)
+  const gitLike = /^(git\+|git:|git@|github:|gitlab:|bitbucket:)/i.test(text) || /\.git(#|$)/i.test(text)
+  if (github && (gitLike || !text.startsWith('@'))) {
+    const parts = (github[3] ?? '').split('&').filter(Boolean)
+    const ref = parts.find(part => !part.includes(':')) ?? ''
+    return {
+      kind: 'git', owner: github[1], repo: github[2],
+      ...(cleanVersion(ref) ? { ref } : {}),
+      rest: parts.filter(part => part !== ref),
+    }
+  }
+  if (gitLike) return { kind: 'git' }
+  if (/^https?:/i.test(text)) return { kind: 'tarball' }
+  return { kind: 'registry' }
+}
+
+const normalizeRegistry = url => `${String(url).trim().replace(/\/+$/, '')}/`
+export const encodeName = name => (name.startsWith('@') ? `@${encodeURIComponent(name.slice(1))}` : encodeURIComponent(name))
+
+export const fetchJson = async (url, headers = {}) => {
+  const response = await fetch(url, { headers: { accept: 'application/json', ...headers }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+  if (!response.ok) throw new Error(`${url} answered ${response.status}`)
+  return response.json()
+}
+
+// The registries the plugin manager installs from, in its order: its configured
+// first one (else pnpm's own), then the fallbacks, unless that first one is private.
+export async function registryPlan(config, manager) {
+  if (typeof config.updateRegistry === 'string' && config.updateRegistry !== '') return [normalizeRegistry(config.updateRegistry)]
+  const configured = await Promise.resolve(manager?.registries?.()).catch(() => null)
+  if (!configured) return [OFFICIAL_REGISTRY, MIRROR_REGISTRY]
+  const fallbacks = (configured.fallbackRegistries ?? []).map(normalizeRegistry)
+  const own = configured.resolved ? normalizeRegistry(configured.resolved) : null
+  const first = configured.registry ? normalizeRegistry(configured.registry) : own ?? OFFICIAL_REGISTRY
+  const isPublic = first === OFFICIAL_REGISTRY || fallbacks.includes(first)
+  return isPublic ? [...new Set([first, ...fallbacks])] : [first]
+}
+
+// The plugin manager's `source` for this package; DSH releases before it reported
+// one leave the profile's own dependency entry to say the same.
+export async function installSpecOf(ctx) {
+  const manager = ctx.get?.('pluginManager')
+  const bundles = await Promise.resolve(manager?.listBundles?.()).catch(() => null)
+  const own = Array.isArray(bundles) ? bundles.find(bundle => bundle.name === PKG.name) : undefined
+  if (typeof own?.source === 'string') return own.source
+  const dir = ctx.get?.('profileContext')?.dir
+  if (typeof dir !== 'string') return undefined
+  try {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies?.[PKG.name]
+  } catch { return undefined }
+}
+
+// The public repository the releases live in, for tags and the "what's new" link.
+export const repoSlug = () =>
+  /github\.com[/:]([\w.-]+\/[\w.-]+?)(?:\.git)?$/i.exec(String(PKG.repository?.url ?? PKG.repository ?? ''))?.[1] ?? null
+
+const repoUrl = () => {
+  const repo = repoSlug()
+  return repo ? `https://github.com/${repo}` : null
+}
+const releasesUrl = () => {
+  const repo = repoUrl()
+  return repo ? `${repo}/releases` : (PKG.homepage ?? null)
+}
+
+export const STARS_TTL_MS = 60 * 60_000
+
+export function install(rt) {
+  const { ctx, config } = rt
+  const enabled = config.updateCheck !== false
+  const manager = () => ctx.get?.('pluginManager')
+
+  const status = {
+    name: PKG.name, current: PKG.version, latest: null, source: 'unknown', notesUrl: releasesUrl(),
+    checkedAt: 0, phase: 'idle', installed: null, error: null,
+  }
+  // Where the newest version was found, and the spec that installs it.
+  let target = null
+  let checking = null
+
+  const view = () => ({
+    name: status.name, current: status.current, latest: status.latest, source: status.source, notesUrl: status.notesUrl,
+    repoUrl: repoUrl(), enabled,
+    checkedAt: status.checkedAt, phase: status.phase, installed: status.installed, error: status.error,
+    available: status.phase !== 'installed' && target !== null && status.latest !== null && newer(status.latest, status.current),
+  })
+
+  // Asked only while the About page is open, so a closed page never calls GitHub.
+  // A failed answer keeps the last count and is asked again next time.
+  let stars = { count: null, at: 0 }
+  let starring = null
+  async function repoStars() {
+    const repo = repoSlug()
+    if (repo === null) return null
+    if (Date.now() - stars.at < STARS_TTL_MS) return stars.count
+    starring ??= fetchJson(`https://api.github.com/repos/${repo}`, { 'user-agent': `${PKG.name}/${PKG.version}` })
+      .then((info) => { if (Number.isInteger(info?.stargazers_count)) stars = { count: info.stargazers_count, at: Date.now() } })
+      .catch(error => rt.warn('ds-bot: star count failed: %s', error?.message ?? error))
+      .finally(() => { starring = null })
+    await starring
+    return stars.count
+  }
+
+  async function newestFromRegistry() {
+    for (const registry of await registryPlan(config, manager())) {
+      try {
+        const version = cleanVersion((await fetchJson(`${registry}${encodeName(PKG.name)}/latest`)).version)
+        if (version) return { version, spec: `${PKG.name}@${version}`, registry }
+      } catch { /* unreachable, or no copy there yet: ask the next one */ }
+    }
+    return null
+  }
+
+  async function newestFromGitHub(source) {
+    if (!source.ref) return null
+    const release = await fetchJson(`https://api.github.com/repos/${source.owner}/${source.repo}/releases/latest`, { 'user-agent': `${PKG.name}/${PKG.version}` })
+    const version = cleanVersion(release?.tag_name)
+    if (!version) return null
+    // The API answers through redirects, so the release's html_url names the
+    // repository's current address; the install moves to it.
+    const current = /^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/releases\//.exec(release.html_url ?? '')
+    const [owner, repo] = current ? [current[1], current[2]] : [source.owner, source.repo]
+    const fragment = [release.tag_name, ...source.rest].join('&')
+    return { version, spec: `github:${owner}/${repo}#${fragment}` }
+  }
+
+  async function runCheck() {
+    const source = sourceOf(await installSpecOf(ctx))
+    status.source = source.kind
+    let found = null
+    try {
+      if (source.kind === 'registry') found = await newestFromRegistry()
+      else if (source.kind === 'git') found = await newestFromGitHub(source)
+    } catch (error) {
+      rt.warn('ds-bot: update check failed: %s', error?.message ?? error)
+    }
+    status.checkedAt = Date.now()
+    // Nothing found now (a linked checkout, a moved tag, an unreachable registry)
+    // retires the version a check before it found; offering it would install over
+    // a source that never updates.
+    if (found === null) {
+      status.latest = null
+      target = null
+      return
+    }
+    status.latest = found.version
+    target = newer(found.version, status.current) ? found : null
+  }
+
+  /** Ask where the package came from for its newest version; a fresh check ignores the last answer. */
+  async function check({ fresh = false } = {}) {
+    if (!enabled) return view()
+    if (checking) return checking
+    if (!fresh && Date.now() - status.checkedAt < CHECK_TTL_MS) return view()
+    checking = runCheck().finally(() => { checking = null })
+    await checking
+    return view()
+  }
+
+  /** Start reinstalling the newest version; the answer comes back through `check`. */
+  function start() {
+    if (status.phase === 'installing') return view()
+    if (target === null) throw new Error('No DS Bot update is available')
+    const service = manager()
+    if (typeof service?.installBundle !== 'function') throw new Error('The DSH plugin manager is not available in this profile')
+    const chosen = target
+    Object.assign(status, { phase: 'installing', error: null })
+    void Promise.resolve(service.installBundle(chosen.spec, chosen.registry ? { registry: chosen.registry } : {}))
+      .then((result) => {
+        if (result?.error || !['applied', 'restart-required'].includes(result?.application)) {
+          throw new Error(result?.error?.diagnostic ?? result?.error?.code ?? `install ${result?.application ?? 'failed'}`)
+        }
+        Object.assign(status, { phase: 'installed', installed: cleanVersion(result.version) ?? chosen.version })
+      })
+      .catch((error) => {
+        rt.warn('ds-bot: update to %s failed: %s', chosen.spec, error?.message ?? error)
+        Object.assign(status, { phase: 'failed', error: String(error?.message ?? error).slice(0, 600) })
+      })
+    return view()
+  }
+
+  if (enabled) {
+    ctx.effect(() => {
+      const timer = setTimeout(() => { void check() }, STARTUP_DELAY_MS)
+      // A pending first check never keeps the process alive.
+      timer.unref?.()
+      return () => clearTimeout(timer)
+    }, 'ds-bot: update check')
+  }
+
+  Object.assign(rt, { updateCheck: check, updateStart: start, updateView: view, repoStars })
+}