Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

31.2 KB
Raw Blame
/** A person, or any agent of the project but a Buddy, tags people in a message; each tag waits in the person's Swarm-wide list
 *  until they reply in that conversation or mark it done. Tags live in SuperTabMention, never in the tab state, so an older backend still
 *  reads and writes a tab that has them. Called inside SuperTabStore's transactions. */
import { createHash } from 'node:crypto'
import type { Prisma, PrismaClient } from '@prisma/client'
import { ensureIndex } from '../lib/db/indexes.js'
import { activeWork, agentOnly, fail, isLeads, person, stableId, type Actor, type Conversation, type MessageDraft, type SuperTabState } from './model.js'
import { canReadGroup, canReadProject, groupProject, projectAgent, projectOf, projectsOf } from './projects.js'
import { isBuddyChat, isSwarmBuddyChat } from './buddies.js'
import { groupsBy, readBy } from './parts/indexed.js'
import { deliveredCopies } from './pageReads.js'
import { shownNameOf } from './personNames.js'
import { usernameOf } from './usernames.js'

type Tx = Prisma.TransactionClient
export const MAX_MENTIONS = 5
/** A tag drops off the list this long after it was made: refused on read, and removed by a TTL index. */
export const MENTION_EXPIRY_MS = 30 * 24 * 60 * 60_000
/** A Lead's tag about a task with no worker (message.send mentionsIfNoWorker) is listed only after this long, and only if the
 *  group still has no worker and the Lead has done nothing for it since: the Lead sees a failed start first and usually
 *  restarts the task within minutes, so a person tagged at once got a notice they could do nothing about (Dee, 2026-10-29). */
export const NO_WORKER_GRACE_MS = 20 * 60_000
/** The mention `mention.done` names, read from this tab by the store. */
export interface MentionTarget { id: string; personId: string; conversationId: string }
/** Mongo omits unset fields, so `resolvedAt: null` alone would miss a row written without it. */
const waiting: Prisma.SuperTabMentionWhereInput = { OR: [{ resolvedAt: null }, { resolvedAt: { isSet: false } }] }

/** Run by the singleton worker at startup, like the terminal answer expiry. */
export async function ensureMentionExpiry(db: PrismaClient): Promise<void> {
  await ensureIndex(db, 'SuperTabMention', { key: { createdAt: 1 }, name: 'mention_expiry', expireAfterSeconds: MENTION_EXPIRY_MS / 1000 })
}

/** `@name` or `@name@domain`, as people tag in chat. Never right after a letter, digit, `@` or `/` (an address, a path, a
 *  link), and a name never ends in a dot: `@dee.` closes a sentence. Desktop (message_text.dart) and the phone
 *  (swarm_message_row.dart) use this same pattern; tagFixture.json is the table all three pass. */
const TAG = /(?<![\w@/])@([\w+-]+(?:\.[\w+-]+)*)(@[\w-]+(?:\.[\w-]+)+)?/g
const FENCE = /^ {0,3}(`{3,}|~{3,})/
const blank = (part: string) => part.replace(/[^\n]/g, ' ')

/** [text] with what is never a tag blanked out, as Markdown renders it: fenced and indented code, code spans, bare links and
 *  link destinations. */
function prose(text: string): string {
  const lines = text.split('\n')
  let fence: string | null = null
  let indented = false
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i]!
    if (fence) {
      const close = FENCE.exec(line)
      if (close && close[1]![0] === fence[0] && close[1]!.length >= fence.length && !line.slice(close[0].length).trim()) fence = null
      lines[i] = blank(line)
      continue
    }
    const open = FENCE.exec(line)
    if (open && !(open[1]![0] === '`' && line.slice(open[0].length).includes('`'))) {
      fence = open[1]!
      lines[i] = blank(line)
      indented = false
      continue
    }
    // Indented code starts after a blank line (or the first line) and runs while its lines stay indented.
    const startsCode: boolean = /^( {4}|\t)/.test(line) && line.trim() !== '' && (indented || i === 0 || !lines[i - 1]!.trim())
    indented = startsCode || (indented && !line.trim())
    if (startsCode) lines[i] = blank(line)
  }
  return lines.join('\n')
    .replace(/(?<!`)(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/g, blank)
    .replace(/\]\([^)\]]*\)/g, blank)
    .replace(/\b(?:https?:\/\/|www\.)\S+/gi, blank)
}

