@soffits/dsh-telegram-bot 0.0.0-stage → 0.4.0

package/src/message-context.js

@@ -0,0 +1,339 @@
+/**
+ * Describe what an incoming Telegram message replies to, quotes or forwards,
+ * as short labelled plain text the agent reads before the message itself.
+ */
+
+/** Longest quoted or forwarded text passed to the agent, in characters. */
+export const QUOTE_LIMIT = 2000
+
+/** Longest text of a message sent on someone's behalf passed to the agent, in characters. */
+export const SENT_TEXT_LIMIT = 8000
+
+/** Largest file Telegram lets a bot download (getFile). */
+export const DOWNLOAD_LIMIT_BYTES = 20 * 1024 * 1024
+
+/** Labels the bridge puts on prompts it mirrors from other clients. */
+const MIRROR_LABELS = [
+  ['🖥 From Web:', 'the Web UI (a user prompt this bot mirrored into the chat, not an assistant answer)'],
+  ['🖥 Из Web:', 'the Web UI (a user prompt this bot mirrored into the chat, not an assistant answer)'],
+  ['⏰ Scheduled task:', 'a scheduled task (a prompt this bot mirrored into the chat, not an assistant answer)'],
+  ['⏰ Задача по расписанию:', 'a scheduled task (a prompt this bot mirrored into the chat, not an assistant answer)'],
+]
+
+/**
+ * Text or caption of a message.
+ * @param message - Telegram message or external reply.
+ * @returns the text, or an empty string.
+ */
+export function messageBody(message) {
+  if (typeof message?.text === 'string') return message.text
+  if (typeof message?.caption === 'string') return message.caption
+  return ''
+}
+
+/**
+ * True when the message was forwarded from somewhere else.
+ * @param message - Telegram message.
+ */
+export function isForwarded(message) {
+  return originOf(message) !== undefined
+}
+
+/**
+ * The photo, document, spoken recording (voice, audio, round video) or
+ * sticker of a message, when the bot can download it.
+ * @param message - Telegram message or external reply.
+ * @returns the file kind and size, or undefined.
+ */
+export function downloadableFile(message) {
+  const photo = Array.isArray(message?.photo) ? message.photo.at(-1) : undefined
+  const candidates = [['photo', photo], ['document', message?.document], ['voice', message?.voice], ['video_note', message?.video_note], ['audio', message?.audio], ['sticker', message?.sticker]]
+  const found = candidates.find(([, file]) => typeof file?.file_id === 'string')
+  if (found === undefined) return undefined
+  const [kind, file] = found
+  return { kind, size: typeof file.file_size === 'number' ? file.file_size : undefined }
+}
+
+/**
+ * The message a reply points at, ignoring the topic's own first message,
+ * which Telegram sets as the reply target of every message in a topic.
+ * @param message - Telegram message.
+ * @returns the replied-to message, or undefined.
+ */
+export function repliedMessage(message) {
+  const target = message?.reply_to_message
+  if (target === undefined || target === null) return undefined
+  if (target.forum_topic_created !== undefined) return undefined
+  if (message.is_topic_message === true && target.message_id === message.message_thread_id) return undefined
+  return target
+}
+
+/**
+ * Chat and message id of the message a reply points at, for looking it up
+ * in the sent-message log.
+ * @param message - Telegram message.
+ * @returns { chatId, messageId }, or undefined when it is not a reply.
+ */
+export function replyReference(message) {
+  if (originOf(message) !== undefined) return undefined
+  const target = repliedMessage(message)
+  if (target !== undefined) return { chatId: target.chat?.id ?? message.chat?.id, messageId: target.message_id }
+  const external = message?.external_reply
+  if (external?.chat?.id !== undefined && Number.isSafeInteger(external.message_id)) return { chatId: external.chat.id, messageId: external.message_id }
+  return undefined
+}
+
+/**
+ * Build the prompt text for one message: context lines, then the message.
+ * A forwarded message is shown in full inside its context block.
+ * @param message - Telegram message.
+ * @param options - botId: this bot's user id; replyFile: outcome of attaching
+ *   the replied-to file ('attached', 'too-large', 'failed'); ownFile: true when
+ *   the message's own photo or document is attached; maxQuote: text limit;
+ *   sent: the sent-message log entry the replied-to message belongs to;
+ *   currentSession: the session now bound to the topic.
+ * @returns the prompt text, possibly empty.
+ */
+export function composePrompt(message, options = {}) {
+  const body = messageBody(message).trim()
+  const forward = describeForward(message, body, options)
+  const reply = forward === undefined ? describeReply(message, options) : undefined
+  const sent = reply === undefined ? undefined : describeSent(options.sent, { currentSession: options.currentSession })
+  const blocks = [reply, sent, forward].filter((block) => block !== undefined)
+  if (forward === undefined && body.length > 0) blocks.push(body)
+  return blocks.join('\n\n')
+}
+
+/**
+ * The line that tells the agent who wrote a Telegram message. Several allowed
+ * users can talk to the same bot, each in their own chat.
+ * @param user - Telegram `from` of the message.
+ * @returns a one-line label, or undefined without a sender.
+ */
+export function senderLabel(user) {
+  if (user === undefined || user === null || user.id === undefined) return undefined
+  const name = [user.first_name, user.last_name].filter((part) => typeof part === 'string' && part.trim().length > 0).join(' ').trim()
+  const details = []
+  if (typeof user.username === 'string' && user.username.length > 0) details.push(`@${user.username}`)
+  details.push(`user id ${user.id}`)
+  return name.length > 0 ? `[Telegram message from ${name} (${details.join(', ')})]` : `[Telegram message from ${details.join(', ')}]`
+}
+
+/**
+ * Describe the replied-to or externally replied message, if any.
+ * @returns the context block, or undefined.
+ */
+export function describeReply(message, options = {}) {
+  const limit = options.maxQuote ?? QUOTE_LIMIT
+  const quote = typeof message?.quote?.text === 'string' && message.quote.text.trim().length > 0 ? message.quote.text : undefined
+  const target = repliedMessage(message)
+  if (target !== undefined) {
+    const details = [`sent ${formatDate(target.date)}`]
+    const origin = originOf(target)
+    if (origin !== undefined) details.push(`forwarded from ${describeOrigin(origin, message, options)}${origin.date === undefined ? '' : `, originally sent ${formatDate(origin.date)}`}`)
+    const media = mediaNote(target, options.replyFile)
+    if (media !== undefined) details.push(media)
+    const text = quote ?? messageBody(target)
+    const label = quote === undefined ? '' : '; the user quoted only this part'
+    const head = `[Replying to a message from ${describeSender(target, message, options)} (${details.join('; ')})${label}]`
+    return text.trim().length === 0 ? head : `${head}\n${quoteLines(text, limit)}`
+  }
+  const external = message?.external_reply
+  if (external === undefined || external === null) {
+    if (message?.reply_to_story !== undefined) return '[Replying to a Telegram story]'
+    return undefined
+  }
+  const details = []
+  if (external.origin !== undefined) {
+    details.push(`from ${describeOrigin(external.origin, message, options)}`)
+    if (external.origin.date !== undefined) details.push(`sent ${formatDate(external.origin.date)}`)
+  }
+  if (external.chat !== undefined && external.origin?.type !== 'channel') details.push(`in ${chatName(external.chat)}`)
+  const link = messageLink(external.chat, external.message_id)
+  if (link !== undefined) details.push(link)
+  const media = mediaNote(external, options.replyFile)
+  if (media !== undefined) details.push(media)
+  const head = `[Replying to a message from another chat${details.length === 0 ? '' : ` (${details.join('; ')})`}${quote === undefined ? '' : '; the user quoted this part'}]`
+  if (quote !== undefined) return `${head}\n${quoteLines(quote, limit)}`
+  return `${head}\n(The bot cannot see the text of messages in other chats unless the user quotes it.)`
+}
+
+/**
+ * Describe a forwarded message together with its content.
+ * @returns the context block, or undefined when the message is not forwarded.
+ */
+export function describeForward(message, body = messageBody(message).trim(), options = {}) {
+  const origin = originOf(message)
+  if (origin === undefined) return undefined
+  const details = []
+  if (origin.date !== undefined) details.push(`originally sent ${formatDate(origin.date)}`)
+  const link = origin.type === 'channel' ? messageLink(origin.chat, origin.message_id) : undefined
+  if (link !== undefined) details.push(link)
+  const media = mediaNote(message, options.ownFile === true ? 'attached' : undefined)
+  if (media !== undefined) details.push(media)
+  const head = `[Forwarded message from ${describeOrigin(origin, message, options)}${details.length === 0 ? '' : ` (${details.join('; ')})`}]`
+  return body.length === 0 ? head : `${head}\n${quoteLines(body, options.maxQuote ?? QUOTE_LIMIT)}`
+}
+
+/**
+ * Describe a message the bot sent into a topic on someone's behalf (a script,
+ * a job, a plugin or another session): who sent it, when, where it was
+ * recorded, and its full text, which may span several Telegram messages.
+ * @param sent - entry from the sent-message log.
+ * @param options - currentSession: session now bound to the topic; limit: text limit.
+ * @returns the context block, or undefined.
+ */
+export function describeSent(sent, options = {}) {
+  if (sent === undefined || sent === null) return undefined
+  const details = []
+  const time = Date.parse(sent.sentAt ?? '')
+  details.push(Number.isFinite(time) ? `sent ${formatDate(time / 1000)}` : 'sent at an unknown time')
+  if (typeof sent.job === 'string' && sent.job.length > 0) details.push(`by job "${sent.job}"`)
+  if (typeof sent.fromSession === 'string' && sent.fromSession.length > 0) details.push(`from DSH session ${sent.fromSession}`)
+  else if (typeof sent.label === 'string' && sent.label.length > 0 && sent.job == null) details.push(`by ${sent.label}`)
+  if (Array.isArray(sent.messageIds) && sent.messageIds.length > 1) details.push(`${sent.messageIds.length} Telegram messages`)
+  if (sent.sticker !== undefined && sent.sticker !== null) details.push(`with sticker ${[sent.sticker.emoji, sent.sticker.setName === null || sent.sticker.setName === undefined ? undefined : `from set "${sent.sticker.setName}"`, `(${sent.sticker.id})`].filter(Boolean).join(' ')}`)
+  if (Array.isArray(sent.files) && sent.files.length > 0) details.push(`with ${sent.files.length === 1 ? 'file' : 'files'} ${sent.files.map((name) => `"${name}"`).join(', ')}`)
+  const bound = typeof sent.boundSession === 'string' ? sent.boundSession : undefined
+  if (bound !== undefined && sent.recorded === true && bound !== options.currentSession) details.push(`recorded in session ${bound}, not this one`)
+  else if (bound === undefined) details.push('the topic had no session then')
+  const head = `[The replied-to message was posted by the bot on behalf of another sender (${details.join('; ')}). Full text:]`
+  const body = typeof sent.text === 'string' && sent.text.trim().length > 0
+    ? quoteLines(sent.text, options.limit ?? SENT_TEXT_LIMIT) + (sent.textCut > 0 ? `\n> […${sent.textCut} more characters not kept]` : '')
+    : '> (no text)'
+  const sessions = [sent.fromSession, bound !== options.currentSession && sent.recorded === true ? bound : undefined]
+    .filter((id, index, all) => typeof id === 'string' && id.length > 0 && all.indexOf(id) === index)
+  const hint = sessions.length === 0 ? '' : `\n(For more context, open session ${sessions.join(' or ')}.)`
+  return `${head}\n${body}${hint}`
+}
+
+/** Forward origin of a message, including the fields older Bot API versions used. */
+function originOf(message) {
+  if (message?.forward_origin !== undefined && message.forward_origin !== null) return message.forward_origin
+  const date = message?.forward_date
+  if (message?.forward_from_chat !== undefined) {
+    return { type: message.forward_from_chat.type === 'channel' ? 'channel' : 'chat', chat: message.forward_from_chat, sender_chat: message.forward_from_chat, message_id: message.forward_from_message_id, author_signature: message.forward_signature, date }
+  }
+  if (message?.forward_from !== undefined) return { type: 'user', sender_user: message.forward_from, date }
+  if (typeof message?.forward_sender_name === 'string') return { type: 'hidden_user', sender_user_name: message.forward_sender_name, date }
+  return undefined
+}
+
+/** Who wrote a replied-to message, from the reader's point of view. */
+function describeSender(target, message, options) {
+  const from = target.from
+  if (from !== undefined && options.botId !== undefined && from.id === options.botId) {
+    const text = messageBody(target)
+    const mirrored = MIRROR_LABELS.find(([label]) => text.startsWith(label))
+    return mirrored === undefined ? 'the assistant (this bot)' : mirrored[1]
+  }
+  if (target.sender_chat !== undefined) return chatName(target.sender_chat)
+  if (from !== undefined && message?.from !== undefined && from.id === message.from.id) return 'the user (their own earlier message)'
+  if (from !== undefined) return personName(from)
+  return 'an unknown sender'
+}
+
+/** Name the origin of a forwarded message. */
+function describeOrigin(origin, message, options) {
+  const signature = typeof origin.author_signature === 'string' && origin.author_signature.length > 0 ? `, signed ${origin.author_signature}` : ''
+  if (origin.type === 'user') {
+    const user = origin.sender_user
+    if (user !== undefined && options.botId !== undefined && user.id === options.botId) return 'the assistant (this bot)'
+    if (user !== undefined && message?.from !== undefined && user.id === message.from.id) return 'the user themselves'
+    return user === undefined ? 'a user' : personName(user)
+  }
+  if (origin.type === 'hidden_user') return `${origin.sender_user_name ?? 'a user'} (account hidden)`
+  if (origin.type === 'channel') return `channel ${chatName(origin.chat)}${signature}`
+  if (origin.type === 'chat') return `${chatName(origin.sender_chat)}${signature}`
+  return 'an unknown source'
+}
+
+function personName(user) {
+  const name = [user.first_name, user.last_name].filter((part) => typeof part === 'string' && part.length > 0).join(' ')
+  const handle = typeof user.username === 'string' && user.username.length > 0 ? `@${user.username}` : ''
+  const label = name.length > 0 ? (handle.length > 0 ? `${name} (${handle})` : name) : (handle.length > 0 ? handle : 'a user')
+  return user.is_bot === true ? `${label}, a bot` : label
+}
+
+function chatName(chat) {
+  if (chat === undefined || chat === null) return 'a chat'
+  const title = typeof chat.title === 'string' && chat.title.length > 0
+    ? `"${chat.title}"`
+    : [chat.first_name, chat.last_name].filter(Boolean).join(' ')
+  const handle = typeof chat.username === 'string' && chat.username.length > 0 ? `@${chat.username}` : ''
+  if (title.length > 0) return handle.length > 0 ? `${title} (${handle})` : title
+  return handle.length > 0 ? handle : 'a chat'
+}
+
+/** Public link to a channel or supergroup message, when one exists. */
+function messageLink(chat, messageId) {
+  if (chat === undefined || chat === null || !Number.isSafeInteger(messageId)) return undefined
+  if (typeof chat.username === 'string' && chat.username.length > 0) return `https://t.me/${chat.username}/${messageId}`
+  const id = String(chat.id ?? '')
+  if (id.startsWith('-100')) return `https://t.me/c/${id.slice(4)}/${messageId}`
+  return undefined
+}
+
+/** Note the media a message carries and whether it was attached. */
+function mediaNote(message, fileOutcome) {
+  const kind = mediaKind(message)
+  if (kind === undefined) return undefined
+  if (downloadableFile(message) === undefined) return `contains ${kind}, not attached`
+  if (fileOutcome === 'attached') return `contains ${kind}, attached`
+  if (fileOutcome === 'too-large') return `contains ${kind}, too large to attach`
+  if (fileOutcome === 'failed') return `contains ${kind}, could not be downloaded`
+  return `contains ${kind}`
+}
+
+function mediaKind(message) {
+  if (message === undefined || message === null) return undefined
+  if (Array.isArray(message.photo) && message.photo.length > 0) return 'a photo'
+  if (message.document !== undefined && message.animation === undefined) {
+    return typeof message.document.file_name === 'string' ? `a file "${message.document.file_name}"` : 'a file'
+  }
+  if (message.video !== undefined) return 'a video'
+  if (message.animation !== undefined) return 'a GIF'
+  if (message.audio !== undefined) {
+    const title = [message.audio.performer, message.audio.title].filter(Boolean).join(' - ')
+    return title.length > 0 ? `audio "${title}"` : 'audio'
+  }
+  if (message.voice !== undefined) return 'a voice message'
+  if (message.video_note !== undefined) return 'a video message'
+  if (message.sticker !== undefined) {
+    const emoji = typeof message.sticker.emoji === 'string' ? ` ${message.sticker.emoji}` : ''
+    const set = typeof message.sticker.set_name === 'string' ? ` from set "${message.sticker.set_name}"` : ''
+    return `a sticker${emoji}${set}`
+  }
+  if (message.poll !== undefined) return `a poll "${message.poll.question ?? ''}"`
+  if (message.venue !== undefined) return `a venue "${message.venue.title ?? ''}"`
+  if (message.location !== undefined) return `a location (${message.location.latitude}, ${message.location.longitude})`
+  if (message.contact !== undefined) return `a contact (${[message.contact.first_name, message.contact.last_name].filter(Boolean).join(' ')})`
+  if (message.story !== undefined) return 'a story'
+  if (message.paid_media !== undefined) return 'paid media'
+  if (message.dice !== undefined) return `a dice roll ${message.dice.emoji ?? ''}`.trim()
+  if (message.checklist !== undefined) return 'a checklist'
+  if (message.game !== undefined) return 'a game'
+  if (message.invoice !== undefined) return 'an invoice'
+  return undefined
+}
+
+/** UTC date for a Telegram unix timestamp. */
+function formatDate(seconds) {
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds)) return 'at an unknown time'
+  return `${new Date(seconds * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC`
+}
+
+/** Quote text line by line, cut at a word boundary near the limit. */
+function quoteLines(text, limit) {
+  let shown = text.trim()
+  let note = ''
+  if (shown.length > limit) {
+    let cut = shown.lastIndexOf(' ', limit)
+    const newline = shown.lastIndexOf('\n', limit)
+    if (newline > cut) cut = newline
+    if (cut < limit * 0.8) cut = limit
+    note = `\n> […truncated, ${shown.length - cut} more characters]`
+    shown = shown.slice(0, cut).trimEnd()
+  }
+  return shown.split('\n').map((line) => `> ${line}`).join('\n') + note
+}

