@restregular/dsh-memory 0.11.1 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,219 @@
1
+ /**
2
+ * 注入审计 v2 的事件类型。
3
+ *
4
+ * 这些类型是 **memory-inject 与面板 API 的共同语义**:store 负责生成
5
+ * `id/seq/at/schemaVersion`,调用方只提供事实字段。设计口径见
6
+ * `docs/audit-implementation-review.md` 与 audit v2 实施计划:
7
+ *
8
+ * - evaluation 评估:候选、选中、省略、预算、检索/加载结果
9
+ * - delivery 投递:最终消息是否真的被追加,或被什么拦下
10
+ * - signal 信号:观察到、入队、消费
11
+ * - lifecycle 生命周期:压缩、禁用、审计存储健康
12
+ * - error 错误:失败阶段 + 稳定错误码(不存堆栈/原文)
13
+ *
14
+ * 不变量:
15
+ * - 不存记忆正文、原始工具参数、完整提示词、异常堆栈;
16
+ * - 所有自由文本必须已经过 `sanitizeAuditText`;
17
+ * - `selected.contentIds` 只表示“被评估选中”,不等于“已投递”;
18
+ * - 只有拿到追加成功的事实才能写 `delivery.status='appended'`。
19
+ */
20
+
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+
40
+
41
+
42
+
43
+
44
+
45
+
46
+
47
+
48
+
49
+
50
+
51
+
52
+
53
+
54
+
55
+
56
+
57
+                       
58
+
59
+                   
60
+
61
+           
62
+
63
+                    
64
+
65
+
66
+
67
+
68
+
69
+
70
+
71
+
72
+
73
+
74
+
75
+                 
76
+
77
+          
78
+
79
+          
80
+
81
+            
82
+
83
+
84
+
85
+
86
+
87
+
88
+
89
+
90
+
91
+
92
+
93
+
94
+
95
+
96
+
97
+     
98
+
99
+
100
+
101
+
102
+
103
+
104
+
105
+
106
+
107
+
108
+
109
+
110
+
111
+
112
+                           
113
+
114
+
115
+                    
116
+
117
+
118
+                          
119
+
120
+
121
+
122
+
123
+
124
+
125
+
126
+
127
+
128
+
129
+
130
+                     
131
+
132
+
133
+
134
+
135
+
136
+
137
+
138
+
139
+
140
+
141
+
142
+
143
+
144
+
145
+
146
+
147
+
148
+
149
+
150
+
151
+
152
+
153
+
154
+
155
+
156
+
157
+
158
+
159
+
160
+
161
+
162
+
163
+
164
+
165
+
166
+
167
+
168
+
169
+
170
+                  
171
+
172
+
173
+
174
+ /** store 负责生成 schemaVersion/id/seq/at;调用方只给事实。 */
175
+
176
+
177
+
178
+
179
+
180
+
181
+
182
+
183
+
184
+
185
+                      
186
+
187
+
188
+
189
+
190
+
191
+
192
+
193
+
194
+
195
+
196
+
197
+
198
+
199
+
200
+
201
+
202
+
203
+
204
+
205
+
206
+
207
+
208
+
209
+
210
+
211
+
212
+
213
+
214
+
215
+
216
+
217
+
218
+
219
+ //# sourceURL=source/memory-inject/src/audit-types.ts
@@ -1,87 +1,330 @@
1
1
  /**
2
- * 注入审计:每次摘要/召回评估都留一条结构化记录。
2
+ * 注入审计 v2:进程内有界存储 + 类型化查询 + 统一脱敏。
3
3
  *
4
- * 第一版不要求复杂 UI:记录放在内存环形缓冲里,provider 通过
5
- * `attachInjectAudit()` 挂上,面板 `GET /memory/api/audit?session=` 读取。
6
- * 不记录任何凭据/令牌;检索查询会先过凭据脱敏,再最多截到 200 字。
4
+ * 定位(见 docs/audit-implementation-review.md):这是“可观测、可查询、可核对”
5
+ * 的注入诊断系统,不是法律意义上的防篡改审计。存储默认在内存,重启即失;
6
+ * 但必须如实暴露 capacity/dropped/writeErrors/persistence。
7
+ *
8
+ * 安全边界:
9
+ * - 所有自由文本在写入前必须经过 `sanitizeAuditText` / `auditQuery`;
10
+ * - 先限制扫描长度(默认 4000 字符),再跑凭据正则,最后截到 200 字;
11
+ * - 不保存正文、原始工具参数、异常堆栈;错误只保存稳定 code。
12
+ *
13
+ * 记录失败绝不能影响 Agent 主链路:`record()` 内部吞掉异常并累加 writeErrors。
7
14
  */
8
15
 
9
16
  import { redactSecrets } from '../provider/secrets.js'