/** The tags [text] holds, in order: each name as written after its `@`, lowercased, a full address with its domain. */
export function tagTokens(text: string): string[] {
  return [...prose(text).matchAll(TAG)].map(match => `${match[1]}${match[2] ?? ''}`.toLowerCase())
}

/** The people [text] names, in order, once each: `@username` in any case, or `@` and their full address. [names] is the
 *  Swarm's usernames by person (usernames.ts swarmUsernames). */
export function namedIn(state: SuperTabState, text: string, names: ReadonlyMap<string, string>): string[] {
  const tokens = tagTokens(text)
  if (!tokens.length) return []
  const byName = new Map([...names].map(([id, name]) => [name.toLowerCase(), id]))
  const ids = tokens.flatMap(token => {
    const id = token.includes('@') ? state.people.find(p => p.email.toLowerCase() === token)?.id : byName.get(token)
    return id && state.people.some(p => p.id === id) ? [id] : []
  })
  return [...new Set(ids)]
}

/** The agents of [group] that [text] names by `@Name` (task #2963): its display name or name in any case, matched only when
 *  exactly one agent there goes by it and no person's username is the same, so a person's tag stays a tag. [names] is the
 *  Swarm's usernames by person (usernames.ts swarmUsernames). A Buddy chat names no one this way: its sessions hear their own
 *  threads alone (buddySessions.ts). */
export function agentsNamedIn(state: SuperTabState, group: Conversation, text: string, names: ReadonlyMap<string, string>): string[] {
  if (isBuddyChat(group)) return []
  const people = new Set([...names.values()].map(name => name.toLowerCase()))
  const tokens = tagTokens(text).filter(token => !token.includes('@') && !people.has(token))
  if (!tokens.length) return []
  const members = state.agents.filter(a => group.agentIds.includes(a.id))
  return [...new Set(tokens.flatMap(token => {
    const matches = members.filter(a => a.displayName?.toLowerCase() === token || a.name.toLowerCase() === token)
    return matches.length === 1 ? [matches[0]!.id] : []
  }))]
}

/** Whether [text] says `@` and exactly [name] outside code and links, in any case: a stored name that ends in a dot, chosen
 *  before such names were refused, reads as a shorter tag in [namedIn] but is still said. */
export function saysName(text: string, name: string): boolean {
  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
  return new RegExp(`(?<![\\w@/])@${escaped}(?![\\w+-]|\\.[\\w+-])`, 'i').test(prose(text))
}

/** [tags] on the first line of [text], as a person types them in chat. Only text that opens with a block (a list, heading,
 *  quote, table, code, divider or link definition) keeps them on a line of their own, so that block still renders. The same
 *  rule as Desktop's SuperTabMessageText.withTags, which shows an older message's unsaid tags. */
export function withTags(tags: string[], text: string): string {
  if (!tags.length) return text
  const body = text.replace(/^(?:[ \t]*\n)+/, '')
  if (!body) return tags.join(' ')
  return OPENS_BLOCK.test(body) ? `${tags.join(' ')}\n\n${body}` : `${tags.join(' ')} ${body}`
}
const OPENS_BLOCK = new RegExp('^(?: {4}|\\t| {0,3}(?:[-*+](?:[ \\t\\n]|$)|#{1,6}(?:[ \\t\\n]|$)|>'
  + '|\\d{1,9}[.)](?:[ \\t\\n]|$)|```|~~~|\\||\\[[^\\]\\n]+\\]:'
  + '|(?:(?:\\*[ \\t]*){3,}|(?:-[ \\t]*){3,}|(?:_[ \\t]*){3,})(?:\\n|$)))')

/** Whether [actor] may tag people in [group]: a person who can post there; any agent of the project but a Buddy, in its own
 *  project's conversations (project instructions, phase 4); nobody in the Leads conversation. */
