@soffits/dsh-matrix-bot 0.0.0-stage → 0.1.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/app.js ADDED
@@ -0,0 +1,446 @@
1
+ /** Host runtime: the Matrix connection, incoming events and the wiring of the parts. */
2
+ import { mkdir, writeFile } from 'node:fs/promises'
3
+ import { join } from 'node:path'
4
+ import { COMMANDS, SIGIL, helpText } from './commands.js'
5
+ import { dataDir, name, SERVICE_NAME } from './constants.js'
6
+ import { createEvents } from './events.js'
7
+ import { createHelpers } from './helpers.js'
8
+ import { connect as realConnect } from './matrix.js'
9
+ import { createModelCatalog } from './models.js'
10
+ import { createOperations } from './operations.js'
11
+ import { createOutbound } from './outbound.js'
12
+ import { createPrompts } from './prompts.js'
13
+ import { createReactions } from './reactions.js'
14
+ import { createPrincipalTagger } from './sender.js'
15
+ import { createSession, resolveAgent } from './sessions.js'
16
+ import { createSpaces } from './spaces.js'
17
+ import { createSpool } from './spool.js'
18
+ import { openState } from './state.js'
19
+ import { createTitles } from './titles.js'
20
+ import { createTurns } from './turns.js'
21
+
22
+ /**
23
+ * Read a Config field that may be a plain value or a volatile reference.
24
+ * @param value - Config field.
25
+ * @param fallback - value used when the field is absent.
26
+ */
27
+ export function readLive(value, fallback) {
28
+ if (value !== null && typeof value === 'object' && typeof value.get === 'function') {
29
+ try {
30
+ const current = value.get()
31
+ return current === undefined ? fallback : current
32
+ } catch {
33
+ return fallback
34
+ }
35
+ }
36
+ return value === undefined || value === null ? fallback : value
37
+ }
38
+
39
+ /** @returns a short message for any thrown value. */
40
+ export function messageOf(error) {
41
+ return error instanceof Error ? error.message : String(error?.message ?? error)
42
+ }
43
+
44
+ /** Shortest and longest pause before connecting again after a failure. */
45
+ const RETRY_MIN_MS = 5_000
46
+ const RETRY_MAX_MS = 5 * 60_000
47
+
48
+ /**
49
+ * Mount the bot.
50
+ * @param ctx - Host plugin context.
51
+ * @param config - live plugin configuration.
52
+ */
53
+ export function apply(ctx, config) {
54
+ createBridge(ctx, config, realConnect)
55
+ }
56
+
57
+ /**
58
+ * The bot with its Matrix side passed in, so tests can drive it with a fake.
59
+ * @param ctx - Host plugin context.
60
+ * @param config - live plugin configuration.
61
+ * @param connect - `connect(options)` from `matrix.js`, or a fake with the same shape.
62
+ */
63
+ export function createBridge(ctx, config, connect) {
64
+ // The Host keeps no plugin logger output, so lines also go to the process's
65
+ // own output, which is where an operator reads DSH's log.
66
+ const logger = typeof ctx.logger === 'function' ? ctx.logger('matrix') : ctx.logger
67
+ const info = (message) => {
68
+ logger?.info?.(message)
69
+ if (process.env.NODE_ENV !== 'test') console.log(`[dsh-matrix-bot] ${message}`)
70
+ }
71
+ const warn = (message) => {
72
+ logger?.warn?.(message)
73
+ if (process.env.NODE_ENV !== 'test') console.error(`[dsh-matrix-bot] ${message}`)
74
+ }
75
+ const setting = (field, fallback) => readLive(config[field], fallback)
76
+ const lifetime = new AbortController()
77
+
78
+ /** The connection while it runs (see `matrix.js`). */
79
+ let matrix
80
+ let starting
81
+ let retryTimer
82
+ let retryDelay = RETRY_MIN_MS
83
+ /** The account as configured when the running connection logged in. */
84
+ let account
85
+ /** The previous connection's stop; a new one waits for it, as both would use one crypto store. */
86
+ let stopped = Promise.resolve()
87
+ let disposed = false
88
+ let store
89
+ const storeReady = openState().then((opened) => { store = opened })
90
+ /** Live per-room state by room id. */
91
+ const rooms = new Map()
92
+ const modelCatalog = createModelCatalog(ctx)
93
+ const principals = createPrincipalTagger()
94
+ let status = { state: 'starting', updatedAt: new Date().toISOString() }
95
+
96
+ async function publishStatus(patch) {
97
+ status = { ...status, ...patch, updatedAt: new Date().toISOString() }
98
+ try {
99
+ await mkdir(dataDir(), { recursive: true, mode: 0o700 })
100
+ await writeFile(join(dataDir(), 'status.json'), JSON.stringify(status, null, 2) + '\n', { mode: 0o600 })
101
+ } catch {
102
+ // Diagnostics never take the runtime down.
103
+ }
104
+ }
105
+
106
+ function reportError(scope, error) {
107
+ warn(`${scope}: ${messageOf(error)}`)
108
+ void publishStatus({ lastError: { scope, detail: messageOf(error), at: new Date().toISOString() } })
109
+ }
110
+
111
+ function fireAndForget(scope, task) {
112
+ Promise.resolve().then(task).catch((error) => reportError(scope, error))
113
+ }
114
+
115
+ /** @returns the live state of one room. */
116
+ function roomState(roomId) {
117
+ let room = rooms.get(roomId)
118
+ if (room === undefined) {
119
+ room = { roomId, out: Promise.resolve(), lastInbound: undefined, admission: undefined, goalPhase: undefined }
120
+ rooms.set(roomId, room)
121
+ }
122
+ return room
123
+ }
124
+
125
+ function requireMatrix() {
126
+ if (matrix === undefined) throw new Error('The Matrix bot is not running.')
127
+ return matrix
128
+ }
129
+ const isRunning = () => matrix !== undefined
130
+ const getStore = () => store
131
+
132
+ const outbound = createOutbound({ requireMatrix, roomState, reportError, messageOf })
133
+ const { notice, queueOut, sendText } = outbound
134
+ const reactions = createReactions({ ctx, getStore, outbound, isRunning, reportError })
135
+ const turns = createTurns({
136
+ ctx,
137
+ getStore,
138
+ isRunning,
139
+ setting,
140
+ outbound,
141
+ reactions,
142
+ roomState,
143
+ publishStatus,
144
+ fireAndForget,
145
+ messageOf,
146
+ setTyping: async (roomId, typing, ms) => matrix?.setTyping(roomId, typing, ms),
147
+ })
148
+ const { currentTurn } = turns
149
+ const helpers = createHelpers({ ctx, getStore, isRunning, outbound, currentTurn, reportError })
150
+ const operations = createOperations({
151
+ ctx,
152
+ getStore,
153
+ storeReady,
154
+ requireMatrix,
155
+ getMatrix: () => matrix,
156
+ getStatus: () => status,
157
+ setting,
158
+ outbound,
159
+ currentTurn,
160
+ reportError,
161
+ messageOf,
162
+ })
163
+ const { sendToRoom, listRooms, allowUser, describe } = operations
164
+ const spaces = createSpaces({ requireMatrix, getStore, setting, notice, commands: COMMANDS, sigil: SIGIL, helpText, info, warn })
165
+ const titles = createTitles({ ctx, getStore, warn })
166
+
167
+ const prompts = createPrompts({
168
+ roomOfAgent: (agent) => {
169
+ const sessionId = agent.session?.id ?? agent.id
170
+ const roomId = store?.roomOfSession(sessionId)
171
+ if (roomId === undefined) return undefined
172
+ // Only turns started from Matrix ask there; others ask where they started.
173
+ return currentTurn(sessionId)?.ours === true ? roomId : undefined
174
+ },
175
+ send: (roomId, text) => notice(roomId, text),
176
+ react: (roomId, eventId, key) => outbound.react(roomId, eventId, key),
177
+ warn,
178
+ })
179
+
180
+ // ---------------------------------------------------------------- sessions
181
+
182
+ /**
183
+ * The live agent of a room's session, creating the session when the room
184
+ * has none.
185
+ * @param roomId - room id.
186
+ * @param options - `{ claim }`: end the blank state of a new session at once.
187
+ */
188
+ async function ensureAgent(roomId, { claim = false } = {}) {
189
+ await storeReady
190
+ const record = store.room(roomId)
191
+ if (typeof record?.sessionId === 'string') {
192
+ try {
193
+ const agent = await resolveAgent(ctx, record.sessionId)
194
+ prompts.attach(agent)
195
+ return agent
196
+ } catch (error) {
197
+ warn(`session ${record.sessionId} of room ${roomId} could not be resumed, starting a new one: ${messageOf(error)}`)
198
+ await store.release(roomId)
199
+ }
200
+ }
201
+ const cwd = record?.cwd ?? setting('cwd', process.cwd())
202
+ const preset = String(setting('agentPreset', '')).trim() || undefined
203
+ const model = store.data.picks[roomId]
204
+ const agent = await createSession(ctx, { cwd, preset, model, roomId, claim, warn })
205
+ const sessionId = agent.session?.id ?? agent.id
206
+ await store.bind(roomId, { sessionId, cwd })
207
+ await titles.apply(sessionId)
208
+ prompts.attach(agent)
209
+ info(`room ${roomId} now uses session ${sessionId}`)
210
+ return agent
211
+ }
212
+
213
+ const events = createEvents({
214
+ ctx,
215
+ getStore,
216
+ storeReady,
217
+ getMatrix: () => matrix,
218
+ setting,
219
+ spaces,
220
+ prompts,
221
+ reactions,
222
+ principals,
223
+ titles,
224
+ notice,
225
+ roomState,
226
+ ensureAgent,
227
+ publishStatus,
228
+ getBridge: () => bridge,
229
+ reportError,
230
+ info,
231
+ warn,
232
+ signal: lifetime.signal,
233
+ })
234
+ const { onEvent, onInvite, onLeave } = events
235
+
236
+ // ---------------------------------------------------------- send service
237
+
238
+ const service = {
239
+ send: (request = {}) => sendToRoom(request),
240
+ rooms: () => listRooms(),
241
+ }
242
+ if (typeof ctx.provide === 'function') ctx.provide(SERVICE_NAME, service)
243
+
244
+ // -------------------------------------------------------------- lifecycle
245
+
246
+ /** The login settings, or an error naming what is missing. */
247
+ function loginSettings() {
248
+ const homeserver = String(setting('homeserver', '')).trim()
249
+ const userId = String(setting('userId', '')).trim()
250
+ const passwordFile = String(setting('passwordFile', '')).trim()
251
+ const missing = [!homeserver && 'homeserver', !userId && 'userId', !passwordFile && 'passwordFile'].filter(Boolean)
252
+ if (missing.length > 0) throw new Error(`set ${missing.join(', ')} in the plugin settings`)
253
+ const recoveryKeyFile = String(setting('recoveryKeyFile', '')).trim() || join(dataDir(), 'recovery-key')
254
+ return { homeserver, userId, passwordFile, recoveryKeyFile, deviceName: String(setting('deviceName', 'DSH')) }
255
+ }
256
+
257
+ async function startRuntime() {
258
+ if (disposed || matrix !== undefined) return
259
+ if (setting('enabled', true) === false) {
260
+ await publishStatus({ state: 'disabled', detail: '' })
261
+ return
262
+ }
263
+ await publishStatus({ state: 'starting', detail: '' })
264
+ let connection
265
+ try {
266
+ await stopped
267
+ if (store.data.since === undefined) {
268
+ store.data.since = Date.now()
269
+ await store.save()
270
+ }
271
+ const login = loginSettings()
272
+ connection = await connect({ dir: join(dataDir(), 'account'), ...login, info, warn })
273
+ account = login.userId
274
+ if (disposed) {
275
+ stopped = Promise.resolve(connection.stop()).catch(() => {})
276
+ return
277
+ }
278
+ matrix = connection
279
+ await connection.start({
280
+ onEvent: (roomId, event) => onEvent(roomId, event),
281
+ onInvite: (roomId, event) => fireAndForget('invite', () => onInvite(roomId, event)),
282
+ onLeave: (roomId) => fireAndForget('leave', () => onLeave(roomId)),
283
+ })
284
+ await applyProfile()
285
+ retryDelay = RETRY_MIN_MS
286
+ const encryption = connection.encryption()
287
+ info(`running as ${connection.userId} (device ${connection.deviceId}; ${encryption.verified ? 'verified' : 'NOT verified'}, key backup ${encryption.backup ? 'on' : 'off'})`)
288
+ await publishStatus({ state: 'running', detail: '', userId: connection.userId, deviceId: connection.deviceId, encryption, startedAt: Date.now() })
289
+ spool.start().catch((error) => reportError('spool', error))
290
+ // Working reactions left by turns that ended while the bot was down.
291
+ await reactions.resume().catch((error) => reportError('reactions', error))
292
+ } catch (error) {
293
+ reportError('start', error)
294
+ await publishStatus({ state: 'error', detail: messageOf(error) })
295
+ if (matrix === undefined && connection !== undefined) stopped = Promise.resolve(connection.stop()).catch(() => {})
296
+ stopRuntime()
297
+ scheduleRetry()
298
+ }
299
+ }
300
+
301
+ /** Bring the account's name and picture to the settings. */
302
+ async function applyProfile() {
303
+ const displayName = String(setting('displayName', '')).trim()
304
+ const avatar = String(setting('avatar', '')).trim()
305
+ const newAvatar = avatar.length > 0 && store.data.avatar !== avatar ? avatar : undefined
306
+ try {
307
+ await matrix.setProfile({ displayName, avatar: newAvatar })
308
+ if (newAvatar !== undefined) {
309
+ store.data.avatar = newAvatar
310
+ await store.save()
311
+ }
312
+ } catch (error) {
313
+ reportError('profile', error)
314
+ }
315
+ }
316
+
317
+ function stopRuntime() {
318
+ const current = matrix
319
+ matrix = undefined
320
+ spool.stop()
321
+ if (current === undefined) return
322
+ stopped = Promise.resolve(current.stop()).catch((error) => reportError('stop', error))
323
+ void publishStatus({ state: disposed ? 'stopped' : 'restarting' })
324
+ }
325
+
326
+ function scheduleRetry() {
327
+ if (disposed || retryTimer !== undefined) return
328
+ const delay = retryDelay
329
+ retryDelay = Math.min(RETRY_MAX_MS, retryDelay * 2)
330
+ info(`connecting again in ${Math.round(delay / 1000)} s`)
331
+ retryTimer = setTimeout(() => {
332
+ retryTimer = undefined
333
+ void start()
334
+ }, delay)
335
+ retryTimer.unref?.()
336
+ }
337
+
338
+ function start() {
339
+ starting ??= startRuntime().finally(() => { starting = undefined })
340
+ return starting
341
+ }
342
+
343
+ async function restart(reason) {
344
+ info(`restart: ${reason}`)
345
+ await starting
346
+ stopRuntime()
347
+ await start()
348
+ }
349
+
350
+ /** Apply a settings change: start or stop, reconnect when the login changed. */
351
+ async function applySettings() {
352
+ if (setting('enabled', true) === false) {
353
+ stopRuntime()
354
+ await publishStatus({ state: 'disabled' })
355
+ return
356
+ }
357
+ if (matrix === undefined) {
358
+ await start()
359
+ return
360
+ }
361
+ if (account !== String(setting('userId', '')).trim()) {
362
+ await restart('the account changed')
363
+ return
364
+ }
365
+ await applyProfile()
366
+ await store.clearPending(setting('allowedUsers', []).map((entry) => entry?.userId).filter(Boolean))
367
+ }
368
+
369
+ // Requests from the `dsh-matrix` command.
370
+ const spool = createSpool({
371
+ ready: () => matrix !== undefined,
372
+ onError: (error) => reportError('spool', error),
373
+ handle: async (request) => {
374
+ if (request.op === 'send') return sendToRoom(request)
375
+ if (request.op === 'status') return describe()
376
+ if (request.op === 'rooms') return listRooms()
377
+ if (request.op === 'allow') return allowUser(request.userId, request.name)
378
+ throw new Error(`unknown request ${request.op}`)
379
+ },
380
+ })
381
+
382
+ /** What commands may use. */
383
+ const bridge = {
384
+ ctx,
385
+ setting,
386
+ store: () => store,
387
+ matrix: requireMatrix,
388
+ roomState,
389
+ currentTurn,
390
+ ensureAgent,
391
+ reactions,
392
+ helpers,
393
+ spaces,
394
+ notice,
395
+ say: (roomId, text) => queueOut(roomId, () => sendText(roomId, text)),
396
+ modelCatalog,
397
+ prompts,
398
+ describe,
399
+ restart: (reason) => fireAndForget('restart', () => restart(reason)),
400
+ applyTitle: (sessionId) => titles.apply(sessionId),
401
+ info,
402
+ warn,
403
+ signal: lifetime.signal,
404
+ }
405
+
406
+ ctx.on('session/event', (session, event) => {
407
+ try {
408
+ turns.onSessionEvent(session, event)
409
+ } catch (error) {
410
+ reportError('session-event', error)
411
+ }
412
+ // Titles change after the title service folded this event.
413
+ if (store === undefined || store.roomOfSession(session?.id) === undefined) return
414
+ if (event?.type === 'session/title' && event.data?.source?.kind !== 'user') fireAndForget('title', () => titles.apply(session.id))
415
+ else if (event?.type === 'request/header') fireAndForget('title', () => titles.start(session.id))
416
+ }, { global: true })
417
+
418
+ ctx.on('agent/assistant-stream', (payload) => {
419
+ try {
420
+ turns.onStream(payload?.agent?.session?.id, payload?.frame)
421
+ } catch (error) {
422
+ reportError('stream', error)
423
+ }
424
+ }, { global: true })
425
+
426
+ ctx.on('agent/pre-step', (payload, next) => principals.preStep(payload, next), { global: true })
427
+ ctx.on('subagent/start', (event) => fireAndForget('helpers', () => helpers.onStart(event)), { global: true })
428
+ ctx.on('subagent/end', (event) => fireAndForget('helpers', () => helpers.onEnd(event)), { global: true })
429
+
430
+ ctx.on('settings/document-updated', (namespace) => {
431
+ if (namespace === name) fireAndForget('settings', () => applySettings())
432
+ })
433
+
434
+ ctx.effect(() => {
435
+ void storeReady.then(() => start()).catch((error) => reportError('start', error))
436
+ return () => {
437
+ disposed = true
438
+ lifetime.abort()
439
+ if (retryTimer !== undefined) clearTimeout(retryTimer)
440
+ prompts.cancelAll()
441
+ helpers.dispose()
442
+ turns.dispose()
443
+ stopRuntime()
444
+ }
445
+ }, 'dsh-matrix-bot: runtime')
446
+ }