ds-bot 0.0.0-stage → 0.1.0

package/src/host/prompt.js

@@ -0,0 +1,67 @@
+// Prompt: one section whose text depends only on the rendering Session's own Bot
+// record, so the prefix stays byte-stable across turns and roster changes.
+
+const TEAM_RULES = [
+  '## How your Bot team works',
+  '- Every Bot is its own long-lived conversation with the user, with its own memory and computer.',
+  '- The team changes over time. Call list_bots whenever you need to know who exists; do not rely on memory.',
+  '- message_bot sends an asynchronous message to another Bot. Its reply arrives later as a new "[Reply from …]" message. Never wait, poll, or resend.',
+  '- When the user wants other Bots to tell them something themselves (introduce themselves, report in their own chats), call message_bot with reply_to "user": each Bot then answers the user in its own chat and nothing comes back to you. Do not relay those answers yourself.',
+  '- When a "[Message from …]" arrives, your final text in that turn is delivered back to that Bot automatically and the user does not see it. Answer it directly and briefly, as a list of facts. Never invent facts: say "not discussed yet" when you do not know.',
+  '- When a "[Message from … · the user sees your reply here]" arrives, your reply is shown to the user in your own chat and is not sent back. Talk to the user directly, as yourself.',
+  '- When a "[Reply from …]" arrives, tell the user the outcome if it matters to them.',
+  '- Chat like a teammate texting: short sentences, often two or three short messages instead of one long one, no headings. When the user asks for a deliverable (a plan, schedule, draft, or list), write it out in full in the chat; never claim you gave something you did not write. Mention other Bots by their exact name.',
+  '- Offer choices with ask_user (a tap-to-answer card) instead of long option lists in text. Calling it ends your turn at once, so write everything you want to say before the call, in the same reply. The answer arrives as the user\'s next message. Never use ask_user_question: it blocks you, and messages from other Bots would queue behind it.',
+  '- You may be in group chats with the user and other Bots. You speak in each group from a separate conversation of yours, apart from your own chat with the user. There your turn arrives as a "[Group chat …]" message that shows the speaking order, and your reply is posted to the group. In a group, read_own_chat shows your own chat (the group sees that you looked; share only what the group needs). In your own chat, read_group_chat shows what was said in a group. A group may have an admin, who steers it: the admin can call members with @Name, change the group with update_group, and start a new discussion there with post_to_group.',
+  '- When you need a key, token, or password, call request_secret: the user types it into a secure card and you never see it. Never ask the user to paste one into the chat. Use it through its environment variable ($DSH_SECRET_<NAME> in bash, $env:DSH_SECRET_<NAME> in PowerShell) and never print it. list_secrets shows which keys exist.',
+  '- web_search results say which search backend answered. If web_search fails, never guess URLs or present pages you remember as search results: use a browser tool if you have one, otherwise tell the user that search is unavailable and the reason it gave.',
+  '- Your conversations are long-lived. When one grows long, either its older messages are condensed in place into a summary you wrote (a "[Checkpoint N]" message), or it moves on to a fresh part that opens with a handoff note you wrote and your latest messages (a "[Handoff · part N]" message). What leaves your working context stays saved. When you need the exact earlier wording or a detail the summary or note does not show in full (a full path, a figure, every item of a complete list or a final summary), call read_own_chat with words to look for, or with part N to read the note that closed an earlier part; never fill such a detail in from memory. Each line it returns starts with an anchor such as [part 2 #1234 · 10-08 14:22]; pass the anchor as around to read what was said around it.',
+  '- Reply in the user\'s language.',
+].join('\n')
+
+const MAIN_RULES = [
+  '## You are the Main Bot (Chief of Staff)',
+  '- You run the user\'s Bot team: you decide who does what, create new Bots, and report back.',
+  '- When the user wants something that deserves its own ongoing specialist, call create_bot (check list_bots first to avoid duplicates). Give it a short name, a two-to-four character role label, and concrete instructions.',
+  '- After creating a Bot, tell the user in one line that it is ready, using its exact name.',
+  '- Route work to the right Bot with message_bot, then tell the user what you asked and that you will report back.',
+  '- Every Bot runs on one model of its own (list_bots shows it). Pass model to create_bot or update_bot only when the user names one; list_models gives the provider/model refs.',
+  '- Use update_bot to rename a Bot, change its role, color, model, or instructions when the user asks.',
+  '- You run the group chats too. create_group makes a group (you join it as its admin unless you name another); update_group changes any group\'s name, notice, members, admin, or reply mode; post_to_group posts into any group as you, which starts a round of replies the user reads there; delete_group archives a group, only when the user asks. list_bots shows every group.',
+  '- The team can have more than one Main Bot; list_bots marks them. They share these powers, so coordinate with them through message_bot.',
+].join('\n')
+
+export function install(rt) {
+  const { ctx } = rt
+
+  // A group Session renders exactly its Bot's text, so both share one cached prefix.
+  const promptFor = (id) => {
+    const self = rt.selfOf(id)
+    const bot = rt.botOf(self)
+    if (bot !== undefined) {
+      return [
+        '# Your identity',
+        `You are ${bot.name}, a Bot on the user's team in DS Bot.${bot.role ? ` Your role: ${bot.role}.` : ''}`,
+        bot.instructions ? `\n${bot.instructions}` : '',
+        '',
+        rt.isMain(self) ? `${MAIN_RULES}\n\n${TEAM_RULES}` : TEAM_RULES,
+      ].join('\n')
+    }
+    const room = rt.roomOf(id)
+    if (room !== undefined) {
+      return [
+        '# Group chat relay',
+        'This conversation is a group chat between the user and several Bots. You are only the relay, not a participant.',
+        'For every new user message: call group_relay exactly once with no arguments, then end your turn with an empty reply. Never add your own text.',
+      ].join('\n')
+    }
+    return ''
+  }
+
+  ctx.effect(() => ctx.systemPrompt.section({
+    name: 'bot-identity',
+    order: 640,
+    interpolate: false,
+    text: context => promptFor(context?.agent?.id),
+  }), 'ds-bot: identity section')
+}