function mayTag(state: SuperTabState, actor: Actor, group: Conversation): boolean {
  // Nobody else reads a person's one Buddy chat, so nobody is tagged there (Dee, 10-31).
  if (isLeads(group) || isSwarmBuddyChat(group)) return false
  return actor.kind !== 'agent' || projectAgent(state, actor, groupProject(state, group).id)
}

/** The people [named] by a post's text whom it tags: only when [actor] may tag here, only people who can read [group], never
 *  the author. Anyone else stays plain text: a name in a sentence is never an error. */
export function textTags(state: SuperTabState, actor: Actor, group: Conversation, named: string[]): string[] {
  if (!mayTag(state, actor, group)) return []
  return named.filter(id => (actor.kind !== 'person' || id !== actor.userId) && state.people.some(p => p.id === id
    && canReadGroup(state, { kind: 'person', userId: p.id, email: p.email }, group)))
}

/** A person who can post here tags people; so does any agent of the project but a Buddy, in that project's conversations.
 *  Never in the Leads conversation, and only people who can read the conversation. A person's tag of themselves is dropped. */
export function checkMentions(state: SuperTabState, actor: Actor, group: Conversation, personIds: string[]): string[] {
  const ids = [...new Set(personIds)].filter(id => actor.kind !== 'person' || id !== actor.userId)
  if (!ids.length) return ids
  if (isLeads(group)) fail('INVALID_MENTION', 'Nobody is tagged in the Leads conversation.', 400)
  if (isSwarmBuddyChat(group)) fail('INVALID_MENTION', 'Nobody else reads your Buddy chat.', 400)
  if (actor.kind === 'agent' && !projectAgent(state, actor, groupProject(state, group).id)) {
    fail('FORBIDDEN', 'Only a person or an agent of this project tags people here.', 403)
  }
  for (const id of ids) {
    const member = state.people.find(p => p.id === id) ?? fail('INVALID_MENTION', 'Tag a person in this Swarm.', 400)
    if (!canReadGroup(state, { kind: 'person', userId: member.id, email: member.email }, group)) {
      fail('INVALID_MENTION', `${usernameOf(state, member.id)} cannot read this conversation.`, 400)
    }
  }
  return ids
}

/** Writes the tags `messages` carry, and answers the rows it wrote (push/notices.ts tells their phones). */
export async function writeMentions(tx: Tx, tabId: string, state: SuperTabState, messages: MessageDraft[], now: number): Promise<MentionRow[]> {
  const data = messages.flatMap(message => (message.mentions ?? []).map(personId => ({
    id: stableId(tabId, message.id, personId), tabId, personId, projectId: state.conversations.find(c => c.id === message.conversationId)!.projectId ?? 'lead',
    conversationId: message.conversationId, messageId: message.id, authorAgentId: message.author.id,
    createdAt: new Date(now), resolvedAt: null, resolvedBy: null, ...(message.holdMentions ? { holdUntil: new Date(now + NO_WORKER_GRACE_MS) } : {}),
  })))
  if (data.length) await tx.superTabMention.createMany({ data })
  await bringBackUnfollowed(tx, tabId, messages, now)
  return data
}
type MentionRow = { id: string; personId: string; conversationId: string; messageId: string; holdUntil?: Date }

/** Who tagged, as the inbox and a phone notice name them: a person by the name the Swarm shows for them (a person's name in a
 *  message is their email, personNames.ts), an agent by its own. */
export function taggerName(state: SuperTabState, author: { kind?: string; id?: string; name?: string; displayName?: string } | undefined): string {
  return author?.kind === 'person' ? shownNameOf(state, author.id ?? '') ?? 'Someone' : author?.displayName ?? author?.name ?? 'Lead'
}

/** A tag in a thread reply puts the thread back on the tagged person's Threads page, as in Slack: their Unfollow of it is cleared
 *  (follow back to no choice; updatedAt moves so their other devices read the change), in the write of the tag. A reply that tags
 *  nobody leaves an Unfollow as it is, and a send that tags nobody in a thread sends no command. At most MAX_MENTIONS ids a message,
 *  in one raw update by `_id`, which Prisma would send as $expr (hotFilters.test.ts). */
