@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.
@@ -0,0 +1,214 @@
1
+ /**
2
+ * Session controls from a room: model, reasoning effort, access mode and
3
+ * context use, picked from numbered lists.
4
+ */
5
+ import { defaultModelOf, effortChoices, effortName, findModel, modelName, pickedSelection, sessionModelOf } from './models.js'
6
+ import { controllerOf, currentPermission, permissionOptions, setPermission } from './sessions.js'
7
+
8
+ /** @returns `n` as a 1-based list index into `items`, or undefined. */
9
+ export function pick(items, value) {
10
+ const number = Number(value)
11
+ return Number.isSafeInteger(number) && number >= 1 && number <= items.length ? items[number - 1] : undefined
12
+ }
13
+
14
+ /** The room's session id, or undefined. */
15
+ export function sessionOf(bridge, roomId) {
16
+ const id = bridge.store().room(roomId)?.sessionId
17
+ return typeof id === 'string' ? id : undefined
18
+ }
19
+
20
+ /** The room session's live agent when it is loaded, or undefined. */
21
+ export function liveAgent(bridge, roomId) {
22
+ const sessionId = sessionOf(bridge, roomId)
23
+ return sessionId === undefined ? undefined : bridge.ctx.get('agents')?.get(sessionId)
24
+ }
25
+
26
+ /** @returns a compact token count, such as 1M or 12.3k. */
27
+ function formatTokens(value) {
28
+ if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return '?'
29
+ if (value >= 1_000_000) return `${Math.round(value / 100_000) / 10}M`
30
+ if (value >= 1000) return `${Math.round(value / 100) / 10}k`
31
+ return String(value)
32
+ }
33
+
34
+ /** @returns context use, such as "16.8k of 1M" or "16.8k used". */
35
+ function contextLabel({ used, windowSize }) {
36
+ if (used === undefined) return windowSize === undefined ? 'unknown' : `${formatTokens(windowSize)} window`
37
+ return windowSize === undefined ? `${formatTokens(used)} used` : `${formatTokens(used)} of ${formatTokens(windowSize)}`
38
+ }
39
+
40
+ /** Model, effort and access mode of a room's session. */
41
+ async function controls(bridge, roomId) {
42
+ const catalog = await bridge.modelCatalog.load()
43
+ const sessionId = sessionOf(bridge, roomId)
44
+ const current = await sessionModelOf(bridge.ctx, sessionId) ?? defaultModelOf(bridge.ctx)
45
+ const agent = liveAgent(bridge, roomId)
46
+ const mode = currentPermission(bridge.ctx, agent)
47
+ const modeName = permissionOptions(bridge.ctx).find((option) => option.value === mode)?.name ?? mode ?? '?'
48
+ return { catalog, current, mode, modeName }
49
+ }
50
+
51
+ /** Context window and last request size of a room's session. */
52
+ async function contextUse(bridge, roomId, current) {
53
+ let windowSize
54
+ try {
55
+ const llm = bridge.ctx.get('llm')
56
+ const resolve = llm?.resolveModelInfo ?? llm?.resolveModel
57
+ const info = current === undefined || resolve === undefined ? undefined : await resolve.call(llm, current.provider, current.model)
58
+ windowSize = info?.context?.contextWindow
59
+ } catch {
60
+ // Unknown.
61
+ }
62
+ if (windowSize === undefined) {
63
+ const catalog = await bridge.modelCatalog.load()
64
+ windowSize = findModel(catalog, current)?.model?.contextWindow
65
+ }
66
+ let used
67
+ const sessionId = sessionOf(bridge, roomId)
68
+ if (sessionId !== undefined) {
69
+ try {
70
+ const events = (await bridge.ctx.get('sessionQuery')?.readSurface(sessionId))?.events ?? []
71
+ for (let index = events.length - 1; index >= 0; index -= 1) {
72
+ const usage = events[index]?.type === 'assistant/message' ? (events[index].data?.usage ?? events[index].data?.message?.usage) : undefined
73
+ if (usage === undefined) continue
74
+ used = (usage.inputTokens ?? 0) + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
75
+ break
76
+ }
77
+ } catch {
78
+ // Unknown.
79
+ }
80
+ }
81
+ return { windowSize, used }
82
+ }
83
+
84
+ /** Apply a model selection the way the Web picker does, and remember it for /new. */
85
+ async function selectModel(bridge, roomId, selection) {
86
+ const store = bridge.store()
87
+ store.data.picks[roomId] = selection
88
+ await store.save()
89
+ const agent = await bridge.ensureAgent(roomId, { claim: true })
90
+ const controller = controllerOf(bridge.ctx)
91
+ if (typeof controller?.selectModel === 'function') {
92
+ await controller.selectModel({ sessionId: agent.session?.id ?? agent.id, ...selection })
93
+ return
94
+ }
95
+ agent.model.select(selection)
96
+ }
97
+
98
+ /** Handlers of the control commands, merged into the command table. */
99
+ export const CONTROL_HANDLERS = {
100
+ async menu(bridge, { roomId }) {
101
+ const { catalog, current, modeName } = await controls(bridge, roomId)
102
+ const context = await contextUse(bridge, roomId, current)
103
+ await bridge.notice(roomId, [
104
+ 'Session controls:',
105
+ `🤖 Model: ${modelName(catalog, current)} — !model`,
106
+ `🧠 Effort: ${effortName(catalog, current, 'Default')} — !effort`,
107
+ `🛡 Access: ${modeName} — !mode`,
108
+ `📚 Context: ${contextLabel(context)} — !context`,
109
+ ].join('\n'))
110
+ },
111
+
112
+ async model(bridge, { roomId }, args) {
113
+ const { catalog, current } = await controls(bridge, roomId)
114
+ if (catalog === undefined || catalog.groups.length === 0) {
115
+ await bridge.notice(roomId, 'No models are available right now.')
116
+ return
117
+ }
118
+ const [first, second] = args.split(/\s+/u).filter(Boolean)
119
+ if (first === undefined) {
120
+ await bridge.notice(roomId, [
121
+ `Model now: ${modelName(catalog, current)}`,
122
+ '',
123
+ ...catalog.groups.map((group, index) => `${index + 1}. ${group.name ?? group.id} (${group.models.length})${group.id === current?.provider ? ' ✅' : ''}`),
124
+ ...(catalog.failures.length > 0 ? ['', `Unavailable: ${catalog.failures.map((failure) => failure.name ?? failure.id).join(', ')}`] : []),
125
+ '',
126
+ '!model <n> lists the models of provider n.',
127
+ ].join('\n'))
128
+ return
129
+ }
130
+ const group = pick(catalog.groups, first)
131
+ if (group === undefined) {
132
+ await bridge.notice(roomId, `No provider ${first}; !model lists them.`)
133
+ return
134
+ }
135
+ if (second === undefined) {
136
+ await bridge.notice(roomId, [
137
+ `${group.name ?? group.id}:`,
138
+ ...group.models.map((model, index) => `${index + 1}. ${model.name ?? model.id}${group.id === current?.provider && model.id === current?.model ? ' ✅' : ''}`),
139
+ '',
140
+ `!model ${first} <n> switches this room's session to model n.`,
141
+ ].join('\n'))
142
+ return
143
+ }
144
+ const model = pick(group.models, second)
145
+ if (model === undefined) {
146
+ await bridge.notice(roomId, `No model ${second}; !model ${first} lists them.`)
147
+ return
148
+ }
149
+ await selectModel(bridge, roomId, pickedSelection(current, group.id, model))
150
+ await bridge.notice(roomId, `🤖 Model: ${model.name ?? model.id}`)
151
+ },
152
+
153
+ async effort(bridge, { roomId }, args) {
154
+ const { catalog, current } = await controls(bridge, roomId)
155
+ const model = findModel(catalog, current)?.model
156
+ const choices = effortChoices(model, 'Default')
157
+ if (choices.length === 0) {
158
+ await bridge.notice(roomId, 'This model has no effort setting.')
159
+ return
160
+ }
161
+ const effective = current?.reasoningEffort ?? model?.reasoning?.defaultEffort
162
+ if (args.length === 0) {
163
+ await bridge.notice(roomId, [
164
+ 'Reasoning effort:',
165
+ ...choices.map((choice, index) => `${index + 1}. ${choice.name}${choice.id === effective ? ' ✅' : ''}`),
166
+ '',
167
+ '!effort <n> picks one.',
168
+ ].join('\n'))
169
+ return
170
+ }
171
+ const choice = pick(choices, args.split(/\s+/u)[0])
172
+ if (choice === undefined || current === undefined) {
173
+ await bridge.notice(roomId, `No effort ${args}; !effort lists them.`)
174
+ return
175
+ }
176
+ await selectModel(bridge, roomId, { provider: current.provider, model: current.model, ...(choice.id === undefined ? {} : { reasoningEffort: choice.id }) })
177
+ await bridge.notice(roomId, `🧠 Effort: ${choice.name}`)
178
+ },
179
+
180
+ async mode(bridge, { roomId }, args) {
181
+ const options = permissionOptions(bridge.ctx)
182
+ const { mode } = await controls(bridge, roomId)
183
+ if (args.length === 0) {
184
+ await bridge.notice(roomId, [
185
+ 'Access mode of this session:',
186
+ ...options.map((option, index) => `${index + 1}. ${option.name}${option.value === mode ? ' ✅' : ''}`),
187
+ '',
188
+ '!mode <n> picks one.',
189
+ ].join('\n'))
190
+ return
191
+ }
192
+ const option = pick(options, args.split(/\s+/u)[0])
193
+ if (option === undefined) {
194
+ await bridge.notice(roomId, `No mode ${args}; !mode lists them.`)
195
+ return
196
+ }
197
+ setPermission(bridge.ctx, await bridge.ensureAgent(roomId, { claim: true }), option.value)
198
+ await bridge.notice(roomId, `🛡 Access: ${option.name}`)
199
+ },
200
+
201
+ async context(bridge, { roomId }) {
202
+ const { catalog, current, modeName } = await controls(bridge, roomId)
203
+ const context = await contextUse(bridge, roomId, current)
204
+ await bridge.notice(roomId, [
205
+ 'Context:',
206
+ `Model: ${modelName(catalog, current)}${current === undefined ? '' : ` (${current.provider}/${current.model})`}`,
207
+ `Window: ${formatTokens(context.windowSize)}`,
208
+ `Last request: ${context.used === undefined ? 'unknown' : formatTokens(context.used)}`,
209
+ `Effort: ${effortName(catalog, current, 'Default')}`,
210
+ `Access: ${modeName}`,
211
+ ].join('\n'))
212
+ },
213
+
214
+ }
package/src/events.js ADDED
@@ -0,0 +1,251 @@
1
+ /**
2
+ * Incoming events: invites, messages, reactions and Space changes, checked
3
+ * against the allowlist and handed to commands, prompts or the room's session.
4
+ */
5
+ import { randomUUID } from 'node:crypto'
6
+ import { join } from 'node:path'
7
+ import { parseCommand, runCommand } from './commands.js'
8
+ import { dataDir, POST_SOURCE_KIND, REQUEST_PREFIX } from './constants.js'
9
+ import { composePrompt, hasMedia, ownText, replyInfo, replyTargetOf } from './inbound.js'
10
+ import { allowedEntry } from './operations.js'
11
+ import { matrixUserPrincipal, withPrincipal } from './sender.js'
12
+ import { admitPrompt, hasRequest, recordMessage, unarchive } from './sessions.js'
13
+ import { clip } from './text.js'
14
+
15
+ /** @returns a short message for any thrown value. */
16
+ function messageOf(error) {
17
+ return error instanceof Error ? error.message : String(error?.message ?? error)
18
+ }
19
+
20
+ /**
21
+ * Create the event handlers.
22
+ * @param deps - `{ ctx, getStore, storeReady, getMatrix, setting, spaces, prompts, reactions, principals, titles, notice, roomState, ensureAgent, publishStatus, getBridge, reportError, info, warn, signal }`.
23
+ * @returns `{ onEvent, onInvite, onLeave }`.
24
+ */
25
+ export function createEvents({ ctx, getStore, storeReady, getMatrix, setting, spaces, prompts, reactions, principals, titles, notice, roomState, ensureAgent, publishStatus, getBridge, reportError, info, warn, signal }) {
26
+ /** Event ids being handled, so an event seen twice is handled once. */
27
+ const handling = new Set()
28
+
29
+ /** @returns `{ userId, name }` of an allowed sender, or undefined. */
30
+ function allowedSender(userId) {
31
+ const entry = allowedEntry(setting('allowedUsers', []), userId)
32
+ if (entry === undefined) return undefined
33
+ return { userId, name: String(entry.name ?? '').trim() || userId.slice(1, userId.indexOf(':')) }
34
+ }
35
+
36
+ /** Remember a room's name and its person's name for the session title. */
37
+ async function noteRoomIdentity(roomId, sender) {
38
+ const record = getStore().room(roomId)
39
+ let roomName = record?.roomName
40
+ if (roomName === undefined) {
41
+ roomName = (await getMatrix().getState(roomId, 'm.room.name').catch(() => undefined))?.name ?? ''
42
+ }
43
+ if (await getStore().describeRoom(roomId, { person: sender.name, roomName })) {
44
+ const sessionId = getStore().room(roomId)?.sessionId
45
+ if (typeof sessionId === 'string') await titles.apply(sessionId)
46
+ }
47
+ }
48
+
49
+ // ----------------------------------------------------------------- inbound
50
+
51
+ /**
52
+ * One timeline event of any joined room, decrypted when it could be.
53
+ * @param roomId - room id.
54
+ * @param event - raw event.
55
+ */
56
+ async function onEvent(roomId, event) {
57
+ await storeReady
58
+ const matrix = getMatrix()
59
+ if (matrix === undefined || event?.sender === matrix.userId) return
60
+ // The first sync of a new account carries old history, which is not new to the bot.
61
+ if (typeof event.origin_server_ts === 'number' && event.origin_server_ts < (getStore().data.since ?? 0)) return
62
+ try {
63
+ if (event.type === 'm.room.message') await onMessage(roomId, event)
64
+ else if (event.type === 'm.reaction') await onReaction(roomId, event)
65
+ else if (event.type === 'm.space.child') await spaces.onChild(roomId, event)
66
+ else if (event.type === 'm.room.power_levels') await retryWaitingSpace(roomId)
67
+ else if (event.type === 'm.room.name' && getStore().room(roomId) !== undefined) {
68
+ await getStore().describeRoom(roomId, { roomName: String(event.content?.name ?? '') })
69
+ const sessionId = getStore().room(roomId)?.sessionId
70
+ if (typeof sessionId === 'string') await titles.apply(sessionId)
71
+ }
72
+ } catch (error) {
73
+ reportError(`event ${event.event_id} in ${roomId}`, error)
74
+ }
75
+ }
76
+
77
+ /** A Space that waited for the bot's power level may be adoptable now. */
78
+ async function retryWaitingSpace(roomId) {
79
+ for (const [userId, record] of Object.entries(getStore().data.people)) {
80
+ if (record?.waitingSpace !== roomId) continue
81
+ if (await spaces.adoptSpace(userId, roomId)) await getStore().describePerson(userId, { waitingSpace: undefined })
82
+ }
83
+ }
84
+
85
+ /** An invite: allowed people get the bot, others are turned down. */
86
+ async function onInvite(roomId, event) {
87
+ await storeReady
88
+ const inviter = event?.sender
89
+ const sender = allowedSender(inviter)
90
+ if (sender === undefined) {
91
+ const first = await getStore().notePending({ userId: String(inviter ?? 'unknown'), roomId, kind: 'invite' })
92
+ if (first) info(`turned down an invite from ${inviter}; add them to allowedUsers to let them in`)
93
+ await getMatrix()?.leave(roomId).catch(() => {})
94
+ return
95
+ }
96
+ try {
97
+ await getMatrix().join(roomId)
98
+ await spaces.onJoinedByInvite(roomId, inviter)
99
+ info(`joined ${roomId} on ${inviter}'s invite`)
100
+ } catch (error) {
101
+ reportError(`invite to ${roomId}`, error)
102
+ }
103
+ }
104
+
105
+ /** The bot left or was removed: the room's session stays in DSH. */
106
+ async function onLeave(roomId) {
107
+ await storeReady
108
+ if (getStore().room(roomId) !== undefined) await getStore().forget(roomId)
109
+ }
110
+
111
+ /**
112
+ * One message: check the sender, run a command or hand the message to the
113
+ * room's session, then send a read receipt.
114
+ */
115
+ async function onMessage(roomId, event) {
116
+ const content = event.content ?? {}
117
+ if (content['m.relates_to']?.rel_type === 'm.replace' || handling.has(event.event_id)) return
118
+ const sender = allowedSender(event.sender)
119
+ if (sender === undefined) {
120
+ const first = await getStore().notePending({ userId: String(event.sender), roomId, kind: 'message' })
121
+ if (first) info(`ignored a message from ${event.sender}; add them to allowedUsers to let them in`)
122
+ return
123
+ }
124
+ let record = getStore().room(roomId)
125
+ // A room the bot is in without a record (state lost or made before) becomes the sender's.
126
+ if (record?.owner === undefined && (await getMatrix().getState(roomId, 'm.room.create'))?.type !== 'm.space') {
127
+ await spaces.onJoinedByInvite(roomId, sender.userId)
128
+ record = getStore().room(roomId)
129
+ }
130
+ // A room is one person's: other people's messages there are not prompts.
131
+ if (record?.owner !== sender.userId) return
132
+ handling.add(event.event_id)
133
+ try {
134
+ await noteRoomIdentity(roomId, sender)
135
+ await publishStatus({ lastMessageAt: Date.now(), lastRoomId: roomId })
136
+ roomState(roomId).lastInbound = event.event_id
137
+ const media = hasMedia(content)
138
+ if (!media && prompts.consumeReply(roomId, ownText(content))) {
139
+ await getMatrix().readReceipt(roomId, event.event_id).catch(() => {})
140
+ return
141
+ }
142
+ const command = media ? undefined : parseCommand(content)
143
+ if (command !== undefined) {
144
+ try {
145
+ await runCommand(getBridge(), { roomId, sender, eventId: event.event_id }, command)
146
+ } catch (error) {
147
+ await notice(roomId, `❌ ${messageOf(error)}`)
148
+ }
149
+ await getMatrix().readReceipt(roomId, event.event_id).catch(() => {})
150
+ return
151
+ }
152
+ if (!media && ownText(content).length === 0) return
153
+ try {
154
+ await dispatchPrompt(roomId, event, sender)
155
+ } catch (error) {
156
+ await notice(roomId, `❌ Your message did not reach the session: ${messageOf(error)}`)
157
+ throw error
158
+ }
159
+ await getMatrix().readReceipt(roomId, event.event_id).catch(() => {})
160
+ } finally {
161
+ handling.delete(event.event_id)
162
+ }
163
+ }
164
+
165
+ /**
166
+ * Hand a message to the room's session: into the running turn (`steer`) or
167
+ * after it (`queue`), with its sender, reply context and media. The message
168
+ * gets the working reaction first, so the sender sees at once that it was
169
+ * taken.
170
+ */
171
+ async function dispatchPrompt(roomId, event, sender) {
172
+ const room = roomState(roomId)
173
+ // Messages reach the session in the order they arrived.
174
+ while (room.admission !== undefined) await room.admission
175
+ let release
176
+ room.admission = new Promise((resolve) => { release = resolve })
177
+ const requestId = `${REQUEST_PREFIX}${roomId}:${event.event_id}`
178
+ const steer = setting('busyMessages', 'steer') !== 'queue'
179
+ let react = false
180
+ try {
181
+ const boundId = getStore().room(roomId)?.sessionId
182
+ const live = typeof boundId === 'string' ? ctx.get('agents')?.get(boundId) : undefined
183
+ // A message handed over before (a restart before its receipt) gets no new sign.
184
+ react = live === undefined || !hasRequest(live, requestId)
185
+ if (react) await reactions.mark(roomId, event.event_id, reactions.emojiFor(live?.status !== undefined && live.status !== 'idle', steer))
186
+ const replyTo = replyTargetOf(event.content)
187
+ const target = replyTo === undefined ? undefined : await getMatrix().getEvent(roomId, replyTo).catch(() => undefined)
188
+ const reply = replyInfo(target, { botId: getMatrix().userId, senderId: sender.userId, sentRecord: replyTo === undefined ? undefined : getStore().sentRecord(replyTo), names: { [sender.userId]: sender.name } })
189
+ const prompt = await composePrompt(event, {
190
+ download: (content) => getMatrix().download(content),
191
+ mediaDir: join(dataDir(), 'media'),
192
+ attachments: ctx.get('attachments'),
193
+ voice: {
194
+ mode: setting('transcriber', 'dsh'),
195
+ language: setting('transcribeLanguage', ''),
196
+ command: setting('transcribeCommand', []),
197
+ ffmpeg: setting('ffmpegPath', 'ffmpeg'),
198
+ speech: ctx.get('speech'),
199
+ },
200
+ signal: signal,
201
+ warn,
202
+ })
203
+ const agent = await ensureAgent(roomId)
204
+ const sessionId = agent.session?.id ?? agent.id
205
+ if (await unarchive(ctx, sessionId)) info(`unarchived session ${sessionId} for a message from room ${roomId}`)
206
+ const running = agent.status !== undefined && agent.status !== 'idle'
207
+ const mode = running && steer ? 'steer' : 'queue'
208
+ const principal = matrixUserPrincipal(sender.userId, { name: sender.name, roomId, room: getStore().room(roomId)?.roomName })
209
+ const envelope = {
210
+ ...(typeof event.origin_server_ts === 'number' ? { sentAt: event.origin_server_ts } : {}),
211
+ ...(reply === undefined ? {} : { replyTo: reply }),
212
+ }
213
+ const metadata = { principal, ...(Object.keys(envelope).length === 0 ? {} : { envelope }) }
214
+ principals.remember(requestId, metadata)
215
+ const admitted = await admitPrompt(ctx, agent, { requestId, text: prompt.text, attachments: prompt.attachments, mode, ...metadata }, signal)
216
+ if (!react) return
217
+ if (admitted) reactions.admitted(event.event_id)
218
+ else await reactions.release([event.event_id])
219
+ } catch (error) {
220
+ if (react) await reactions.release([event.event_id]).catch(() => {})
221
+ throw error
222
+ } finally {
223
+ room.admission = undefined
224
+ release()
225
+ }
226
+ }
227
+
228
+ /**
229
+ * A reaction: the answer to a question or approval, otherwise noted in the
230
+ * room's session.
231
+ */
232
+ async function onReaction(roomId, event) {
233
+ const relation = event.content?.['m.relates_to']
234
+ if (relation?.rel_type !== 'm.annotation' || typeof relation.event_id !== 'string') return
235
+ const sender = allowedSender(event.sender)
236
+ if (sender === undefined || getStore().room(roomId)?.owner !== sender.userId) return
237
+ if (prompts.onReaction(roomId, relation.event_id, String(relation.key ?? ''))) return
238
+ const sessionId = getStore().room(roomId)?.sessionId
239
+ const agent = typeof sessionId === 'string' ? ctx.get('agents')?.get(sessionId) : undefined
240
+ if (agent === undefined) return
241
+ const target = await getMatrix().getEvent(roomId, relation.event_id).catch(() => undefined)
242
+ if (target === undefined) return
243
+ const owner = target.sender === getMatrix().userId ? 'your message' : 'the message'
244
+ const text = `[Matrix: ${sender.name} reacted ${relation.key} to ${owner} ${relation.event_id}:]\n${clip(ownText(target.content), 500)}`
245
+ const message = { id: randomUUID(), role: 'user', content: [{ type: 'text', text }], source: { kind: POST_SOURCE_KIND, form: 'notice', summary: clip(`${sender.name} reacted ${relation.key}`, 120) } }
246
+ recordMessage(agent, withPrincipal(message, matrixUserPrincipal(sender.userId, { name: sender.name, roomId })))
247
+ }
248
+
249
+
250
+ return { onEvent, onInvite, onLeave }
251
+ }
package/src/helpers.js ADDED
@@ -0,0 +1,179 @@
1
+ /**
2
+ * Helper activity: subagents started under a room's session are shown in one
3
+ * status message, edited in place as they start and finish and left as it is
4
+ * once all of them are done. `/agents` lists a session's helpers on demand.
5
+ */
6
+ import { sessionModelOf } from './models.js'
7
+ import { recentAssistantTexts } from './sessions.js'
8
+ import { clip } from './text.js'
9
+
10
+ /** Pause that lets several starts or ends share one edit. */
11
+ const EDIT_DELAY_MS = 1500
12
+ /** Parent links followed from a helper up to the room's session. */
13
+ const MAX_DEPTH = 8
14
+ /** Helpers `/agents` lists at most. */
15
+ const LIST_LIMIT = 8
16
+
17
+ /** @returns minutes between two times, as shown in the status message. */
18
+ function minutes(from, to) {
19
+ const value = Math.floor((to - from) / 60_000)
20
+ return value < 1 ? '<1 min' : `${value} min`
21
+ }
22
+
23
+ /**
24
+ * The status text of one room's helpers.
25
+ * @param helpers - helper records in start order.
26
+ * @param now - current time in ms.
27
+ */
28
+ export function boardText(helpers, now) {
29
+ const running = helpers.filter((helper) => helper.endedAt === undefined)
30
+ const count = (n) => `${n} helper${n === 1 ? '' : 's'}`
31
+ const head = running.length > 0 ? `🤖 ${count(running.length)} working:` : `🤖 ${count(helpers.length)} done:`
32
+ const lines = helpers.map((helper) => {
33
+ const model = helper.model ? `${helper.model}, ` : ''
34
+ if (helper.endedAt === undefined) return `⏳ ${helper.label} (${model}${minutes(helper.startedAt, now)})`
35
+ const failed = helper.stopReason !== undefined && helper.stopReason !== 'completed'
36
+ return `${failed ? '✗' : '✓'} ${helper.label} (${model}${minutes(helper.startedAt, helper.endedAt)}${failed ? `, ${helper.stopReason}` : ''})`
37
+ })
38
+ return [head, ...lines].join('\n')
39
+ }
40
+
41
+ /**
42
+ * Create the helper tracker.
43
+ * @param deps - `{ ctx, getStore, isRunning, outbound, currentTurn, reportError, now }`.
44
+ * @returns `{ onStart, onEnd, list, dispose }`.
45
+ */
46
+ export function createHelpers({ ctx, getStore, isRunning, outbound, currentTurn, reportError, now = Date.now }) {
47
+ const { queueOut, sendText, editText } = outbound
48
+ /** Open status messages by room id: `{ messageId, helpers: Map<runId, helper>, timer }`. */
49
+ const boards = new Map()
50
+
51
+ /** @returns the room whose session started this helper (directly or through other helpers). */
52
+ function roomOfHelper(childId) {
53
+ const agents = ctx.get('agents')
54
+ const store = getStore()
55
+ let sessionId = agents?.get(childId)?.session?.header?.parentSession
56
+ for (let depth = 0; depth < MAX_DEPTH && typeof sessionId === 'string'; depth += 1) {
57
+ const roomId = store?.roomOfSession(sessionId)
58
+ if (roomId !== undefined) return { roomId, sessionId }
59
+ sessionId = agents?.get(sessionId)?.session?.header?.parentSession
60
+ }
61
+ return undefined
62
+ }
63
+
64
+ /**
65
+ * Fill in labels from the parents' catalogs. A child can be announced
66
+ * before its parent's catalog lists it, so this runs at every publish until
67
+ * the label is found; meanwhile the id stands in.
68
+ */
69
+ async function nameHelpers(helpers) {
70
+ for (const helper of helpers) {
71
+ if (helper.named) continue
72
+ try {
73
+ const children = await ctx.get('subagents')?.listChildren(helper.parentId)
74
+ const label = children?.find((child) => child.id === helper.id)?.label
75
+ if (typeof label === 'string' && label.trim()) {
76
+ helper.label = clip(label.trim(), 80)
77
+ helper.named = true
78
+ }
79
+ } catch {
80
+ // The catalog is optional.
81
+ }
82
+ }
83
+ }
84
+
85
+ /** Send or edit a room's status message after a short pause. */
86
+ function schedule(roomId, board) {
87
+ if (board.timer !== undefined) return
88
+ board.timer = setTimeout(() => {
89
+ board.timer = undefined
90
+ void queueOut(roomId, () => publish(roomId, board)).catch((error) => reportError(`helpers in room ${roomId}`, error))
91
+ }, EDIT_DELAY_MS)
92
+ board.timer.unref?.()
93
+ }
94
+
95
+ /** Bring the status message up to date; a finished board is left as it is. */
96
+ async function publish(roomId, board) {
97
+ if (!isRunning()) return
98
+ const helpers = [...board.helpers.values()]
99
+ await nameHelpers(helpers)
100
+ const text = boardText(helpers, now())
101
+ const done = helpers.every((helper) => helper.endedAt !== undefined)
102
+ if (done && boards.get(roomId) === board) boards.delete(roomId)
103
+ if (board.messageId !== undefined) {
104
+ try {
105
+ await editText(roomId, board.messageId, text, { plain: true })
106
+ return
107
+ } catch (error) {
108
+ // Without edits the new state goes out as its own message.
109
+ reportError(`editing helper status ${board.messageId}`, error)
110
+ }
111
+ }
112
+ const [messageId] = await sendText(roomId, text, { plain: true })
113
+ board.messageId = messageId
114
+ }
115
+
116
+ /**
117
+ * A helper started (`subagent/start`).
118
+ * @param info - `{ runId, id, local }`.
119
+ */
120
+ async function onStart(info) {
121
+ const found = roomOfHelper(info?.id)
122
+ if (found === undefined) return
123
+ const { roomId, sessionId } = found
124
+ const turn = currentTurn(sessionId)
125
+ let board = boards.get(roomId)
126
+ // Helpers show where the session's answers show.
127
+ if (board === undefined && !(turn !== undefined && (turn.ours || turn.goal || turn.mirrored))) return
128
+ if (board === undefined) {
129
+ board = { messageId: undefined, helpers: new Map(), timer: undefined }
130
+ boards.set(roomId, board)
131
+ }
132
+ const parentId = ctx.get('agents')?.get(info.id)?.session?.header?.parentSession ?? sessionId
133
+ const helper = { id: info.id, parentId, label: `helper ${String(info.id).slice(0, 8)}`, named: false, model: '', startedAt: now(), endedAt: undefined, stopReason: undefined }
134
+ board.helpers.set(info.runId, helper)
135
+ helper.model = (await sessionModelOf(ctx, info.id).catch(() => undefined))?.model ?? ''
136
+ schedule(roomId, board)
137
+ }
138
+
139
+ /**
140
+ * A helper finished (`subagent/end`).
141
+ * @param info - `{ runId, id, stopReason }`.
142
+ */
143
+ function onEnd(info) {
144
+ for (const [roomId, board] of boards) {
145
+ const helper = board.helpers.get(info?.runId)
146
+ if (helper === undefined) continue
147
+ helper.endedAt = now()
148
+ helper.stopReason = info.stopReason
149
+ schedule(roomId, board)
150
+ return
151
+ }
152
+ }
153
+
154
+ /**
155
+ * The helpers of a session for `/agents`, newest last, with each one's last report.
156
+ * @param sessionId - the room's session.
157
+ * @returns `[{ id, label, running, createdAt, report }]`.
158
+ */
159
+ async function list(sessionId) {
160
+ const children = await ctx.get('subagents')?.listChildren(sessionId)
161
+ if (!Array.isArray(children)) return undefined
162
+ const result = []
163
+ for (const child of children.slice(-LIST_LIMIT)) {
164
+ const agent = ctx.get('agents')?.get(child.id)
165
+ const running = agent !== undefined && agent.status !== undefined && agent.status !== 'idle'
166
+ const [report = ''] = await recentAssistantTexts(ctx, child.id, 1)
167
+ result.push({ id: child.id, label: child.label || `helper ${String(child.id).slice(0, 8)}`, running, createdAt: child.createdAt, report })
168
+ }
169
+ return result
170
+ }
171
+
172
+ /** Stop pending edits. */
173
+ function dispose() {
174
+ for (const board of boards.values()) if (board.timer !== undefined) clearTimeout(board.timer)
175
+ boards.clear()
176
+ }
177
+
178
+ return { onStart, onEnd, list, dispose }
179
+ }