dsh-mindmark 0.0.0-stage → 0.4.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/store.js ADDED
@@ -0,0 +1,1028 @@
1
+ // dsh-mindmark — durable store for user annotations.
2
+ //
3
+ // The document lives outside every workspace, under the Harness home, because
4
+ // annotations belong to a conversation rather than to one project:
5
+ //
6
+ // {
7
+ // "version": 2,
8
+ // "sessions": {
9
+ // "<sessionId>": {
10
+ // "mode": "brief" | "full", // optional; injection view mode
11
+ // "annotations": [Annotation],
12
+ // "messages": { "<messageKey>": { "text": "...", "turn": 3 } }
13
+ // }
14
+ // }
15
+ // }
16
+ //
17
+ // Writes are atomic (temp + rename with retry) and a copy of the previous good
18
+ // document is retained as `state.backup.json`. Loading never throws: a corrupt
19
+ // file is moved aside and treated as empty. Saving never throws either — a
20
+ // failed save is reported through the optional logger and the in-memory state
21
+ // stays usable, so the HTTP boundary can never emit an unhandled rejection.
22
+
23
+ import fs from 'node:fs'
24
+ import os from 'node:os'
25
+ import path from 'node:path'
26
+
27
+ export const STATE_VERSION = 2
28
+ export const MAX_ANNOTATIONS_PER_SESSION = 300
29
+ export const MAX_ID_LENGTH = 80
30
+ export const MAX_QUOTE_LENGTH = 2000
31
+ export const MAX_NOTE_LENGTH = 2000
32
+ export const MAX_CONTEXT_LENGTH = 80
33
+ export const MAX_ROOT_SELECTOR_LENGTH = 300
34
+ export const MAX_SESSION_ID_LENGTH = 200
35
+ export const MAX_MESSAGE_KEY_LENGTH = 200
36
+ export const MAX_MESSAGE_TEXT_LENGTH = 20000
37
+ export const ANNOTATION_STYLES = ['highlight', 'underline', 'strike', 'comment', 'rewrite', 'move', 'reference']
38
+ /** Styles whose meaning needs the user's own words. */
39
+ export const NOTE_STYLES = ['comment', 'rewrite']
40
+ /** Material attached to a `reference` annotation. */
41
+ export const MATERIAL_KINDS = ['text', 'url', 'file']
42
+ export const MAX_MATERIAL_CHARS = 200000
43
+ export const MAX_MATERIAL_TITLE = 120
44
+ export const MAX_MATERIAL_URL = 2000
45
+ export const MATERIAL_EXCERPT_CHARS = 600
46
+ /** Materials up to this size are sent whole; longer ones are read through the tool. */
47
+ export const MATERIAL_INLINE_CHARS = 2000
48
+ export const MATERIAL_CHUNK_CHARS = 8000
49
+ export const ANNOTATION_STATUSES = ['pending', 'resolved']
50
+ export const INJECTION_MODES = ['brief', 'full']
51
+ export const DEFAULT_MODE = 'brief'
52
+
53
+ /** Error carrying a stable, user-facing code for the HTTP boundary / tool. */
54
+ export class AnnotateInputError extends Error {
55
+ constructor(code, message) {
56
+ super(message)
57
+ this.name = 'AnnotateInputError'
58
+ this.code = code
59
+ }
60
+ }
61
+
62
+ /** Resolve `$DSH_HOME/annotations/state.json` (or `%USERPROFILE%\.dsh/...`). */
63
+ export function resolveStatePath(env = process.env) {
64
+ const home =
65
+ typeof env?.DSH_HOME === 'string' && env.DSH_HOME.trim() !== ''
66
+ ? env.DSH_HOME
67
+ : path.join(os.homedir(), '.dsh')
68
+ return path.join(home, 'annotations', 'state.json')
69
+ }
70
+
71
+ /** Empty-but-valid document. */
72
+ export function emptyState() {
73
+ return { version: STATE_VERSION, sessions: {} }
74
+ }
75
+
76
+ function truncate(value, max) {
77
+ return typeof value === 'string' ? value.slice(0, max) : ''
78
+ }
79
+
80
+ /** Server-side id for a record whose client omitted `id`. */
81
+ export function generateAnnotationId() {
82
+ return `ann_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
83
+ }
84
+
85
+ /**
86
+ * Validate a session id coming from the wire or from an Agent. Returns the id
87
+ * unchanged (session ids are opaque) and throws a user-facing InputError
88
+ * otherwise.
89
+ */
90
+ export function validateSessionId(sessionId) {
91
+ if (
92
+ typeof sessionId !== 'string' ||
93
+ sessionId.trim() === '' ||
94
+ sessionId.length > MAX_SESSION_ID_LENGTH
95
+ ) {
96
+ throw new AnnotateInputError('invalid-session-id', '会话 ID 无效。')
97
+ }
98
+ return sessionId
99
+ }
100
+
101
+ /** Validate an injection mode from the wire or the tool. */
102
+ export function validateMode(mode) {
103
+ if (!INJECTION_MODES.includes(mode)) {
104
+ throw new AnnotateInputError('invalid-mode', '模式必须是 brief(精简)或 full(完整)。')
105
+ }
106
+ return mode
107
+ }
108
+
109
+ function contextString(value, max) {
110
+ if (value === undefined || value === null) return ''
111
+ if (typeof value !== 'string') {
112
+ throw new AnnotateInputError('invalid-annotation-context', '标注上下文格式不正确。')
113
+ }
114
+ return truncate(value, max)
115
+ }
116
+
117
+ function optionalInteger(value) {
118
+ if (value === undefined || value === null || value === '') return undefined
119
+ const number = typeof value === 'number' ? value : Number(value)
120
+ if (!Number.isInteger(number) || number < 0) return undefined
121
+ return number
122
+ }
123
+
124
+ function hostOf(url) {
125
+ try {
126
+ return new URL(url).host
127
+ } catch {
128
+ return url.slice(0, MAX_MATERIAL_TITLE)
129
+ }
130
+ }
131
+
132
+ /**
133
+ * Validate the material of a `reference` annotation (wire format). Returns
134
+ * `{ meta, content }`: `meta` is what the annotation record keeps, `content`
135
+ * goes to its own file under `annotations/materials/`.
136
+ */
137
+ export function validateMaterialInput(raw) {
138
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
139
+ throw new AnnotateInputError('missing-material', '依据需要附上参考材料(粘贴文本、链接或文件)。')
140
+ }
141
+ if (!MATERIAL_KINDS.includes(raw.kind)) {
142
+ throw new AnnotateInputError('invalid-material-kind', '材料类型必须是 text、url 或 file。')
143
+ }
144
+ const content = typeof raw.content === 'string' ? raw.content.trim() : ''
145
+ if (content === '') {
146
+ throw new AnnotateInputError('missing-material', '参考材料不能为空。')
147
+ }
148
+ let title = typeof raw.title === 'string' ? raw.title.trim().replace(/\s+/g, ' ').slice(0, MAX_MATERIAL_TITLE) : ''
149
+ if (raw.kind === 'url') {
150
+ if (content.length > MAX_MATERIAL_URL || !/^https?:\/\/\S+$/i.test(content)) {
151
+ throw new AnnotateInputError('invalid-material-url', '链接必须是以 http:// 或 https:// 开头的网址。')
152
+ }
153
+ if (title === '') title = hostOf(content)
154
+ return { meta: { kind: 'url', title, url: content, length: 0, excerpt: '' }, content }
155
+ }
156
+ if (content.length > MAX_MATERIAL_CHARS) {
157
+ throw new AnnotateInputError(
158
+ 'material-too-long',
159
+ `材料太长:最多 ${MAX_MATERIAL_CHARS} 字,请只保留和这一段相关的部分。`,
160
+ )
161
+ }
162
+ if (title === '') title = raw.kind === 'file' ? '文件' : '粘贴的材料'
163
+ return {
164
+ meta: { kind: raw.kind, title, length: content.length, excerpt: content.slice(0, MATERIAL_EXCERPT_CHARS) },
165
+ content,
166
+ }
167
+ }
168
+
169
+ function normalizeStoredMaterial(raw) {
170
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
171
+ if (!MATERIAL_KINDS.includes(raw.kind)) return null
172
+ const title = truncate(typeof raw.title === 'string' ? raw.title : '', MAX_MATERIAL_TITLE)
173
+ if (raw.kind === 'url') {
174
+ const url = truncate(raw.url, MAX_MATERIAL_URL)
175
+ if (!/^https?:\/\//i.test(url)) return null
176
+ return { kind: 'url', title, url, length: 0, excerpt: '' }
177
+ }
178
+ return {
179
+ kind: raw.kind,
180
+ title,
181
+ length: optionalInteger(raw.length) ?? 0,
182
+ excerpt: truncate(raw.excerpt, MATERIAL_EXCERPT_CHARS),
183
+ }
184
+ }
185
+
186
+ /**
187
+ * Where a `move` annotation goes, inside the same message. Either an insertion
188
+ * point (the caret: the passage goes right after `targetPrefix`), or, when the
189
+ * user selected text as the target, that text (`targetQuote`), which the moved
190
+ * passage replaces. `targetPrefix` / `targetSuffix` are the text right before
191
+ * and after the point or the replaced text; `targetOffset` (and `targetEnd`
192
+ * for a replacement) are offsets in the captured message when the source
193
+ * passage is anchored there.
194
+ */
195
+ function moveTargetOf(raw, anchor) {
196
+ const targetPrefix = contextString(raw.targetPrefix, MAX_CONTEXT_LENGTH)
197
+ const targetSuffix = contextString(raw.targetSuffix, MAX_CONTEXT_LENGTH)
198
+ let targetQuote = ''
199
+ if (raw.targetQuote !== undefined && raw.targetQuote !== null && raw.targetQuote !== '') {
200
+ if (typeof raw.targetQuote !== 'string' || raw.targetQuote.length > MAX_QUOTE_LENGTH) {
201
+ throw new AnnotateInputError('invalid-move-target', `被替换的文字必须是 1–${MAX_QUOTE_LENGTH} 个字符。`)
202
+ }
203
+ targetQuote = raw.targetQuote.trim() === '' ? '' : raw.targetQuote
204
+ }
205
+ if (targetPrefix === '' && targetSuffix === '' && targetQuote === '') {
206
+ throw new AnnotateInputError('missing-move-target', '移动需要指定目标位置。')
207
+ }
208
+ const target = { targetPrefix, targetSuffix }
209
+ if (targetQuote !== '') target.targetQuote = targetQuote
210
+ const offset = optionalInteger(raw.targetOffset)
211
+ if (anchor !== undefined && offset !== undefined) {
212
+ if (targetQuote === '') {
213
+ if (offset >= anchor.start && offset <= anchor.end) {
214
+ throw new AnnotateInputError('invalid-move-target', '目标位置不能在被移动的文字里面,也不能是原处。')
215
+ }
216
+ } else {
217
+ const end = optionalInteger(raw.targetEnd) ?? offset + targetQuote.length
218
+ if (offset < anchor.end && end > anchor.start) {
219
+ throw new AnnotateInputError('invalid-move-target', '被替换的文字不能和被移动的文字重叠。')
220
+ }
221
+ target.targetEnd = end
222
+ }
223
+ target.targetOffset = offset
224
+ }
225
+ return target
226
+ }
227
+
228
+ /** Drop the style-specific fields a record of another style must not carry. */
229
+ function stripForeignFields(record) {
230
+ if (record.style !== 'move') {
231
+ delete record.targetPrefix
232
+ delete record.targetSuffix
233
+ delete record.targetOffset
234
+ delete record.targetEnd
235
+ delete record.targetQuote
236
+ }
237
+ if (record.style !== 'reference') delete record.material
238
+ return record
239
+ }
240
+
241
+ /**
242
+ * Normalize one incoming Annotation (wire format, client -> Host). Missing
243
+ * optional fields are filled in; anything shaped wrongly is rejected with a
244
+ * Chinese message so the route can answer 400.
245
+ */
246
+ export function validateAnnotationInput(raw) {
247
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
248
+ throw new AnnotateInputError('invalid-annotation', '标注格式不正确。')
249
+ }
250
+ if (!ANNOTATION_STYLES.includes(raw.style)) {
251
+ throw new AnnotateInputError(
252
+ 'invalid-annotation-style',
253
+ `标注类型必须是 ${ANNOTATION_STYLES.join('、')} 之一。`,
254
+ )
255
+ }
256
+ if (
257
+ typeof raw.quote !== 'string' ||
258
+ raw.quote.trim().length < 1 ||
259
+ raw.quote.trim().length > MAX_QUOTE_LENGTH
260
+ ) {
261
+ throw new AnnotateInputError(
262
+ 'invalid-annotation-quote',
263
+ `标注文本必须是 1–${MAX_QUOTE_LENGTH} 个字符的字符串。`,
264
+ )
265
+ }
266
+
267
+ let note = ''
268
+ if (raw.note !== undefined && raw.note !== null) {
269
+ if (typeof raw.note !== 'string') {
270
+ throw new AnnotateInputError('invalid-annotation-note', '批注内容必须是字符串。')
271
+ }
272
+ note = raw.note.trim().slice(0, MAX_NOTE_LENGTH)
273
+ }
274
+ if (NOTE_STYLES.includes(raw.style) && note === '') {
275
+ throw new AnnotateInputError(
276
+ 'missing-annotation-note',
277
+ raw.style === 'rewrite' ? '改写需要给出替换后的文字。' : '批注需要填写内容。',
278
+ )
279
+ }
280
+
281
+ let id
282
+ if (raw.id === undefined || raw.id === null || raw.id === '') {
283
+ id = generateAnnotationId()
284
+ } else if (typeof raw.id === 'string') {
285
+ id = raw.id.trim().slice(0, MAX_ID_LENGTH)
286
+ if (id === '') id = generateAnnotationId()
287
+ } else {
288
+ throw new AnnotateInputError('invalid-annotation-id', '标注 ID 必须是字符串。')
289
+ }
290
+
291
+ let createdAt
292
+ if (raw.createdAt === undefined || raw.createdAt === null) {
293
+ createdAt = new Date().toISOString()
294
+ } else if (typeof raw.createdAt === 'string' && raw.createdAt.trim() !== '') {
295
+ createdAt = raw.createdAt
296
+ } else {
297
+ throw new AnnotateInputError('invalid-annotation-created-at', '标注时间格式不正确。')
298
+ }
299
+
300
+ const messageKey = contextString(raw.messageKey, MAX_MESSAGE_KEY_LENGTH)
301
+ const messageStart = optionalInteger(raw.messageStart)
302
+ const messageEnd = optionalInteger(raw.messageEnd)
303
+ const anchored =
304
+ messageKey !== '' &&
305
+ messageStart !== undefined &&
306
+ messageEnd !== undefined &&
307
+ messageEnd > messageStart
308
+
309
+ // Keep harmless unknown fields from newer/older clients; the known fields win.
310
+ const record = {
311
+ ...raw,
312
+ id,
313
+ style: raw.style,
314
+ quote: raw.quote,
315
+ note,
316
+ prefix: contextString(raw.prefix, MAX_CONTEXT_LENGTH),
317
+ suffix: contextString(raw.suffix, MAX_CONTEXT_LENGTH),
318
+ rootSelector: contextString(raw.rootSelector, MAX_ROOT_SELECTOR_LENGTH),
319
+ messageKey: anchored ? messageKey : '',
320
+ createdAt,
321
+ status: 'pending',
322
+ injections: 0,
323
+ }
324
+ stripForeignFields(record)
325
+ delete record.targetOffset
326
+ delete record.targetEnd
327
+ delete record.targetQuote
328
+ if (record.style === 'move') {
329
+ Object.assign(record, moveTargetOf(raw, anchored ? { start: messageStart, end: messageEnd } : undefined))
330
+ }
331
+ if (record.style === 'reference') record.material = validateMaterialInput(raw.material).meta
332
+ return withAnchor(record, anchored ? messageStart : undefined, anchored ? messageEnd : undefined, optionalInteger(raw.turn))
333
+ }
334
+
335
+ /** Set or drop the optional anchor fields so a record never carries `undefined` keys. */
336
+ function withAnchor(record, messageStart, messageEnd, turn) {
337
+ if (messageStart === undefined || messageEnd === undefined) {
338
+ delete record.messageStart
339
+ delete record.messageEnd
340
+ } else {
341
+ record.messageStart = messageStart
342
+ record.messageEnd = messageEnd
343
+ }
344
+ if (turn === undefined) delete record.turn
345
+ else record.turn = turn
346
+ return record
347
+ }
348
+
349
+ /**
350
+ * Normalize one incoming message capture `{ key, text, turn }` (the full text
351
+ * of the message an annotation belongs to). Returns null when it is unusable;
352
+ * a bad capture never fails the annotation itself.
353
+ */
354
+ export function validateMessageInput(raw) {
355
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
356
+ const key = typeof raw.key === 'string' ? raw.key.trim().slice(0, MAX_MESSAGE_KEY_LENGTH) : ''
357
+ if (key === '') return null
358
+ if (typeof raw.text !== 'string' || raw.text.length === 0 || raw.text.length > MAX_MESSAGE_TEXT_LENGTH) {
359
+ return null
360
+ }
361
+ const turn = optionalInteger(raw.turn)
362
+ return turn === undefined ? { key, text: raw.text } : { key, text: raw.text, turn }
363
+ }
364
+
365
+ /** Normalize one stored record. Returns null for a malformed entry. */
366
+ function normalizeStoredAnnotation(raw) {
367
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
368
+ if (typeof raw.id !== 'string' || raw.id.trim() === '') return null
369
+ if (!ANNOTATION_STYLES.includes(raw.style)) return null
370
+ if (typeof raw.quote !== 'string') return null
371
+ const quoteLength = raw.quote.trim().length
372
+ if (quoteLength < 1 || quoteLength > MAX_QUOTE_LENGTH) return null
373
+ if (typeof raw.createdAt !== 'string' || raw.createdAt.trim() === '') return null
374
+ const messageKey = truncate(raw.messageKey, MAX_MESSAGE_KEY_LENGTH)
375
+ const messageStart = optionalInteger(raw.messageStart)
376
+ const messageEnd = optionalInteger(raw.messageEnd)
377
+ const anchored =
378
+ messageKey !== '' && messageStart !== undefined && messageEnd !== undefined && messageEnd > messageStart
379
+ const injections = optionalInteger(raw.injections) ?? 0
380
+ const status = ANNOTATION_STATUSES.includes(raw.status) ? raw.status : 'pending'
381
+ const record = withAnchor({
382
+ ...raw,
383
+ id: truncate(raw.id.trim(), MAX_ID_LENGTH),
384
+ style: raw.style,
385
+ quote: raw.quote,
386
+ note: truncate(typeof raw.note === 'string' ? raw.note.trim() : '', MAX_NOTE_LENGTH),
387
+ prefix: truncate(raw.prefix, MAX_CONTEXT_LENGTH),
388
+ suffix: truncate(raw.suffix, MAX_CONTEXT_LENGTH),
389
+ rootSelector: truncate(raw.rootSelector, MAX_ROOT_SELECTOR_LENGTH),
390
+ messageKey: anchored ? messageKey : '',
391
+ createdAt: raw.createdAt,
392
+ status,
393
+ injections,
394
+ }, anchored ? messageStart : undefined, anchored ? messageEnd : undefined, optionalInteger(raw.turn))
395
+ if (status === 'resolved') {
396
+ record.resolvedAt = typeof raw.resolvedAt === 'string' ? raw.resolvedAt : raw.createdAt
397
+ record.resolvedBy = typeof raw.resolvedBy === 'string' ? raw.resolvedBy.slice(0, 20) : 'user'
398
+ } else {
399
+ delete record.resolvedAt
400
+ delete record.resolvedBy
401
+ }
402
+ if (record.lastInjectedTurn !== undefined && optionalInteger(record.lastInjectedTurn) === undefined) {
403
+ delete record.lastInjectedTurn
404
+ }
405
+ stripForeignFields(record)
406
+ if (record.style === 'move') {
407
+ record.targetPrefix = truncate(raw.targetPrefix, MAX_CONTEXT_LENGTH)
408
+ record.targetSuffix = truncate(raw.targetSuffix, MAX_CONTEXT_LENGTH)
409
+ const targetQuote = typeof raw.targetQuote === 'string' && raw.targetQuote.trim() !== '' ? truncate(raw.targetQuote, MAX_QUOTE_LENGTH) : ''
410
+ if (targetQuote === '') delete record.targetQuote
411
+ else record.targetQuote = targetQuote
412
+ if (record.targetPrefix === '' && record.targetSuffix === '' && targetQuote === '') return null
413
+ const offset = optionalInteger(raw.targetOffset)
414
+ if (offset === undefined || !anchored) delete record.targetOffset
415
+ else record.targetOffset = offset
416
+ const end = optionalInteger(raw.targetEnd)
417
+ if (targetQuote === '' || record.targetOffset === undefined || end === undefined || end <= offset) delete record.targetEnd
418
+ else record.targetEnd = end
419
+ }
420
+ if (record.style === 'reference') {
421
+ const material = normalizeStoredMaterial(raw.material)
422
+ if (material === null) return null
423
+ record.material = material
424
+ }
425
+ return record
426
+ }
427
+
428
+ function normalizeStoredMessages(raw, annotations) {
429
+ const messages = {}
430
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return messages
431
+ const referenced = new Set(annotations.map(item => item.messageKey).filter(key => key !== ''))
432
+ for (const [key, value] of Object.entries(raw)) {
433
+ if (!referenced.has(key)) continue
434
+ const message = validateMessageInput({ ...(value ?? {}), key })
435
+ if (message !== null) messages[key] = { text: message.text, ...(message.turn === undefined ? {} : { turn: message.turn }) }
436
+ }
437
+ return messages
438
+ }
439
+
440
+ /** Normalize one stored session. Returns null when it carries nothing worth keeping. */
441
+ function normalizeStoredSession(raw) {
442
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
443
+ const annotations = []
444
+ if (Array.isArray(raw.annotations)) {
445
+ for (const item of raw.annotations) {
446
+ const annotation = normalizeStoredAnnotation(item)
447
+ if (annotation !== null) annotations.push(annotation)
448
+ }
449
+ }
450
+ const mode = INJECTION_MODES.includes(raw.mode) && raw.mode !== DEFAULT_MODE ? raw.mode : undefined
451
+ if (annotations.length === 0 && mode === undefined) return null
452
+ const capped =
453
+ annotations.length > MAX_ANNOTATIONS_PER_SESSION
454
+ ? annotations.slice(-MAX_ANNOTATIONS_PER_SESSION)
455
+ : annotations
456
+ const session = { annotations: capped, messages: normalizeStoredMessages(raw.messages, capped) }
457
+ if (mode !== undefined) session.mode = mode
458
+ return session
459
+ }
460
+
461
+ /**
462
+ * Coerce an arbitrary parsed document into the safe in-memory shape. Never
463
+ * throws: garbage sections and malformed records are dropped, empty session
464
+ * keys are removed, and the per-session cap is re-applied.
465
+ */
466
+ export function normalizeState(raw) {
467
+ const state = emptyState()
468
+ try {
469
+ const sessions =
470
+ raw !== null &&
471
+ typeof raw === 'object' &&
472
+ !Array.isArray(raw) &&
473
+ raw.sessions !== null &&
474
+ typeof raw.sessions === 'object' &&
475
+ !Array.isArray(raw.sessions)
476
+ ? raw.sessions
477
+ : {}
478
+ for (const [sessionId, sessionRaw] of Object.entries(sessions)) {
479
+ if (
480
+ typeof sessionId !== 'string' ||
481
+ sessionId.trim() === '' ||
482
+ sessionId.length > MAX_SESSION_ID_LENGTH
483
+ ) {
484
+ continue
485
+ }
486
+ const session = normalizeStoredSession(sessionRaw)
487
+ if (session !== null) state.sessions[sessionId] = session
488
+ }
489
+ } catch {
490
+ // `normalizeState` never throws; a partially normalized document is fine.
491
+ }
492
+ return state
493
+ }
494
+
495
+ /** Drop session keys that carry nothing (no annotations and the default mode). */
496
+ function pruneEmptySessions(state) {
497
+ if (state === null || typeof state !== 'object' || Array.isArray(state)) return state
498
+ if (state.sessions === null || typeof state.sessions !== 'object' || Array.isArray(state.sessions)) {
499
+ state.sessions = {}
500
+ return state
501
+ }
502
+ for (const [sessionId, session] of Object.entries(state.sessions)) {
503
+ const empty =
504
+ session === null ||
505
+ typeof session !== 'object' ||
506
+ !Array.isArray(session.annotations) ||
507
+ session.annotations.length === 0
508
+ const defaultMode = session?.mode === undefined || session?.mode === DEFAULT_MODE
509
+ if (empty && defaultMode) {
510
+ delete state.sessions[sessionId]
511
+ } else if (empty) {
512
+ session.annotations = []
513
+ session.messages = {}
514
+ }
515
+ }
516
+ return state
517
+ }
518
+
519
+ function ensureDirectory(filePath) {
520
+ fs.mkdirSync(path.dirname(filePath), { recursive: true })
521
+ }
522
+
523
+ /**
524
+ * Load a document. A missing file means an empty document; a corrupt file is
525
+ * copied aside (`state.json.corrupt-<ts>`) instead of being silently
526
+ * overwritten. Never throws.
527
+ */
528
+ export function loadStateFile(filePath, { logger } = {}) {
529
+ try {
530
+ ensureDirectory(filePath)
531
+ } catch (error) {
532
+ logger?.warn?.(`dsh-mindmark: cannot create the annotation directory: ${String(error)}`)
533
+ return emptyState()
534
+ }
535
+ let raw
536
+ try {
537
+ raw = fs.readFileSync(filePath, 'utf8')
538
+ } catch (error) {
539
+ if (error?.code !== 'ENOENT') {
540
+ logger?.warn?.(`dsh-mindmark: cannot read ${filePath}: ${String(error)}`)
541
+ }
542
+ return emptyState()
543
+ }
544
+ try {
545
+ return normalizeState(JSON.parse(raw))
546
+ } catch (error) {
547
+ const backup = `${filePath}.corrupt-${Date.now()}`
548
+ try {
549
+ fs.copyFileSync(filePath, backup)
550
+ } catch {
551
+ // Best effort: the unreadable original remains in place.
552
+ }
553
+ logger?.warn?.(
554
+ `dsh-mindmark: annotation state was unreadable (${String(error)}); backup at ${backup}`,
555
+ )
556
+ return emptyState()
557
+ }
558
+ }
559
+
560
+ /** `state.json` -> `state.backup.json` (contract's name). */
561
+ export function backupPathFor(filePath) {
562
+ const base = path.basename(filePath)
563
+ const stem = base.toLowerCase().endsWith('.json') ? base.slice(0, -'.json'.length) : base
564
+ return path.join(path.dirname(filePath), `${stem}.backup.json`)
565
+ }
566
+
567
+ /** Windows can briefly lock the destination after an antivirus scan. */
568
+ function replaceWithRetry(temp, filePath) {
569
+ let lastError
570
+ for (let attempt = 0; attempt < 6; attempt += 1) {
571
+ try {
572
+ fs.renameSync(temp, filePath)
573
+ return
574
+ } catch (error) {
575
+ lastError = error
576
+ if (error?.code !== 'EPERM' && error?.code !== 'EBUSY' && error?.code !== 'EACCES') {
577
+ throw error
578
+ }
579
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 40 * (attempt + 1))
580
+ }
581
+ }
582
+ // A non-atomic copy is still preferable to losing the user's annotations.
583
+ fs.copyFileSync(temp, filePath)
584
+ fs.unlinkSync(temp)
585
+ if (!fs.existsSync(filePath)) throw lastError
586
+ }
587
+
588
+ /** Atomically replace the document, keeping one previous good copy. */
589
+ export function saveStateFile(filePath, state) {
590
+ ensureDirectory(filePath)
591
+ const document = pruneEmptySessions(
592
+ state !== null && typeof state === 'object' && !Array.isArray(state) ? state : emptyState(),
593
+ )
594
+ const json = `${JSON.stringify(document, null, 2)}\n`
595
+ const temp = `${filePath}.${process.pid}.${Date.now()}.tmp`
596
+ fs.writeFileSync(temp, json, { encoding: 'utf8', mode: 0o600 })
597
+ try {
598
+ if (fs.existsSync(filePath)) {
599
+ try {
600
+ fs.copyFileSync(filePath, backupPathFor(filePath))
601
+ } catch {
602
+ // The next successful write can try the backup again.
603
+ }
604
+ }
605
+ replaceWithRetry(temp, filePath)
606
+ } finally {
607
+ try {
608
+ if (fs.existsSync(temp)) fs.unlinkSync(temp)
609
+ } catch {
610
+ // Leftover temp files are harmless.
611
+ }
612
+ }
613
+ }
614
+
615
+ function cleanIds(ids) {
616
+ return new Set((Array.isArray(ids) ? ids : []).filter(id => typeof id === 'string' && id.trim() !== ''))
617
+ }
618
+
619
+ /**
620
+ * Small synchronous store; the document is tiny and mutations are serialized.
621
+ * Save failures are logged but never thrown, so the HTTP handler and the tool
622
+ * keep working with the in-memory document.
623
+ */
624
+ export class AnnotationStore {
625
+ constructor(filePath, { logger, defaultMode } = {}) {
626
+ this.filePath = filePath ?? resolveStatePath()
627
+ this.logger = logger
628
+ this.defaultMode = INJECTION_MODES.includes(defaultMode) ? defaultMode : DEFAULT_MODE
629
+ this.materialsDir = path.join(path.dirname(this.filePath), 'materials')
630
+ this.state = loadStateFile(this.filePath, { logger })
631
+ this.lastSaveError = null
632
+ // Canonicalize what was loaded (and create the file early, best effort).
633
+ this.persist()
634
+ this.sweepMaterials()
635
+ }
636
+
637
+ // ------------------------------------------------------------ materials
638
+
639
+ materialPath(id) {
640
+ return path.join(this.materialsDir, `${String(id).replace(/[^A-Za-z0-9_-]/g, '_')}.txt`)
641
+ }
642
+
643
+ writeMaterial(id, content) {
644
+ fs.mkdirSync(this.materialsDir, { recursive: true })
645
+ fs.writeFileSync(this.materialPath(id), content, { encoding: 'utf8', mode: 0o600 })
646
+ }
647
+
648
+ readMaterialFile(id) {
649
+ try {
650
+ return fs.readFileSync(this.materialPath(id), 'utf8')
651
+ } catch {
652
+ return undefined
653
+ }
654
+ }
655
+
656
+ deleteMaterials(records) {
657
+ for (const record of records) {
658
+ if (record?.style !== 'reference') continue
659
+ try {
660
+ fs.rmSync(this.materialPath(record.id), { force: true })
661
+ } catch (error) {
662
+ this.logger?.warn?.(`dsh-mindmark: cannot delete material ${record.id}: ${String(error)}`)
663
+ }
664
+ }
665
+ }
666
+
667
+ /** Remove material files no annotation refers to any more (best effort). */
668
+ sweepMaterials() {
669
+ let names
670
+ try {
671
+ names = fs.readdirSync(this.materialsDir)
672
+ } catch {
673
+ return
674
+ }
675
+ const keep = new Set()
676
+ for (const session of Object.values(this.state.sessions)) {
677
+ for (const item of session?.annotations ?? []) {
678
+ if (item.style === 'reference') keep.add(path.basename(this.materialPath(item.id)))
679
+ }
680
+ }
681
+ for (const name of names) {
682
+ if (!name.endsWith('.txt') || keep.has(name)) continue
683
+ try {
684
+ fs.rmSync(path.join(this.materialsDir, name), { force: true })
685
+ } catch {
686
+ // Harmless leftover.
687
+ }
688
+ }
689
+ }
690
+
691
+ /**
692
+ * Read one chunk of the material of a `reference` annotation. Returns
693
+ * undefined when the annotation or its material is gone.
694
+ */
695
+ material(sessionId, id, { offset = 0, limit = MATERIAL_CHUNK_CHARS } = {}) {
696
+ const record = this.sessionFor(sessionId)?.annotations.find(item => item.id === id)
697
+ if (record === undefined || record.style !== 'reference') return undefined
698
+ const meta = record.material
699
+ if (meta.kind === 'url') {
700
+ return { id, kind: 'url', title: meta.title, url: meta.url, total: 0, offset: 0, content: '', nextOffset: -1 }
701
+ }
702
+ const content = this.readMaterialFile(id)
703
+ if (content === undefined) return undefined
704
+ const start = Math.max(0, Math.min(Number.isInteger(offset) ? offset : 0, content.length))
705
+ const size = Number.isInteger(limit) && limit > 0 ? Math.min(limit, MATERIAL_CHUNK_CHARS) : MATERIAL_CHUNK_CHARS
706
+ const end = Math.min(content.length, start + size)
707
+ return {
708
+ id,
709
+ kind: meta.kind,
710
+ title: meta.title,
711
+ total: content.length,
712
+ offset: start,
713
+ content: content.slice(start, end),
714
+ nextOffset: end < content.length ? end : -1,
715
+ }
716
+ }
717
+
718
+ /** Session id -> safe session object, or undefined. */
719
+ sessionFor(sessionId) {
720
+ if (typeof sessionId !== 'string') return undefined
721
+ const session = this.state.sessions[sessionId]
722
+ if (
723
+ session === null ||
724
+ typeof session !== 'object' ||
725
+ !Array.isArray(session.annotations)
726
+ ) {
727
+ return undefined
728
+ }
729
+ if (session.messages === null || typeof session.messages !== 'object' || Array.isArray(session.messages)) {
730
+ session.messages = {}
731
+ }
732
+ return session
733
+ }
734
+
735
+ ensureSession(sessionId) {
736
+ const key = validateSessionId(sessionId)
737
+ let session = this.sessionFor(key)
738
+ if (session === undefined) {
739
+ session = { annotations: [], messages: {} }
740
+ this.state.sessions[key] = session
741
+ }
742
+ return session
743
+ }
744
+
745
+ /** Oldest first, always a fresh array. */
746
+ list(sessionId) {
747
+ const session = this.sessionFor(sessionId)
748
+ if (session === undefined) return []
749
+ return session.annotations.map(annotation => ({ ...annotation }))
750
+ }
751
+
752
+ /** Annotations still waiting for the model, oldest first. */
753
+ pending(sessionId) {
754
+ return this.list(sessionId).filter(annotation => annotation.status !== 'resolved')
755
+ }
756
+
757
+ /** The injection mode for one session (the configured default when unset). */
758
+ getMode(sessionId) {
759
+ const session = this.sessionFor(sessionId)
760
+ const mode = session?.mode
761
+ return INJECTION_MODES.includes(mode) ? mode : this.defaultMode
762
+ }
763
+
764
+ /** Record the injection mode for one session. */
765
+ setMode(sessionId, mode) {
766
+ const next = validateMode(mode)
767
+ const session = this.ensureSession(sessionId)
768
+ if (next === this.defaultMode) delete session.mode
769
+ else session.mode = next
770
+ this.persist()
771
+ return next
772
+ }
773
+
774
+ /** The captured full text of one message, or undefined. */
775
+ messageOf(sessionId, messageKey) {
776
+ const session = this.sessionFor(sessionId)
777
+ if (session === undefined || typeof messageKey !== 'string' || messageKey === '') return undefined
778
+ const message = session.messages[messageKey]
779
+ if (message === null || typeof message !== 'object' || typeof message.text !== 'string') return undefined
780
+ return { ...message }
781
+ }
782
+
783
+ /** Everything the injection builder needs for one session. */
784
+ snapshot(sessionId) {
785
+ const session = this.sessionFor(sessionId)
786
+ const annotations = this.list(sessionId)
787
+ // Short materials travel whole; longer ones are read through the tool.
788
+ const materials = {}
789
+ for (const item of annotations) {
790
+ if (item.style !== 'reference' || item.material.kind === 'url') continue
791
+ if (item.material.length > MATERIAL_INLINE_CHARS) continue
792
+ const content = this.readMaterialFile(item.id)
793
+ if (content !== undefined) materials[item.id] = content
794
+ }
795
+ return {
796
+ mode: this.getMode(sessionId),
797
+ annotations,
798
+ messages:
799
+ session === undefined
800
+ ? {}
801
+ : Object.fromEntries(Object.entries(session.messages).map(([key, value]) => [key, { ...value }])),
802
+ materials,
803
+ }
804
+ }
805
+
806
+ /**
807
+ * Append one annotation. An identical `(style, quote, prefix, suffix, note)`
808
+ * marks the same passage again: its `createdAt` is refreshed, it becomes
809
+ * pending again and moves to the end instead of being duplicated. The
810
+ * per-session cap drops the oldest. `message` optionally captures the full
811
+ * text of the message the annotation belongs to.
812
+ */
813
+ add(sessionId, annotation, message) {
814
+ const record = validateAnnotationInput(annotation)
815
+ const session = this.ensureSession(sessionId)
816
+ const capture = validateMessageInput(message)
817
+ if (capture !== null && record.messageKey === capture.key) {
818
+ session.messages[capture.key] = {
819
+ text: capture.text,
820
+ ...(capture.turn === undefined ? {} : { turn: capture.turn }),
821
+ }
822
+ if (record.turn === undefined && capture.turn !== undefined) record.turn = capture.turn
823
+ } else if (record.messageKey !== '' && session.messages[record.messageKey] === undefined) {
824
+ // Anchored to a message we never captured: keep the offsets harmless.
825
+ record.messageKey = ''
826
+ delete record.messageStart
827
+ delete record.messageEnd
828
+ delete record.targetOffset
829
+ delete record.targetEnd
830
+ }
831
+ const material = record.style === 'reference' ? validateMaterialInput(annotation.material) : null
832
+ const index = session.annotations.findIndex(
833
+ item =>
834
+ item.style === record.style &&
835
+ item.quote === record.quote &&
836
+ item.prefix === record.prefix &&
837
+ item.suffix === record.suffix &&
838
+ item.note === record.note &&
839
+ (item.style !== 'move' ||
840
+ (item.targetPrefix === record.targetPrefix &&
841
+ item.targetSuffix === record.targetSuffix &&
842
+ (item.targetQuote ?? '') === (record.targetQuote ?? ''))),
843
+ )
844
+ let result
845
+ let stored
846
+ if (index >= 0) {
847
+ const existing = session.annotations[index]
848
+ const anchorSource = record.messageKey !== '' ? record : existing
849
+ const refreshed = withAnchor({
850
+ ...existing,
851
+ createdAt: record.createdAt,
852
+ status: 'pending',
853
+ injections: 0,
854
+ messageKey: anchorSource.messageKey ?? '',
855
+ }, anchorSource.messageStart, anchorSource.messageEnd, record.turn ?? existing.turn)
856
+ delete refreshed.resolvedAt
857
+ delete refreshed.resolvedBy
858
+ delete refreshed.lastInjectedTurn
859
+ // A re-marked reference takes the newly attached material.
860
+ if (material !== null) refreshed.material = material.meta
861
+ if (record.style === 'move') {
862
+ if (record.targetOffset !== undefined) refreshed.targetOffset = record.targetOffset
863
+ else if (refreshed.messageStart === undefined) delete refreshed.targetOffset
864
+ if (record.targetEnd !== undefined) refreshed.targetEnd = record.targetEnd
865
+ else if (refreshed.targetOffset === undefined) delete refreshed.targetEnd
866
+ }
867
+ session.annotations.splice(index, 1)
868
+ session.annotations.push(refreshed)
869
+ stored = refreshed
870
+ result = { annotation: { ...refreshed }, deduped: true }
871
+ } else {
872
+ session.annotations.push({ ...record })
873
+ if (session.annotations.length > MAX_ANNOTATIONS_PER_SESSION) {
874
+ const dropped = session.annotations.splice(0, session.annotations.length - MAX_ANNOTATIONS_PER_SESSION)
875
+ this.deleteMaterials(dropped)
876
+ }
877
+ stored = record
878
+ result = { annotation: { ...record }, deduped: false }
879
+ }
880
+ if (material !== null) {
881
+ try {
882
+ this.writeMaterial(stored.id, material.content)
883
+ } catch (error) {
884
+ // Without its material a new reference is meaningless: undo it.
885
+ if (!result.deduped) session.annotations = session.annotations.filter(item => item.id !== stored.id)
886
+ this.logger?.warn?.(`dsh-mindmark: cannot save material: ${String(error)}`)
887
+ throw new AnnotateInputError('material-save-failed', '参考材料保存失败。')
888
+ }
889
+ }
890
+ this.pruneMessages(session)
891
+ this.persist()
892
+ return result
893
+ }
894
+
895
+ /** Drop captured messages no annotation references any more. */
896
+ pruneMessages(session) {
897
+ const referenced = new Set(session.annotations.map(item => item.messageKey).filter(key => key !== ''))
898
+ for (const key of Object.keys(session.messages)) {
899
+ if (!referenced.has(key)) delete session.messages[key]
900
+ }
901
+ }
902
+
903
+ /** Remove annotations by id. Returns how many were removed. */
904
+ remove(sessionId, ids) {
905
+ const session = this.sessionFor(sessionId)
906
+ if (session === undefined) return 0
907
+ const wanted = cleanIds(ids)
908
+ if (wanted.size === 0) return 0
909
+ const dropped = session.annotations.filter(item => wanted.has(item.id))
910
+ session.annotations = session.annotations.filter(item => !wanted.has(item.id))
911
+ const removed = dropped.length
912
+ if (removed > 0) {
913
+ this.pruneMessages(session)
914
+ this.persist()
915
+ this.deleteMaterials(dropped)
916
+ }
917
+ return removed
918
+ }
919
+
920
+ /** Remove every annotation of one session (the mode is kept). Returns how many were removed. */
921
+ clear(sessionId) {
922
+ const session = this.sessionFor(sessionId)
923
+ if (session === undefined) return 0
924
+ const dropped = session.annotations
925
+ const removed = dropped.length
926
+ session.annotations = []
927
+ session.messages = {}
928
+ if (removed > 0) {
929
+ this.persist()
930
+ this.deleteMaterials(dropped)
931
+ }
932
+ return removed
933
+ }
934
+
935
+ /**
936
+ * Mark annotations as handled. `ids` undefined/empty means every pending
937
+ * annotation. `by` records who settled them: `model`, `user` or `cap`.
938
+ * Returns the ids that changed.
939
+ */
940
+ resolve(sessionId, ids, { by = 'user', at } = {}) {
941
+ const session = this.sessionFor(sessionId)
942
+ if (session === undefined) return []
943
+ const wanted = cleanIds(ids)
944
+ const stamp = typeof at === 'string' ? at : new Date().toISOString()
945
+ const changed = []
946
+ for (const item of session.annotations) {
947
+ if (item.status === 'resolved') continue
948
+ if (wanted.size > 0 && !wanted.has(item.id)) continue
949
+ item.status = 'resolved'
950
+ item.resolvedAt = stamp
951
+ item.resolvedBy = by
952
+ changed.push(item.id)
953
+ }
954
+ if (changed.length > 0) this.persist()
955
+ return changed
956
+ }
957
+
958
+ /**
959
+ * Put annotations back in front of the model. `ids` undefined/empty means
960
+ * every annotation. The injection counter restarts. Returns the ids that changed.
961
+ */
962
+ reopen(sessionId, ids) {
963
+ const session = this.sessionFor(sessionId)
964
+ if (session === undefined) return []
965
+ const wanted = cleanIds(ids)
966
+ const changed = []
967
+ for (const item of session.annotations) {
968
+ if (wanted.size > 0 && !wanted.has(item.id)) continue
969
+ if (item.status === 'pending' && item.injections === 0) continue
970
+ item.status = 'pending'
971
+ item.injections = 0
972
+ delete item.resolvedAt
973
+ delete item.resolvedBy
974
+ delete item.lastInjectedTurn
975
+ changed.push(item.id)
976
+ }
977
+ if (changed.length > 0) this.persist()
978
+ return changed
979
+ }
980
+
981
+ /**
982
+ * Count one injection for the given pending annotations and settle those
983
+ * that reached `cap` before this turn (`resolvedBy: 'cap'`).
984
+ * Returns `{ injected: ids, capped: ids }`; only `injected` were included.
985
+ */
986
+ markInjected(sessionId, ids, { turn, cap } = {}) {
987
+ const session = this.sessionFor(sessionId)
988
+ if (session === undefined) return { injected: [], capped: [] }
989
+ const wanted = cleanIds(ids)
990
+ const injected = []
991
+ const capped = []
992
+ const limit = Number.isInteger(cap) && cap > 0 ? cap : undefined
993
+ for (const item of session.annotations) {
994
+ if (item.status === 'resolved' || !wanted.has(item.id)) continue
995
+ if (limit !== undefined && item.injections >= limit) {
996
+ item.status = 'resolved'
997
+ item.resolvedAt = new Date().toISOString()
998
+ item.resolvedBy = 'cap'
999
+ capped.push(item.id)
1000
+ continue
1001
+ }
1002
+ item.injections += 1
1003
+ if (Number.isInteger(turn)) item.lastInjectedTurn = turn
1004
+ injected.push(item.id)
1005
+ }
1006
+ if (injected.length > 0 || capped.length > 0) this.persist()
1007
+ return { injected, capped }
1008
+ }
1009
+
1010
+ /** Pending annotations that may still be injected under `cap`. */
1011
+ injectable(sessionId, cap) {
1012
+ const limit = Number.isInteger(cap) && cap > 0 ? cap : undefined
1013
+ return this.pending(sessionId).filter(item => limit === undefined || item.injections < limit)
1014
+ }
1015
+
1016
+ /** Save the document; failures are logged and recorded, never thrown. */
1017
+ persist() {
1018
+ try {
1019
+ saveStateFile(this.filePath, this.state)
1020
+ this.lastSaveError = null
1021
+ return true
1022
+ } catch (error) {
1023
+ this.lastSaveError = error
1024
+ this.logger?.warn?.(`dsh-mindmark: cannot save ${this.filePath}: ${String(error)}`)
1025
+ return false
1026
+ }
1027
+ }
1028
+ }