async function bringBackUnfollowed(tx: Tx, tabId: string, messages: MessageDraft[], now: number): Promise<void> {
  const ids = [...new Set(messages.flatMap(message => message.thread && message.thread !== message.id ? (message.mentions ?? []).map(personId =>
    stableId(tabId, message.conversationId, message.thread!, personId)) : []))]
  if (!ids.length) return
  const answer = await tx.$runCommandRaw({ update: 'SuperTabThreadMark', updates: [{ q: { _id: { $in: ids }, tabId, follow: false },
    u: { $set: { follow: null, updatedAt: { $date: new Date(now).toISOString() } } }, multi: true }] }) as { writeErrors?: unknown[] }
  if (answer.writeErrors?.length) throw new Error('The database refused some thread follows')
}

/** A stuck line fixed, or its task ended (stuck.ts, task #3915): its tags still waiting resolve as `fixed`. One update per person
 *  on the `[tabId, conversationId, personId]` index, at most MAX_MENTIONS a line. */
export async function resolveTags(tx: Tx, tabId: string, lines: ReadonlyArray<{ conversationId: string; messageId: string; personIds: readonly string[] }>,
  now: number): Promise<void> {
  for (const line of lines) {
    for (const personId of line.personIds) {
      await tx.superTabMention.updateMany({ where: { tabId, conversationId: line.conversationId, personId, messageId: line.messageId, ...waiting },
        data: { resolvedAt: new Date(now), resolvedBy: 'fixed' } })
    }
  }
}

/** Any post by the tagged person in that conversation answers every earlier tag there, in a thread or not. */
export async function resolveByReply(tx: Tx, tabId: string, conversationId: string, personId: string, now: number): Promise<void> {
  await tx.superTabMention.updateMany({ where: { tabId, conversationId, personId, createdAt: { lte: new Date(now) }, ...waiting },
    data: { resolvedAt: new Date(now), resolvedBy: 'reply' } })
}

/** A read mark moved to [sequence] resolves the person's waiting tags it passes: in the chat (threadId null) those shown there, in a
 *  thread those shown only in it (threadsOf, as Desktop's mentionUnread reads them). Most marks find no tag and stop after one read.
 *  A held tag (holdUntil) resolved before its time is never listed, as in resolveByReply (intended). */
export async function resolveRead(db: Tx | PrismaClient, input: { tabId: string; personId: string; conversationId: string; threadId: string | null;
  sequence: number; now: number }): Promise<number> {
  const { tabId, personId, conversationId, threadId, sequence, now } = input, tx = db as Tx
  const rows = await tx.superTabMention.findMany({ where: { tabId, personId, conversationId, createdAt: { gt: new Date(now - MENTION_EXPIRY_MS) }, ...waiting },
    select: { id: true, messageId: true }, orderBy: { createdAt: 'desc' }, take: 500 })
  if (!rows.length) return 0
  // By id through its index (parts/indexed.ts), never a Prisma `in` on a hot collection (hotFilters.test.ts).
  const messages = (await readBy(tx, 'SuperTabMessage', 'id', [{ $match: { _id: { $in: [...new Set(rows.map(r => r.messageId))] }, tabId,
    sequence: { $lte: sequence } } }, { $project: { conversationId: 1, thread: 1, alsoInChat: 1 } }]))
    .map(m => ({ id: m._id as string, conversationId: m.conversationId as string, thread: (m.thread as string | undefined) ?? null,
      alsoInChat: (m.alsoInChat as boolean | undefined) ?? null }))
  const threads = await threadsOf(tx, tabId, messages)
  const passed = new Set(messages.filter(m => (threads.get(m.id) ?? null) === threadId).map(m => m.id))
  return resolveIds(tx, tabId, personId, rows.filter(r => passed.has(r.messageId)).map(r => r.id), 'read', now)
}

/** Resolves these waiting tags of the person in one write, by their ids (at most the 500 a read takes): raw, since Prisma sends
 *  an `in` on this hot collection as $expr (hotFilters.test.ts). `resolvedAt: null` matches an unset one too. Answers how many. */