10
-
11
-
12
-
13
-
14
-
15
-
16
-
17
-
17
+
18
18
 
19
-
20
-
21
-
22
-
23
-
24
-
25
19
 
20
+
26
21
 
27
-
22
+
28
23
 
29
-                     
24
+
25
+
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
30
34
 
31
-
32
-
33
35
 
36
+
37
+
34
38
 
35
-
36
-
37
-
38
-
39
-         
40
-
39
+
40
+
41
+
42
+
43
+
44
+
45
+
46
+
47
+
41
48
 
42
-
43
49
 
44
-
45
-
46
-
47
-
48
-                          
49
-
50
-
51
-
52
50
 
53
- const MAX_ENTRIES = 200
51
+ export const AUDIT_SCHEMA_VERSION = 2
52
+ export const DEFAULT_AUDIT_CAPACITY = 2000
53
+ export const DEFAULT_AUDIT_PER_SESSION = 200
54
+ export const DEFAULT_AUDIT_LIMIT = 50
55
+ export const MAX_AUDIT_LIMIT = 200
56
+
57
+ /** 查询参数错误:面板应把这个 code 映射成 400。 */
58
+ export class AuditQueryError extends Error {
59
+ code
60
+ constructor(code , message ) {
61
+ super(message)
62
+ this.name = 'AuditQueryError'
63
+ this.code = code
64
+ }
65
+ }
66
+
67
+ const MAX_SANITIZE_SCAN = 4000
68
+
69
+ /** 稳定短 hash(FNV-1a 32):用于比较文本是否相同,不保存原文。 */
70
+ export function hashAuditText(text ) {
71
+ let hash = 0x811c9dc5
72
+ for (let i = 0; i < text.length; i++) {
73
+ hash ^= text.charCodeAt(i)
74
+ hash = Math.imul(hash, 16777619)
75
+ }
76
+ return `fnv1a:${(hash >>> 0).toString(16).padStart(8, '0')}`
77
+ }
78
+
79
+ /** 统一的自由文本安全处理:限制扫描长度 → 脱敏 → 折叠空白 → 截断。 */
80
+ export function sanitizeAuditText(text , maxChars = 200) {
81
+ if (typeof text !== 'string' || text.trim() === '') return undefined
82
+ const source = text.slice(0, MAX_SANITIZE_SCAN)
83
+ const redactedText = redactSecrets(source)
84
+ const redacted = redactedText !== source
85
+ const compact = redactedText.replace(/\s+/g, ' ').trim()
86
+ const clipped = compact.slice(0, Math.max(1, maxChars))
87
+ return {
88
+ ...(clipped === '' ? {} : { text: clipped }),
89
+ chars: text.length,
90
+ redacted,
91
+ hash: hashAuditText(compact),
92
+ }
93
+ }
94
+
95
+ /** 兼容旧调用:只返回脱敏后的文本。 */
96
+ export function auditQuery(text ) {
97
+ return sanitizeAuditText(text)?.text
98
+ }
99
+
100
+ /** 标签也可能包含自由文本:逐项脱敏、限长、去重、限量。 */
101
+ export function sanitizeAuditTags(tags , maxItems = 8) {
102
+ if (!Array.isArray(tags)) return []
103
+ const out = []
104
+ const seen = new Set ()
105
+ for (const tag of tags) {
106
+ const field = sanitizeAuditText(String(tag), 40)
107
+ const value = field?.text
108
+ if (value === undefined || seen.has(value)) continue
109
+ seen.add(value)
110
+ out.push(value)
111
+ if (out.length >= maxItems) break
112
+ }
113
+ return out
114
+ }
115
+
116
+ export function auditBudget(budget , used ) {
117
+ const remaining = Math.max(0, budget - used)
118
+ return { budget, used, remaining, over: used > budget }
119
+ }
120
+
121
+ /** 结构化克隆;没有 structuredClone 的旧环境退回 JSON(条目都是纯数据)。 */
122
+ function cloneEntry(entry ) {
123
+ try {
124
+ return structuredClone(entry)
125
+ } catch {
126
+ return JSON.parse(JSON.stringify(entry))
127
+ }
128
+ }
129
+
130
+ function isKeyEntry(entry ) {
131
+ if (entry.kind === 'delivery' || entry.kind === 'error' || entry.kind === 'lifecycle') return true
132
+ return entry.channel === 'digest' || entry.channel === 'rules' || entry.channel === 'rules_delta'
133
+ }
134
+
135
+ function memoryIdsOf(entry ) {
136
+ const ids = []
137
+ const selected = entry.selected
138
+ if (selected !== undefined) {
139
+ ids.push(...(selected.contentIds ?? []), ...(selected.hintIds ?? []), ...(selected.newlyAddedIds ?? []))
140
+ }
141
+ for (const item of entry.omitted ?? []) ids.push(item.id)
142
+ const rules = entry.rules
143
+ if (rules !== undefined) {
144
+ ids.push(...(rules.injectedIds ?? []), ...(rules.omittedIds ?? []))
145
+ }
146
+ ids.push(...(entry.dedup?.ids ?? []))
147
+ return ids
148
+ }
149
+
150
+ function matchesQuery(entry , query ) {
151
+ if (query.sessionId !== undefined && entry.sessionId !== query.sessionId) return false
152
+ if (query.traceId !== undefined && entry.traceId !== query.traceId) return false
153
+ if (query.operationId !== undefined && entry.operationId !== query.operationId) return false
154
+ if (query.memoryId !== undefined && !memoryIdsOf(entry).includes(query.memoryId)) return false
155
+ if (query.channel !== undefined && entry.channel !== query.channel) return false
156
+ if (query.trigger !== undefined && entry.trigger !== query.trigger) return false
157
+ if (query.outcome !== undefined && entry.outcome !== query.outcome) return false
158
+ if (query.problem === true && !isProblemEntry(entry)) return false
159
+ if (query.since !== undefined && entry.at < query.since) return false
160
+ if (query.until !== undefined && entry.at > query.until) return false
161
+ return true
162
+ }
163
+
164
+ function isProblemEntry(entry ) {
165
+ if (entry.outcome === 'failed' || entry.outcome === 'partial') return true
166
+ if ((entry.omitted?.length ?? 0) > 0) return true
167
+ if (entry.error !== undefined) return true
168
+ const delivery = entry.delivery
169
+ if (delivery !== undefined && delivery.status !== 'appended' && delivery.status !== 'unknown') return true
170
+ return false
171
+ }
172
+
173
+ export class InjectAuditStore {
174
+ entries = []
175
+ seq = 0
176
+ dropped = 0
177
+ writeErrors = 0
178
+ lastRecordedAt
179
+ capacity
180
+ perSessionCapacity
54
181
 
55
- export class InjectAuditStore {
56
- entries = []
182
+ constructor(options = {}) {
183
+ this.capacity = Math.max(10, Math.floor(options.capacity ?? DEFAULT_AUDIT_CAPACITY))
184
+ this.perSessionCapacity = Math.max(1, Math.floor(options.perSessionCapacity ?? DEFAULT_AUDIT_PER_SESSION))
185
+ }
57
186
 
58
- record(entry ) {
59
- this.entries.push(entry)
60
- if (this.entries.length > MAX_ENTRIES) this.entries.splice(0, this.entries.length - MAX_ENTRIES)
187
+ /**
188
+ * 写入一条事件。store 负责生成 schemaVersion/id/seq/at;异常只累加 writeErrors,
189
+ * 绝不向调用方抛出(审计是旁路,不是控制面)。
190
+ */
191
+ record(draft ) {
192
+ try {
193
+ const seq = ++this.seq
194
+ const at = typeof draft.at === 'number' && Number.isFinite(draft.at) ? draft.at : Date.now()
195
+ const sessionId = draft.sessionId
196
+ const entry = {
197
+ ...draft,
198
+ schemaVersion: AUDIT_SCHEMA_VERSION,
199
+ id: `${sessionId ?? 'anonymous'}:${seq}`,
200
+ seq,
201
+ at,
202
+ }
203
+ this.entries.push(entry)
204
+ this.lastRecordedAt = at
205
+ this.trimSession(sessionId)
206
+ this.trimGlobal()
207
+ } catch {
208
+ this.writeErrors += 1
209
+ }
61
210
  }
62
211
 
63
- /** 最新在前;可按会话过滤。 */
64
- list(sessionId ) {
212
+ /** 旧接口:最新在前,可按会话过滤。返回副本。 */
213
+ list(sessionId ) {
65
214
  const list = sessionId === undefined
66
215
  ? this.entries
67
216
  : this.entries.filter((entry) => entry.sessionId === sessionId)
68
- return [...list].reverse()
217
+ return [...list].reverse().map(cloneEntry)
218
+ }
219
+
220
+ /** 类型化查询:稳定 seq 倒序、游标分页、返回副本与容量统计。 */
221
+ query(input = {}) {
222
+ const limit = this.resolveLimit(input.limit)
223
+ const cursor = this.resolveCursor(input.cursor)
224
+ const filtered = this.entries.filter((entry) => matchesQuery(entry, input))
225
+ const total = filtered.length
226
+ const afterCursor = cursor === undefined ? filtered : filtered.filter((entry) => entry.seq < cursor)
227
+ // entries 天然按 seq 升序写入;显式排序一次,避免未来导入数据打乱。
228
+ afterCursor.sort((a, b) => b.seq - a.seq)
229
+ const page = afterCursor.slice(0, limit)
230
+ const hasMore = afterCursor.length > page.length
231
+ const last = page[page.length - 1]
232
+ return {
233
+ entries: page.map(cloneEntry),
234
+ total,
235
+ ...(hasMore && last !== undefined ? { nextCursor: String(last.seq) } : {}),
236
+ stats: this.stats(),
237
+ }
69
238
  }
70
239
 
71
- clear() {
240
+ stats() {
241
+ return {
242
+ entries: this.entries.length,
243
+ capacity: this.capacity,
244
+ perSessionCapacity: this.perSessionCapacity,
245
+ dropped: this.dropped,
246
+ writeErrors: this.writeErrors,
247
+ persistence: 'memory',
248
+ ...(this.lastRecordedAt !== undefined ? { lastRecordedAt: this.lastRecordedAt } : {}),
249
+ }
250
+ }
251
+
252
+ /**
253
+ * 只允许清理明确范围:会话或“某时间之前”。没有范围时拒绝,避免一次误触清空全部。
254
+ */
255
+ clear(scope ) {
256
+ if (scope?.sessionId === undefined && scope?.before === undefined) {
257
+ throw new AuditQueryError('AUDIT_QUERY_INVALID', 'clear requires sessionId or before')
258
+ }
259
+ const before = this.entries.length
260
+ this.entries = this.entries.filter((entry) => {
261
+ const sessionMatch = scope.sessionId === undefined || entry.sessionId === scope.sessionId
262
+ const timeMatch = scope.before === undefined || entry.at < scope.before
263
+ return !(sessionMatch && timeMatch)
264
+ })
265
+ return before - this.entries.length
266
+ }
267
+
268
+ /** 插件半边卸载时释放内存;provider 负责不再引用。 */
269
+ dispose() {
72
270
  this.entries = []
73
271
  }
74
- }
75
272
 
76
- /** 查询文本里可能带用户内容:截断并折叠空白,不写凭据。 */
77
- export function auditQuery(text ) {
78
- if (typeof text !== 'string' || text.trim() === '') return undefined
79
- return redactSecrets(text).replace(/\s+/g, ' ').trim().slice(0, 200)
80
- }
273
+ resolveLimit(limit ) {
274
+ if (limit === undefined) return DEFAULT_AUDIT_LIMIT
275
+ if (!Number.isInteger(limit) || limit < 1 || limit > MAX_AUDIT_LIMIT) {
276
+ throw new AuditQueryError('AUDIT_QUERY_INVALID', `limit must be an integer between 1 and ${MAX_AUDIT_LIMIT}`)
277
+ }
278
+ return limit
279
+ }
81
280
 
82
- export function auditBudget(budget , used ) {
83
- return { budget, used, remaining: Math.max(0, budget - used) }
281
+ resolveCursor(cursor ) {
282
+ if (cursor === undefined || cursor === '') return undefined
283
+ if (!/^\d+$/.test(cursor)) throw new AuditQueryError('AUDIT_CURSOR_INVALID', 'cursor must be a seq number')
284
+ const value = Number(cursor)
285
+ if (!Number.isSafeInteger(value) || value < 1) {
286
+ throw new AuditQueryError('AUDIT_CURSOR_INVALID', 'cursor must be a positive seq number')
287
+ }
288
+ return value
289
+ }
290
+
291
+ trimSession(sessionId ) {
292
+ if (sessionId === undefined) return
293
+ let count = 0
294
+ for (const entry of this.entries) if (entry.sessionId === sessionId) count += 1
295
+ while (count > this.perSessionCapacity) {
296
+ const index = this.firstRemovable((entry) => entry.sessionId === sessionId)
297
+ if (index < 0) break
298
+ this.entries.splice(index, 1)
299
+ this.dropped += 1
300
+ count -= 1
301
+ }
302
+ }
303
+
304
+ trimGlobal() {
305
+ while (this.entries.length > this.capacity) {
306
+ const index = this.firstRemovable(() => true)
307
+ if (index < 0) break
308
+ this.entries.splice(index, 1)
309
+ this.dropped += 1
310
+ }
311
+ }
312
+
313
+ /** 优先淘汰非关键通道;全是关键通道时退回最早的。 */
314
+ firstRemovable(predicate ) {
315
+ for (let i = 0; i < this.entries.length; i++) {
316
+ const entry = this.entries[i]
317
+ if (predicate(entry) && !isKeyEntry(entry)) return i
318
+ }
319
+ for (let i = 0; i < this.entries.length; i++) {
320
+ if (predicate(this.entries[i] )) return i
321
+ }
322
+ return -1
323
+ }
84
324
  }
85
325
 
326
+ // 保持旧类型名可导入(外部/旧测试可能引用);新代码请用 AuditEntryV2。
327
+
328
+
86
329
 
87
330
  //# sourceURL=source/memory-inject/src/audit.ts