ds-bot 0.1.2 → 0.1.4

package/src/host/turns.js

@@ -2,7 +2,7 @@
 // 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 { REPLY_KIND, SOURCE_KIND } from './constants.js'
+import { REFERENCE_KIND, REPLY_KIND, SOURCE_KIND } from './constants.js'
 import { textOf } from './text.js'
 import { reminderText } from './schedules.js'
 
@@ -21,18 +21,81 @@ export function turnFailure(error) {
 
 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 }]
+}
+
+// A tool call some models write into their text instead of making it (the XML-like
+// form of their own chat template).
+const WRITTEN_CALL = /<tool_call>\s*<function=|<function=[\w.-]+>\s*<parameter=/
+export const writesToolCall = text => typeof text === 'string' && WRITTEN_CALL.test(text)
+export const stripWrittenCalls = text => text
+  .replace(/<tool_call>[\s\S]*?(?:<\/tool_call>|$)/g, '')
+  .replace(/<function=[\w.-]+>[\s\S]*?(?:<\/function>|$)/g, '')
+  .trim()
+
+const RETRY_TEXT = 'Your last reply wrote a tool call as plain text (<tool_call>…), so it did not run and nothing happened. Call the tool through the tool interface now, then reply as you meant to.'
+
 export function install(rt) {
   const { ctx, state } = rt
 
-  /** @type {Map<string, {turn?:number, pending?:any, info?:any, texts:string[]}>} */
+  // The retry goes where the turn's trigger came from: a group round's waiter or a
+  // Bot's request keeps its exchange; anything else is a nudge in the Bot's own chat.
+  const retryWrittenCall = (id, info) => {
+    const keeps = info !== undefined && (info.role === 'room' || expectsReply(info))
+    return rt.deliver({
+      ...(keeps && info.senderSessionId ? { fromId: info.senderSessionId } : {}),
+      toId: rt.selfOf(id),
+      sessionId: id,
+      role: keeps ? info.role : 'retry',
+      ...(keeps && info.roomId ? { roomId: info.roomId } : {}),
+      hop: keeps ? info.hop ?? 0 : 0,
+      ...(keeps && info.exchangeId ? { exchangeId: info.exchangeId } : {}),
+      ...(keeps && info.audience ? { audience: info.audience } : {}),
+      ...(keeps && info.askedBy ? { askedBy: info.askedBy } : {}),
+      ...(keeps && info.senderRoomId ? { fromRoomId: info.senderRoomId } : {}),
+      note: 'your tool call did not run',
+      retried: true,
+      text: RETRY_TEXT,
+    })
+  }
+
+  /** @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, {resolve:(text:string)=>void}>} member turn waiters keyed by exchange id */
+  /** @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}[]>} messages a room's next relay posts */
+  /** @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)
@@ -45,7 +108,7 @@ export function install(rt) {
   /** @type {Record<string, string>} */
   let activity = {}
   const activityOf = (tool) => {
-    if (/^(message_bot|create_bot|update_bot|create_group|update_group|delete_group|post_to_group)$/.test(tool)) return 'sending'
+    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'
@@ -63,26 +126,33 @@ export function install(rt) {
     if (!turns.includes(turn)) {
       turns.push(turn)
       if (turns.length > 400) turns.splice(0, turns.length - 400)
-      void rt.save()
+      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()
+    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 ((info.role === 'request' && !answersUser(info)) || info.role === 'room' || (info.role === 'handoff' && info.resume !== true)) {
+    if ((expectsReply(info) && !answersUser(info)) || info.role === 'room' || (info.role === 'handoff' && info.resume !== true)) {
       markExchangeTurn(sessionId, entry.turn)
     }
   }
@@ -102,9 +172,52 @@ export function install(rt) {
       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
+  }
+
+  // Per group, the members whose turn there is running; the round's current speaker is
+  // marked, since its round shows it.
+  const roomWorkView = () => {
+    const speaking = new Set([...roomProgress.values()].map(round => `${round.roomId}:${round.speaking}`))
+    const rooms = {}
+    for (const [id, entry] of live) {
+      const owner = rt.groupOwners.get(id)
+      if (entry.turn === undefined || owner === undefined) continue
+      rooms[owner.roomId] = [...(rooms[owner.roomId] ?? []), {
+        botId: owner.botId,
+        since: entry.since,
+        ...(entry.tool ? { tool: entry.tool } : {}),
+        ...(speaking.has(`${owner.roomId}:${owner.botId}`) ? { speaking: true } : {}),
+      }]
+    }
+    return rooms
+  }
+
+  // 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)
@@ -128,21 +241,32 @@ export function install(rt) {
     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':
-        setActivity(id, event.data?.name === 'ask_user' ? undefined : activityOf(String(event.data?.name ?? '')))
+      case 'tool/call': {
+        const name = String(event.data?.name ?? '')
+        setActivity(id, name === 'ask_user' ? undefined : activityOf(name))
+        entry.tool = name
+        if (rt.groupOwners.has(id)) rt.workRoomTurn?.(id, 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
@@ -153,6 +277,14 @@ export function install(rt) {
         // 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
@@ -171,15 +303,36 @@ export function install(rt) {
             name: source.senderName,
             reportBack: source.reportBack === true,
             hop: source.hop ?? 0,
+            ...(source.late ? { late: true } : {}),
+            ...(source.quiet ? { quiet: true } : {}),
+            ...(source.failed ? { failed: source.failed } : {}),
+            ...(source.resumed ? { resumed: true } : {}),
+            ...(source.again ? { again: true } : {}),
+            ...(source.stopped ? { stopped: true } : {}),
+            ...(source.askedBy ? { askedBy: source.askedBy } : {}),
           })
         } 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.info === undefined) claimTrigger(id, entry, source)
-          else entry.pending = source
+          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 : [])
@@ -191,60 +344,131 @@ export function install(rt) {
           // Any user message answers or supersedes the open question card.
           if (state.questions[id] !== undefined) {
             delete state.questions[id]
-            void rt.save()
+            void rt.save().catch(() => {})
           }
         }
         break
       }
       case 'assistant/message': {
-        const text = textOf(event.data?.message?.content)
+        const content = event.data?.message?.content
+        const text = textOf(content)
         if (text !== '') entry.texts.push(text)
+        entry.lastText = text
+        entry.lastCalled = Array.isArray(content) && content.some(block => block?.type === 'tool-call')
         break
       }
       case 'turn/end': {
         setActivity(id, undefined)
         const info = entry.info
-        const reply = entry.texts.join('\n\n').trim()
+        const joined = entry.joined ?? []
+        const texts = entry.texts
+        const { lastText, lastCalled } = entry
         // 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
+        entry.lastText = undefined
+        entry.lastCalled = undefined
         const reason = event.data?.reason
         const failure = reason?.kind === 'error' && !switched ? turnFailure(reason.error) : undefined
         if (failure !== undefined) noteTurnFailure(id, failure)
-        if (info === undefined || switched) break
-        if (info.role === 'room') {
+        if (switched) break
+        // A model that writes its tool call as text ends the turn as if it were done,
+        // though nothing ran. It gets one more turn on the same trigger, so a waiting
+        // round or sender gets the real answer; a second time, the text goes on without
+        // the call.
+        const wroteCall = failure === undefined && reason?.kind === 'completed' && lastCalled !== true && writesToolCall(lastText)
+        const retry = wroteCall && info?.retried !== true && !(info?.role === 'room' && stoppedRoomTurns.has(info.exchangeId))
+        if (retry) void retryWrittenCall(id, info).catch(error => rt.warn('ds-bot: asking %s to run its written tool call failed: %s', id, error))
+        const replyText = () => {
+          const reply = (wroteCall ? texts.map(stripWrittenCalls) : texts).join('\n\n').trim()
+          return wroteCall && reply === '' ? 'Tried to run a tool but wrote the call as text, so it did not run.' : reply
+        }
+        // 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'
+          // A sender that wrote from a group gets the reply in its Session there, while
+          // it is still a member.
+          const back = rt.roomOf(source.senderRoomId)?.sessions?.[source.senderSessionId]
+          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,
+              ...(back ? { sessionId: back } : {}),
+              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,
+              ...(back ? { sessionId: back } : {}),
+              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))
+          }
+        }
+        // A retried turn answers the same waiter or sender, so this one passes nothing on.
+        if (!retry && info?.role === 'room') {
           const waiter = roomWaiters.get(info.exchangeId)
           roomWaiters.delete(info.exchangeId)
-          if (failure !== undefined) waiter?.fail(failure)
-          else waiter?.resolve(reason?.kind === 'aborted' ? null : reply)
-        } else if (info.role === 'request' && !answersUser(info) && failure !== undefined) {
-          // The sender was told a reply comes later; without this it would wait forever.
-          const name = rt.botOf(rt.selfOf(id))?.name ?? 'The other Bot'
-          void rt.deliver({
-            fromId: rt.selfOf(id),
-            toId: info.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: (info.hop ?? 0) + 1,
-            replyTo: info.exchangeId,
-          }).catch(error => rt.warn('ds-bot: failure notice delivery failed: %s', error))
-        } else if (info.role === 'request' && !answersUser(info) && reply !== '') {
+          const stopped = stoppedRoomTurns.delete(info.exchangeId)
+          if (waiter !== undefined) {
+            if (failure !== undefined) waiter.fail(failure)
+            else waiter.resolve(reason?.kind === 'aborted' ? null : replyText())
+          } 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, replyText())
+          }
+        } else if (!retry && info !== undefined) {
+          // A group Session speaks only in its group: the turn that takes a reply to a
+          // message it sent from there posts what it ends with.
+          if (rt.groupOwners.has(id) && (info.role === 'reply' || info.role === 'retry')) {
+            if (failure !== undefined) void rt.lateRoomFailure?.(id, info, failure)
+            else if (reason?.kind !== 'aborted') void rt.lateRoomReply?.(id, info, replyText())
+          } else {
+            answer(info, replyText())
+          }
+        }
+        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: rt.selfOf(id),
-            toId: info.senderSessionId,
-            text: reply,
-            role: 'reply',
-            hop: (info.hop ?? 0) + 1,
-            replyTo: info.exchangeId,
-          }).catch(error => rt.warn('ds-bot: reply delivery failed: %s', error))
+            fromId: request.info.senderSessionId,
+            toId: rt.selfOf(id),
+            sessionId: id,
+            text: request.text,
+            role: 'request',
+            hop: request.info.hop ?? 0,
+            exchangeId: request.info.exchangeId,
+            ...(request.info.senderRoomId ? { fromRoomId: request.info.senderRoomId } : {}),
+            deferred: true,
+          }).catch(error => rt.warn('ds-bot: deferred request delivery failed: %s', error))
         }
         break
       }
     }
   })
 