async function resolveIds(tx: Tx, tabId: string, personId: string, ids: string[], by: 'read' | 'answer', now: number): Promise<number> {
  if (!ids.length) return 0
  const answer = await tx.$runCommandRaw({ update: 'SuperTabMention', updates: [{ q: { _id: { $in: ids }, tabId, personId, resolvedAt: null },
    u: { $set: { resolvedAt: { $date: new Date(now).toISOString() }, resolvedBy: by } }, multi: true }] }) as { nModified?: number; writeErrors?: unknown[] }
  if (answer.writeErrors?.length) throw new Error('The database refused some tag resolves')
  return answer.nModified ?? 0
}

/** The agents a person's post answers: its recipients, and in their own Buddy chat also the coordinator of each project the Buddy
 *  relays to (every project they read for the Swarm chat, the chat's own for a project chat). */
export function answeredAgents(state: SuperTabState, actor: Extract<Actor, { kind: 'person' }>, group: Conversation, recipients: readonly string[]): string[] {
  const coordinators = !isBuddyChat(group) || !group.audience?.people.some(p => p.id === actor.userId) ? []
    : (isSwarmBuddyChat(group) ? projectsOf(state).filter(p => canReadProject(state, actor, p)) : [projectOf(state, group.projectId ?? 'lead')])
      .map(p => state.conversations.find(c => c.id === p.leadConversationId)?.leadId)
  return [...new Set([...recipients.filter(id => state.agents.some(a => a.id === id)), ...coordinators.filter((id): id is string => !!id)])]
}

/** A post to an agent answers every tag that agent made for the person, in any conversation. A held tag (holdUntil) resolved
 *  before its time is never listed, as in resolveByReply (intended). The agent that made a tag is in no index: the person's
 *  waiting tags are read once by theirs, as resolveRead reads them, and the agents' resolved in one write. */
export async function resolveByAnswer(tx: Tx, tabId: string, personId: string, agentIds: readonly string[], now: number): Promise<void> {
  if (!agentIds.length) return
  const answered = new Set(agentIds)
  const rows = await tx.superTabMention.findMany({ where: { tabId, personId, createdAt: { gt: new Date(now - MENTION_EXPIRY_MS), lte: new Date(now) }, ...waiting },
    select: { id: true, authorAgentId: true }, orderBy: { createdAt: 'desc' }, take: 500 })
  await resolveIds(tx, tabId, personId, rows.filter(row => answered.has(row.authorAgentId)).map(row => row.id), 'answer', now)
}

/** A worker took the group: its held tags are over. A listed one moves to Earlier; one not yet listed is dropped, as if never
 *  made. Run before [dropHeldTags] of the same command, which would drop the listed ones too. */
export async function resolveWhenWorked(tx: Tx, tabId: string, conversationId: string, now: number): Promise<void> {
  const held = { tabId, conversationId, holdUntil: { isSet: true as const }, ...waiting }
  await tx.superTabMention.updateMany({ where: { ...held, holdUntil: { lte: new Date(now) } }, data: { resolvedAt: new Date(now), resolvedBy: 'worker' } })
  await tx.superTabMention.deleteMany({ where: held })
}

/** The task was handled (leadAction in the state: any agent's route, start or assignment there, or its coordinator's post): the
 *  held tags made before that are dropped for good, listed or not.
 *  Dropped, not resolved, so a later reply or assignment cannot bring one back in Earlier. */
export async function dropHeldTags(tx: Tx, tabId: string, conversationId: string, now: number): Promise<void> {
  await tx.superTabMention.deleteMany({ where: { tabId, conversationId, holdUntil: { isSet: true }, createdAt: { lt: new Date(now) }, ...waiting } })
}

/** Whether a tag is listed: a held one only once its time has come, while its group still has no worker; one answered before
 *  it came up was never listed. */
function listed(row: { resolvedAt: Date | null; holdUntil?: Date | null }, group: Conversation, now: number): boolean {
  if (!row.holdUntil) return true
  if (row.resolvedAt) return row.resolvedAt >= row.holdUntil
  return now >= row.holdUntil.getTime() && !group.archived && !activeWork(group)
}

