dsh-mindmark 0.0.0-stage → 0.3.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/LICENSE +21 -0
- package/README.en.md +88 -0
- package/README.md +99 -2
- package/client.js +2296 -0
- package/cordis.patch.yml +14 -0
- package/docs/demo.gif +0 -0
- package/icon.svg +9 -0
- package/index.js +566 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +56 -6
- package/src/inject.js +191 -0
- package/src/lessons.js +187 -0
- package/src/store.js +747 -0
package/src/store.js
ADDED
|
@@ -0,0 +1,747 @@
|
|
|
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']
|
|
38
|
+
/** Styles whose meaning needs the user's own words. */
|
|
39
|
+
export const NOTE_STYLES = ['comment', 'rewrite']
|
|
40
|
+
export const ANNOTATION_STATUSES = ['pending', 'resolved']
|
|
41
|
+
export const INJECTION_MODES = ['brief', 'full']
|
|
42
|
+
export const DEFAULT_MODE = 'brief'
|
|
43
|
+
|
|
44
|
+
/** Error carrying a stable, user-facing code for the HTTP boundary / tool. */
|
|
45
|
+
export class AnnotateInputError extends Error {
|
|
46
|
+
constructor(code, message) {
|
|
47
|
+
super(message)
|
|
48
|
+
this.name = 'AnnotateInputError'
|
|
49
|
+
this.code = code
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** Resolve `$DSH_HOME/annotations/state.json` (or `%USERPROFILE%\.dsh/...`). */
|
|
54
|
+
export function resolveStatePath(env = process.env) {
|
|
55
|
+
const home =
|
|
56
|
+
typeof env?.DSH_HOME === 'string' && env.DSH_HOME.trim() !== ''
|
|
57
|
+
? env.DSH_HOME
|
|
58
|
+
: path.join(os.homedir(), '.dsh')
|
|
59
|
+
return path.join(home, 'annotations', 'state.json')
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Empty-but-valid document. */
|
|
63
|
+
export function emptyState() {
|
|
64
|
+
return { version: STATE_VERSION, sessions: {} }
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function truncate(value, max) {
|
|
68
|
+
return typeof value === 'string' ? value.slice(0, max) : ''
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Server-side id for a record whose client omitted `id`. */
|
|
72
|
+
export function generateAnnotationId() {
|
|
73
|
+
return `ann_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Validate a session id coming from the wire or from an Agent. Returns the id
|
|
78
|
+
* unchanged (session ids are opaque) and throws a user-facing InputError
|
|
79
|
+
* otherwise.
|
|
80
|
+
*/
|
|
81
|
+
export function validateSessionId(sessionId) {
|
|
82
|
+
if (
|
|
83
|
+
typeof sessionId !== 'string' ||
|
|
84
|
+
sessionId.trim() === '' ||
|
|
85
|
+
sessionId.length > MAX_SESSION_ID_LENGTH
|
|
86
|
+
) {
|
|
87
|
+
throw new AnnotateInputError('invalid-session-id', '会话 ID 无效。')
|
|
88
|
+
}
|
|
89
|
+
return sessionId
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** Validate an injection mode from the wire or the tool. */
|
|
93
|
+
export function validateMode(mode) {
|
|
94
|
+
if (!INJECTION_MODES.includes(mode)) {
|
|
95
|
+
throw new AnnotateInputError('invalid-mode', '模式必须是 brief(精简)或 full(完整)。')
|
|
96
|
+
}
|
|
97
|
+
return mode
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
function contextString(value, max) {
|
|
101
|
+
if (value === undefined || value === null) return ''
|
|
102
|
+
if (typeof value !== 'string') {
|
|
103
|
+
throw new AnnotateInputError('invalid-annotation-context', '标注上下文格式不正确。')
|
|
104
|
+
}
|
|
105
|
+
return truncate(value, max)
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
function optionalInteger(value) {
|
|
109
|
+
if (value === undefined || value === null || value === '') return undefined
|
|
110
|
+
const number = typeof value === 'number' ? value : Number(value)
|
|
111
|
+
if (!Number.isInteger(number) || number < 0) return undefined
|
|
112
|
+
return number
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Normalize one incoming Annotation (wire format, client -> Host). Missing
|
|
117
|
+
* optional fields are filled in; anything shaped wrongly is rejected with a
|
|
118
|
+
* Chinese message so the route can answer 400.
|
|
119
|
+
*/
|
|
120
|
+
export function validateAnnotationInput(raw) {
|
|
121
|
+
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
|
|
122
|
+
throw new AnnotateInputError('invalid-annotation', '标注格式不正确。')
|
|
123
|
+
}
|
|
124
|
+
if (!ANNOTATION_STYLES.includes(raw.style)) {
|
|
125
|
+
throw new AnnotateInputError(
|
|
126
|
+
'invalid-annotation-style',
|
|
127
|
+
`标注类型必须是 ${ANNOTATION_STYLES.join('、')} 之一。`,
|
|
128
|
+
)
|
|
129
|
+
}
|
|
130
|
+
if (
|
|
131
|
+
typeof raw.quote !== 'string' ||
|
|
132
|
+
raw.quote.trim().length < 1 ||
|
|
133
|
+
raw.quote.trim().length > MAX_QUOTE_LENGTH
|
|
134
|
+
) {
|
|
135
|
+
throw new AnnotateInputError(
|
|
136
|
+
'invalid-annotation-quote',
|
|
137
|
+
`标注文本必须是 1–${MAX_QUOTE_LENGTH} 个字符的字符串。`,
|
|
138
|
+
)
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
let note = ''
|
|
142
|
+
if (raw.note !== undefined && raw.note !== null) {
|
|
143
|
+
if (typeof raw.note !== 'string') {
|
|
144
|
+
throw new AnnotateInputError('invalid-annotation-note', '批注内容必须是字符串。')
|
|
145
|
+
}
|
|
146
|
+
note = raw.note.trim().slice(0, MAX_NOTE_LENGTH)
|
|
147
|
+
}
|
|
148
|
+
if (NOTE_STYLES.includes(raw.style) && note === '') {
|
|
149
|
+
throw new AnnotateInputError(
|
|
150
|
+
'missing-annotation-note',
|
|
151
|
+
raw.style === 'rewrite' ? '改写需要给出替换后的文字。' : '批注需要填写内容。',
|
|
152
|
+
)
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
let id
|
|
156
|
+
if (raw.id === undefined || raw.id === null || raw.id === '') {
|
|
157
|
+
id = generateAnnotationId()
|
|
158
|
+
} else if (typeof raw.id === 'string') {
|
|
159
|
+
id = raw.id.trim().slice(0, MAX_ID_LENGTH)
|
|
160
|
+
if (id === '') id = generateAnnotationId()
|
|
161
|
+
} else {
|
|
162
|
+
throw new AnnotateInputError('invalid-annotation-id', '标注 ID 必须是字符串。')
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
let createdAt
|
|
166
|
+
if (raw.createdAt === undefined || raw.createdAt === null) {
|
|
167
|
+
createdAt = new Date().toISOString()
|
|
168
|
+
} else if (typeof raw.createdAt === 'string' && raw.createdAt.trim() !== '') {
|
|
169
|
+
createdAt = raw.createdAt
|
|
170
|
+
} else {
|
|
171
|
+
throw new AnnotateInputError('invalid-annotation-created-at', '标注时间格式不正确。')
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
const messageKey = contextString(raw.messageKey, MAX_MESSAGE_KEY_LENGTH)
|
|
175
|
+
const messageStart = optionalInteger(raw.messageStart)
|
|
176
|
+
const messageEnd = optionalInteger(raw.messageEnd)
|
|
177
|
+
const anchored =
|
|
178
|
+
messageKey !== '' &&
|
|
179
|
+
messageStart !== undefined &&
|
|
180
|
+
messageEnd !== undefined &&
|
|
181
|
+
messageEnd > messageStart
|
|
182
|
+
|
|
183
|
+
// Keep harmless unknown fields from newer/older clients; the known fields win.
|
|
184
|
+
const record = {
|
|
185
|
+
...raw,
|
|
186
|
+
id,
|
|
187
|
+
style: raw.style,
|
|
188
|
+
quote: raw.quote,
|
|
189
|
+
note,
|
|
190
|
+
prefix: contextString(raw.prefix, MAX_CONTEXT_LENGTH),
|
|
191
|
+
suffix: contextString(raw.suffix, MAX_CONTEXT_LENGTH),
|
|
192
|
+
rootSelector: contextString(raw.rootSelector, MAX_ROOT_SELECTOR_LENGTH),
|
|
193
|
+
messageKey: anchored ? messageKey : '',
|
|
194
|
+
createdAt,
|
|
195
|
+
status: 'pending',
|
|
196
|
+
injections: 0,
|
|
197
|
+
}
|
|
198
|
+
return withAnchor(record, anchored ? messageStart : undefined, anchored ? messageEnd : undefined, optionalInteger(raw.turn))
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** Set or drop the optional anchor fields so a record never carries `undefined` keys. */
|
|
202
|
+
function withAnchor(record, messageStart, messageEnd, turn) {
|
|
203
|
+
if (messageStart === undefined || messageEnd === undefined) {
|
|
204
|
+
delete record.messageStart
|
|
205
|
+
delete record.messageEnd
|
|
206
|
+
} else {
|
|
207
|
+
record.messageStart = messageStart
|
|
208
|
+
record.messageEnd = messageEnd
|
|
209
|
+
}
|
|
210
|
+
if (turn === undefined) delete record.turn
|
|
211
|
+
else record.turn = turn
|
|
212
|
+
return record
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Normalize one incoming message capture `{ key, text, turn }` (the full text
|
|
217
|
+
* of the message an annotation belongs to). Returns null when it is unusable;
|
|
218
|
+
* a bad capture never fails the annotation itself.
|
|
219
|
+
*/
|
|
220
|
+
export function validateMessageInput(raw) {
|
|
221
|
+
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
|
|
222
|
+
const key = typeof raw.key === 'string' ? raw.key.trim().slice(0, MAX_MESSAGE_KEY_LENGTH) : ''
|
|
223
|
+
if (key === '') return null
|
|
224
|
+
if (typeof raw.text !== 'string' || raw.text.length === 0 || raw.text.length > MAX_MESSAGE_TEXT_LENGTH) {
|
|
225
|
+
return null
|
|
226
|
+
}
|
|
227
|
+
const turn = optionalInteger(raw.turn)
|
|
228
|
+
return turn === undefined ? { key, text: raw.text } : { key, text: raw.text, turn }
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/** Normalize one stored record. Returns null for a malformed entry. */
|
|
232
|
+
function normalizeStoredAnnotation(raw) {
|
|
233
|
+
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
|
|
234
|
+
if (typeof raw.id !== 'string' || raw.id.trim() === '') return null
|
|
235
|
+
if (!ANNOTATION_STYLES.includes(raw.style)) return null
|
|
236
|
+
if (typeof raw.quote !== 'string') return null
|
|
237
|
+
const quoteLength = raw.quote.trim().length
|
|
238
|
+
if (quoteLength < 1 || quoteLength > MAX_QUOTE_LENGTH) return null
|
|
239
|
+
if (typeof raw.createdAt !== 'string' || raw.createdAt.trim() === '') return null
|
|
240
|
+
const messageKey = truncate(raw.messageKey, MAX_MESSAGE_KEY_LENGTH)
|
|
241
|
+
const messageStart = optionalInteger(raw.messageStart)
|
|
242
|
+
const messageEnd = optionalInteger(raw.messageEnd)
|
|
243
|
+
const anchored =
|
|
244
|
+
messageKey !== '' && messageStart !== undefined && messageEnd !== undefined && messageEnd > messageStart
|
|
245
|
+
const injections = optionalInteger(raw.injections) ?? 0
|
|
246
|
+
const status = ANNOTATION_STATUSES.includes(raw.status) ? raw.status : 'pending'
|
|
247
|
+
const record = withAnchor({
|
|
248
|
+
...raw,
|
|
249
|
+
id: truncate(raw.id.trim(), MAX_ID_LENGTH),
|
|
250
|
+
style: raw.style,
|
|
251
|
+
quote: raw.quote,
|
|
252
|
+
note: truncate(typeof raw.note === 'string' ? raw.note.trim() : '', MAX_NOTE_LENGTH),
|
|
253
|
+
prefix: truncate(raw.prefix, MAX_CONTEXT_LENGTH),
|
|
254
|
+
suffix: truncate(raw.suffix, MAX_CONTEXT_LENGTH),
|
|
255
|
+
rootSelector: truncate(raw.rootSelector, MAX_ROOT_SELECTOR_LENGTH),
|
|
256
|
+
messageKey: anchored ? messageKey : '',
|
|
257
|
+
createdAt: raw.createdAt,
|
|
258
|
+
status,
|
|
259
|
+
injections,
|
|
260
|
+
}, anchored ? messageStart : undefined, anchored ? messageEnd : undefined, optionalInteger(raw.turn))
|
|
261
|
+
if (status === 'resolved') {
|
|
262
|
+
record.resolvedAt = typeof raw.resolvedAt === 'string' ? raw.resolvedAt : raw.createdAt
|
|
263
|
+
record.resolvedBy = typeof raw.resolvedBy === 'string' ? raw.resolvedBy.slice(0, 20) : 'user'
|
|
264
|
+
} else {
|
|
265
|
+
delete record.resolvedAt
|
|
266
|
+
delete record.resolvedBy
|
|
267
|
+
}
|
|
268
|
+
if (record.lastInjectedTurn !== undefined && optionalInteger(record.lastInjectedTurn) === undefined) {
|
|
269
|
+
delete record.lastInjectedTurn
|
|
270
|
+
}
|
|
271
|
+
return record
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
function normalizeStoredMessages(raw, annotations) {
|
|
275
|
+
const messages = {}
|
|
276
|
+
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return messages
|
|
277
|
+
const referenced = new Set(annotations.map(item => item.messageKey).filter(key => key !== ''))
|
|
278
|
+
for (const [key, value] of Object.entries(raw)) {
|
|
279
|
+
if (!referenced.has(key)) continue
|
|
280
|
+
const message = validateMessageInput({ ...(value ?? {}), key })
|
|
281
|
+
if (message !== null) messages[key] = { text: message.text, ...(message.turn === undefined ? {} : { turn: message.turn }) }
|
|
282
|
+
}
|
|
283
|
+
return messages
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/** Normalize one stored session. Returns null when it carries nothing worth keeping. */
|
|
287
|
+
function normalizeStoredSession(raw) {
|
|
288
|
+
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
|
|
289
|
+
const annotations = []
|
|
290
|
+
if (Array.isArray(raw.annotations)) {
|
|
291
|
+
for (const item of raw.annotations) {
|
|
292
|
+
const annotation = normalizeStoredAnnotation(item)
|
|
293
|
+
if (annotation !== null) annotations.push(annotation)
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
const mode = INJECTION_MODES.includes(raw.mode) && raw.mode !== DEFAULT_MODE ? raw.mode : undefined
|
|
297
|
+
if (annotations.length === 0 && mode === undefined) return null
|
|
298
|
+
const capped =
|
|
299
|
+
annotations.length > MAX_ANNOTATIONS_PER_SESSION
|
|
300
|
+
? annotations.slice(-MAX_ANNOTATIONS_PER_SESSION)
|
|
301
|
+
: annotations
|
|
302
|
+
const session = { annotations: capped, messages: normalizeStoredMessages(raw.messages, capped) }
|
|
303
|
+
if (mode !== undefined) session.mode = mode
|
|
304
|
+
return session
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Coerce an arbitrary parsed document into the safe in-memory shape. Never
|
|
309
|
+
* throws: garbage sections and malformed records are dropped, empty session
|
|
310
|
+
* keys are removed, and the per-session cap is re-applied.
|
|
311
|
+
*/
|
|
312
|
+
export function normalizeState(raw) {
|
|
313
|
+
const state = emptyState()
|
|
314
|
+
try {
|
|
315
|
+
const sessions =
|
|
316
|
+
raw !== null &&
|
|
317
|
+
typeof raw === 'object' &&
|
|
318
|
+
!Array.isArray(raw) &&
|
|
319
|
+
raw.sessions !== null &&
|
|
320
|
+
typeof raw.sessions === 'object' &&
|
|
321
|
+
!Array.isArray(raw.sessions)
|
|
322
|
+
? raw.sessions
|
|
323
|
+
: {}
|
|
324
|
+
for (const [sessionId, sessionRaw] of Object.entries(sessions)) {
|
|
325
|
+
if (
|
|
326
|
+
typeof sessionId !== 'string' ||
|
|
327
|
+
sessionId.trim() === '' ||
|
|
328
|
+
sessionId.length > MAX_SESSION_ID_LENGTH
|
|
329
|
+
) {
|
|
330
|
+
continue
|
|
331
|
+
}
|
|
332
|
+
const session = normalizeStoredSession(sessionRaw)
|
|
333
|
+
if (session !== null) state.sessions[sessionId] = session
|
|
334
|
+
}
|
|
335
|
+
} catch {
|
|
336
|
+
// `normalizeState` never throws; a partially normalized document is fine.
|
|
337
|
+
}
|
|
338
|
+
return state
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
/** Drop session keys that carry nothing (no annotations and the default mode). */
|
|
342
|
+
function pruneEmptySessions(state) {
|
|
343
|
+
if (state === null || typeof state !== 'object' || Array.isArray(state)) return state
|
|
344
|
+
if (state.sessions === null || typeof state.sessions !== 'object' || Array.isArray(state.sessions)) {
|
|
345
|
+
state.sessions = {}
|
|
346
|
+
return state
|
|
347
|
+
}
|
|
348
|
+
for (const [sessionId, session] of Object.entries(state.sessions)) {
|
|
349
|
+
const empty =
|
|
350
|
+
session === null ||
|
|
351
|
+
typeof session !== 'object' ||
|
|
352
|
+
!Array.isArray(session.annotations) ||
|
|
353
|
+
session.annotations.length === 0
|
|
354
|
+
const defaultMode = session?.mode === undefined || session?.mode === DEFAULT_MODE
|
|
355
|
+
if (empty && defaultMode) {
|
|
356
|
+
delete state.sessions[sessionId]
|
|
357
|
+
} else if (empty) {
|
|
358
|
+
session.annotations = []
|
|
359
|
+
session.messages = {}
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
return state
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
function ensureDirectory(filePath) {
|
|
366
|
+
fs.mkdirSync(path.dirname(filePath), { recursive: true })
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Load a document. A missing file means an empty document; a corrupt file is
|
|
371
|
+
* copied aside (`state.json.corrupt-<ts>`) instead of being silently
|
|
372
|
+
* overwritten. Never throws.
|
|
373
|
+
*/
|
|
374
|
+
export function loadStateFile(filePath, { logger } = {}) {
|
|
375
|
+
try {
|
|
376
|
+
ensureDirectory(filePath)
|
|
377
|
+
} catch (error) {
|
|
378
|
+
logger?.warn?.(`dsh-mindmark: cannot create the annotation directory: ${String(error)}`)
|
|
379
|
+
return emptyState()
|
|
380
|
+
}
|
|
381
|
+
let raw
|
|
382
|
+
try {
|
|
383
|
+
raw = fs.readFileSync(filePath, 'utf8')
|
|
384
|
+
} catch (error) {
|
|
385
|
+
if (error?.code !== 'ENOENT') {
|
|
386
|
+
logger?.warn?.(`dsh-mindmark: cannot read ${filePath}: ${String(error)}`)
|
|
387
|
+
}
|
|
388
|
+
return emptyState()
|
|
389
|
+
}
|
|
390
|
+
try {
|
|
391
|
+
return normalizeState(JSON.parse(raw))
|
|
392
|
+
} catch (error) {
|
|
393
|
+
const backup = `${filePath}.corrupt-${Date.now()}`
|
|
394
|
+
try {
|
|
395
|
+
fs.copyFileSync(filePath, backup)
|
|
396
|
+
} catch {
|
|
397
|
+
// Best effort: the unreadable original remains in place.
|
|
398
|
+
}
|
|
399
|
+
logger?.warn?.(
|
|
400
|
+
`dsh-mindmark: annotation state was unreadable (${String(error)}); backup at ${backup}`,
|
|
401
|
+
)
|
|
402
|
+
return emptyState()
|
|
403
|
+
}
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
/** `state.json` -> `state.backup.json` (contract's name). */
|
|
407
|
+
export function backupPathFor(filePath) {
|
|
408
|
+
const base = path.basename(filePath)
|
|
409
|
+
const stem = base.toLowerCase().endsWith('.json') ? base.slice(0, -'.json'.length) : base
|
|
410
|
+
return path.join(path.dirname(filePath), `${stem}.backup.json`)
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
/** Windows can briefly lock the destination after an antivirus scan. */
|
|
414
|
+
function replaceWithRetry(temp, filePath) {
|
|
415
|
+
let lastError
|
|
416
|
+
for (let attempt = 0; attempt < 6; attempt += 1) {
|
|
417
|
+
try {
|
|
418
|
+
fs.renameSync(temp, filePath)
|
|
419
|
+
return
|
|
420
|
+
} catch (error) {
|
|
421
|
+
lastError = error
|
|
422
|
+
if (error?.code !== 'EPERM' && error?.code !== 'EBUSY' && error?.code !== 'EACCES') {
|
|
423
|
+
throw error
|
|
424
|
+
}
|
|
425
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 40 * (attempt + 1))
|
|
426
|
+
}
|
|
427
|
+
}
|
|
428
|
+
// A non-atomic copy is still preferable to losing the user's annotations.
|
|
429
|
+
fs.copyFileSync(temp, filePath)
|
|
430
|
+
fs.unlinkSync(temp)
|
|
431
|
+
if (!fs.existsSync(filePath)) throw lastError
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
/** Atomically replace the document, keeping one previous good copy. */
|
|
435
|
+
export function saveStateFile(filePath, state) {
|
|
436
|
+
ensureDirectory(filePath)
|
|
437
|
+
const document = pruneEmptySessions(
|
|
438
|
+
state !== null && typeof state === 'object' && !Array.isArray(state) ? state : emptyState(),
|
|
439
|
+
)
|
|
440
|
+
const json = `${JSON.stringify(document, null, 2)}\n`
|
|
441
|
+
const temp = `${filePath}.${process.pid}.${Date.now()}.tmp`
|
|
442
|
+
fs.writeFileSync(temp, json, { encoding: 'utf8', mode: 0o600 })
|
|
443
|
+
try {
|
|
444
|
+
if (fs.existsSync(filePath)) {
|
|
445
|
+
try {
|
|
446
|
+
fs.copyFileSync(filePath, backupPathFor(filePath))
|
|
447
|
+
} catch {
|
|
448
|
+
// The next successful write can try the backup again.
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
replaceWithRetry(temp, filePath)
|
|
452
|
+
} finally {
|
|
453
|
+
try {
|
|
454
|
+
if (fs.existsSync(temp)) fs.unlinkSync(temp)
|
|
455
|
+
} catch {
|
|
456
|
+
// Leftover temp files are harmless.
|
|
457
|
+
}
|
|
458
|
+
}
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
function cleanIds(ids) {
|
|
462
|
+
return new Set((Array.isArray(ids) ? ids : []).filter(id => typeof id === 'string' && id.trim() !== ''))
|
|
463
|
+
}
|
|
464
|
+
|
|
465
|
+
/**
|
|
466
|
+
* Small synchronous store; the document is tiny and mutations are serialized.
|
|
467
|
+
* Save failures are logged but never thrown, so the HTTP handler and the tool
|
|
468
|
+
* keep working with the in-memory document.
|
|
469
|
+
*/
|
|
470
|
+
export class AnnotationStore {
|
|
471
|
+
constructor(filePath, { logger, defaultMode } = {}) {
|
|
472
|
+
this.filePath = filePath ?? resolveStatePath()
|
|
473
|
+
this.logger = logger
|
|
474
|
+
this.defaultMode = INJECTION_MODES.includes(defaultMode) ? defaultMode : DEFAULT_MODE
|
|
475
|
+
this.state = loadStateFile(this.filePath, { logger })
|
|
476
|
+
this.lastSaveError = null
|
|
477
|
+
// Canonicalize what was loaded (and create the file early, best effort).
|
|
478
|
+
this.persist()
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
/** Session id -> safe session object, or undefined. */
|
|
482
|
+
sessionFor(sessionId) {
|
|
483
|
+
if (typeof sessionId !== 'string') return undefined
|
|
484
|
+
const session = this.state.sessions[sessionId]
|
|
485
|
+
if (
|
|
486
|
+
session === null ||
|
|
487
|
+
typeof session !== 'object' ||
|
|
488
|
+
!Array.isArray(session.annotations)
|
|
489
|
+
) {
|
|
490
|
+
return undefined
|
|
491
|
+
}
|
|
492
|
+
if (session.messages === null || typeof session.messages !== 'object' || Array.isArray(session.messages)) {
|
|
493
|
+
session.messages = {}
|
|
494
|
+
}
|
|
495
|
+
return session
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
ensureSession(sessionId) {
|
|
499
|
+
const key = validateSessionId(sessionId)
|
|
500
|
+
let session = this.sessionFor(key)
|
|
501
|
+
if (session === undefined) {
|
|
502
|
+
session = { annotations: [], messages: {} }
|
|
503
|
+
this.state.sessions[key] = session
|
|
504
|
+
}
|
|
505
|
+
return session
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/** Oldest first, always a fresh array. */
|
|
509
|
+
list(sessionId) {
|
|
510
|
+
const session = this.sessionFor(sessionId)
|
|
511
|
+
if (session === undefined) return []
|
|
512
|
+
return session.annotations.map(annotation => ({ ...annotation }))
|
|
513
|
+
}
|
|
514
|
+
|
|
515
|
+
/** Annotations still waiting for the model, oldest first. */
|
|
516
|
+
pending(sessionId) {
|
|
517
|
+
return this.list(sessionId).filter(annotation => annotation.status !== 'resolved')
|
|
518
|
+
}
|
|
519
|
+
|
|
520
|
+
/** The injection mode for one session (the configured default when unset). */
|
|
521
|
+
getMode(sessionId) {
|
|
522
|
+
const session = this.sessionFor(sessionId)
|
|
523
|
+
const mode = session?.mode
|
|
524
|
+
return INJECTION_MODES.includes(mode) ? mode : this.defaultMode
|
|
525
|
+
}
|
|
526
|
+
|
|
527
|
+
/** Record the injection mode for one session. */
|
|
528
|
+
setMode(sessionId, mode) {
|
|
529
|
+
const next = validateMode(mode)
|
|
530
|
+
const session = this.ensureSession(sessionId)
|
|
531
|
+
if (next === this.defaultMode) delete session.mode
|
|
532
|
+
else session.mode = next
|
|
533
|
+
this.persist()
|
|
534
|
+
return next
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
/** The captured full text of one message, or undefined. */
|
|
538
|
+
messageOf(sessionId, messageKey) {
|
|
539
|
+
const session = this.sessionFor(sessionId)
|
|
540
|
+
if (session === undefined || typeof messageKey !== 'string' || messageKey === '') return undefined
|
|
541
|
+
const message = session.messages[messageKey]
|
|
542
|
+
if (message === null || typeof message !== 'object' || typeof message.text !== 'string') return undefined
|
|
543
|
+
return { ...message }
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
/** Everything the injection builder needs for one session. */
|
|
547
|
+
snapshot(sessionId) {
|
|
548
|
+
const session = this.sessionFor(sessionId)
|
|
549
|
+
return {
|
|
550
|
+
mode: this.getMode(sessionId),
|
|
551
|
+
annotations: this.list(sessionId),
|
|
552
|
+
messages:
|
|
553
|
+
session === undefined
|
|
554
|
+
? {}
|
|
555
|
+
: Object.fromEntries(Object.entries(session.messages).map(([key, value]) => [key, { ...value }])),
|
|
556
|
+
}
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
/**
|
|
560
|
+
* Append one annotation. An identical `(style, quote, prefix, suffix, note)`
|
|
561
|
+
* marks the same passage again: its `createdAt` is refreshed, it becomes
|
|
562
|
+
* pending again and moves to the end instead of being duplicated. The
|
|
563
|
+
* per-session cap drops the oldest. `message` optionally captures the full
|
|
564
|
+
* text of the message the annotation belongs to.
|
|
565
|
+
*/
|
|
566
|
+
add(sessionId, annotation, message) {
|
|
567
|
+
const record = validateAnnotationInput(annotation)
|
|
568
|
+
const session = this.ensureSession(sessionId)
|
|
569
|
+
const capture = validateMessageInput(message)
|
|
570
|
+
if (capture !== null && record.messageKey === capture.key) {
|
|
571
|
+
session.messages[capture.key] = {
|
|
572
|
+
text: capture.text,
|
|
573
|
+
...(capture.turn === undefined ? {} : { turn: capture.turn }),
|
|
574
|
+
}
|
|
575
|
+
if (record.turn === undefined && capture.turn !== undefined) record.turn = capture.turn
|
|
576
|
+
} else if (record.messageKey !== '' && session.messages[record.messageKey] === undefined) {
|
|
577
|
+
// Anchored to a message we never captured: keep the offsets harmless.
|
|
578
|
+
record.messageKey = ''
|
|
579
|
+
record.messageStart = undefined
|
|
580
|
+
record.messageEnd = undefined
|
|
581
|
+
}
|
|
582
|
+
const index = session.annotations.findIndex(
|
|
583
|
+
item =>
|
|
584
|
+
item.style === record.style &&
|
|
585
|
+
item.quote === record.quote &&
|
|
586
|
+
item.prefix === record.prefix &&
|
|
587
|
+
item.suffix === record.suffix &&
|
|
588
|
+
item.note === record.note,
|
|
589
|
+
)
|
|
590
|
+
let result
|
|
591
|
+
if (index >= 0) {
|
|
592
|
+
const existing = session.annotations[index]
|
|
593
|
+
const anchorSource = record.messageKey !== '' ? record : existing
|
|
594
|
+
const refreshed = withAnchor({
|
|
595
|
+
...existing,
|
|
596
|
+
createdAt: record.createdAt,
|
|
597
|
+
status: 'pending',
|
|
598
|
+
injections: 0,
|
|
599
|
+
messageKey: anchorSource.messageKey ?? '',
|
|
600
|
+
}, anchorSource.messageStart, anchorSource.messageEnd, record.turn ?? existing.turn)
|
|
601
|
+
delete refreshed.resolvedAt
|
|
602
|
+
delete refreshed.resolvedBy
|
|
603
|
+
delete refreshed.lastInjectedTurn
|
|
604
|
+
session.annotations.splice(index, 1)
|
|
605
|
+
session.annotations.push(refreshed)
|
|
606
|
+
result = { annotation: { ...refreshed }, deduped: true }
|
|
607
|
+
} else {
|
|
608
|
+
session.annotations.push({ ...record })
|
|
609
|
+
if (session.annotations.length > MAX_ANNOTATIONS_PER_SESSION) {
|
|
610
|
+
session.annotations.splice(0, session.annotations.length - MAX_ANNOTATIONS_PER_SESSION)
|
|
611
|
+
}
|
|
612
|
+
result = { annotation: { ...record }, deduped: false }
|
|
613
|
+
}
|
|
614
|
+
this.pruneMessages(session)
|
|
615
|
+
this.persist()
|
|
616
|
+
return result
|
|
617
|
+
}
|
|
618
|
+
|
|
619
|
+
/** Drop captured messages no annotation references any more. */
|
|
620
|
+
pruneMessages(session) {
|
|
621
|
+
const referenced = new Set(session.annotations.map(item => item.messageKey).filter(key => key !== ''))
|
|
622
|
+
for (const key of Object.keys(session.messages)) {
|
|
623
|
+
if (!referenced.has(key)) delete session.messages[key]
|
|
624
|
+
}
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
/** Remove annotations by id. Returns how many were removed. */
|
|
628
|
+
remove(sessionId, ids) {
|
|
629
|
+
const session = this.sessionFor(sessionId)
|
|
630
|
+
if (session === undefined) return 0
|
|
631
|
+
const wanted = cleanIds(ids)
|
|
632
|
+
if (wanted.size === 0) return 0
|
|
633
|
+
const before = session.annotations.length
|
|
634
|
+
session.annotations = session.annotations.filter(item => !wanted.has(item.id))
|
|
635
|
+
const removed = before - session.annotations.length
|
|
636
|
+
if (removed > 0) {
|
|
637
|
+
this.pruneMessages(session)
|
|
638
|
+
this.persist()
|
|
639
|
+
}
|
|
640
|
+
return removed
|
|
641
|
+
}
|
|
642
|
+
|
|
643
|
+
/** Remove every annotation of one session (the mode is kept). Returns how many were removed. */
|
|
644
|
+
clear(sessionId) {
|
|
645
|
+
const session = this.sessionFor(sessionId)
|
|
646
|
+
if (session === undefined) return 0
|
|
647
|
+
const removed = session.annotations.length
|
|
648
|
+
session.annotations = []
|
|
649
|
+
session.messages = {}
|
|
650
|
+
if (removed > 0) this.persist()
|
|
651
|
+
return removed
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
/**
|
|
655
|
+
* Mark annotations as handled. `ids` undefined/empty means every pending
|
|
656
|
+
* annotation. `by` records who settled them: `model`, `user` or `cap`.
|
|
657
|
+
* Returns the ids that changed.
|
|
658
|
+
*/
|
|
659
|
+
resolve(sessionId, ids, { by = 'user', at } = {}) {
|
|
660
|
+
const session = this.sessionFor(sessionId)
|
|
661
|
+
if (session === undefined) return []
|
|
662
|
+
const wanted = cleanIds(ids)
|
|
663
|
+
const stamp = typeof at === 'string' ? at : new Date().toISOString()
|
|
664
|
+
const changed = []
|
|
665
|
+
for (const item of session.annotations) {
|
|
666
|
+
if (item.status === 'resolved') continue
|
|
667
|
+
if (wanted.size > 0 && !wanted.has(item.id)) continue
|
|
668
|
+
item.status = 'resolved'
|
|
669
|
+
item.resolvedAt = stamp
|
|
670
|
+
item.resolvedBy = by
|
|
671
|
+
changed.push(item.id)
|
|
672
|
+
}
|
|
673
|
+
if (changed.length > 0) this.persist()
|
|
674
|
+
return changed
|
|
675
|
+
}
|
|
676
|
+
|
|
677
|
+
/**
|
|
678
|
+
* Put annotations back in front of the model. `ids` undefined/empty means
|
|
679
|
+
* every annotation. The injection counter restarts. Returns the ids that changed.
|
|
680
|
+
*/
|
|
681
|
+
reopen(sessionId, ids) {
|
|
682
|
+
const session = this.sessionFor(sessionId)
|
|
683
|
+
if (session === undefined) return []
|
|
684
|
+
const wanted = cleanIds(ids)
|
|
685
|
+
const changed = []
|
|
686
|
+
for (const item of session.annotations) {
|
|
687
|
+
if (wanted.size > 0 && !wanted.has(item.id)) continue
|
|
688
|
+
if (item.status === 'pending' && item.injections === 0) continue
|
|
689
|
+
item.status = 'pending'
|
|
690
|
+
item.injections = 0
|
|
691
|
+
delete item.resolvedAt
|
|
692
|
+
delete item.resolvedBy
|
|
693
|
+
delete item.lastInjectedTurn
|
|
694
|
+
changed.push(item.id)
|
|
695
|
+
}
|
|
696
|
+
if (changed.length > 0) this.persist()
|
|
697
|
+
return changed
|
|
698
|
+
}
|
|
699
|
+
|
|
700
|
+
/**
|
|
701
|
+
* Count one injection for the given pending annotations and settle those
|
|
702
|
+
* that reached `cap` before this turn (`resolvedBy: 'cap'`).
|
|
703
|
+
* Returns `{ injected: ids, capped: ids }`; only `injected` were included.
|
|
704
|
+
*/
|
|
705
|
+
markInjected(sessionId, ids, { turn, cap } = {}) {
|
|
706
|
+
const session = this.sessionFor(sessionId)
|
|
707
|
+
if (session === undefined) return { injected: [], capped: [] }
|
|
708
|
+
const wanted = cleanIds(ids)
|
|
709
|
+
const injected = []
|
|
710
|
+
const capped = []
|
|
711
|
+
const limit = Number.isInteger(cap) && cap > 0 ? cap : undefined
|
|
712
|
+
for (const item of session.annotations) {
|
|
713
|
+
if (item.status === 'resolved' || !wanted.has(item.id)) continue
|
|
714
|
+
if (limit !== undefined && item.injections >= limit) {
|
|
715
|
+
item.status = 'resolved'
|
|
716
|
+
item.resolvedAt = new Date().toISOString()
|
|
717
|
+
item.resolvedBy = 'cap'
|
|
718
|
+
capped.push(item.id)
|
|
719
|
+
continue
|
|
720
|
+
}
|
|
721
|
+
item.injections += 1
|
|
722
|
+
if (Number.isInteger(turn)) item.lastInjectedTurn = turn
|
|
723
|
+
injected.push(item.id)
|
|
724
|
+
}
|
|
725
|
+
if (injected.length > 0 || capped.length > 0) this.persist()
|
|
726
|
+
return { injected, capped }
|
|
727
|
+
}
|
|
728
|
+
|
|
729
|
+
/** Pending annotations that may still be injected under `cap`. */
|
|
730
|
+
injectable(sessionId, cap) {
|
|
731
|
+
const limit = Number.isInteger(cap) && cap > 0 ? cap : undefined
|
|
732
|
+
return this.pending(sessionId).filter(item => limit === undefined || item.injections < limit)
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
/** Save the document; failures are logged and recorded, never thrown. */
|
|
736
|
+
persist() {
|
|
737
|
+
try {
|
|
738
|
+
saveStateFile(this.filePath, this.state)
|
|
739
|
+
this.lastSaveError = null
|
|
740
|
+
return true
|
|
741
|
+
} catch (error) {
|
|
742
|
+
this.lastSaveError = error
|
|
743
|
+
this.logger?.warn?.(`dsh-mindmark: cannot save ${this.filePath}: ${String(error)}`)
|
|
744
|
+
return false
|
|
745
|
+
}
|
|
746
|
+
}
|
|
747
|
+
}
|