ds-bot 0.1.2 → 0.1.4

package/src/host/roster.js

@@ -4,6 +4,7 @@ import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { MAX_AVATAR_IMAGE, ROOM_MAX_MEMBERS, ROOM_MODES, ROOM_NAME_MAX, ROOM_NOTICE_MAX } from './constants.js'
 import { currentColor, isColor, unquote } from './text.js'
+import { nameProblem } from '../shared/mentions.js'
 
 export function install(rt) {
   const { ctx, config, home, defaults, state } = rt
@@ -56,52 +57,67 @@ export function install(rt) {
   // greeting waits until a model is chosen. So does a Bot made when no model is served.
   async function createBot({ name: botName, role = '', instructions = '', color, brief = '', createdBy, main = false, avatar, model, effort, copyOf, pickModel = false }) {
     const cleanName = String(botName ?? '').trim().slice(0, 40)
-    if (cleanName === '') throw new Error('A Bot needs a name')
+    const problem = nameProblem(cleanName)
+    if (problem !== undefined) throw new Error(problem)
     if (rt.findBot(cleanName)) throw new Error(`A Bot named ${cleanName} already exists`)
     const cleanAvatarValue = cleanAvatar(avatar)
     // The model is fixed at creation, so a later change of the DSH default leaves it alone.
     const modelRef = model ? await rt.resolveModel(model) : pickModel ? undefined : await rt.defaultModel()
     const effortId = modelRef !== undefined && effort !== undefined ? await rt.resolveEffort(modelRef, effort) : undefined
     const id = await createSession(cleanName)
-    state.bots[id] = {
-      id,
-      name: cleanName,
-      role: String(role).trim().slice(0, 24),
-      // A color is only stored when the user picks one; otherwise the id picks it.
-      ...(isColor(currentColor(color)) ? { color: currentColor(color) } : {}),
-      ...(cleanAvatarValue ? { avatar: cleanAvatarValue } : {}),
-      ...(modelRef ? { model: modelRef } : {}),
-      ...(effortId ? { effort: effortId } : {}),
-      instructions: String(instructions).trim(),
-      createdAt: Date.now(),
-      createdBy: createdBy ?? null,
-    }
-    if (main) state.mainBotIds.push(id)
-    const creator = rt.botOf(createdBy)
-    const original = rt.botOf(copyOf)
-    const language = rt.uiLanguage?.()
-    const kickoff = main
-      ? `You were just set up as the user's Main Bot. Greet the user in one or two short messages: say you will run their Bot team and that they can come to you for anything that needs a decision. Then use ask_user to ask what they want the team to help with first (3-4 short options). Write in ${language ?? 'the user\'s language if known; otherwise Chinese'}.`
-      : original
-        ? `The user just made you as a copy of ${original.name}: same job, fresh memory. Greet the user in one short message, then use ask_user to ask what this copy should focus on (3-4 short options).`
-        : creator
-          ? `${creator.name} just created you for the user.${brief ? ` Why you exist: ${brief}` : ''}\nGreet the user in one short message, then use ask_user to ask where to start (3-4 short options relevant to your role, with allowCustom). Keep it brief.`
-          : brief
-            ? `The user just created you and sent this first message:\n\n${brief}\n\nIntroduce yourself in one short line, then help with it.`
-            : 'The user just created you. Greet the user in one short message, then use ask_user to ask what you should focus on (3-4 short options, with allowCustom).'
-    const text = !main && language ? `${kickoff}\nWrite in ${language}.` : kickoff
-    const bot = state.bots[id]
-    if (modelRef === undefined) {
-      bot.kickoff = { text, from: createdBy ?? null, ...(main ? { main: true } : {}) }
+    try {
+      state.bots[id] = {
+        id,
+        name: cleanName,
+        role: String(role).trim().slice(0, 24),
+        // A color is only stored when the user picks one; otherwise the id picks it.
+        ...(isColor(currentColor(color)) ? { color: currentColor(color) } : {}),
+        ...(cleanAvatarValue ? { avatar: cleanAvatarValue } : {}),
+        ...(modelRef ? { model: modelRef } : {}),
+        ...(effortId ? { effort: effortId } : {}),
+        instructions: String(instructions).trim(),
+        createdAt: Date.now(),
+        createdBy: createdBy ?? null,
+        capabilities: [],
+      }
+      if (main) state.mainBotIds.push(id)
+      const creator = rt.botOf(createdBy)
+      const original = rt.botOf(copyOf)
+      const language = rt.uiLanguage?.()
+      const kickoff = main
+        ? `You were just set up as the user's Main Bot. Greet the user in one or two short messages: say you will run their Bot team and that they can come to you for anything that needs a decision. Then use ask_user to ask what they want the team to help with first (3-4 short options). Write in ${language ?? 'the user\'s language if known; otherwise Chinese'}.`
+        : original
+          ? `The user just made you as a copy of ${original.name}: same job, fresh memory. Greet the user in one short message, then use ask_user to ask what this copy should focus on (3-4 short options).`
+          : creator
+            ? `${creator.name} just created you for the user.${brief ? ` Why you exist: ${brief}` : ''}\nGreet the user in one short message, then use ask_user to ask where to start (3-4 short options relevant to your role, with allowCustom). Keep it brief.`
+            : brief
+              ? `The user just created you and sent this first message:\n\n${brief}\n\nIntroduce yourself in one short line, then help with it.`
+              : 'The user just created you. Greet the user in one short message, then use ask_user to ask what you should focus on (3-4 short options, with allowCustom).'
+      const text = !main && language ? `${kickoff}\nWrite in ${language}.` : kickoff
+      const bot = state.bots[id]
+      if (modelRef === undefined) {
+        bot.kickoff = { text, from: createdBy ?? null, ...(main ? { main: true } : {}) }
+        await rt.save()
+        return bot
+      }
       await rt.save()
+      // The greeting runs on the Bot's own model, once its provider is registered.
+      void rt.waitForModel(bot)
+        .then(() => rt.applyModel(bot).catch(error => rt.warn('ds-bot: model for %s not applied: %s', cleanName, error)))
+        .then(() => sendKickoff(bot, { text, from: createdBy }))
       return bot
+    } catch (error) {
+      // The Bot's Session was already made: archive it instead of leaving an orphan.
+      delete state.bots[id]
+      state.mainBotIds = state.mainBotIds.filter(other => other !== id)
+      rt.chatOwners.delete(id)
+      // A save that another change queued meanwhile still carries this Bot; a later
+      // one writes the team without it.
+      void rt.save().catch(() => {})
+      await ctx.workspaceRegistry.archiveSession(id)
+        .catch(archiveError => rt.warn('ds-bot: archiving the Session for %s failed: %s', cleanName, archiveError))
+      throw error
     }
-    await rt.save()
-    // The greeting runs on the Bot's own model, once its provider is registered.
-    void rt.waitForModel(bot)
-      .then(() => rt.applyModel(bot).catch(error => rt.warn('ds-bot: model for %s not applied: %s', cleanName, error)))
-      .then(() => sendKickoff(bot, { text, from: createdBy }))
-    return bot
   }
 
   function sendKickoff(bot, { text, from }) {
@@ -114,7 +130,7 @@ export function install(rt) {
     const bot = rt.botOf(botId)
     if (bot?.kickoff === undefined) return
     delete bot.kickoff
-    void rt.save()
+    void rt.save().catch(() => {})
   }
 
   async function duplicateBot(id) {
@@ -140,6 +156,9 @@ export function install(rt) {
       const next = String(patch.name).trim().slice(0, 40)
       const clash = rt.findBot(next)
       if (next === '' || (clash && clash.id !== id)) throw new Error(`Name ${next} is not available`)
+      // A name saved before the rule stays usable until it changes.
+      const problem = next === bot.name ? undefined : nameProblem(next)
+      if (problem !== undefined) throw new Error(problem)
       bot.name = next
       const agent = await rt.resolveAgent(rt.chatOf(id))
       await ctx.sessionTitle.rename(agent.session, next)
@@ -242,19 +261,28 @@ export function install(rt) {
     if (mode !== undefined && !ROOM_MODES.includes(mode)) throw new Error(`Reply mode must be one of ${ROOM_MODES.join(', ')}`)
     const title = custom || autoRoomName(members)
     const id = await createSession(title)
-    state.rooms[id] = {
-      id,
-      name: title,
-      ...(custom ? { named: true } : {}),
-      members,
-      admin: adminId,
-      mode: mode ?? 'admin',
-      notice: cleanNotice(notice),
-      createdAt: Date.now(),
-      createdBy: createdBy ?? null,
+    try {
+      state.rooms[id] = {
+        id,
+        name: title,
+        ...(custom ? { named: true } : {}),
+        members,
+        admin: adminId,
+        mode: mode ?? 'admin',
+        notice: cleanNotice(notice),
+        createdAt: Date.now(),
+        createdBy: createdBy ?? null,
+      }
+      await rt.save()
+      return state.rooms[id]
+    } catch (error) {
+      // The group's Session was already made: archive it instead of leaving an orphan.
+      delete state.rooms[id]
+      void rt.save().catch(() => {})
+      await ctx.workspaceRegistry.archiveSession(id)
+        .catch(archiveError => rt.warn('ds-bot: archiving the Session for %s failed: %s', title, archiveError))
+      throw error
     }
-    await rt.save()
-    return state.rooms[id]
   }
 
   // `actorId` is the Bot asking, or undefined for the user. Returns what changed, in words.
@@ -328,8 +356,12 @@ export function install(rt) {
     for (const botId of Object.keys(room.sessions ?? {})) rt.dropGroupSession(room, botId)
     delete state.rooms[id]
     rt.roomInbox.delete(id)
-    await rt.save()
-    await ctx.workspaceRegistry.archiveSession(id).catch(() => {})
+    const failed = await saveForDelete()
+    // Armed scheduled tasks refuse a plain archive and would keep delivering into
+    // the deleted group; the session-stop that stopActivity runs removes them.
+    await ctx.workspaceRegistry.archiveSession(id, { stopActivity: true })
+      .catch(error => rt.warn('ds-bot: group chat %s not archived: %s', room.name, error))
+    if (failed !== undefined) throw failed
   }
 
   // The first Main Bot is the sidebar tile. `replace` gives a Main Bot's place to
@@ -364,13 +396,14 @@ export function install(rt) {
   }
 
   async function deleteBot(id) {
-    if (rt.botOf(id) === undefined) throw new Error('Unknown Bot')
+    const bot = rt.botOf(id)
+    if (bot === undefined) throw new Error('Unknown Bot')
     if (rt.isMain(id)) throw new Error('A Main Bot cannot be deleted; remove its Main Bot role first')
     // Before the Bot and its group Sessions leave the state, which the archive reads.
     const archived = rt.archiveBotMemory(id)
     const current = rt.chatOf(id)
     // Questions and exchange turns are kept per Session, so every part of the chat is cleared.
-    const parts = new Set([id, current, ...(rt.botOf(id).segments ?? []).map(segment => segment.sessionId)])
+    const parts = new Set([id, current, ...(bot.segments ?? []).map(segment => segment.sessionId)])
     delete state.bots[id]
     for (const part of parts) {
       delete state.questions[part]
@@ -387,8 +420,29 @@ export function install(rt) {
     await followMemberNames(touched)
     await rt.forgetBotSecrets(id)
     await archived
-    await rt.save()
-    await ctx.workspaceRegistry.archiveSession(current).catch(() => {})
+    const failed = await saveForDelete()
+    // Same as deleteRoom: stopActivity removes the Session's armed scheduled tasks.
+    // Past parts are archived too: a part move can leave tasks on the old Session,
+    // which otherwise stays armed and invisible. Already-archived ids are a no-op.
+    for (const part of parts) {
+      await ctx.workspaceRegistry.archiveSession(part, { stopActivity: true })
+        .catch(error => rt.warn('ds-bot: Bot %s not archived: %s', bot.name, error))
+    }
+    if (failed !== undefined) throw failed
+  }
+
+  // A deletion whose save fails stays in memory, and the next save writes it, so its
+  // Sessions are stopped anyway: left armed, their scheduled tasks would keep running
+  // with nothing in the team to show or delete them. Only a host that lost the team
+  // to another dsh keeps them, since the other host's copy still has them.
+  async function saveForDelete() {
+    try {
+      await rt.save()
+      return undefined
+    } catch (error) {
+      if (error?.code === 'ELOCKLOST' || rt.readOnly() !== undefined) throw error
+      return error
+    }
   }
 
   async function bootstrap() {

package/src/host/secrets.js

@@ -526,5 +526,13 @@ export function install(rt) {
     return () => { if (usedTimer !== null) clearTimeout(usedTimer) }
   }, 'ds-bot: load secrets')
 
-  Object.assign(rt, { secretsView, secretValue: name => secrets.get(name)?.value, secretEndpoint, forgetBotSecrets, loadSecrets, redactSecrets: text => redact(text) })
+  Object.assign(rt, {
+    secretsView,
+    secretValue: name => secrets.get(name)?.value,
+    canUseSecret: (name, botId) => canUse(secrets.get(name), botId),
+    secretEndpoint,
+    forgetBotSecrets,
+    loadSecrets,
+    redactSecrets: text => redact(text),
+  })
 }

package/src/host/store.js

@@ -2,7 +2,7 @@
 // host on the same data from writing it, and the indexes that map a Session to the Bot
 // or group chat it belongs to.
 import { mkdirSync, statSync } from 'node:fs'
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { copyFile, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { LEGACY_THEMES, MAX_EXCHANGES, ROOM_MODES } from './constants.js'
 import { homeLock } from './home-lock.js'
@@ -11,8 +11,8 @@ import { currentColor, normalize, unquote } from './text.js'
 export function install(rt) {
   const { ctx, home, statePath } = rt
 
-  /** @type {{version:1, workspaceId?:string, mainBotIds:string[], bots:Record<string,any>, rooms:Record<string,any>, agents:Record<string,any>, exchanges:any[], exchangeTurns:Record<string,number[]>, revision:number}} */
-  const state = { version: 1, mainBotIds: [], bots: {}, rooms: {}, agents: {}, exchanges: [], exchangeTurns: {}, questions: {}, prefs: {}, revision: 0 }
+  /** @type {{version:1, workspaceId?:string, mainBotIds:string[], bots:Record<string,any>, rooms:Record<string,any>, agents:Record<string,any>, capabilities:{items:Record<string,any>}, exchanges:any[], exchangeTurns:Record<string,number[]>, revision:number}} */
+  const state = { version: 1, mainBotIds: [], bots: {}, rooms: {}, agents: {}, capabilities: { items: {} }, exchanges: [], exchangeTurns: {}, questions: {}, prefs: {}, revision: 0 }
   let loaded = null
   let writing = Promise.resolve()
   const { warn } = rt
@@ -22,7 +22,9 @@ export function install(rt) {
   // undefined while this host may write.
   let holder
   let lockBroken = false
+  let stuck
   let warnedReadOnly = false
+  let stopped = false
   // mtime and size of the state.json this host last read or wrote.
   let seen = ''
   const stamp = () => {
@@ -40,39 +42,80 @@ export function install(rt) {
       mkdirSync(home, { recursive: true })
       holder = lock.claim()
     } catch (error) {
-      // An unusable lock (a read-only or odd file system) must not stop the team.
+      // An unusable lock (a read-only or odd file system) must not stop the team; a
+      // save that then cannot write still rejects.
       lockBroken = true
       holder = undefined
       warn('ds-bot: cannot lock %s, so another dsh on the same data could undo changes: %s', home, error)
     }
   }
   const readOnly = () => {
+    if (stuck !== undefined) return `The Bot team file ${statePath} could not be read (${stuck}). DS Bot does not change it; fix or move the file and reload.`
     if (holder === undefined) return undefined
     const where = holder.pid ? `pid ${holder.pid}${holder.host ? ` on ${holder.host}` : ''}` : 'unknown process'
     return `The Bot team in ${home} is open in another dsh (Web or Desktop, ${where}). This window shows the team but cannot change it; close the other one and reload.`
   }
 
   const readFileState = async () => {
+    let contents
     try {
+      contents = await readFile(statePath, 'utf8')
+    } catch (error) {
       seen = stamp()
-      const parsed = JSON.parse(await readFile(statePath, 'utf8'))
-      return parsed?.version === 1 ? parsed : undefined
+      if (error?.code === 'ENOENT') {
+        stuck = undefined
+        return undefined
+      }
+      stuck = error?.code ?? error?.message ?? String(error)
+      warn('ds-bot: unreadable state %s: %s', statePath, error)
+      return undefined
+    }
+    seen = stamp()
+    let parsed
+    try {
+      parsed = JSON.parse(contents)
     } catch (error) {
-      if (error?.code !== 'ENOENT') warn('ds-bot: unreadable state %s: %s', statePath, error)
+      const backup = `${statePath}.broken-${Date.now()}`
+      try {
+        await copyFile(statePath, backup)
+        stuck = undefined
+        warn('ds-bot: unreadable state %s: %s; backed up as %s', statePath, error, backup)
+      } catch (copyError) {
+        stuck = copyError?.code ?? copyError?.message ?? error?.message ?? String(error)
+        warn('ds-bot: unreadable state %s: %s; backup failed: %s', statePath, error, copyError)
+      }
       return undefined
     }
+    if (parsed?.version === 1) {
+      stuck = undefined
+      return parsed
+    }
+    stuck = 'saved by a newer DS Bot; update DS Bot'
+    return undefined
   }
 
   // Fill `state` from the saved file and bring an older team up to date. Returns the
   // groups whose Session titles still need the new name.
   const adopt = (parsed) => {
+    const hadCapabilities = parsed !== null && parsed !== undefined && Object.hasOwn(parsed, 'capabilities')
     for (const key of Object.keys(state)) delete state[key]
     Object.assign(state, JSON.parse(EMPTY), parsed ?? {})
     state.prefs ??= {}
     // Teams saved before the DSH Agent existed carry no `agents`; corrupt values reset.
     if (state.agents === null || typeof state.agents !== 'object' || Array.isArray(state.agents)) state.agents = {}
-    let migrated = false
+    let migrated = !hadCapabilities
+    if (state.capabilities === null || typeof state.capabilities !== 'object' || Array.isArray(state.capabilities)) {
+      state.capabilities = { items: {} }
+      migrated = true
+    } else if (state.capabilities.items === null || typeof state.capabilities.items !== 'object' || Array.isArray(state.capabilities.items)) {
+      state.capabilities.items = {}
+      migrated = true
+    }
     for (const bot of Object.values(state.bots)) {
+      if (!Array.isArray(bot.capabilities)) {
+        bot.capabilities = []
+        migrated = true
+      }
       if (bot.color !== currentColor(bot.color)) {
         bot.color = currentColor(bot.color)
         migrated = true
@@ -129,7 +172,15 @@ export function install(rt) {
     if (holder !== undefined) warn('ds-bot: %s', readOnly())
     const { migrated, stale } = adopt(await readFileState())
     if (holder !== undefined) return
-    if (migrated) await save()
+    if (migrated && stuck === undefined) {
+      // A failed write must not poison `loaded`: the migrated state stays in
+      // memory and the next save() writes it.
+      try {
+        await save()
+      } catch (error) {
+        warn('ds-bot: saving the migrated Bot team failed: %s', error)
+      }
+    }
     // Not awaited: renaming a session must not hold up the first roster read.
     for (const room of stale) void rt.retitleRoom(room)
   })()
@@ -137,18 +188,42 @@ export function install(rt) {
   // A reading host follows the file and takes over once the other host has gone.
   const refresh = async () => {
     await load()
-    if (holder === undefined) return
-    claimLock()
-    if (holder === undefined) {
-      warn('ds-bot: the other dsh has closed; this one now saves the Bot team')
-      warnedReadOnly = false
-      adopt(await readFileState())
-      return
+    const hadHolder = holder !== undefined
+    if (hadHolder) {
+      claimLock()
+      if (holder === undefined) {
+        warn('ds-bot: the other dsh has closed; this one now saves the Bot team')
+        warnedReadOnly = false
+        adopt(await readFileState())
+        return
+      }
+    } else if (!lockBroken && !lock.owns()) {
+      // A cached "writer" is stale once the lock file no longer names this host:
+      // another dsh may have taken it over, or the file may just be gone. Re-claim
+      // and re-check instead of trusting the flag.
+      claimLock()
+      if (lockBroken) return
+      if (holder === undefined) {
+        // The lock was free: still the writer, but the file may carry changes
+        // written while no host held it.
+        warnedReadOnly = false
+        adopt(await readFileState())
+        return
+      }
+      warn('ds-bot: %s', readOnly())
     }
-    if (stamp() !== seen) adopt(await readFileState())
+    if ((stuck !== undefined || holder !== undefined) && stamp() !== seen) adopt(await readFileState())
   }
 
+  const warnReadOnly = () => {
+    if (!warnedReadOnly) {
+      warnedReadOnly = true
+      warn('ds-bot: not saving the Bot team: %s', readOnly())
+    }
+    return false
+  }
   const writable = () => {
+    if (stuck !== undefined) return warnReadOnly()
     if (lockBroken) return true
     if (holder === undefined && lock.owns()) return true
     // Lost the lock: retake it when nobody else holds it (its file was deleted), else
@@ -157,31 +232,51 @@ export function install(rt) {
       claimLock()
       if (holder === undefined) return true
     }
-    if (!warnedReadOnly) {
-      warnedReadOnly = true
-      warn('ds-bot: not saving the Bot team: %s', readOnly())
-    }
-    return false
+    return warnReadOnly()
   }
 
   const save = () => {
+    if (stopped) return writing
     indexSessions()
     // A reading host keeps the file's revision, so its window does not skip the next change.
     if (!writable()) return writing
     state.revision += 1
     state.exchanges = state.exchanges.slice(-MAX_EXCHANGES)
     const snapshot = JSON.stringify(state, null, 2)
-    writing = writing.then(async () => {
-      await mkdir(home, { recursive: true })
+    const run = writing.then(async () => {
       const temp = `${statePath}.${process.pid}.tmp`
-      await writeFile(temp, snapshot, 'utf8')
-      await rename(temp, statePath)
-      seen = stamp()
-    }).catch(error => { warn('ds-bot: state write failed: %s', error) })
-    return writing
+      try {
+        await mkdir(home, { recursive: true })
+        const ensureLock = () => {
+          if (lockBroken) return
+          if (!lock.owns()) {
+            const error = new Error('ds-bot lost the state lock to another dsh')
+            error.code = 'ELOCKLOST'
+            throw error
+          }
+        }
+        ensureLock()
+        await writeFile(temp, snapshot, 'utf8')
+        ensureLock()
+        await rename(temp, statePath)
+        seen = stamp()
+        rt.capabilitiesStateSaved?.()
+      } catch (error) {
+        await unlink(temp).catch(() => {})
+        throw error
+      }
+    })
+    writing = run.catch(() => {})
+    return run.catch(error => {
+      warn('ds-bot: state write failed: %s', error)
+      throw error
+    })
   }
 
-  ctx.effect(() => () => lock.release(), 'ds-bot: state lock')
+  ctx.effect(() => () => {
+    stopped = true
+    return writing.finally(() => lock.release())
+  }, 'ds-bot: state lock')
 
   const botOf = id => (id === undefined ? undefined : state.bots[id])
   const roomOf = id => (id === undefined ? undefined : state.rooms[id])
@@ -233,7 +328,10 @@ export function install(rt) {
     delete room.sessions[botId]
     if (room.segments !== undefined) delete room.segments[botId]
     groupOwners.delete(sessionId)
-    void ctx.workspaceRegistry.archiveSession(sessionId).catch(() => {})
+    rt.cancelApprovals?.(sessionId)
+    // A plain archive refuses a running Session, which would go on working for a group
+    // that no longer has it.
+    void ctx.workspaceRegistry.archiveSession(sessionId, { stopActivity: true }).catch(() => {})
   }
   const findBot = (ref) => {
     if (ref === undefined) return undefined

package/src/host/time-context.js

@@ -0,0 +1,46 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+
+const SOURCE = 'ds-bot-time-context'
+const isClock = source => source?.kind === SOURCE || source?.kind === 'time-context'
+
+export function install(rt) {
+  const { ctx, config } = rt
+  const interval = config.timeRefreshIntervalMs ?? 600_000
+  if (!Number.isSafeInteger(interval) || interval < 0) throw new TypeError('timeRefreshIntervalMs must be a non-negative safe integer')
+  const formatter = new Intl.DateTimeFormat('en-CA', {
+    ...(config.timeZone ? { timeZone: config.timeZone } : {}),
+    year: 'numeric', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23',
+    timeZoneName: 'longOffset',
+  })
+  const zone = formatter.resolvedOptions().timeZone
+
+  ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+    const decision = await next()
+    if (decision.kind === 'reject' || signal.aborted) return decision
+    await rt.load()
+    if (!rt.isBotSession(agent.id) || signal.aborted) return decision
+    // A loaded DSH clock covers every step itself. Its listener may run before or
+    // after this one (a reload reorders them), so its presence is read from its
+    // projection, not from the messages added so far.
+    if (ctx.get?.('sessionProjections')?.stateOf(agent.session, 'timeContext') !== undefined) return decision
+    if (decision.messages.some(message => isClock(message.source))) return decision
+    const now = Date.now()
+    for await (const event of rt.eventsBackwards(agent.id, signal, Infinity)) {
+      if (event.type === 'user/message' && isClock(event.data.source)) {
+        if (now >= event.time && now - event.time < interval) return decision
+        break
+      }
+      if (event.time <= now - interval) break
+    }
+    if (signal.aborted) return decision
+    const text = `Current time: ${formatter.format(now)} (${zone}).`
+    return {
+      ...decision,
+      messages: [...decision.messages, createUserMessage({
+        content: [{ type: 'text', text }],
+        source: { kind: SOURCE, form: 'snapshot', sections: [{ name: SOURCE, text }] },
+      })],
+    }
+  }, { prepend: true })
+}