/** The tags a person's post in this conversation is about to answer (resolveByReply), for the leaderboard's credit
 *  (leaderboard/record.ts recordPost): only which message and when. */
export async function openTags(tx: Tx, tabId: string, conversationId: string, personId: string, now: number): Promise<Array<{ messageId: string; createdAt: number }>> {
  const rows = await tx.superTabMention.findMany({ where: { tabId, conversationId, personId, createdAt: { gt: new Date(now - MENTION_EXPIRY_MS), lte: new Date(now) },
    ...waiting }, select: { messageId: true, createdAt: true } })
  return rows.map(row => ({ messageId: row.messageId, createdAt: row.createdAt.getTime() }))
}

export async function readMention(tx: Tx, tabId: string, id: string): Promise<MentionTarget | undefined> {
  return await tx.superTabMention.findFirst({ where: { id, tabId }, select: { id: true, personId: true, conversationId: true } }) ?? undefined
}

/** Marking an answered tag done again keeps how it was answered. */
export async function markDone(tx: Tx, tabId: string, id: string, personId: string, now: number): Promise<void> {
  await tx.superTabMention.updateMany({ where: { id, tabId, personId, ...waiting }, data: { resolvedAt: new Date(now), resolvedBy: 'done' } })
}

/** A person's unexpired tags in a Swarm, waiting or answered, newest first: the rows [readable] lists and counts. */
const tagRows = (tabId: string, personId: string, now: number, open: boolean | null) => ({
  where: { tabId, personId, createdAt: { gt: new Date(now - MENTION_EXPIRY_MS) }, ...(open === null ? {} : open ? waiting : { resolvedAt: { not: null } }) },
  orderBy: { createdAt: 'desc' as const }, take: 500,
})

/** The fields a changes poll needs both to hold tagged conversations and derive its mention badge from the same read. */
export type WaitingTagRow = { id: string; projectId: string; conversationId: string; messageId: string; authorAgentId: string; createdAt: Date;
  resolvedAt: Date | null; resolvedBy: string | null; holdUntil: Date | null }
export async function waitingTagRows(tx: Tx, tabId: string, personId: string, now: number): Promise<WaitingTagRow[]> {
  return await tx.superTabMention.findMany({ ...tagRows(tabId, personId, now, true),
    select: { id: true, projectId: true, conversationId: true, messageId: true, authorAgentId: true, createdAt: true, resolvedAt: true, resolvedBy: true,
      holdUntil: true } })
}

/** The conversations of a person's waiting tags, newest tag first, once each: those [waitingMentions] may read beyond what a
 *  read holds, so a change poll can hold them per conversation (read/service.ts). */
export async function waitingTagConversations(tx: Tx, tabId: string, personId: string, now: number): Promise<string[]> {
  const rows = await tx.superTabMention.findMany({ ...tagRows(tabId, personId, now, true), select: { conversationId: true } })
  return [...new Set(rows.map(row => row.conversationId))]
}

/** The person's own unexpired tags in conversations they can still read, newest first, each with its conversation. The badge
 *  counts this same list. Ordinary loads leave quiet (dormant) conversations out of the state, so the ones a tag is in are
 *  read here: the count and the list check the same conversations whichever state they get.
 *  ponytail: capped at 500 per state; page it if a person ever gets more in 30 days. */
async function readable(tx: Tx, tabId: string, state: SuperTabState, actor: Extract<Actor, { kind: 'person' }>, now: number, open: boolean | null,
  waitingRows?: WaitingTagRow[]) {
  person(state, actor.userId)
  const rows = open && waitingRows ? waitingRows : await tx.superTabMention.findMany(tagRows(tabId, actor.userId, now, open))
  const groups = new Map(state.conversations.map(c => [c.id, c]))
  const missing = [...new Set(rows.map(r => r.conversationId))].filter(id => !groups.has(id))
  if (missing.length) {
    // By id through its index (parts/indexed.ts): every person's read counts these on each poll.
    for (const row of await groupsBy(tx, 'key', [{ $match: { tabId, deleted: false, key: { $in: missing } } }, { $project: { _id: 0, key: 1,
      data: { title: 1, kind: 1, projectId: 1, audience: 1, archived: 1, assignment: { status: 1 } } } }])) {
      groups.set(row.key as string, row.data as unknown as Conversation)
    }
  }
  return rows.flatMap(row => {
    const group = groups.get(row.conversationId)
    return group && !isLeads(group) && canReadGroup(state, actor, group) && listed(row, group, now) ? [{ row, group }] : []
  })
}

