@soffits/dsh-matrix-bot 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/spool.js ADDED
@@ -0,0 +1,172 @@
1
+ /**
2
+ * File spool for requests from outside the Host process (the `dsh-matrix`
3
+ * command): a sender writes one request file, the running plugin handles it
4
+ * and writes a result file next to it. Senders need no network access to the
5
+ * Host, only write access to the DSH home, and requests wait while the bot is
6
+ * stopped.
7
+ */
8
+ import { randomUUID } from 'node:crypto'
9
+ import { watch } from 'node:fs'
10
+ import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
11
+ import { join } from 'node:path'
12
+ import { spoolDir } from './constants.js'
13
+
14
+ /** Result files older than this are removed by the plugin. */
15
+ const RESULT_TTL_MS = 24 * 60 * 60 * 1000
16
+
17
+ /**
18
+ * Write one request atomically.
19
+ * @param request - `{ op, ... }`.
20
+ * @param dir - spool directory.
21
+ * @returns the request id.
22
+ */
23
+ export async function enqueue(request, dir = spoolDir()) {
24
+ await mkdir(dir, { recursive: true, mode: 0o700 })
25
+ const id = `${Date.now()}-${randomUUID().slice(0, 8)}`
26
+ const temporary = join(dir, `${id}.tmp`)
27
+ await writeFile(temporary, JSON.stringify({ ...request, id, createdAt: Date.now() }) + '\n', { mode: 0o600 })
28
+ await rename(temporary, join(dir, `${id}.json`))
29
+ return id
30
+ }
31
+
32
+ /**
33
+ * Wait for the plugin's result for one request.
34
+ * @param id - request id from {@link enqueue}.
35
+ * @param timeoutMs - how long to wait.
36
+ * @param dir - spool directory.
37
+ * @returns the result document, or undefined after the timeout.
38
+ */
39
+ export async function waitForResult(id, timeoutMs, dir = spoolDir()) {
40
+ const path = join(dir, `${id}.result.json`)
41
+ const deadline = Date.now() + timeoutMs
42
+ for (;;) {
43
+ try {
44
+ const result = JSON.parse(await readFile(path, 'utf8'))
45
+ await rm(path, { force: true })
46
+ return result
47
+ } catch {
48
+ // Not written yet.
49
+ }
50
+ if (Date.now() >= deadline) return undefined
51
+ await new Promise((resolve) => setTimeout(resolve, 200))
52
+ }
53
+ }
54
+
55
+ /**
56
+ * Remove a request that was never picked up.
57
+ * @param id - request id.
58
+ * @param dir - spool directory.
59
+ * @returns true when it was still waiting and is gone now.
60
+ */
61
+ export async function withdraw(id, dir = spoolDir()) {
62
+ try {
63
+ await rm(join(dir, `${id}.json`))
64
+ return true
65
+ } catch {
66
+ return false
67
+ }
68
+ }
69
+
70
+ /**
71
+ * Plugin side: handle spooled requests one at a time.
72
+ * @param options - `{ handle, ready, onError, dir, intervalMs }`: `handle`
73
+ * resolves one request to its result; `ready` says whether requests can be
74
+ * handled now.
75
+ * @returns `{ start, stop, drain }`.
76
+ */
77
+ export function createSpool({ handle, ready, onError, dir = spoolDir(), intervalMs = 1000 }) {
78
+ let timer
79
+ let watcher
80
+ let draining
81
+ let again = false
82
+ let running = false
83
+
84
+ async function recover() {
85
+ for (const name of await readdir(dir).catch(() => [])) {
86
+ if (name.endsWith('.processing')) {
87
+ await rename(join(dir, name), join(dir, name.replace(/\.processing$/u, '.json'))).catch(() => {})
88
+ }
89
+ }
90
+ }
91
+
92
+ async function sweep(names) {
93
+ for (const name of names) {
94
+ if (!name.endsWith('.result.json')) continue
95
+ const path = join(dir, name)
96
+ const info = await stat(path).catch(() => undefined)
97
+ if (info !== undefined && Date.now() - info.mtimeMs > RESULT_TTL_MS) await rm(path, { force: true })
98
+ }
99
+ }
100
+
101
+ async function drainOnce() {
102
+ if (!ready()) return
103
+ const names = (await readdir(dir).catch(() => [])).sort()
104
+ await sweep(names)
105
+ for (const name of names) {
106
+ if (!name.endsWith('.json') || name.endsWith('.result.json')) continue
107
+ if (!ready()) return
108
+ const id = name.slice(0, -'.json'.length)
109
+ const claimed = join(dir, `${id}.processing`)
110
+ try {
111
+ await rename(join(dir, name), claimed)
112
+ } catch {
113
+ continue
114
+ }
115
+ let outcome
116
+ try {
117
+ const request = JSON.parse(await readFile(claimed, 'utf8'))
118
+ outcome = { ok: true, result: await handle(request) }
119
+ } catch (error) {
120
+ outcome = { ok: false, error: typeof error?.message === 'string' ? error.message : String(error) }
121
+ }
122
+ try {
123
+ await writeFile(join(dir, `${id}.result.json`), JSON.stringify(outcome) + '\n', { mode: 0o600 })
124
+ await rm(claimed, { force: true })
125
+ } catch (error) {
126
+ onError(error)
127
+ }
128
+ }
129
+ }
130
+
131
+ function drain() {
132
+ if (draining !== undefined) {
133
+ again = true
134
+ return draining
135
+ }
136
+ draining = (async () => {
137
+ do {
138
+ again = false
139
+ await drainOnce()
140
+ } while (again)
141
+ })().catch(onError).finally(() => { draining = undefined })
142
+ return draining
143
+ }
144
+
145
+ async function start() {
146
+ if (running) return
147
+ running = true
148
+ await mkdir(dir, { recursive: true, mode: 0o700 })
149
+ await recover()
150
+ // Stopped while getting ready.
151
+ if (!running) return
152
+ try {
153
+ watcher = watch(dir, () => { void drain() })
154
+ watcher.on('error', () => {})
155
+ } catch {
156
+ // The interval still picks requests up.
157
+ }
158
+ timer = setInterval(() => { void drain() }, intervalMs)
159
+ timer.unref?.()
160
+ void drain()
161
+ }
162
+
163
+ function stop() {
164
+ running = false
165
+ if (timer !== undefined) clearInterval(timer)
166
+ timer = undefined
167
+ watcher?.close()
168
+ watcher = undefined
169
+ }
170
+
171
+ return { start, stop, drain }
172
+ }
package/src/state.js ADDED
@@ -0,0 +1,203 @@
1
+ /**
2
+ * Durable bot state: each person's Space, which DSH session each room is
3
+ * bound to, people who wrote without being allowed, what was sent on behalf
4
+ * of jobs and sessions (so a reply to it can say where it came from), and
5
+ * the bot's working reactions.
6
+ */
7
+ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
8
+ import { dirname, join } from 'node:path'
9
+ import { dataDir } from './constants.js'
10
+
11
+ /** Sent-message records kept for replies. */
12
+ const SENT_LIMIT = 500
13
+ /** Unknown senders remembered for the pending list. */
14
+ const PENDING_LIMIT = 50
15
+ /** Maps that make up the document. */
16
+ const MAPS = ['rooms', 'people', 'pending', 'picks', 'reactions']
17
+
18
+ /** @returns an empty state document. */
19
+ function emptyState() {
20
+ return { version: 1, ...Object.fromEntries(MAPS.map((key) => [key, {}])), sent: [] }
21
+ }
22
+
23
+ /**
24
+ * Read a JSON object, or undefined when the file is missing or broken.
25
+ * @param path - file path.
26
+ */
27
+ async function readJson(path) {
28
+ try {
29
+ const parsed = JSON.parse(await readFile(path, 'utf8'))
30
+ return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined
31
+ } catch {
32
+ return undefined
33
+ }
34
+ }
35
+
36
+ /**
37
+ * Open the state file.
38
+ * @param path - defaults to `<data dir>/state.json`.
39
+ * @returns the store.
40
+ */
41
+ export async function openState(path = join(dataDir(), 'state.json')) {
42
+ const loaded = await readJson(path)
43
+ const state = { ...emptyState(), ...(loaded ?? {}) }
44
+ for (const key of MAPS) {
45
+ if (state[key] === null || typeof state[key] !== 'object' || Array.isArray(state[key])) state[key] = {}
46
+ }
47
+ if (!Array.isArray(state.sent)) state.sent = []
48
+ let writing = Promise.resolve()
49
+
50
+ const store = {
51
+ path,
52
+ /** The raw document; mutate through the methods below. */
53
+ get data() {
54
+ return state
55
+ },
56
+ /** Write the document atomically; writes are serialized, and one that failed does not stop the next. */
57
+ save() {
58
+ writing = writing.catch(() => {}).then(async () => {
59
+ await mkdir(dirname(path), { recursive: true, mode: 0o700 })
60
+ const temporary = `${path}.${process.pid}.tmp`
61
+ await writeFile(temporary, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 })
62
+ await rename(temporary, path)
63
+ })
64
+ return writing
65
+ },
66
+
67
+ // ------------------------------------------------------------- people
68
+
69
+ /** @returns a person's record (`{ spaces, lobbyId }`), or undefined. */
70
+ person(userId) {
71
+ return state.people[userId]
72
+ },
73
+ /** @returns the person whose Space holds this room, or undefined. */
74
+ ownerOfSpace(spaceId) {
75
+ for (const [userId, record] of Object.entries(state.people)) {
76
+ if (record?.spaces?.includes(spaceId)) return userId
77
+ }
78
+ return undefined
79
+ },
80
+ /** Add a Space to a person; the newest is where new rooms go. */
81
+ async addSpace(userId, spaceId, fields = {}) {
82
+ const record = state.people[userId] ?? { spaces: [] }
83
+ record.spaces = [...(record.spaces ?? []).filter((id) => id !== spaceId), spaceId]
84
+ state.people[userId] = { ...record, ...fields }
85
+ await store.save()
86
+ },
87
+ /** Merge fields into a person's record. */
88
+ async describePerson(userId, fields) {
89
+ state.people[userId] = { spaces: [], ...(state.people[userId] ?? {}), ...fields }
90
+ await store.save()
91
+ },
92
+
93
+ // -------------------------------------------------------------- rooms
94
+
95
+ /** @returns the record of a room, or undefined. */
96
+ room(roomId) {
97
+ return state.rooms[roomId]
98
+ },
99
+ /** @returns the room bound to a session, or undefined. */
100
+ roomOfSession(sessionId) {
101
+ if (typeof sessionId !== 'string') return undefined
102
+ for (const [roomId, record] of Object.entries(state.rooms)) {
103
+ if (record?.sessionId === sessionId) return roomId
104
+ }
105
+ return undefined
106
+ },
107
+ /**
108
+ * Bind a room to a session; a session is shown in one room at a time, so
109
+ * another room bound to it loses the binding.
110
+ */
111
+ async bind(roomId, record) {
112
+ for (const [other, entry] of Object.entries(state.rooms)) {
113
+ if (other !== roomId && entry?.sessionId === record.sessionId) delete entry.sessionId
114
+ }
115
+ state.rooms[roomId] = { ...(state.rooms[roomId] ?? {}), ...record, updatedAt: Date.now() }
116
+ await store.save()
117
+ },
118
+ /**
119
+ * Merge fields into a room's record, saving only when something changed.
120
+ * @returns true when the record changed.
121
+ */
122
+ async describeRoom(roomId, fields) {
123
+ const record = state.rooms[roomId] ?? {}
124
+ if (Object.entries(fields).every(([key, value]) => record[key] === value)) return false
125
+ state.rooms[roomId] = { ...record, ...fields }
126
+ await store.save()
127
+ return true
128
+ },
129
+ /** Forget a room's session (the room keeps its other settings). */
130
+ async release(roomId) {
131
+ const record = state.rooms[roomId]
132
+ if (record === undefined) return undefined
133
+ const previous = record.sessionId
134
+ delete record.sessionId
135
+ await store.save()
136
+ return previous
137
+ },
138
+ /** Forget a room entirely (the bot left it). */
139
+ async forget(roomId) {
140
+ delete state.rooms[roomId]
141
+ await store.save()
142
+ },
143
+
144
+ // ------------------------------------------------------------ pending
145
+
146
+ /** Remember someone who wrote or invited without being allowed. @returns true the first time. */
147
+ async notePending(entry) {
148
+ const known = state.pending[entry.userId]
149
+ state.pending[entry.userId] = { ...entry, firstSeen: known?.firstSeen ?? Date.now(), lastSeen: Date.now(), count: (known?.count ?? 0) + 1 }
150
+ const keys = Object.keys(state.pending)
151
+ if (keys.length > PENDING_LIMIT) {
152
+ keys.sort((left, right) => state.pending[left].lastSeen - state.pending[right].lastSeen)
153
+ for (const key of keys.slice(0, keys.length - PENDING_LIMIT)) delete state.pending[key]
154
+ }
155
+ await store.save()
156
+ return known === undefined
157
+ },
158
+ /** Drop pending entries that are allowed now. */
159
+ async clearPending(userIds) {
160
+ let changed = false
161
+ for (const userId of userIds) {
162
+ if (state.pending[userId] === undefined) continue
163
+ delete state.pending[userId]
164
+ changed = true
165
+ }
166
+ if (changed) await store.save()
167
+ },
168
+
169
+ // --------------------------------------------------------------- sent
170
+
171
+ /** Record messages sent on someone's behalf. */
172
+ async noteSent(record) {
173
+ state.sent.push({ ...record, at: Date.now() })
174
+ if (state.sent.length > SENT_LIMIT) state.sent.splice(0, state.sent.length - SENT_LIMIT)
175
+ await store.save()
176
+ },
177
+ /** @returns the send record holding an event id, or undefined. */
178
+ sentRecord(eventId) {
179
+ for (let index = state.sent.length - 1; index >= 0; index -= 1) {
180
+ if (state.sent[index].eventIds?.includes(eventId)) return state.sent[index]
181
+ }
182
+ return undefined
183
+ },
184
+
185
+ // ---------------------------------------------------------- reactions
186
+
187
+ /** @returns target event id → `{ roomId, reactionId }` of the bot's working reactions. */
188
+ reactions() {
189
+ return { ...state.reactions }
190
+ },
191
+ /** Remember the working reaction the bot put on a message. */
192
+ async noteReaction(eventId, entry) {
193
+ state.reactions[eventId] = entry
194
+ await store.save()
195
+ },
196
+ /** Forget working reactions that were removed. */
197
+ async dropReactions(eventIds) {
198
+ for (const eventId of eventIds) delete state.reactions[eventId]
199
+ await store.save()
200
+ },
201
+ }
202
+ return store
203
+ }
package/src/text.js ADDED
@@ -0,0 +1,125 @@
1
+ /**
2
+ * Text going between DSH and Matrix: the answer a turn leaves, Markdown
3
+ * rendered to the HTML Matrix clients show, splitting, and the silent marker.
4
+ */
5
+ import MarkdownIt from 'markdown-it'
6
+ import { MAX_MESSAGE_TEXT, SILENT_REPLY } from './constants.js'
7
+
8
+ /** Raw HTML in answers is escaped: clients get only what Markdown makes. */
9
+ const markdown = new MarkdownIt({ html: false, linkify: true, breaks: true })
10
+
11
+ /**
12
+ * The answer one assistant message holds: the last text block of a message
13
+ * that called no tool. Text written between tool calls is working narration,
14
+ * not part of the answer; a message that called a tool is mid-chain.
15
+ * @param message - an assistant message (`{ content: [...] }`).
16
+ * @returns the answer, or '' when the message holds none.
17
+ */
18
+ export function messageAnswer(message) {
19
+ const content = Array.isArray(message?.content) ? message.content : []
20
+ if (content.some((block) => block?.type === 'tool-call')) return ''
21
+ const texts = content
22
+ .filter((block) => block?.type === 'text' && typeof block.text === 'string')
23
+ .map((block) => block.text.trim())
24
+ .filter((text) => text.length > 0)
25
+ return texts.at(-1) ?? ''
26
+ }
27
+
28
+ /**
29
+ * Remove the silent marker from the end of an answer.
30
+ * @param text - final answer.
31
+ * @returns `{ text, silent }`: the rest of the text and whether the marker was there.
32
+ */
33
+ export function stripSilent(text) {
34
+ const trimmed = String(text ?? '').trim()
35
+ if (!trimmed.endsWith(SILENT_REPLY)) return { text: trimmed, silent: false }
36
+ return { text: trimmed.slice(0, -SILENT_REPLY.length).trim(), silent: true }
37
+ }
38
+
39
+ /**
40
+ * Local image paths a Markdown answer shows inline (`![alt](/abs/path)` or a
41
+ * `file://` URL), outside code. Matrix clients cannot show them inline, so they
42
+ * are sent as files after the text.
43
+ * @param markdown - answer text.
44
+ * @returns absolute paths, without duplicates.
45
+ */
46
+ export function localImagePaths(markdown) {
47
+ const found = []
48
+ const pattern = /!\[[^\]]*\]\(\s*(?:<([^>\n]+)>|([^)\s]+))(?:\s+"[^"\n]*")?\s*\)/gu
49
+ let fenced = false
50
+ for (const line of String(markdown ?? '').split('\n')) {
51
+ if (/^\s*```/u.test(line)) {
52
+ fenced = !fenced
53
+ continue
54
+ }
55
+ if (fenced) continue
56
+ for (const match of line.split(/`[^`]*`/gu).join(' ').matchAll(pattern)) {
57
+ let target = (match[1] ?? match[2]).trim()
58
+ if (/^file:\/\//iu.test(target)) {
59
+ try {
60
+ target = decodeURIComponent(new URL(target).pathname)
61
+ } catch {
62
+ continue
63
+ }
64
+ }
65
+ if (target.startsWith('/') && !found.includes(target)) found.push(target)
66
+ }
67
+ }
68
+ return found
69
+ }
70
+
71
+ /**
72
+ * Render Markdown to the HTML of a Matrix message's `formatted_body`.
73
+ * @param text - Markdown.
74
+ * @returns HTML.
75
+ */
76
+ export function toHtml(text) {
77
+ return markdown.render(String(text ?? '')).trim()
78
+ }
79
+
80
+ /**
81
+ * Whether streamed text so far could still turn out to be only the silent
82
+ * marker, so it is not shown yet.
83
+ * @param text - streamed text.
84
+ */
85
+ export function mayBeSilent(text) {
86
+ const trimmed = String(text ?? '').trim()
87
+ return trimmed.length === 0 || SILENT_REPLY.startsWith(trimmed)
88
+ }
89
+
90
+ /**
91
+ * Split text into messages no longer than the limit, preferring paragraph,
92
+ * then line, then word boundaries.
93
+ * @param text - Markdown or plain text.
94
+ * @param limit - longest message.
95
+ * @returns non-empty parts.
96
+ */
97
+ export function splitText(text, limit = MAX_MESSAGE_TEXT) {
98
+ const parts = []
99
+ let rest = String(text ?? '').trim()
100
+ while (rest.length > limit) {
101
+ const window = rest.slice(0, limit)
102
+ let cut = window.lastIndexOf('\n\n')
103
+ if (cut < limit / 2) cut = window.lastIndexOf('\n')
104
+ if (cut < limit / 2) cut = window.lastIndexOf(' ')
105
+ if (cut < limit / 2) cut = limit
106
+ parts.push(rest.slice(0, cut).trim())
107
+ rest = rest.slice(cut).trim()
108
+ }
109
+ if (rest.length > 0) parts.push(rest)
110
+ return parts
111
+ }
112
+
113
+ /**
114
+ * Cut a preview to a length, on a word boundary when one is near.
115
+ * @param text - any text.
116
+ * @param max - longest result.
117
+ * @returns the preview, with an ellipsis when cut.
118
+ */
119
+ export function clip(text, max) {
120
+ const value = String(text ?? '').trim()
121
+ if (value.length <= max) return value
122
+ const cut = value.slice(0, max - 1)
123
+ const space = cut.lastIndexOf(' ')
124
+ return `${space > max * 0.6 ? cut.slice(0, space) : cut}…`
125
+ }
package/src/titles.js ADDED
@@ -0,0 +1,174 @@
1
+ /**
2
+ * Session titles of room sessions: `Matrix-<person>-<task>`. `person` is
3
+ * who the room is with (their name), `task` the conversation
4
+ * title DSH generates, or the room's name until there is one. DSH has no title
5
+ * hook, so a generated title is appended again with the prefix and the same
6
+ * source, which keeps automatic titling going.
7
+ */
8
+
9
+ /** Title source marker shared with the other chat bridges' formats. */
10
+ export const TITLE_SOURCE = 'Matrix'
11
+
12
+ /** Words taken from the first message when DSH's fallback title is the sender line. */
13
+ const FALLBACK_WORDS = 8
14
+
15
+ /** @returns one line of text, without the separator dashes doubling up. */
16
+ function clean(value) {
17
+ return String(value ?? '').replace(/\s+/gu, ' ').trim()
18
+ }
19
+
20
+ /**
21
+ * The full title.
22
+ * @param person - who the room is with.
23
+ * @param task - conversation title.
24
+ */
25
+ export function roomTitle(person, task) {
26
+ return `${TITLE_SOURCE}-${clean(person) || 'unknown'}-${clean(task)}`
27
+ }
28
+
29
+ /**
30
+ * The conversation part of a title, without a `Matrix-<person>-` prefix.
31
+ * @param title - current title.
32
+ * @param persons - names the prefix may carry (the current one and earlier ones).
33
+ */
34
+ export function taskOf(title, persons) {
35
+ const value = clean(title)
36
+ for (const person of persons) {
37
+ if (person === undefined || person === null) continue
38
+ const prefix = `${TITLE_SOURCE}-${clean(person) || 'unknown'}-`
39
+ if (value.startsWith(prefix)) return value.slice(prefix.length)
40
+ }
41
+ return value
42
+ }
43
+
44
+ /**
45
+ * A conversation title from the first message of a session, used when DSH's
46
+ * fallback title is the bot's sender line.
47
+ * @param events - session events.
48
+ * @returns a few words of the first message's own text, or ''.
49
+ */
50
+ export function firstMessageTask(events) {
51
+ for (const event of Array.isArray(events) ? events : []) {
52
+ if (event?.type !== 'user/message' || event.data?.source?.kind !== 'user') continue
53
+ const text = (event.data.content ?? []).filter((block) => block?.type === 'text').map((block) => block.text).join('\n')
54
+ const body = text.split('\n').filter((line) => !/^\[[^\]]*\]$/u.test(line.trim())).join(' ')
55
+ const words = clean(body).split(' ').filter(Boolean)
56
+ if (words.length > 0) return words.slice(0, FALLBACK_WORDS).join(' ')
57
+ }
58
+ return ''
59
+ }
60
+
61
+ /**
62
+ * Keep a bound session's title in the room format.
63
+ * @param options - `{ service, session, person, earlier, placeholder, previous, warn }`:
64
+ * the title service, the live session, who the room is with, names an older
65
+ * title may carry instead, the task shown before a conversation title
66
+ * exists, and the placeholder title the bot set earlier (so a renamed room
67
+ * moves it).
68
+ * @returns the placeholder title now set by the bot, or `previous`.
69
+ */
70
+ export function syncTitle({ service, session, person, earlier = [], placeholder, previous, warn }) {
71
+ if (service === undefined || session === undefined) return previous
72
+ let current
73
+ try {
74
+ current = service.get(session)
75
+ } catch (error) {
76
+ warn?.(`title not read for ${session.id}: ${error?.message ?? error}`)
77
+ return previous
78
+ }
79
+ const placeholderTitle = roomTitle(person, placeholder)
80
+ // A title someone typed stays; only the bot's own placeholder follows the room.
81
+ if (current === undefined || (current.source?.kind === 'user' && current.title === previous && previous !== placeholderTitle)) {
82
+ service.rename(session, placeholderTitle)
83
+ return placeholderTitle
84
+ }
85
+ if (current.source?.kind === 'user') return previous
86
+ let task = taskOf(current.title, [person, ...earlier])
87
+ if (current.source?.kind === 'fallback' && /^\[Matrix message from/u.test(task)) {
88
+ task = firstMessageTask(typeof session.snapshotEvents === 'function' ? session.snapshotEvents() : []) || placeholder
89
+ }
90
+ const wanted = roomTitle(person, task)
91
+ if (wanted !== current.title) {
92
+ session.append('session/title', {
93
+ title: wanted,
94
+ messageSeqs: Array.isArray(current.messageSeqs) ? [...current.messageSeqs] : [],
95
+ source: current.source,
96
+ })
97
+ }
98
+ return previous
99
+ }
100
+
101
+ /**
102
+ * Whether a session still shows the bot's placeholder, so its first
103
+ * conversation title should be generated.
104
+ * @param service - title service.
105
+ * @param session - live session.
106
+ * @param previous - the placeholder title the bot set.
107
+ */
108
+ export function showsPlaceholder(service, session, previous) {
109
+ try {
110
+ const current = service.get(session)
111
+ return current?.source?.kind === 'user' && current.title === previous
112
+ } catch {
113
+ return false
114
+ }
115
+ }
116
+
117
+ /**
118
+ * Titles of the sessions bound to rooms.
119
+ * @param deps - `{ ctx, getStore, warn }`.
120
+ * @returns `{ apply, start }`.
121
+ */
122
+ export function createTitles({ ctx, getStore, warn }) {
123
+ /** Sessions whose first conversation title is being generated. */
124
+ const requests = new Set()
125
+
126
+ /** Bring a bound session's title to `Matrix-<person>-<task>`. */
127
+ async function apply(sessionId) {
128
+ const store = getStore()
129
+ const roomId = store?.roomOfSession(sessionId)
130
+ const record = roomId === undefined ? undefined : store.room(roomId)
131
+ const session = ctx.get('agents')?.get(sessionId)?.session
132
+ if (record === undefined || session === undefined) return
133
+ try {
134
+ const person = record.person ?? record.roomName ?? roomId
135
+ const placeholder = record.roomName || 'Matrix room'
136
+ const placeholderTitle = syncTitle({
137
+ service: ctx.get('sessionTitle'),
138
+ session,
139
+ person,
140
+ earlier: record.titlePersons ?? [],
141
+ placeholder,
142
+ previous: record.placeholderTitle,
143
+ warn,
144
+ })
145
+ const titlePersons = [person, ...(record.titlePersons ?? []).filter((name) => name !== person)].slice(0, 5)
146
+ await store.describeRoom(roomId, { placeholderTitle, titlePersons })
147
+ } catch (error) {
148
+ warn(`title of ${sessionId} not set: ${error?.message ?? error}`)
149
+ }
150
+ }
151
+
152
+ /**
153
+ * Ask DSH for a session's first conversation title once it has a prompt
154
+ * and a model route, while it still shows the bot's placeholder: the
155
+ * placeholder is a user title, which stops automatic titling.
156
+ */
157
+ function start(sessionId) {
158
+ const store = getStore()
159
+ const roomId = store?.roomOfSession(sessionId)
160
+ const service = ctx.get('sessionTitle')
161
+ const session = ctx.get('agents')?.get(sessionId)?.session
162
+ if (roomId === undefined || session === undefined || typeof service?.refresh !== 'function' || requests.has(sessionId)) return
163
+ if (!showsPlaceholder(service, session, store.room(roomId)?.placeholderTitle)) return
164
+ const events = typeof session.snapshotEvents === 'function' ? session.snapshotEvents() : []
165
+ if (!events.some((event) => event?.type === 'user/message' && event.data?.source?.kind === 'user')) return
166
+ requests.add(sessionId)
167
+ Promise.resolve()
168
+ .then(() => service.refresh(session))
169
+ .catch((error) => warn(`title of ${sessionId} not generated: ${error?.message ?? error}`))
170
+ .finally(() => requests.delete(sessionId))
171
+ }
172
+
173
+ return { apply, start }
174
+ }