-  Object.assign(rt, { live, liveOf, roomWaiters, roomProgress, roomInbox, activityView })
+  Object.assign(rt, { live, liveOf, roomWaiters, roomProgress, roomInbox, activityView, workView, roomWorkView, callDetail, stopRoomTurn })
 }

package/src/host/update.js

@@ -161,8 +161,12 @@ export function install(rt) {
     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:${source.owner}/${source.repo}#${fragment}` }
+    return { version, spec: `github:${owner}/${repo}#${fragment}` }
   }
 
   async function runCheck() {

package/src/shared/mentions.js

@@ -0,0 +1,65 @@
+// "@Name" is read by one rule everywhere: the group host picks who answers with it,
+// and the client draws the same mentions in the bubbles, so what the user sees called
+// is what gets called. Pure, so both sides import it.
+
+export const ALL_WORDS = ['all', 'everyone', '所有人', '全体']
+// A letter, digit, "_" or "-" after a name means a longer word ("@Mi" in "@MiniMax"),
+// and "/", "\" or a "." that goes on into a word mean a path: DSH writes a file
+// reference as "@docs/guide.md", which must not call a Bot named Docs. A letter,
+// digit, "_", "." or "/" before "@" means an address ("a@b", "medium.com/@Writer").
+const NAME_GOES_ON = /^(?:[a-z0-9_\-/\\]|\.[a-z0-9_-])/i
+const ADDRESS_BEFORE = /[a-z0-9_./]/i
+// Code and Markdown links, with or without a title, are literal text.
+const LITERAL = /```[\s\S]*?(?:```|$)|`[^`\n]*`|\[[^\]\n]*\]\([^)\s]*(?:\s+(?:"[^"\n]*"|'[^'\n]*'))?\)/g
+
+const fitsAt = (text, at, word) => text.slice(at, at + word.length).toLowerCase() === word.toLowerCase()
+  && !NAME_GOES_ON.test(text.slice(at + word.length))
+const overlaps = (spans, start, end) => spans.some(span => start < span.end && span.start < end)
+
+// What a Bot may be named: something "@" can call without a second reading.
+export function nameProblem(name) {
+  const text = String(name ?? '').trim()
+  if (text === '') return 'A Bot needs a name'
+  if (/[@`\r\n]/.test(text)) return 'A Bot name cannot contain @, ` or a line break'
+  if (ALL_WORDS.includes(text.toLowerCase())) return `"${text}" calls everyone in a group, so it cannot be a Bot name`
+  return undefined
+}
+
+// DSH writes each referenced conversation into the message once as "@label"; that one
+// occurrence per listed label is a reference, not a call. Longest labels go first so
+// "@K notes" is never read as the label "K".
+export function referenceSpans(text, labels = []) {
+  const spans = []
+  for (const label of [...labels].sort((a, b) => b.length - a.length)) {
+    const mention = `@${label}`
+    for (let at = text.indexOf(mention); at !== -1; at = text.indexOf(mention, at + 1)) {
+      const end = at + mention.length
+      if ((at > 0 && ADDRESS_BEFORE.test(text[at - 1])) || NAME_GOES_ON.test(text.slice(end)) || overlaps(spans, at, end)) continue
+      spans.push({ start: at, end, label })
+      break
+    }
+  }
+  return spans.sort((a, b) => a.start - b.start)
+}
+
+// Every "@Name" and "@all" outside code, links and references, in order. Longest names
+// match first, so "@新 Bot 2" is never "@新 Bot"; a name may hold spaces.
+export function mentionSpans(text, bots, { references = [] } = {}) {
+  const value = String(text ?? '')
+  const skip = [
+    ...[...value.matchAll(LITERAL)].map(match => ({ start: match.index, end: match.index + match[0].length })),
+    ...referenceSpans(value, references),
+  ]
+  const byLength = bots.filter(bot => bot?.name).sort((a, b) => b.name.length - a.name.length)
+  const spans = []
+  for (let at = value.indexOf('@'); at !== -1; at = value.indexOf('@', at + 1)) {
+    if ((at > 0 && ADDRESS_BEFORE.test(value[at - 1])) || overlaps(skip, at, at + 1)) continue
+    const bot = byLength.find(candidate => fitsAt(value, at + 1, candidate.name))
+    const all = bot ? undefined : ALL_WORDS.find(word => fitsAt(value, at + 1, word))
+    if (!bot && !all) continue
+    const end = at + 1 + (bot ? bot.name.length : all.length)
+    spans.push(bot ? { start: at, end, bot } : { start: at, end, all: true })
+    at = end - 1
+  }
+  return spans
+}