export async function mentionsWaiting(tx: Tx, tabId: string, state: SuperTabState, actor: Extract<Actor, { kind: 'person' }>, now: number): Promise<number> {
  return (await waitingMentions(tx, tabId, state, actor, now)).count
}

/** A person's waiting tags: how many, and a digest of which, as decisions.ts decisionsWaiting. A client reads its lists again
 *  when either moves (a tag made, answered or expired, though the count may stay), not on every change of the Swarm. Only
 *  the person's own tags they can still read go into it, and only their ids. */
export async function waitingMentions(tx: Tx, tabId: string, state: SuperTabState, actor: Extract<Actor, { kind: 'person' }>,
  now: number, waitingRows?: WaitingTagRow[]): Promise<{ count: number; digest: string }> {
  const ids = (await readable(tx, tabId, state, actor, now, true, waitingRows)).map(({ row }) => row.id).sort()
  return { count: ids.length, digest: mentionsDigest(ids) }
}

/** Which of these Swarms hold a waiting tag for the person, by one plain match (the index on tabId, personId, createdAt
 *  bounds it; Prisma would send `in` as an $expr that no index can). Raw, so a Swarm list counts a page of Swarms at once. */
export const swarmsWithTags = (tabIds: string[], personId: string, now: number) => [{ $match: { tabId: { $in: tabIds }, personId, resolvedAt: null,
  createdAt: { $gt: { $date: new Date(now - MENTION_EXPIRY_MS).toISOString() } } } }, { $group: { _id: '$tabId' } }]

/** The digest of a sorted list of waiting tag ids; a Swarm with none has this one. */
export function mentionsDigest(ids: string[]): string {
  return createHash('sha256').update(ids.join('\n')).digest('base64url').slice(0, 16)
}

export async function listMentions(tx: Tx, tabId: string, state: SuperTabState, actor: Extract<Actor, { kind: 'person' }>, now: number, open: boolean) {
  const tagged = await readable(tx, tabId, state, actor, now, open)
  // By id with a plain `$in` (parts/indexed.ts readBy): Prisma's `id: { in }` goes as an `$expr` OR of one branch per id, which
  // planned slowly (1,640 ms on prod, Ken's scan of 2026-11-04, task #2674).
  const messages = tagged.length ? (await readBy(tx, 'SuperTabMessage', 'id', [{ $match: { _id: { $in: [...new Set(tagged.map(t => t.row.messageId))] }, tabId } },
    { $project: { text: 1, author: 1, conversationId: 1, thread: 1, alsoInChat: 1, sequence: 1 } }])).map(r => ({ id: r._id as string,
    text: r.text as string, author: r.author, conversationId: r.conversationId as string, thread: (r.thread as string | undefined) ?? null,
    alsoInChat: (r.alsoInChat as boolean | undefined) ?? null, sequence: r.sequence as number })) : []
  const threads = await threadsOf(tx, tabId, messages)
  return tagged.map(({ row, group }) => {
    const message = messages.find(m => m.id === row.messageId)
    const author = message?.author as { kind?: string; name?: string; displayName?: string } | undefined
    const authorName = taggerName(state, author && { ...author, id: row.authorAgentId })
    return { id: row.id, projectId: row.projectId, projectName: projectOf(state, group.projectId ?? 'lead').name,
      conversationId: row.conversationId, conversationTitle: group.title, messageId: row.messageId,
      leadId: row.authorAgentId, leadName: authorName, leadKind: author?.kind ?? null, text: (message?.text ?? '').slice(0, 200),
      createdAt: row.createdAt, resolvedAt: row.resolvedAt, resolvedBy: row.resolvedBy, threadId: message ? threads.get(message.id) ?? null : null,
      // Where the tagged message is in its chat: Desktop clears its red number once the reader has read past it (Slack).
      messageSequence: message?.sequence ?? null }
  })
}