package/src/models.js

@@ -0,0 +1,257 @@
+/**
+ * Model selection for Telegram topics. The session's live agent owns its
+ * model (`agent.model.current()`); the bot keeps no copy of it. The picker
+ * reads the same catalog as the Web model picker
+ * (`sessionController.modelCatalog()`), so every configured provider and
+ * model shows up with its Web display name.
+ */
+import { createHash } from 'node:crypto'
+
+/** Rows of providers or models shown per picker page, sized for a phone. */
+export const MODEL_PAGE_SIZE = 8
+
+/** How long one catalog read is reused for labels and menus. */
+const CATALOG_TTL_MS = 60_000
+
+/**
+ * Short stable key for a provider or a provider/model pair, for callback data
+ * (Telegram allows 64 bytes, and provider/model ids can be longer).
+ * @param provider - provider id.
+ * @param model - model id, or undefined for the provider itself.
+ * @returns 12 hex characters.
+ */
+export function catalogKey(provider, model) {
+  return createHash('sha256').update(`${provider}\n${model ?? ''}`).digest('hex').slice(0, 12)
+}
+
+/**
+ * Copy a selection, dropping an absent effort.
+ * @param selection - provider, model and optional effort.
+ * @returns a detached selection.
+ */
+function toSelection({ provider, model, reasoningEffort }) {
+  return { provider, model, ...(reasoningEffort === undefined ? {} : { reasoningEffort }) }
+}
+
+/**
+ * Read a session's current model: the live agent's own choice, or, for a
+ * session that is not running, its recorded selection.
+ * @param ctx - Host context.
+ * @param sessionId - DSH session id.
+ * @returns the selection, or undefined when the session has none recorded.
+ */
+export async function sessionModelOf(ctx, sessionId) {
+  if (typeof sessionId !== 'string') return undefined
+  const agent = ctx.get('agents')?.get(sessionId)
+  if (typeof agent?.model?.current === 'function') {
+    const current = agent.model.current()
+    return current === undefined ? undefined : toSelection(current)
+  }
+  const query = ctx.get('sessionQuery')
+  if (typeof query?.observeSession !== 'function') return undefined
+  let observation
+  try {
+    observation = await query.observeSession(sessionId)
+    // The modelSelection projection's view: `next` is the pending choice or
+    // the route of the last request.
+    const view = observation?.projections?.values?.modelSelection
+    const recorded = view?.next ?? view?.pending ?? view?.lastUsed
+    return typeof recorded?.provider === 'string' && typeof recorded?.model === 'string' ? toSelection(recorded) : undefined
+  } catch {
+    return undefined
+  } finally {
+    observation?.[Symbol.dispose]?.()
+  }
+}
+
+/**
+ * Read the deployment default model (the one the Web UI saves).
+ * @param ctx - Host context.
+ * @returns the selection, or undefined without a default-model service.
+ */
+export function defaultModelOf(ctx) {
+  try {
+    const selection = ctx.get('agentDefaultModel')?.currentSelection()
+    if (typeof selection?.provider === 'string' && typeof selection?.model === 'string') return toSelection(selection)
+  } catch {
+    // No default configured.
+  }
+  return undefined
+}
+
+/** Failure codes that mean a route is gone from this host, not briefly down. */
+const GONE_ROUTE_CODES = new Set(['NO_ADAPTER', 'UNKNOWN_MODEL'])
+
+/**
+ * Move a session off a model route this host no longer has (a provider that
+ * was removed, a model dropped from its catalog) onto the default model, so
+ * a topic left on that route answers again instead of failing every turn
+ * with NO_ADAPTER. The switch is recorded on the session only, the way a job
+ * picks its model; the saved default stays as it is. Routes that resolve, or
+ * fail for any other reason, are left alone.
+ * @param ctx - Host context (`llm`, `agentDefaultModel`).
+ * @param agent - the session's live agent.
+ * @returns the dead route and the default it moved to, or undefined.
+ */
+export async function healGoneRoute(ctx, agent) {
+  const current = agent?.model?.current?.()
+  const llm = ctx.get('llm')
+  if (current === undefined || typeof llm?.resolveCallConfig !== 'function') return undefined
+  try {
+    await llm.resolveCallConfig(toSelection(current))
+    return undefined
+  } catch (error) {
+    if (!GONE_ROUTE_CODES.has(error?.code)) return undefined
+  }
+  const fallback = defaultModelOf(ctx)
+  if (fallback === undefined || (fallback.provider === current.provider && fallback.model === current.model)) return undefined
+  agent.model.select(fallback)
+  return { from: toSelection(current), to: fallback }
+}
+
+/**
+ * Whether two selections name the same provider, model and effort.
+ * @param left - first selection.
+ * @param right - second selection.
+ * @returns true when they agree.
+ */
+export function sameSelection(left, right) {
+  return left?.provider === right?.provider && left?.model === right?.model && left?.reasoningEffort === right?.reasoningEffort
+}
+
+/**
+ * Cached reader for the Web model catalog.
+ * @param ctx - Host context.
+ * @returns `load()` resolving the catalog, or undefined when it is unavailable.
+ */
+export function createModelCatalog(ctx) {
+  let cached
+  let loadedAt = 0
+  let pending
+  return {
+    /**
+     * @param fresh - skip the short-lived cache (used before applying a pick).
+     * @returns `{ groups, failures }` as the Web picker gets it, or undefined.
+     */
+    async load(fresh = false) {
+      if (!fresh && cached !== undefined && Date.now() - loadedAt < CATALOG_TTL_MS) return cached
+      pending ??= (async () => {
+        const controller = ctx.get('sessionController')
+        if (typeof controller?.modelCatalog !== 'function') return undefined
+        const catalog = await controller.modelCatalog()
+        cached = { groups: Array.isArray(catalog?.groups) ? catalog.groups : [], failures: Array.isArray(catalog?.failures) ? catalog.failures : [] }
+        loadedAt = Date.now()
+        return cached
+      })().finally(() => { pending = undefined })
+      try {
+        return await pending
+      } catch {
+        return cached
+      }
+    },
+  }
+}
+
+/**
+ * Find a catalog entry for a selection.
+ * @param catalog - loaded catalog.
+ * @param selection - provider and model.
+ * @returns `{ group, model }`, or undefined.
+ */
+export function findModel(catalog, selection) {
+  const group = catalog?.groups.find((entry) => entry.id === selection?.provider)
+  const model = group?.models.find((entry) => entry.id === selection?.model)
+  return model === undefined ? undefined : { group, model }
+}
+
+/**
+ * Resolve a provider callback key.
+ * @param catalog - loaded catalog.
+ * @param key - `catalogKey(provider)`.
+ * @returns the provider group, or undefined.
+ */
+export function providerByKey(catalog, key) {
+  return catalog?.groups.find((group) => catalogKey(group.id) === key)
+}
+
+/**
+ * Resolve a model callback key.
+ * @param catalog - loaded catalog.
+ * @param key - `catalogKey(provider, model)`.
+ * @returns `{ group, model }`, or undefined.
+ */
+export function modelByKey(catalog, key) {
+  for (const group of catalog?.groups ?? []) {
+    const model = group.models.find((entry) => catalogKey(group.id, entry.id) === key)
+    if (model !== undefined) return { group, model }
+  }
+  return undefined
+}
+
+/**
+ * Display name of a selection's model, as the Web picker shows it.
+ * @param catalog - loaded catalog, or undefined.
+ * @param selection - provider and model.
+ * @returns the name, or the raw model id.
+ */
+export function modelName(catalog, selection) {
+  if (selection === undefined) return '?'
+  return findModel(catalog, selection)?.model.name ?? selection.model
+}
+
+/**
+ * Effort choices for one catalog model, the same list the Web picker builds:
+ * a provider-default entry when the model has no default effort, then its
+ * efforts. A model without reasoning has none.
+ * @param model - catalog model entry.
+ * @param defaultLabel - label for the provider default.
+ * @returns `{ id, name }` entries; `id` undefined means the provider default.
+ */
+export function effortChoices(model, defaultLabel) {
+  const reasoning = model?.reasoning
+  if (reasoning === undefined) return []
+  return [
+    ...(reasoning.defaultEffort === undefined ? [{ id: undefined, name: defaultLabel }] : []),
+    ...reasoning.efforts.map((effort) => ({ id: effort.id, name: effort.name })),
+  ]
+}
+
+/**
+ * Display name of a selection's effective effort.
+ * @param catalog - loaded catalog, or undefined.
+ * @param selection - current selection.
+ * @param defaultLabel - label for the provider default.
+ * @returns the name.
+ */
+export function effortName(catalog, selection, defaultLabel) {
+  const reasoning = findModel(catalog, selection)?.model.reasoning
+  const effective = selection?.reasoningEffort ?? reasoning?.defaultEffort
+  if (effective === undefined) return defaultLabel
+  return reasoning?.efforts.find((effort) => effort.id === effective)?.name ?? effective
+}
+
+/**
+ * The selection a model pick makes, by the Web picker's rule: the same model
+ * keeps its effort, another model starts at its default effort.
+ * @param current - the session's current selection.
+ * @param provider - picked provider id.
+ * @param model - picked catalog model entry.
+ * @returns the selection to apply.
+ */
+export function pickedSelection(current, provider, model) {
+  const same = current?.provider === provider && current?.model === model.id
+  const reasoningEffort = same ? current.reasoningEffort ?? model.reasoning?.defaultEffort : model.reasoning?.defaultEffort
+  return toSelection({ provider, model: model.id, reasoningEffort })
+}
+
+/**
+ * Cut one page out of a list.
+ * @param items - all entries.
+ * @param page - requested page, clamped to the valid range.
+ * @returns the page's items, its index and the page count.
+ */
+export function pageOf(items, page) {
+  const pages = Math.max(1, Math.ceil(items.length / MODEL_PAGE_SIZE))
+  const index = Math.min(Math.max(0, Number.isSafeInteger(page) ? page : 0), pages - 1)
+  return { items: items.slice(index * MODEL_PAGE_SIZE, (index + 1) * MODEL_PAGE_SIZE), page: index, pages }
+}