package/web-search.js

@@ -472,6 +472,15 @@ export const ENGINES = {
 
 const aborted = signal => new WebError('web search aborted', 'WEB_ABORTED', { cause: signal?.reason })
 
+// AbortSignal.timeout's wait is unref'd, so under Node 22's test runner a pending subtest
+// is cancelled as soon as nothing ref'd holds the loop — and a mocked fetch holds nothing.
+// A plain setTimeout keeps the loop honest; the abort reason stays a TimeoutError.
+const timeoutAfter = (ms) => {
+  const timeout = new AbortController()
+  const timer = setTimeout(() => timeout.abort(new DOMException('The operation timed out.', 'TimeoutError')), ms)
+  return { timeout, timer }
+}
+
 function checkSearchApi(api, index) {
   const where = `web-search-auto: searchApis[${index}]`
   if (!isRecord(api)) throw new Error(`${where} must be an object`)
@@ -551,7 +560,7 @@ export function createAutoSearchProvider(deps, config = {}) {
 
   async function attempt(candidate, route, credential, request, signal, budget, known) {
     const call = candidate.request({ query: request.query, maxResults: request.maxResults })
-    const timeout = AbortSignal.timeout(budget)
+    const { timeout, timer } = timeoutAfter(budget)
     let response
     let text
     try {
@@ -561,12 +570,14 @@ export function createAutoSearchProvider(deps, config = {}) {
         redirect: 'error',
         headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': USER_AGENT, ...route.headers, ...call.headers, ...credential.headers(candidate) },
         body: JSON.stringify(call.body),
-        signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+        signal: signal === undefined ? timeout.signal : AbortSignal.any([signal, timeout.signal]),
       })
       text = await response.text()
     } catch (error) {
       if (signal?.aborted) throw aborted(signal)
-      return { reason: timeout.aborted ? `timed out after ${seconds(budget)}` : `request failed: ${reasonOf(error)}` }
+      return timeout.signal.aborted ? { reason: `timed out after ${seconds(budget)}`, timedOut: true } : { reason: `request failed: ${reasonOf(error)}` }
+    } finally {
+      clearTimeout(timer)
     }
     if (!response.ok) {
       const detail = errorDetail(text)
@@ -593,7 +604,7 @@ export function createAutoSearchProvider(deps, config = {}) {
     const keyOf = candidate => [route.provider, candidate.url, candidate.model ?? ''].join('\n')
     const works = candidate => memory.get(keyOf(candidate))?.works === true
     const ordered = [...plan.candidates.filter(works), ...plan.candidates.filter(candidate => !works(candidate))]
-    const deadline = now() + options.nativeTimeoutMs
+    let deadline = now() + options.nativeTimeoutMs
     const notes = []
     let credential
     for (const candidate of ordered) {
@@ -622,6 +633,9 @@ export function createAutoSearchProvider(deps, config = {}) {
       notes.push(`${where}: ${outcome.reason}`)
       if (outcome.skip !== undefined) memory.set(keyOf(candidate), { until: now() + SKIP_FOR[outcome.skip], reason: outcome.reason })
       if (outcome.final) break
+      // A timed-out attempt had all the time that was left, but the timer and now() use
+      // different clocks, so now() can still read a millisecond before the deadline.
+      if (outcome.timedOut) deadline = now()
     }
     return { reason: `route "${route.provider}": ${notes.join('; ')}` }
   }
@@ -651,14 +665,16 @@ export function createAutoSearchProvider(deps, config = {}) {
       const remaining = deadline - now()
       if (remaining <= 0) { attempts.push(`${host}: skipped, out of time`); continue }
       // Leave later engines a share of the budget when an earlier one hangs.
-      const timeout = AbortSignal.timeout(index === options.engines.length - 1 ? remaining : Math.min(remaining, Math.ceil(options.fallbackTimeoutMs / 2)))
+      const { timeout, timer } = timeoutAfter(index === options.engines.length - 1 ? remaining : Math.min(remaining, Math.ceil(options.fallbackTimeoutMs / 2)))
       let fetched
       try {
-        fetched = await fetchPage(engine, url, signal === undefined ? timeout : AbortSignal.any([signal, timeout]))
+        fetched = await fetchPage(engine, url, signal === undefined ? timeout.signal : AbortSignal.any([signal, timeout.signal]))
       } catch (error) {
         if (signal?.aborted) throw aborted(signal)
-        attempts.push(`${host}: ${timeout.aborted ? 'timed out' : `${error?.code ? `${error.code} ` : ''}${reasonOf(error)}`}`)
+        attempts.push(`${host}: ${timeout.signal.aborted ? 'timed out' : `${error?.code ? `${error.code} ` : ''}${reasonOf(error)}`}`)
         continue
+      } finally {
+        clearTimeout(timer)
       }
       const at = new URL(fetched.url).host
       if (fetched.page.statusCode !== 200) { attempts.push(`${at}: HTTP ${fetched.page.statusCode}`); continue }