/** A thread a person's own tag is in: the tagged message's thread (a reply's root, or a root itself), in the tag's conversation. */
export interface TaggedThread { conversationId: string; threadId: string; at: number }

/** The threads the person's own unexpired tags are in, waiting or answered, newest tag first, once each, at most `limit` of those
 *  `keep` accepts (the caller's own filters apply before the count, so threads it drops never use up the limit) (the
 *  Threads list, read/followedThreads.ts: a tag in a chat they never opened has no thread mark, so no other read finds it). Only
 *  tags [readable] lists: conversations they can read, never a held Lead notice before its time. A message is taken only in the
 *  conversation its tag names, and only its thread id leaves here, so a tag never names a thread of another chat. Its root
 *  and replies are read and checked by the caller. The tags by one indexed read of at most 500 rows (tagRows), their messages by id
 *  in one more. */
export async function taggedThreads(tx: Tx, tabId: string, state: SuperTabState, actor: Extract<Actor, { kind: 'person' }>, now: number,
  limit: number, keep: (thread: TaggedThread) => boolean = () => true): Promise<TaggedThread[]> {
  const tagged = await readable(tx, tabId, state, actor, now, null)
  if (!tagged.length) return []
  const found = await readBy(tx, 'SuperTabMessage', 'id', [{ $match: { _id: { $in: [...new Set(tagged.map(t => t.row.messageId))] }, tabId } },
    { $project: { conversationId: 1, thread: 1 } }])
  const messages = new Map(found.map(r => [r._id as string, r]))
  const seen = new Set<string>()
  const threads: TaggedThread[] = []
  for (const { row } of tagged) {
    const message = messages.get(row.messageId)
    const threadId = typeof message?.thread === 'string' ? message.thread : null
    if (!threadId || message!.conversationId !== row.conversationId) continue
    const key = `${row.conversationId}\u0000${threadId}`
    if (seen.has(key)) continue
    seen.add(key)
    const thread = { conversationId: row.conversationId, threadId, at: row.createdAt.getTime() }
    if (!keep(thread)) continue
    threads.push(thread)
    if (threads.length >= limit) break
  }
  return threads
}

/** For each tagged message that is a thread reply only (not also sent to the chat), its thread's root: the tag belongs to the
 *  thread, not the chat's main stream (Desktop counts it on Threads, as Slack does). Only a root the person may read, in the
 *  tag's own conversation, roots its own thread: an agent-only or delivered-copy root reads as none, so the tag counts as the
 *  chat's and no root id they cannot open leaves here. The roots by id in one read. */
async function threadsOf(tx: Tx, tabId: string, messages: Array<{ id: string; conversationId: string; thread: string | null; alsoInChat: boolean | null }>):
  Promise<Map<string, string>> {
  const replies = messages.filter(m => m.thread && m.thread !== m.id && m.alsoInChat !== true)
  if (!replies.length) return new Map()
  const found = await readBy(tx, 'SuperTabMessage', 'id', [{ $match: { _id: { $in: [...new Set(replies.map(m => m.thread!))] }, tabId } },
    { $project: { conversationId: 1, thread: 1, source: 1, recipientIds: 1 } }])
  const roots = found.map(r => ({ id: r._id as string, conversationId: r.conversationId as string, thread: r.thread, source: r.source ?? null,
    recipientIds: (r.recipientIds as string[] | undefined) ?? [] })).filter(r => r.thread === r.id && !agentOnly(r.source, r.recipientIds))
  const copies = await deliveredCopies(tx, tabId, roots)
  const shown = new Map(roots.filter(r => !copies.has(r.id)).map(r => [r.id, r.conversationId]))
  return new Map(replies.filter(m => shown.get(m.thread!) === m.conversationId).map(m => [m.id, m.thread!]))
}