@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/models.js ADDED
@@ -0,0 +1,191 @@
1
+ /**
2
+ * Model selection for rooms. The session's live agent owns its model
3
+ * (`agent.model.current()`); the bot keeps no copy of it. Lists come from the
4
+ * same catalog as the Web model picker (`sessionController.modelCatalog()`),
5
+ * so every configured provider and model shows with its Web display name.
6
+ */
7
+
8
+ /** How long one catalog read is reused for labels and menus. */
9
+ const CATALOG_TTL_MS = 60_000
10
+
11
+ /**
12
+ * Copy a selection, dropping an absent effort.
13
+ * @param selection - provider, model and optional effort.
14
+ * @returns a detached selection.
15
+ */
16
+ function toSelection({ provider, model, reasoningEffort }) {
17
+ return { provider, model, ...(reasoningEffort === undefined ? {} : { reasoningEffort }) }
18
+ }
19
+
20
+ /**
21
+ * Read a session's current model: the live agent's own choice, or, for a
22
+ * session that is not running, its recorded selection.
23
+ * @param ctx - Host context.
24
+ * @param sessionId - DSH session id.
25
+ * @returns the selection, or undefined when the session has none recorded.
26
+ */
27
+ export async function sessionModelOf(ctx, sessionId) {
28
+ if (typeof sessionId !== 'string') return undefined
29
+ const agent = ctx.get('agents')?.get(sessionId)
30
+ if (typeof agent?.model?.current === 'function') {
31
+ const current = agent.model.current()
32
+ return current === undefined ? undefined : toSelection(current)
33
+ }
34
+ const query = ctx.get('sessionQuery')
35
+ if (typeof query?.observeSession !== 'function') return undefined
36
+ let observation
37
+ try {
38
+ observation = await query.observeSession(sessionId)
39
+ // The modelSelection projection's view: `next` is the pending choice or
40
+ // the route of the last request.
41
+ const view = observation?.projections?.values?.modelSelection
42
+ const recorded = view?.next ?? view?.pending ?? view?.lastUsed
43
+ return typeof recorded?.provider === 'string' && typeof recorded?.model === 'string' ? toSelection(recorded) : undefined
44
+ } catch {
45
+ return undefined
46
+ } finally {
47
+ observation?.[Symbol.dispose]?.()
48
+ }
49
+ }
50
+
51
+ /**
52
+ * Read the deployment default model (the one the Web UI saves).
53
+ * @param ctx - Host context.
54
+ * @returns the selection, or undefined without a default-model service.
55
+ */
56
+ export function defaultModelOf(ctx) {
57
+ try {
58
+ const selection = ctx.get('agentDefaultModel')?.currentSelection()
59
+ if (typeof selection?.provider === 'string' && typeof selection?.model === 'string') return toSelection(selection)
60
+ } catch {
61
+ // No default configured.
62
+ }
63
+ return undefined
64
+ }
65
+
66
+ /**
67
+ * Whether the catalog no longer offers a selection's provider or model, for
68
+ * example after a provider was removed from the profile. A provider the
69
+ * catalog reports as failing is not counted: its models are unknown now, not
70
+ * gone. Without a catalog nothing is called gone.
71
+ * @param catalog - loaded catalog, or undefined.
72
+ * @param selection - provider and model, or undefined.
73
+ * @returns true when the selection names something the catalog dropped.
74
+ */
75
+ export function isGoneModel(catalog, selection) {
76
+ if (catalog === undefined || typeof selection?.provider !== 'string' || typeof selection?.model !== 'string') return false
77
+ if (catalog.failures.some((failure) => failure?.id === selection.provider)) return false
78
+ return findModel(catalog, selection) === undefined
79
+ }
80
+
81
+ /**
82
+ * Whether two selections name the same provider, model and effort.
83
+ * @param left - first selection.
84
+ * @param right - second selection.
85
+ * @returns true when they agree.
86
+ */
87
+ export function sameSelection(left, right) {
88
+ return left?.provider === right?.provider && left?.model === right?.model && left?.reasoningEffort === right?.reasoningEffort
89
+ }
90
+
91
+ /**
92
+ * Cached reader for the Web model catalog.
93
+ * @param ctx - Host context.
94
+ * @returns `load()` resolving the catalog, or undefined when it is unavailable.
95
+ */
96
+ export function createModelCatalog(ctx) {
97
+ let cached
98
+ let loadedAt = 0
99
+ let pending
100
+ return {
101
+ /**
102
+ * @param fresh - skip the short-lived cache (used before applying a pick).
103
+ * @returns `{ groups, failures }` as the Web picker gets it, or undefined.
104
+ */
105
+ async load(fresh = false) {
106
+ if (!fresh && cached !== undefined && Date.now() - loadedAt < CATALOG_TTL_MS) return cached
107
+ pending ??= (async () => {
108
+ const controller = ctx.get('sessionController')
109
+ if (typeof controller?.modelCatalog !== 'function') return undefined
110
+ const catalog = await controller.modelCatalog()
111
+ cached = { groups: Array.isArray(catalog?.groups) ? catalog.groups : [], failures: Array.isArray(catalog?.failures) ? catalog.failures : [] }
112
+ loadedAt = Date.now()
113
+ return cached
114
+ })().finally(() => { pending = undefined })
115
+ try {
116
+ return await pending
117
+ } catch {
118
+ return cached
119
+ }
120
+ },
121
+ }
122
+ }
123
+
124
+ /**
125
+ * Find a catalog entry for a selection.
126
+ * @param catalog - loaded catalog.
127
+ * @param selection - provider and model.
128
+ * @returns `{ group, model }`, or undefined.
129
+ */
130
+ export function findModel(catalog, selection) {
131
+ const group = catalog?.groups.find((entry) => entry.id === selection?.provider)
132
+ const model = group?.models.find((entry) => entry.id === selection?.model)
133
+ return model === undefined ? undefined : { group, model }
134
+ }
135
+
136
+ /**
137
+ * Display name of a selection's model, as the Web picker shows it.
138
+ * @param catalog - loaded catalog, or undefined.
139
+ * @param selection - provider and model.
140
+ * @returns the name, or the raw model id.
141
+ */
142
+ export function modelName(catalog, selection) {
143
+ if (selection === undefined) return '?'
144
+ return findModel(catalog, selection)?.model.name ?? selection.model
145
+ }
146
+
147
+ /**
148
+ * Effort choices for one catalog model, the same list the Web picker builds:
149
+ * a provider-default entry when the model has no default effort, then its
150
+ * efforts. A model without reasoning has none.
151
+ * @param model - catalog model entry.
152
+ * @param defaultLabel - label for the provider default.
153
+ * @returns `{ id, name }` entries; `id` undefined means the provider default.
154
+ */
155
+ export function effortChoices(model, defaultLabel) {
156
+ const reasoning = model?.reasoning
157
+ if (reasoning === undefined) return []
158
+ return [
159
+ ...(reasoning.defaultEffort === undefined ? [{ id: undefined, name: defaultLabel }] : []),
160
+ ...reasoning.efforts.map((effort) => ({ id: effort.id, name: effort.name })),
161
+ ]
162
+ }
163
+
164
+ /**
165
+ * Display name of a selection's effective effort.
166
+ * @param catalog - loaded catalog, or undefined.
167
+ * @param selection - current selection.
168
+ * @param defaultLabel - label for the provider default.
169
+ * @returns the name.
170
+ */
171
+ export function effortName(catalog, selection, defaultLabel) {
172
+ const reasoning = findModel(catalog, selection)?.model.reasoning
173
+ const effective = selection?.reasoningEffort ?? reasoning?.defaultEffort
174
+ if (effective === undefined) return defaultLabel
175
+ return reasoning?.efforts.find((effort) => effort.id === effective)?.name ?? effective
176
+ }
177
+
178
+ /**
179
+ * The selection a model pick makes, by the Web picker's rule: the same model
180
+ * keeps its effort, another model starts at its default effort.
181
+ * @param current - the session's current selection.
182
+ * @param provider - picked provider id.
183
+ * @param model - picked catalog model entry.
184
+ * @returns the selection to apply.
185
+ */
186
+ export function pickedSelection(current, provider, model) {
187
+ const same = current?.provider === provider && current?.model === model.id
188
+ const reasoningEffort = same ? current.reasoningEffort ?? model.reasoning?.defaultEffort : model.reasoning?.defaultEffort
189
+ return toSelection({ provider, model: model.id, reasoningEffort })
190
+ }
191
+
@@ -0,0 +1,150 @@
1
+ /**
2
+ * What the bot offers outside rooms: the send service, the room list,
3
+ * allowing a person, and its status.
4
+ */
5
+ import { randomUUID } from 'node:crypto'
6
+ import { POST_SOURCE_KIND } from './constants.js'
7
+ import { finalError } from './outbound.js'
8
+ import { sendPrincipal, withPrincipal } from './sender.js'
9
+ import { recordMessage, resolveAgent } from './sessions.js'
10
+ import { clip } from './text.js'
11
+
12
+ /** @returns the allowlist entry of a user id, or undefined. */
13
+ export function allowedEntry(allowed, userId) {
14
+ if (typeof userId !== 'string' || userId.length === 0) return undefined
15
+ return (Array.isArray(allowed) ? allowed : []).find((entry) => typeof entry?.userId === 'string' && entry.userId.trim() === userId)
16
+ }
17
+
18
+ /**
19
+ * Create the operations.
20
+ * @param deps - `{ ctx, getStore, storeReady, requireMatrix, getMatrix, getStatus, setting, outbound, currentTurn, reportError, messageOf }`.
21
+ */
22
+ export function createOperations({ ctx, getStore, storeReady, requireMatrix, getMatrix, getStatus, setting, outbound, currentTurn, reportError, messageOf }) {
23
+ const { queueOut, sendText, sendFiles, checkFiles, react, redact } = outbound
24
+
25
+ /**
26
+ * Send text, files or a reaction into a room on behalf of a job, a session
27
+ * or a command, and record it in the session bound to that room.
28
+ * @param request - `{ to, text, files, from, replyTo, reaction }`: `to` is
29
+ * the room id; `from` `{ job, jobId, sessionId, label }` names the sender;
30
+ * `replyTo` replies to an event; `reaction` reacts to `replyTo` instead of
31
+ * sending text.
32
+ * @returns where it went and whether the session recorded it.
33
+ */
34
+ async function sendToRoom(request) {
35
+ await storeReady
36
+ const store = getStore()
37
+ requireMatrix()
38
+ const roomId = typeof request?.to === 'string' ? request.to.trim() : ''
39
+ const record = store.room(roomId)
40
+ if (record === undefined) throw finalError(`Unknown room ${request?.to}; !id in a room shows its id.`)
41
+ const replyTo = typeof request?.replyTo === 'string' && request.replyTo.length > 0 ? request.replyTo : undefined
42
+ if (typeof request?.reaction === 'string') {
43
+ if (replyTo === undefined) throw finalError('A reaction needs replyTo: the event id to react to.')
44
+ if (request.reaction.length === 0) throw finalError('Give the reaction to send; removing one is not supported.')
45
+ const reactionId = await react(roomId, replyTo, request.reaction)
46
+ return { roomId, reacted: replyTo, eventId: reactionId }
47
+ }
48
+ const text = typeof request?.text === 'string' ? request.text.trim() : ''
49
+ const paths = Array.isArray(request?.files) ? request.files.map(String) : []
50
+ if (text.length === 0 && paths.length === 0) throw finalError('Nothing to send: give text or files.')
51
+ const from = request?.from ?? {}
52
+ const sessionId = record.sessionId
53
+ const ownTurn = typeof from.sessionId === 'string' && from.sessionId === sessionId ? currentTurn(sessionId) : undefined
54
+ // The answer of a turn this room receives is delivered by itself, so text
55
+ // a session sends into its own room would arrive twice.
56
+ const delivered = ownTurn !== undefined && (ownTurn.ours || ownTurn.goal || ownTurn.mirrored)
57
+ if (delivered && paths.length === 0) {
58
+ throw finalError('This session is bound to that room and its answer is delivered there when the turn ends: write the text in your answer instead of sending it.')
59
+ }
60
+ const files = await checkFiles(paths)
61
+ const eventIds = await queueOut(roomId, async () => {
62
+ const ids = text.length > 0 ? await sendText(roomId, text, { replyTo }) : []
63
+ ids.push(...await sendFiles(roomId, files))
64
+ return ids
65
+ })
66
+ if (ownTurn !== undefined) {
67
+ ownTurn.sent = true
68
+ if (text.length > 0) ownTurn.sentTexts.push(text)
69
+ }
70
+ await store.noteSent({
71
+ roomId,
72
+ eventIds,
73
+ text,
74
+ files: files.map((file) => file.name),
75
+ job: typeof from.job === 'string' && from.job.trim() ? from.job.trim() : null,
76
+ fromSession: typeof from.sessionId === 'string' ? from.sessionId : null,
77
+ label: typeof from.label === 'string' ? from.label : null,
78
+ })
79
+ let recorded = false
80
+ let recordError
81
+ if (typeof sessionId === 'string') {
82
+ try {
83
+ const agent = await resolveAgent(ctx, sessionId)
84
+ const self = sessionId === from.sessionId
85
+ const by = self ? ' by this session' : from.job ? ` by job "${from.job}"` : from.sessionId ? ` by session ${from.sessionId}` : from.label ? ` by ${from.label}` : ''
86
+ const header = `Sent to Matrix room "${record.roomName ?? roomId}"${by}`
87
+ const content = [{ type: 'text', text: `[${header}]${text ? `\n${text}` : ''}${files.length > 0 ? `\n[Files: ${files.map((file) => file.name).join(', ')}]` : ''}` }]
88
+ const message = { id: randomUUID(), role: 'user', content, source: { kind: POST_SOURCE_KIND, form: 'notice', summary: clip(header, 120), roomId, self } }
89
+ recordMessage(agent, withPrincipal(message, sendPrincipal(from)))
90
+ recorded = true
91
+ } catch (error) {
92
+ recordError = messageOf(error)
93
+ reportError('send-record', error)
94
+ }
95
+ }
96
+ return { roomId, room: record.roomName ?? null, eventIds, sessionId: sessionId ?? null, recorded, ...(recordError ? { recordError } : {}) }
97
+ }
98
+
99
+ /** Known rooms: every room of an allowed person, with its name and session. */
100
+ async function listRooms() {
101
+ await storeReady
102
+ return Object.entries(getStore().data.rooms)
103
+ .filter(([, record]) => typeof record?.owner === 'string')
104
+ .map(([roomId, record]) => ({ roomId, name: record.roomName ?? null, owner: record.owner, sessionId: record.sessionId ?? null }))
105
+ }
106
+
107
+ /**
108
+ * Add someone to `allowedUsers` through the Host's config editor, which
109
+ * writes the profile's patch the same way the settings page does.
110
+ * @param userId - their Matrix user id.
111
+ * @param name - how their messages are labelled.
112
+ */
113
+ async function allowUser(userId, name = '') {
114
+ const id = String(userId ?? '').trim()
115
+ if (!/^@[^:\s]+:\S+$/u.test(id)) throw finalError(`Not a Matrix user id: ${userId}`)
116
+ const entry = ctx.fiber?.entry
117
+ const editor = ctx.get('configEditor')
118
+ if (entry === undefined || editor === undefined) throw new Error('This profile cannot save the bot\'s configuration; add the user id to allowedUsers by hand.')
119
+ const label = String(name ?? '').trim()
120
+ await editor.edit(entry, (current) => {
121
+ const list = Array.isArray(current?.allowedUsers) ? current.allowedUsers.filter((item) => item?.userId !== id) : []
122
+ return { ...current, allowedUsers: [...list, { userId: id, name: label }] }
123
+ })
124
+ await storeReady
125
+ await getStore().clearPending([id])
126
+ return { userId: id, name: label }
127
+ }
128
+
129
+ /** The bot's status for commands and the command line. */
130
+ function describe() {
131
+ const matrix = getMatrix()
132
+ const status = getStatus()
133
+ const store = getStore()
134
+ return {
135
+ state: status.state,
136
+ running: matrix !== undefined,
137
+ homeserver: setting('homeserver', ''),
138
+ userId: matrix?.userId,
139
+ deviceId: matrix?.deviceId,
140
+ encryption: matrix?.encryption() ?? { verified: false, backup: false },
141
+ uptimeSeconds: status.startedAt === undefined ? 0 : Math.round((Date.now() - status.startedAt) / 1000),
142
+ allowedUsers: setting('allowedUsers', []).filter((entry) => entry?.userId).length,
143
+ pending: Object.values(store?.data.pending ?? {}),
144
+ people: Object.entries(store?.data.people ?? {}).map(([userId, record]) => ({ userId, spaces: record.spaces ?? [], lobbyId: record.lobbyId ?? null })),
145
+ lastError: status.lastError,
146
+ }
147
+ }
148
+
149
+ return { sendToRoom, listRooms, allowUser, describe, redact }
150
+ }
@@ -0,0 +1,141 @@
1
+ /** Sending into rooms: Markdown as HTML, split, edits, files, reactions and notices, in order per room. */
2
+ import { readFile, stat } from 'node:fs/promises'
3
+ import { basename, extname, isAbsolute } from 'node:path'
4
+ import { MAX_FILE_BYTES } from './constants.js'
5
+ import { splitText, toHtml } from './text.js'
6
+
7
+ /** An error that a retry will not fix. */
8
+ export function finalError(message) {
9
+ return Object.assign(new Error(message), { retryable: false })
10
+ }
11
+
12
+ /** MIME types by file extension, for what the bot sends. */
13
+ const MIME_TYPES = {
14
+ '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp',
15
+ '.mp3': 'audio/mpeg', '.ogg': 'audio/ogg', '.oga': 'audio/ogg', '.opus': 'audio/ogg', '.m4a': 'audio/mp4', '.wav': 'audio/wav',
16
+ '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime',
17
+ '.pdf': 'application/pdf', '.txt': 'text/plain', '.md': 'text/markdown', '.json': 'application/json', '.zip': 'application/zip',
18
+ }
19
+
20
+ /** @returns `{ mimetype, msgtype }` of a file by its name. */
21
+ export function mediaKind(path) {
22
+ const mimetype = MIME_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream'
23
+ const msgtype = mimetype.startsWith('image/') ? 'm.image' : mimetype.startsWith('audio/') ? 'm.audio' : mimetype.startsWith('video/') ? 'm.video' : 'm.file'
24
+ return { mimetype, msgtype }
25
+ }
26
+
27
+ /**
28
+ * The content of a text message.
29
+ * @param text - Markdown, or plain text when `plain`.
30
+ * @param options - `{ plain, notice, replyTo }`.
31
+ */
32
+ export function textContent(text, { plain = false, notice = false, replyTo } = {}) {
33
+ const content = { msgtype: notice ? 'm.notice' : 'm.text', body: text }
34
+ if (!plain) {
35
+ content.format = 'org.matrix.custom.html'
36
+ content.formatted_body = toHtml(text)
37
+ }
38
+ if (typeof replyTo === 'string') content['m.relates_to'] = { 'm.in_reply_to': { event_id: replyTo } }
39
+ return content
40
+ }
41
+
42
+ /**
43
+ * The content of an edit that replaces a message's text.
44
+ * @param eventId - the message being replaced.
45
+ * @param text - its new text.
46
+ * @param options - as `textContent`.
47
+ */
48
+ export function editContent(eventId, text, options = {}) {
49
+ const fresh = textContent(text, { ...options, replyTo: undefined })
50
+ return {
51
+ ...fresh,
52
+ body: `* ${fresh.body}`,
53
+ ...(fresh.formatted_body === undefined ? {} : { formatted_body: `* ${fresh.formatted_body}` }),
54
+ 'm.new_content': fresh,
55
+ 'm.relates_to': { rel_type: 'm.replace', event_id: eventId },
56
+ }
57
+ }
58
+
59
+ /**
60
+ * Create the sender.
61
+ * @param deps - `{ requireMatrix, roomState, reportError, messageOf }`.
62
+ * @returns `{ queueOut, sendText, editText, checkFiles, sendFiles, react, redact, notice }`.
63
+ */
64
+ export function createOutbound({ requireMatrix, roomState, reportError, messageOf }) {
65
+ /** Run output for a room in order. */
66
+ function queueOut(roomId, task) {
67
+ const room = roomState(roomId)
68
+ const run = room.out.catch(() => {}).then(task)
69
+ room.out = run.catch((error) => reportError('send', error))
70
+ return run
71
+ }
72
+
73
+ /**
74
+ * Send text into a room, split when long.
75
+ * @param roomId - room id.
76
+ * @param text - Markdown.
77
+ * @param options - `{ replyTo, plain, notice }`: event to reply to with the
78
+ * first part; `plain` sends the text without HTML; `notice` marks it as a
79
+ * bot notice.
80
+ * @returns the sent event ids.
81
+ */
82
+ async function sendText(roomId, text, { replyTo, plain = false, notice = false } = {}) {
83
+ const matrix = requireMatrix()
84
+ const ids = []
85
+ for (const [index, part] of splitText(text).entries()) {
86
+ ids.push(await matrix.sendEvent(roomId, 'm.room.message', textContent(part, { plain, notice, replyTo: index === 0 ? replyTo : undefined })))
87
+ }
88
+ return ids
89
+ }
90
+
91
+ /** Replace a message's text. @returns the edit's event id. */
92
+ async function editText(roomId, eventId, text, options = {}) {
93
+ return requireMatrix().sendEvent(roomId, 'm.room.message', editContent(eventId, text, options))
94
+ }
95
+
96
+ /**
97
+ * Check files before anything is sent.
98
+ * @param paths - absolute paths.
99
+ * @returns `{ path, name, size }` entries; throws on the first bad one.
100
+ */
101
+ async function checkFiles(paths) {
102
+ const files = []
103
+ for (const path of paths) {
104
+ if (!isAbsolute(path)) throw finalError(`File paths must be absolute: ${path}`)
105
+ const info = await stat(path).catch((error) => { throw finalError(`${path}: ${messageOf(error)}`) })
106
+ if (!info.isFile()) throw finalError(`${path} is not a file`)
107
+ if (info.size > MAX_FILE_BYTES) throw finalError(`${path} is larger than ${MAX_FILE_BYTES / 1024 / 1024} MB`)
108
+ files.push({ path, name: basename(path), size: info.size })
109
+ }
110
+ return files
111
+ }
112
+
113
+ /** Upload and send checked files, encrypted in encrypted rooms. @returns the event ids. */
114
+ async function sendFiles(roomId, files) {
115
+ const matrix = requireMatrix()
116
+ const ids = []
117
+ for (const file of files) {
118
+ const { mimetype, msgtype } = mediaKind(file.path)
119
+ const media = await matrix.upload(roomId, await readFile(file.path), { name: file.name, mimetype })
120
+ ids.push(await matrix.sendEvent(roomId, 'm.room.message', { msgtype, body: file.name, filename: file.name, info: { mimetype, size: file.size }, ...media }))
121
+ }
122
+ return ids
123
+ }
124
+
125
+ /** React to an event. @returns the reaction's event id. */
126
+ async function react(roomId, eventId, key) {
127
+ return requireMatrix().sendEvent(roomId, 'm.reaction', { 'm.relates_to': { rel_type: 'm.annotation', event_id: eventId, key } })
128
+ }
129
+
130
+ /** Remove one of the bot's events (a reaction, a streamed draft). */
131
+ async function redact(roomId, eventId) {
132
+ return requireMatrix().redact(roomId, eventId)
133
+ }
134
+
135
+ /** A short bot notice (plain text) into a room. @returns its event ids. */
136
+ function notice(roomId, text) {
137
+ return queueOut(roomId, () => sendText(roomId, text, { plain: true, notice: true }))
138
+ }
139
+
140
+ return { queueOut, sendText, editText, checkFiles, sendFiles, react, redact, notice }
141
+ }