package/src/host/roster.js

@@ -0,0 +1,397 @@
+// Roster: creating, changing, and deleting Bots and group chats, the Main Bot role, and
+// the first Main Bot of a new team.
+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'
+
+export function install(rt) {
+  const { ctx, config, home, defaults, state } = rt
+
+  let bootstrapping = null
+
+  async function ensureWorkspace() {
+    if (state.workspaceId && ctx.workspaceRegistry.get(state.workspaceId)) return state.workspaceId
+    const path = config.workspace ?? join(home, 'workspace')
+    await mkdir(path, { recursive: true })
+    const workspace = await ctx.workspaceRegistry.resolveByPath(path) ?? await ctx.workspaceRegistry.create(path, 'DS Bot')
+    state.workspaceId = workspace.id
+    await rt.save()
+    return workspace.id
+  }
+
+  async function createSession(title) {
+    // A Bot's tools run here too; while another dsh holds the team, a new Session would
+    // belong to no saved Bot.
+    const readOnly = rt.readOnly()
+    if (readOnly !== undefined) throw new Error(readOnly)
+    const workspaceId = await ensureWorkspace()
+    const { sessionId } = await ctx.sessionController.create({ workspaceId })
+    const agent = await rt.resolveAgent(sessionId)
+    await ctx.sessionTitle.rename(agent.session, title)
+    return sessionId
+  }
+
+  function cleanAvatar(input) {
+    if (input === null || typeof input !== 'object') return undefined
+    const avatar = {}
+    if (typeof input.shape === 'string' && /^[a-z][\w-]{0,31}$/.test(input.shape)) avatar.shape = input.shape
+    if (typeof input.image === 'string') {
+      if (!/^data:image\/(png|jpeg|webp|gif);base64,[A-Za-z0-9+/=]+$/.test(input.image)) throw new Error('Avatar images must be PNG, JPEG, WebP, or GIF')
+      if (input.image.length > MAX_AVATAR_IMAGE) throw new Error('Avatar image is too large')
+      avatar.image = input.image
+    }
+    return Object.keys(avatar).length > 0 ? avatar : undefined
+  }
+
+  const freshName = (base) => {
+    const stem = base.slice(0, 34)
+    if (!rt.findBot(stem)) return stem
+    let index = 2
+    while (rt.findBot(`${stem} ${index}`)) index += 1
+    return `${stem} ${index}`
+  }
+
+  // `pickModel` leaves the model to the user: the chat opens on a model card, and the
+  // 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, copyOf, pickModel = false }) {
+    const cleanName = String(botName ?? '').trim().slice(0, 40)
+    if (cleanName === '') throw new Error('A Bot needs a name')
+    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 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 } : {}),
+      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 } : {}) }
+      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
+  }
+
+  function sendKickoff(bot, { text, from }) {
+    void rt.deliver({ fromId: from ?? undefined, toId: bot.id, text, role: 'kickoff' })
+      .catch(error => rt.warn('ds-bot: kickoff failed: %s', error))
+  }
+
+  // The user wrote first, so the held greeting would only interrupt.
+  function dropKickoff(botId) {
+    const bot = rt.botOf(botId)
+    if (bot?.kickoff === undefined) return
+    delete bot.kickoff
+    void rt.save()
+  }
+
+  async function duplicateBot(id) {
+    const bot = rt.botOf(id)
+    if (bot === undefined) throw new Error('Unknown Bot')
+    const served = (await rt.catalog()).some(entry => entry.ref === bot.model)
+    return createBot({
+      name: freshName(`${bot.name} copy`),
+      role: bot.role,
+      instructions: bot.instructions,
+      color: bot.color,
+      avatar: bot.avatar,
+      model: served ? bot.model : undefined,
+      copyOf: bot.id,
+    })
+  }
+
+  async function updateBot(id, patch) {
+    const bot = rt.botOf(id)
+    if (bot === undefined) throw new Error('Unknown Bot')
+    if (patch.name !== undefined) {
+      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`)
+      bot.name = next
+      const agent = await rt.resolveAgent(rt.chatOf(id))
+      await ctx.sessionTitle.rename(agent.session, next)
+      await followMemberNames(Object.values(state.rooms).filter(room => room.members.includes(id)))
+    }
+    if (patch.role !== undefined) bot.role = String(patch.role).trim().slice(0, 24)
+    if (patch.instructions !== undefined) bot.instructions = String(patch.instructions).trim()
+    let modelChanged = false
+    if (patch.color !== undefined) {
+      if (patch.color === null) delete bot.color
+      else if (isColor(currentColor(patch.color))) bot.color = currentColor(patch.color)
+    }
+    if (patch.avatar !== undefined) {
+      const avatar = cleanAvatar(patch.avatar)
+      if (avatar) bot.avatar = avatar
+      else delete bot.avatar
+    }
+    if (patch.model !== undefined) {
+      if (patch.model === null || patch.model === '') delete bot.model
+      else bot.model = await rt.resolveModel(patch.model)
+      modelChanged = true
+    }
+    await rt.save()
+    if (modelChanged) await rt.applyModel(bot, { force: true })
+    if (bot.model && bot.kickoff !== undefined) {
+      const held = bot.kickoff
+      delete bot.kickoff
+      await rt.save()
+      sendKickoff(bot, held)
+    }
+    return bot
+  }
+
+  async function setFlags(id, { pinned, hidden }) {
+    const entry = rt.botOf(id) ?? rt.roomOf(id) ?? state.agents[id]
+    if (entry === undefined) throw new Error('Unknown conversation')
+    if (typeof pinned === 'boolean') entry.pinned = pinned
+    if (typeof hidden === 'boolean') entry.hidden = hidden
+    await rt.save()
+    return entry
+  }
+
+  // ---------------------------------------------------------------------------
+  // Group chat settings. The user and every Main Bot may change any group; a group's
+  // admin may change its own group but not delete it. Only a member can be admin.
+
+  const roomBusy = id => [...rt.roomProgress.values()].some(round => round.roomId === id)
+  const autoRoomName = members => ['You', ...members.map(id => rt.botOf(id)?.name).filter(Boolean)].join(', ')
+  const cleanNotice = text => String(text ?? '').trim().slice(0, ROOM_NOTICE_MAX)
+
+  function cleanRoomName(text, selfId) {
+    const next = unquote(text).replace(/\s+/g, ' ').slice(0, ROOM_NAME_MAX)
+    if (next !== '' && rt.findRooms(next).some(room => room.id !== selfId)) throw new Error(`Another group chat is already called "${next}"`)
+    return next
+  }
+
+  async function retitleRoom(room) {
+    try {
+      const agent = await rt.resolveAgent(room.id)
+      await ctx.sessionTitle.rename(agent.session, room.name)
+    } catch (error) {
+      rt.warn('ds-bot: group title for %s not updated: %s', room.name, error)
+    }
+  }
+
+  // Groups without a chosen name are named after their members, so they follow renames.
+  async function followMemberNames(rooms = Object.values(state.rooms)) {
+    for (const room of rooms) {
+      if (room.named) continue
+      const next = autoRoomName(room.members)
+      if (next === room.name) continue
+      room.name = next
+      await retitleRoom(room)
+    }
+  }
+
+  function checkMembers(members) {
+    if (members.length < 2) throw new Error('A group chat needs at least two Bots')
+    if (members.length > ROOM_MAX_MEMBERS) throw new Error(`A group chat holds at most ${ROOM_MAX_MEMBERS} Bots`)
+  }
+
+  async function createRoom({ members: memberIds = [], name: roomName, notice, mode, admin, createdBy } = {}) {
+    const members = [...new Set(memberIds)].filter(id => rt.botOf(id))
+    checkMembers(members)
+    const custom = cleanRoomName(roomName ?? '')
+    // A Main Bot leads the groups it makes; a group the user makes is led by a Main
+    // Bot member when it has one.
+    const adminId = admin !== undefined ? admin : (members.includes(createdBy) ? createdBy : members.find(rt.isMain) ?? null)
+    if (adminId !== null && !members.includes(adminId)) throw new Error('The admin must be a member of the group')
+    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,
+    }
+    await rt.save()
+    return state.rooms[id]
+  }
+
+  // `actorId` is the Bot asking, or undefined for the user. Returns what changed, in words.
+  async function updateRoom(id, patch, actorId) {
+    const room = rt.roomOf(id)
+    if (room === undefined) throw new Error('Unknown group chat')
+    const byMain = actorId === undefined || rt.isMain(actorId)
+    const byAdmin = !byMain && rt.isAdminOf(room, actorId)
+    if (!byMain && !byAdmin) throw new Error(`Only the user, a Main Bot, or the admin of "${room.name}" can change it`)
+    let members = Array.isArray(patch.members) ? [...new Set(patch.members)] : [...room.members]
+    for (const member of patch.add ?? []) if (!members.includes(member)) members.push(member)
+    members = members.filter(member => !(patch.remove ?? []).includes(member) && rt.botOf(member))
+    checkMembers(members)
+    let admin = room.admin ?? null
+    if (patch.admin !== undefined) {
+      admin = patch.admin || null
+      if (admin === null && byAdmin) throw new Error('Hand the admin role to another member instead of leaving the group without one')
+      if (admin !== null && !members.includes(admin)) throw new Error(`${rt.botOf(admin)?.name ?? 'That Bot'} must be a member to be the admin`)
+    }
+    if (admin !== null && !members.includes(admin)) {
+      if (byAdmin && admin === actorId) throw new Error('Hand the admin role to another member before leaving the group')
+      admin = null
+    }
+    if (patch.mode !== undefined && !ROOM_MODES.includes(patch.mode)) throw new Error(`Reply mode must be one of ${ROOM_MODES.join(', ')}`)
+    const name = patch.name === undefined ? undefined : cleanRoomName(patch.name, room.id)
+    const notice = patch.notice === undefined ? undefined : cleanNotice(patch.notice)
+
+    const changes = []
+    const names = ids => ids.map(member => rt.botOf(member)?.name).filter(Boolean).join(', ')
+    const added = members.filter(member => !room.members.includes(member))
+    const removed = room.members.filter(member => !members.includes(member))
+    if (added.length > 0) changes.push(`added ${names(added)}`)
+    if (removed.length > 0) changes.push(`removed ${names(removed)}`)
+    // A member who leaves and comes back starts from a fresh look at the log.
+    for (const member of removed) {
+      if (room.seen) delete room.seen[member]
+      rt.dropGroupSession(room, member)
+    }
+    room.members = members
+    if (admin !== (room.admin ?? null)) changes.push(admin ? `made ${rt.botOf(admin).name} the admin` : 'removed the admin')
+    room.admin = admin
+    if (patch.mode !== undefined && patch.mode !== room.mode) {
+      room.mode = patch.mode
+      changes.push(patch.mode === 'admin' ? 'plain messages now go to the admin first' : 'every member now replies in turn')
+    }
+    if (notice !== undefined && notice !== (room.notice ?? '')) {
+      room.notice = notice
+      changes.push(notice ? 'updated the notice' : 'cleared the notice')
+    }
+    const before = room.name
+    if (name !== undefined) {
+      if (name !== '') {
+        room.named = true
+        room.name = name
+      } else {
+        delete room.named
+      }
+    }
+    if (!room.named) room.name = autoRoomName(room.members)
+    if (room.name !== before) {
+      changes.push(`renamed it "${room.name}"`)
+      await retitleRoom(room)
+    }
+    await rt.save()
+    return { room, changes }
+  }
+
+  async function deleteRoom(id) {
+    const room = rt.roomOf(id)
+    if (room === undefined) throw new Error('Unknown group chat')
+    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(() => {})
+  }
+
+  // The first Main Bot is the sidebar tile. `replace` gives a Main Bot's place to
+  // another Bot in one step, so the team never has none; `primary` moves a Bot to the
+  // front and keeps the others.
+  async function setMain(id, main, { primary = false, replace } = {}) {
+    const bot = rt.botOf(id)
+    if (bot === undefined) throw new Error('Unknown Bot')
+    const others = state.mainBotIds.filter(other => other !== id)
+    let next
+    if (!main) {
+      if (!rt.isMain(id)) return
+      if (others.length === 0) throw new Error('The team needs at least one Main Bot')
+      next = others
+    } else if (replace !== undefined && replace !== id) {
+      const at = others.indexOf(replace)
+      if (at === -1) throw new Error('Only a Main Bot can be replaced')
+      next = others.with(at, id)
+    } else if (primary) {
+      next = [id, ...others]
+    } else {
+      next = rt.isMain(id) ? state.mainBotIds : [...others, id]
+    }
+    // The sidebar shows every Main Bot, so a hidden Bot would vanish again once demoted.
+    if (main) delete bot.hidden
+    // A held setup greeting says "you are the Main Bot"; it must not go out after demotion.
+    for (const other of state.mainBotIds.filter(other => !next.includes(other))) {
+      if (rt.botOf(other)?.kickoff?.main) delete rt.botOf(other).kickoff
+    }
+    state.mainBotIds = next
+    await rt.save()
+  }
+
+  async function deleteBot(id) {
+    if (rt.botOf(id) === 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)])
+    delete state.bots[id]
+    for (const part of parts) {
+      delete state.questions[part]
+      delete state.exchangeTurns[part]
+    }
+    const touched = []
+    for (const room of Object.values(state.rooms)) {
+      if (!room.members.includes(id)) continue
+      room.members = room.members.filter(member => member !== id)
+      if (room.admin === id) room.admin = null
+      rt.dropGroupSession(room, id)
+      touched.push(room)
+    }
+    await followMemberNames(touched)
+    await rt.forgetBotSecrets(id)
+    await archived
+    await rt.save()
+    await ctx.workspaceRegistry.archiveSession(current).catch(() => {})
+  }
+
+  async function bootstrap() {
+    await rt.load()
+    void rt.syncModels()
+    if (state.mainBotIds.some(id => rt.botOf(id))) return
+    // Only the team's first Main Bot is stored as the DeepSeek whale; other Bots get a
+    // look from their id, and a Bot made Main Bot later keeps its own.
+    bootstrapping ??= createBot({ name: defaults.mainName, role: defaults.mainRole, main: true, color: 'deepseek', avatar: { shape: 'whale' }, pickModel: true })
+      .finally(() => { bootstrapping = null })
+    await bootstrapping
+  }
+
+  Object.assign(rt, {
+    ensureWorkspace, createSession, createBot, duplicateBot, updateBot, setFlags,
+    roomBusy, autoRoomName, retitleRoom, createRoom, updateRoom, deleteRoom,
+    setMain, deleteBot, bootstrap, dropKickoff,
+  })
+}

package/src/host/schedules.js

@@ -0,0 +1,151 @@
+// Scheduled tasks. DSH's schedule service stores each task with the Session it belongs
+// to and, when it is due, sends its prompt to that Session as a new message. This
+// module lists the team's tasks for Settings, creates and removes them there, and moves
+// a Bot's tasks along when its chat goes on in a fresh part, so the Bot keeps seeing
+// them. A group chat's task lives on the group's own Session, so the reminder reaches
+// the group like a message from the user (see reminderText). DSH 0.2.0 mounts the service only with its Automation tasks bundle on, so
+// the service is optional and every endpoint reports whether it is there.
+
+const MAX_TITLE = 120
+const TIME = /^([01]\d|2[0-3]):[0-5]\d$/
+
+const invalid = message => Object.assign(new Error(message), { code: 'bot/invalid' })
+
+// What a group sees of a due reminder: DSH frames it for one Session's model
+// ("[SCHEDULE REMINDER]" with JSON fields); the group gets each prompt as one line.
+export function reminderText(text) {
+  const prompts = []
+  const one = /^reminder_prompt_json: (.*)$/m.exec(text)
+  const batch = /^reminders_json: (.*)$/m.exec(text)
+  try {
+    if (one) prompts.push(JSON.parse(one[1]))
+    if (batch) for (const entry of JSON.parse(batch[1])) prompts.push(entry.reminder_prompt)
+  } catch {
+    // A framing this module cannot read goes to the group as it came.
+    return text
+  }
+  const lines = prompts.filter(prompt => typeof prompt === 'string' && prompt.trim() !== '')
+  return lines.length === 0 ? text : lines.map(prompt => `[Scheduled task] ${prompt}`).join('\n')
+}
+
+// The create request that gives a stored record its timing again, for a move.
+function requestOf(record) {
+  const base = { title: record.title, prompt: record.prompt }
+  if (record.kind === 'after' || record.kind === 'at') return { ...base, at: record.scheduledAt }
+  if (record.kind === 'every') return { ...base, every_seconds: record.everySeconds }
+  if (record.kind === 'daily') return { ...base, daily: { time: record.time, time_zone: record.timeZone } }
+  if (record.kind === 'weekly') return { ...base, weekly: { time: record.time, time_zone: record.timeZone, weekdays: record.weekdays } }
+  if (record.kind === 'cron') return { ...base, cron: { expression: record.expression, time_zone: record.timeZone } }
+  return null
+}
+
+// The settings form's timing as a create request selector.
+function selectorOf(when) {
+  const zone = typeof when?.timeZone === 'string' && when.timeZone !== '' ? when.timeZone : 'UTC'
+  switch (when?.kind) {
+    case 'at': {
+      const at = new Date(String(when.at ?? ''))
+      if (Number.isNaN(at.getTime())) throw invalid('Pick a date and time')
+      if (at.getTime() <= Date.now()) throw invalid('Pick a time in the future')
+      return { at: at.toISOString() }
+    }
+    case 'daily':
+      if (!TIME.test(String(when.time))) throw invalid('Pick a time of day')
+      return { daily: { time: `${when.time}:00`, time_zone: zone } }
+    case 'weekly': {
+      if (!TIME.test(String(when.time))) throw invalid('Pick a time of day')
+      const weekdays = [...new Set((Array.isArray(when.weekdays) ? when.weekdays : []).map(Number))].filter(day => Number.isInteger(day) && day >= 1 && day <= 7).sort()
+      if (weekdays.length === 0) throw invalid('Pick at least one day')
+      return { weekly: { time: `${when.time}:00`, time_zone: zone, weekdays } }
+    }
+    case 'every': {
+      const minutes = Number(when.minutes)
+      if (!Number.isInteger(minutes) || minutes < 1 || minutes > 7 * 24 * 60) throw invalid('Repeat every 1 minute to 7 days')
+      return { every_seconds: minutes * 60 }
+    }
+    default:
+      throw invalid('Pick when it runs')
+  }
+}
+
+export function install(rt) {
+  const { ctx, state } = rt
+  let service = null
+
+  const attach = (sub) => {
+    const own = sub.schedule
+    service = own
+    sub.effect(() => () => { if (service === own) service = null }, 'ds-bot: schedule service')
+  }
+  if (typeof ctx.inject === 'function') ctx.inject(['schedule'], attach)
+  else if (ctx.get?.('schedule') !== undefined) attach({ schedule: ctx.get('schedule'), effect: (execute, label) => ctx.effect(execute, label) })
+
+  // The Bot (and group chat) a task's Session speaks for, the group chat for a group's
+  // own Session, or nothing for a Session outside the team.
+  const ownerOf = (sessionId) => {
+    const chat = rt.chatOwners.get(sessionId)
+    if (chat !== undefined) return { botId: chat }
+    if (rt.roomOf(sessionId) !== undefined) return { roomId: sessionId }
+    return rt.groupOwners.get(sessionId) ?? rt.pastOwners.get(sessionId)
+  }
+  const known = owner => owner !== undefined && (owner.botId === undefined ? state.rooms[owner.roomId] !== undefined : state.bots[owner.botId] !== undefined)
+
+  async function schedulesView() {
+    if (service === null) return { available: false, tasks: [] }
+    const tasks = []
+    for (const entry of await service.catalog()) {
+      const owner = ownerOf(entry.sessionId)
+      if (!known(owner)) continue
+      tasks.push({ ...entry, ...owner })
+    }
+    return { available: true, tasks }
+  }
+
+  const endpoints = {
+    schedules: () => schedulesView(),
+    async 'schedule-create'(body) {
+      if (service === null) throw invalid('Automation tasks are off in DSH')
+      const bot = state.bots[body.target]
+      const room = state.rooms[body.target]
+      if (bot === undefined && room === undefined) throw invalid('No such Bot or group chat')
+      const title = String(body.title ?? '').trim()
+      const prompt = String(body.prompt ?? '').trim()
+      if (title === '') throw invalid('Give the task a name')
+      if (title.length > MAX_TITLE) throw invalid(`Keep the name under ${MAX_TITLE} characters`)
+      if (prompt === '') throw invalid('Say what the Bot should do')
+      await service.create(bot ? rt.chatOf(bot.id) : room.id, { title, prompt, ...selectorOf(body.when) })
+      return schedulesView()
+    },
+    async 'schedule-delete'(body) {
+      if (service === null) throw invalid('Automation tasks are off in DSH')
+      if (ownerOf(body.sessionId) === undefined) throw invalid('No such task')
+      await service.delete({ sessionId: body.sessionId, id: body.id })
+      return schedulesView()
+    },
+  }
+
+  // A fresh part takes over the earlier part's active tasks: each is created again on
+  // the fresh Session before the old one goes, so a failure leaves it where it was.
+  async function moveSchedules(fromId, toId) {
+    if (service === null) return
+    let records
+    try {
+      records = await service.list({ sessionId: fromId })
+    } catch (error) {
+      rt.warn('ds-bot: tasks of %s not moved: %s', fromId, error?.message ?? error)
+      return
+    }
+    for (const record of records) {
+      const request = requestOf(record)
+      if (request === null || (request.at !== undefined && Date.parse(request.at) <= Date.now())) continue
+      try {
+        await service.create(toId, request)
+        await service.delete({ sessionId: fromId, id: record.id })
+      } catch (error) {
+        rt.warn('ds-bot: task %s stayed with the earlier part: %s', record.title, error?.message ?? error)
+      }
+    }
+  }
+
+  Object.assign(rt, { scheduleEndpoint: (endpoint, body) => endpoints[endpoint](body ?? {}), moveSchedules })
+}