@xiangyixie/dsh-superagent 0.12.0 → 0.14.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/CHANGELOG.md +175 -0
- package/LICENSE +21 -21
- package/README.md +522 -40
- package/bin/archive.js +185 -185
- package/bin/doctor.js +84 -84
- package/bin/sync.js +187 -187
- package/bin/workbench.js +98 -98
- package/cordis.patch.yml +9 -9
- package/lib/audit.js +562 -555
- package/lib/browser.js +795 -0
- package/lib/console.js +763 -0
- package/lib/cost.js +327 -267
- package/lib/cron.js +387 -0
- package/lib/desktop.js +507 -0
- package/lib/doctor.js +879 -878
- package/lib/goal.js +649 -0
- package/lib/guard.js +856 -841
- package/lib/index.js +3285 -2031
- package/lib/inject.js +138 -138
- package/lib/ledger.js +284 -270
- package/lib/memory.js +736 -736
- package/lib/orchestrator.js +5480 -3851
- package/lib/policy.js +739 -739
- package/lib/report.js +1098 -1068
- package/lib/runtime-control.js +1151 -0
- package/lib/schedule.js +1030 -0
- package/lib/store.js +877 -873
- package/lib/sync.js +456 -456
- package/lib/templates.js +690 -690
- package/lib/user-memory.js +587 -0
- package/lib/watch.js +818 -810
- package/lib/workbench.js +1119 -1119
- package/lib/workspace.js +494 -433
- package/package.json +101 -92
- package/public/console.html +1618 -0
package/lib/audit.js
CHANGED
|
@@ -1,555 +1,562 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Append-only audit trail for dsh-superagent.
|
|
3
|
-
*
|
|
4
|
-
* One JSON object per line, one event per action: a tool call, a path write, a
|
|
5
|
-
* command, a block, a human approval, an attention decision, a run lifecycle
|
|
6
|
-
* step. The file is deliberately plain JSONL so it can be read with `jq`,
|
|
7
|
-
* `grep`, or a spreadsheet without this module, and so a crash cannot corrupt
|
|
8
|
-
* anything except the line that was being written.
|
|
9
|
-
*
|
|
10
|
-
* Concurrent appends are what make an audit log trustworthy in the first place:
|
|
11
|
-
* two workers finishing together must not splice their lines. Writes are
|
|
12
|
-
* serialized inside the process and guarded by a `wx`-created lock file across
|
|
13
|
-
* processes, and the line is written with a single append.
|
|
14
|
-
*
|
|
15
|
-
* This layer is independent of any path/command guard. A guard can be attached
|
|
16
|
-
* with `attachGuard`; when it returns a decision the audit records it, and the
|
|
17
|
-
* guard may only tighten what the policy already said.
|
|
18
|
-
*
|
|
19
|
-
* @module dsh-superagent/audit
|
|
20
|
-
*/
|
|
21
|
-
import { randomUUID } from 'node:crypto'
|
|
22
|
-
import fsp from 'node:fs/promises'
|
|
23
|
-
import path from 'node:path'
|
|
24
|
-
|
|
25
|
-
import { createPolicyLoader, decide, LEVELS } from './policy.js'
|
|
26
|
-
|
|
27
|
-
/** Schema version written into every event. */
|
|
28
|
-
export const AUDIT_VERSION = 1
|
|
29
|
-
|
|
30
|
-
/** Event kinds this module writes. `kind` is free-form for callers, this is the vocabulary. */
|
|
31
|
-
export const EVENT_KINDS = [
|
|
32
|
-
'run.start',
|
|
33
|
-
'run.resume',
|
|
34
|
-
'run.cancel',
|
|
35
|
-
'run.finish',
|
|
36
|
-
'tool.call',
|
|
37
|
-
'path.write',
|
|
38
|
-
'command.exec',
|
|
39
|
-
'attention',
|
|
40
|
-
'blocked',
|
|
41
|
-
'approved',
|
|
42
|
-
]
|
|
43
|
-
|
|
44
|
-
export const CSV_COLUMNS = [
|
|
45
|
-
'at',
|
|
46
|
-
'id',
|
|
47
|
-
'runId',
|
|
48
|
-
'subtaskId',
|
|
49
|
-
'actor',
|
|
50
|
-
'kind',
|
|
51
|
-
'action',
|
|
52
|
-
'target',
|
|
53
|
-
'decision',
|
|
54
|
-
'result',
|
|
55
|
-
'durationMs',
|
|
56
|
-
'rule',
|
|
57
|
-
'source',
|
|
58
|
-
'meta',
|
|
59
|
-
]
|
|
60
|
-
|
|
61
|
-
const LOCK_TIMEOUT_MS = 10000
|
|
62
|
-
const LOCK_STALE_MS = 5000
|
|
63
|
-
const MAX_TARGET = 500
|
|
64
|
-
const MAX_TEXT = 200
|
|
65
|
-
const MAX_META_BYTES = 4000
|
|
66
|
-
|
|
67
|
-
const RANK = { allow: 0, confirm: 1, deny: 2 }
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
if (
|
|
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
|
-
|
|
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
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
}
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
}
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
if (
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
return
|
|
268
|
-
}
|
|
269
|
-
|
|
270
|
-
function
|
|
271
|
-
if (value === null || value === undefined
|
|
272
|
-
const
|
|
273
|
-
|
|
274
|
-
return
|
|
275
|
-
}
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
const
|
|
293
|
-
const
|
|
294
|
-
const
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
if (
|
|
303
|
-
return
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
if (
|
|
313
|
-
|
|
314
|
-
if (
|
|
315
|
-
return
|
|
316
|
-
}
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
return
|
|
323
|
-
}
|
|
324
|
-
|
|
325
|
-
/** Render events as
|
|
326
|
-
export function
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
*
|
|
345
|
-
*
|
|
346
|
-
*
|
|
347
|
-
*
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
*
|
|
352
|
-
*
|
|
353
|
-
*
|
|
354
|
-
*
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
*
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
*
|
|
550
|
-
* @
|
|
551
|
-
*/
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Append-only audit trail for dsh-superagent.
|
|
3
|
+
*
|
|
4
|
+
* One JSON object per line, one event per action: a tool call, a path write, a
|
|
5
|
+
* command, a block, a human approval, an attention decision, a run lifecycle
|
|
6
|
+
* step. The file is deliberately plain JSONL so it can be read with `jq`,
|
|
7
|
+
* `grep`, or a spreadsheet without this module, and so a crash cannot corrupt
|
|
8
|
+
* anything except the line that was being written.
|
|
9
|
+
*
|
|
10
|
+
* Concurrent appends are what make an audit log trustworthy in the first place:
|
|
11
|
+
* two workers finishing together must not splice their lines. Writes are
|
|
12
|
+
* serialized inside the process and guarded by a `wx`-created lock file across
|
|
13
|
+
* processes, and the line is written with a single append.
|
|
14
|
+
*
|
|
15
|
+
* This layer is independent of any path/command guard. A guard can be attached
|
|
16
|
+
* with `attachGuard`; when it returns a decision the audit records it, and the
|
|
17
|
+
* guard may only tighten what the policy already said.
|
|
18
|
+
*
|
|
19
|
+
* @module dsh-superagent/audit
|
|
20
|
+
*/
|
|
21
|
+
import { randomUUID } from 'node:crypto'
|
|
22
|
+
import fsp from 'node:fs/promises'
|
|
23
|
+
import path from 'node:path'
|
|
24
|
+
|
|
25
|
+
import { createPolicyLoader, decide, LEVELS } from './policy.js'
|
|
26
|
+
|
|
27
|
+
/** Schema version written into every event. */
|
|
28
|
+
export const AUDIT_VERSION = 1
|
|
29
|
+
|
|
30
|
+
/** Event kinds this module writes. `kind` is free-form for callers, this is the vocabulary. */
|
|
31
|
+
export const EVENT_KINDS = [
|
|
32
|
+
'run.start',
|
|
33
|
+
'run.resume',
|
|
34
|
+
'run.cancel',
|
|
35
|
+
'run.finish',
|
|
36
|
+
'tool.call',
|
|
37
|
+
'path.write',
|
|
38
|
+
'command.exec',
|
|
39
|
+
'attention',
|
|
40
|
+
'blocked',
|
|
41
|
+
'approved',
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
export const CSV_COLUMNS = [
|
|
45
|
+
'at',
|
|
46
|
+
'id',
|
|
47
|
+
'runId',
|
|
48
|
+
'subtaskId',
|
|
49
|
+
'actor',
|
|
50
|
+
'kind',
|
|
51
|
+
'action',
|
|
52
|
+
'target',
|
|
53
|
+
'decision',
|
|
54
|
+
'result',
|
|
55
|
+
'durationMs',
|
|
56
|
+
'rule',
|
|
57
|
+
'source',
|
|
58
|
+
'meta',
|
|
59
|
+
]
|
|
60
|
+
|
|
61
|
+
const LOCK_TIMEOUT_MS = 10000
|
|
62
|
+
const LOCK_STALE_MS = 5000
|
|
63
|
+
const MAX_TARGET = 500
|
|
64
|
+
const MAX_TEXT = 200
|
|
65
|
+
const MAX_META_BYTES = 4000
|
|
66
|
+
|
|
67
|
+
const RANK = { allow: 0, confirm: 1, deny: 2 }
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Decisions an event may carry. Policy levels plus `attention`, which records a
|
|
71
|
+
* hand-off to a person for an action that was stopped short rather than run.
|
|
72
|
+
* Guard merging below still uses LEVELS only.
|
|
73
|
+
*/
|
|
74
|
+
const RECORDED_DECISIONS = [...LEVELS, 'attention']
|
|
75
|
+
|
|
76
|
+
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
|
|
77
|
+
|
|
78
|
+
function clip(value, limit) {
|
|
79
|
+
if (value === null || value === undefined) return null
|
|
80
|
+
const text = String(value)
|
|
81
|
+
return text.length > limit ? `${text.slice(0, limit)}…` : text
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function serializeMeta(meta) {
|
|
85
|
+
if (meta === null || meta === undefined) return null
|
|
86
|
+
let text
|
|
87
|
+
try {
|
|
88
|
+
text = JSON.stringify(meta)
|
|
89
|
+
} catch {
|
|
90
|
+
return { unserializable: true }
|
|
91
|
+
}
|
|
92
|
+
if (text === undefined) return null
|
|
93
|
+
if (text.length <= MAX_META_BYTES) return JSON.parse(text)
|
|
94
|
+
return { truncated: true, bytes: text.length, preview: text.slice(0, MAX_META_BYTES) }
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Fill in the fields every event carries. Missing values stay `null` instead of
|
|
99
|
+
* disappearing, so a consumer can rely on the column being present.
|
|
100
|
+
*/
|
|
101
|
+
export function normalizeEvent(input, { now = () => Date.now() } = {}) {
|
|
102
|
+
const at = input?.at ?? new Date(now()).toISOString()
|
|
103
|
+
return {
|
|
104
|
+
v: AUDIT_VERSION,
|
|
105
|
+
id: typeof input?.id === 'string' && input.id.trim() ? input.id.trim() : `evt_${randomUUID()}`,
|
|
106
|
+
at,
|
|
107
|
+
runId: clip(input?.runId, MAX_TEXT),
|
|
108
|
+
subtaskId: clip(input?.subtaskId, MAX_TEXT),
|
|
109
|
+
actor: clip(input?.actor, MAX_TEXT),
|
|
110
|
+
kind: clip(input?.kind, 64) ?? 'unknown',
|
|
111
|
+
action: clip(input?.action, 64),
|
|
112
|
+
target: clip(input?.target, MAX_TARGET),
|
|
113
|
+
decision: RECORDED_DECISIONS.includes(input?.decision) ? input.decision : null,
|
|
114
|
+
result: clip(input?.result, 32),
|
|
115
|
+
durationMs: Number.isFinite(input?.durationMs) ? Math.max(0, Math.round(input.durationMs)) : null,
|
|
116
|
+
rule: clip(input?.rule, MAX_TEXT),
|
|
117
|
+
source: clip(input?.source, 64) ?? 'plugin',
|
|
118
|
+
meta: serializeMeta(input?.meta),
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
async function withFileLock(file, work) {
|
|
123
|
+
const lock = `${file}.lock`
|
|
124
|
+
const started = Date.now()
|
|
125
|
+
for (;;) {
|
|
126
|
+
try {
|
|
127
|
+
await fsp.writeFile(lock, `${JSON.stringify({ pid: process.pid, at: Date.now() })}\n`, { encoding: 'utf8', flag: 'wx' })
|
|
128
|
+
break
|
|
129
|
+
} catch (error) {
|
|
130
|
+
if (error?.code !== 'EEXIST') {
|
|
131
|
+
// Windows reports a concurrent create as EPERM/EACCES now and then.
|
|
132
|
+
if (!['EPERM', 'EACCES', 'EBUSY'].includes(error?.code)) throw error
|
|
133
|
+
}
|
|
134
|
+
try {
|
|
135
|
+
const stat = await fsp.stat(lock)
|
|
136
|
+
// A process killed while holding the lock must not stop the log forever.
|
|
137
|
+
if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
|
|
138
|
+
await fsp.unlink(lock)
|
|
139
|
+
continue
|
|
140
|
+
}
|
|
141
|
+
} catch {
|
|
142
|
+
// The holder released it between the two calls; retry immediately.
|
|
143
|
+
continue
|
|
144
|
+
}
|
|
145
|
+
if (Date.now() - started > LOCK_TIMEOUT_MS) {
|
|
146
|
+
throw new Error(`timed out waiting for the audit log lock ${lock}; another process may be stuck`)
|
|
147
|
+
}
|
|
148
|
+
await sleep(2 + Math.random() * 8)
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
try {
|
|
152
|
+
return await work()
|
|
153
|
+
} finally {
|
|
154
|
+
await fsp.unlink(lock).catch(() => {})
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* One append-only JSONL file.
|
|
160
|
+
* @param {{ dir: string, file?: string, sync?: boolean, warn?: (message: string) => void, now?: () => number }} options
|
|
161
|
+
*/
|
|
162
|
+
export function createAuditLog({ dir, file = 'audit.jsonl', sync = true, warn = () => {}, now = () => Date.now() } = {}) {
|
|
163
|
+
const filePath = path.isAbsolute(file) ? file : path.join(dir, file)
|
|
164
|
+
let ready = null
|
|
165
|
+
let chain = Promise.resolve()
|
|
166
|
+
|
|
167
|
+
const ensureDir = () => {
|
|
168
|
+
ready = ready ?? fsp.mkdir(path.dirname(filePath), { recursive: true })
|
|
169
|
+
return ready
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
async function appendLine(line) {
|
|
173
|
+
await ensureDir()
|
|
174
|
+
for (let attempt = 1; ; attempt++) {
|
|
175
|
+
try {
|
|
176
|
+
await withFileLock(filePath, async () => {
|
|
177
|
+
const handle = await fsp.open(filePath, 'a')
|
|
178
|
+
try {
|
|
179
|
+
const { bytesWritten } = await handle.write(line)
|
|
180
|
+
if (bytesWritten !== Buffer.byteLength(line)) {
|
|
181
|
+
throw new Error(`short audit write: ${bytesWritten} of ${Buffer.byteLength(line)} bytes reached ${filePath}`)
|
|
182
|
+
}
|
|
183
|
+
if (sync) await handle.datasync()
|
|
184
|
+
} finally {
|
|
185
|
+
await handle.close()
|
|
186
|
+
}
|
|
187
|
+
})
|
|
188
|
+
return
|
|
189
|
+
} catch (error) {
|
|
190
|
+
// A reader holding the file can fail the open on Windows; retry before
|
|
191
|
+
// reporting a lost event, because a lost event is the one thing an
|
|
192
|
+
// audit log must not quietly produce.
|
|
193
|
+
if (attempt >= 3 || !['EPERM', 'EACCES', 'EBUSY'].includes(error?.code)) throw error
|
|
194
|
+
await sleep(20 * attempt)
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
return {
|
|
200
|
+
file: filePath,
|
|
201
|
+
dir,
|
|
202
|
+
/**
|
|
203
|
+
* Append one event. Calls are serialized in-process, so two callers in the
|
|
204
|
+
* same tick still produce two whole lines in call order.
|
|
205
|
+
* @param {object} input - event fields.
|
|
206
|
+
* @returns {Promise<{ ok: boolean, event?: object, error?: Error }>} never throws.
|
|
207
|
+
*/
|
|
208
|
+
async append(input) {
|
|
209
|
+
const event = normalizeEvent(input, { now })
|
|
210
|
+
const line = `${JSON.stringify(event)}\n`
|
|
211
|
+
const run = chain.then(() => appendLine(line))
|
|
212
|
+
// Keep the chain alive after a failure, so one ENOSPC does not stop the log.
|
|
213
|
+
chain = run.catch(() => {})
|
|
214
|
+
try {
|
|
215
|
+
await run
|
|
216
|
+
return { ok: true, event }
|
|
217
|
+
} catch (error) {
|
|
218
|
+
warn(`cannot append to the audit log ${filePath}: ${error?.message ?? error}`)
|
|
219
|
+
return { ok: false, event, error }
|
|
220
|
+
}
|
|
221
|
+
},
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* Read every complete line. A trailing fragment is reported as torn rather
|
|
225
|
+
* than parsed, and an unparsable line is counted instead of aborting the
|
|
226
|
+
* read: one bad byte must not hide the other 10,000 events.
|
|
227
|
+
* @returns {Promise<{ events: object[], invalid: number, torn: number }>}
|
|
228
|
+
*/
|
|
229
|
+
async read() {
|
|
230
|
+
let text
|
|
231
|
+
try {
|
|
232
|
+
text = await fsp.readFile(filePath, 'utf8')
|
|
233
|
+
} catch (error) {
|
|
234
|
+
if (error?.code === 'ENOENT') return { events: [], invalid: 0, torn: 0 }
|
|
235
|
+
throw error
|
|
236
|
+
}
|
|
237
|
+
const events = []
|
|
238
|
+
let invalid = 0
|
|
239
|
+
let torn = 0
|
|
240
|
+
const lines = text.split('\n')
|
|
241
|
+
const endsWithNewline = text.endsWith('\n')
|
|
242
|
+
for (let i = 0; i < lines.length; i++) {
|
|
243
|
+
const line = lines[i]
|
|
244
|
+
if (!line.trim()) continue
|
|
245
|
+
if (i === lines.length - 1 && !endsWithNewline) {
|
|
246
|
+
torn++
|
|
247
|
+
continue
|
|
248
|
+
}
|
|
249
|
+
try {
|
|
250
|
+
const parsed = JSON.parse(line)
|
|
251
|
+
if (parsed && typeof parsed === 'object') events.push(parsed)
|
|
252
|
+
else invalid++
|
|
253
|
+
} catch {
|
|
254
|
+
invalid++
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
return { events, invalid, torn }
|
|
258
|
+
},
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
function within(value, from, to) {
|
|
263
|
+
const at = Date.parse(value ?? '')
|
|
264
|
+
if (!Number.isFinite(at)) return false
|
|
265
|
+
if (from !== null && at < from) return false
|
|
266
|
+
if (to !== null && at > to) return false
|
|
267
|
+
return true
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
function asList(value) {
|
|
271
|
+
if (value === null || value === undefined) return null
|
|
272
|
+
const list = Array.isArray(value) ? value : [value]
|
|
273
|
+
const cleaned = list.map(item => String(item).trim()).filter(Boolean)
|
|
274
|
+
return cleaned.length > 0 ? cleaned : null
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
function bound(value, label) {
|
|
278
|
+
if (value === null || value === undefined || value === '') return null
|
|
279
|
+
const at = Date.parse(value)
|
|
280
|
+
if (!Number.isFinite(at)) throw new Error(`${label} is not a timestamp this log can compare: ${JSON.stringify(value)}`)
|
|
281
|
+
return at
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/**
|
|
285
|
+
* Filter events by run, subtask, kind, decision, result, actor, target text and
|
|
286
|
+
* time window.
|
|
287
|
+
* @param {object[]} events - parsed events, in file order.
|
|
288
|
+
* @param {object} filter - query.
|
|
289
|
+
* @returns {object[]} matching events in the requested order.
|
|
290
|
+
*/
|
|
291
|
+
export function filterEvents(events, filter = {}) {
|
|
292
|
+
const runId = filter.runId ? String(filter.runId) : null
|
|
293
|
+
const subtaskId = filter.subtaskId ? String(filter.subtaskId) : null
|
|
294
|
+
const kinds = asList(filter.kind)
|
|
295
|
+
const decisions = asList(filter.decision)
|
|
296
|
+
const results = asList(filter.result)
|
|
297
|
+
const actor = filter.actor ? String(filter.actor) : null
|
|
298
|
+
const target = filter.target ? String(filter.target).toLowerCase() : null
|
|
299
|
+
const from = bound(filter.since ?? filter.from, 'since')
|
|
300
|
+
const to = bound(filter.until ?? filter.to, 'until')
|
|
301
|
+
const matched = events.filter(event => {
|
|
302
|
+
if (runId && event.runId !== runId) return false
|
|
303
|
+
if (subtaskId && event.subtaskId !== subtaskId) return false
|
|
304
|
+
if (kinds && !kinds.includes(event.kind)) return false
|
|
305
|
+
if (decisions && !decisions.includes(event.decision)) return false
|
|
306
|
+
if (results && !results.includes(event.result)) return false
|
|
307
|
+
if (actor && event.actor !== actor) return false
|
|
308
|
+
if (target && !String(event.target ?? '').toLowerCase().includes(target)) return false
|
|
309
|
+
if ((from !== null || to !== null) && !within(event.at, from, to)) return false
|
|
310
|
+
return true
|
|
311
|
+
})
|
|
312
|
+
if (filter.order === 'desc') matched.reverse()
|
|
313
|
+
const limit = Number(filter.limit)
|
|
314
|
+
if (Number.isFinite(limit) && limit > 0) return matched.slice(0, Math.trunc(limit))
|
|
315
|
+
return matched
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
function csvCell(value) {
|
|
319
|
+
if (value === null || value === undefined) return ''
|
|
320
|
+
let text = typeof value === 'object' ? JSON.stringify(value) : String(value)
|
|
321
|
+
if (/[",\r\n]/.test(text)) text = `"${text.replace(/"/g, '""')}"`
|
|
322
|
+
return text
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
/** Render events as a CSV document with a header row. */
|
|
326
|
+
export function toCsv(events) {
|
|
327
|
+
const rows = [CSV_COLUMNS.join(',')]
|
|
328
|
+
for (const event of events) rows.push(CSV_COLUMNS.map(column => csvCell(event[column])).join(','))
|
|
329
|
+
return `${rows.join('\n')}\n`
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/** Render events as JSONL, one normalized event per line. */
|
|
333
|
+
export function toJsonl(events) {
|
|
334
|
+
return events.map(event => JSON.stringify(event)).join('\n') + (events.length > 0 ? '\n' : '')
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
function defaultExportName(format, now) {
|
|
338
|
+
const stamp = new Date(now()).toISOString().replace(/[:.]/g, '-')
|
|
339
|
+
return `audit-export-${stamp}.${format === 'csv' ? 'csv' : 'jsonl'}`
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/**
|
|
343
|
+
* Optional external guard, e.g. the path/command layer that owns its own rules.
|
|
344
|
+
* It receives the same request the audit layer was given and may return
|
|
345
|
+
* `{ decision }` or the `{ blocked, rule, reason }` shape a tool-call guard
|
|
346
|
+
* already produces. `null` means "no opinion". It may only tighten.
|
|
347
|
+
* @typedef {(request: object) => Promise<object | null> | object | null} GuardHook
|
|
348
|
+
*/
|
|
349
|
+
|
|
350
|
+
/**
|
|
351
|
+
* The audit layer the plugin and a guard both talk to.
|
|
352
|
+
*
|
|
353
|
+
* @param {{
|
|
354
|
+
* dir: string,
|
|
355
|
+
* policyFile?: string | null,
|
|
356
|
+
* policy?: object | null,
|
|
357
|
+
* guard?: GuardHook | null,
|
|
358
|
+
* warn?: (message: string) => void,
|
|
359
|
+
* now?: () => number,
|
|
360
|
+
* sync?: boolean,
|
|
361
|
+
* }} options
|
|
362
|
+
*/
|
|
363
|
+
export function createAuditor({
|
|
364
|
+
dir,
|
|
365
|
+
policyFile = null,
|
|
366
|
+
policy = null,
|
|
367
|
+
guard = null,
|
|
368
|
+
warn = () => {},
|
|
369
|
+
now = () => Date.now(),
|
|
370
|
+
sync = true,
|
|
371
|
+
} = {}) {
|
|
372
|
+
const log = createAuditLog({ dir, warn, now, sync })
|
|
373
|
+
const loader = policyFile ? createPolicyLoader({ file: policyFile, warn }) : null
|
|
374
|
+
let fixedPolicy = policy
|
|
375
|
+
let attachedGuard = guard
|
|
376
|
+
|
|
377
|
+
async function currentPolicy() {
|
|
378
|
+
if (fixedPolicy) return { policy: fixedPolicy, error: null }
|
|
379
|
+
if (loader) return loader.get()
|
|
380
|
+
return { policy: null, error: null }
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
async function resolve(request) {
|
|
384
|
+
const started = now()
|
|
385
|
+
const state = await currentPolicy()
|
|
386
|
+
let verdict
|
|
387
|
+
if (!state.policy) {
|
|
388
|
+
// A configured but unreadable policy fails closed: an audit trail that
|
|
389
|
+
// cannot say what was allowed must not wave the action through.
|
|
390
|
+
verdict = state.error
|
|
391
|
+
? {
|
|
392
|
+
decision: 'deny',
|
|
393
|
+
rule: 'policy.invalid',
|
|
394
|
+
reason: `the permission policy could not be loaded: ${state.error.message ?? state.error}`,
|
|
395
|
+
relaxedFrom: null,
|
|
396
|
+
match: null,
|
|
397
|
+
}
|
|
398
|
+
: decide(null, request)
|
|
399
|
+
} else {
|
|
400
|
+
verdict = decide(state.policy, request)
|
|
401
|
+
}
|
|
402
|
+
let source = verdict.rule === 'no-policy' ? 'default' : 'policy'
|
|
403
|
+
if (attachedGuard) {
|
|
404
|
+
let guardVerdict = null
|
|
405
|
+
try {
|
|
406
|
+
guardVerdict = await attachedGuard(request)
|
|
407
|
+
} catch (error) {
|
|
408
|
+
warn(`audit guard threw on ${request?.kind}: ${error?.message ?? error}`)
|
|
409
|
+
guardVerdict = { decision: 'deny', reason: `the guard failed: ${error?.message ?? error}` }
|
|
410
|
+
}
|
|
411
|
+
const decision = LEVELS.includes(guardVerdict?.decision)
|
|
412
|
+
? guardVerdict.decision
|
|
413
|
+
: guardVerdict?.blocked === true ? 'deny' : null
|
|
414
|
+
// The guard shares the "only tighten" rule: it can add a deny or a
|
|
415
|
+
// confirmation on top of the policy, never remove one.
|
|
416
|
+
if (decision && RANK[decision] > RANK[verdict.decision]) {
|
|
417
|
+
verdict = {
|
|
418
|
+
decision,
|
|
419
|
+
rule: `guard.${guardVerdict.rule ?? 'verdict'}`,
|
|
420
|
+
reason: guardVerdict.reason ?? `the guard requires ${decision}`,
|
|
421
|
+
relaxedFrom: null,
|
|
422
|
+
match: guardVerdict.match ?? null,
|
|
423
|
+
}
|
|
424
|
+
source = 'guard'
|
|
425
|
+
}
|
|
426
|
+
}
|
|
427
|
+
return { verdict, source, durationMs: now() - started }
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
const resultFor = decision => (decision === 'deny' ? 'blocked' : decision === 'confirm' ? 'pending' : 'ok')
|
|
431
|
+
|
|
432
|
+
/**
|
|
433
|
+
* Read and filter the log.
|
|
434
|
+
* @param {object} [filter] - runId, subtaskId, kind, decision, result, actor, target, since, until, limit, order.
|
|
435
|
+
*/
|
|
436
|
+
async function query(filter = {}) {
|
|
437
|
+
const { events, invalid, torn } = await log.read()
|
|
438
|
+
const matched = filterEvents(events, filter)
|
|
439
|
+
return { events: matched, total: matched.length, scanned: events.length, invalid, torn, file: log.file }
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
/**
|
|
443
|
+
* Write the matching events to one deliverable file.
|
|
444
|
+
* @param {object} [options] - `format` ('jsonl' | 'csv'), `outFile`, plus any query filter.
|
|
445
|
+
* @returns {Promise<{ path: string, count: number, bytes: number, format: string, invalid: number }>}
|
|
446
|
+
*/
|
|
447
|
+
async function exportEvents(options = {}) {
|
|
448
|
+
const format = options.format === 'csv' ? 'csv' : 'jsonl'
|
|
449
|
+
const { events, invalid } = await query(options)
|
|
450
|
+
const target = options.outFile
|
|
451
|
+
? path.resolve(options.outFile)
|
|
452
|
+
: path.join(dir, defaultExportName(format, now))
|
|
453
|
+
const body = format === 'csv' ? toCsv(events) : toJsonl(events)
|
|
454
|
+
await fsp.mkdir(path.dirname(target), { recursive: true })
|
|
455
|
+
await fsp.writeFile(target, body, 'utf8')
|
|
456
|
+
return { path: target, count: events.length, bytes: Buffer.byteLength(body), format, invalid }
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
const api = {
|
|
460
|
+
dir,
|
|
461
|
+
log,
|
|
462
|
+
file: log.file,
|
|
463
|
+
policyFile,
|
|
464
|
+
|
|
465
|
+
/** Last policy problem, or null. */
|
|
466
|
+
async policyError() {
|
|
467
|
+
const state = await currentPolicy()
|
|
468
|
+
return state.error ?? null
|
|
469
|
+
},
|
|
470
|
+
|
|
471
|
+
/** Replace the policy in memory (used by tests and by a caller that parses its own file). */
|
|
472
|
+
setPolicy(next) {
|
|
473
|
+
fixedPolicy = next
|
|
474
|
+
return api
|
|
475
|
+
},
|
|
476
|
+
|
|
477
|
+
/** Attach or replace the external guard. Pass null to detach. */
|
|
478
|
+
attachGuard(next) {
|
|
479
|
+
attachedGuard = typeof next === 'function' ? next : null
|
|
480
|
+
return api
|
|
481
|
+
},
|
|
482
|
+
|
|
483
|
+
/**
|
|
484
|
+
* Append one event. Never throws and never blocks the caller: a failure is
|
|
485
|
+
* reported to the warn sink and returned.
|
|
486
|
+
* @param {object} input - event fields.
|
|
487
|
+
*/
|
|
488
|
+
async record(input) {
|
|
489
|
+
return log.append(input)
|
|
490
|
+
},
|
|
491
|
+
|
|
492
|
+
/**
|
|
493
|
+
* Review one action, record the verdict, and return it. The returned
|
|
494
|
+
* `eventId` is what an approval or a later execution event refers to.
|
|
495
|
+
* @param {{ kind: string, runId?: string, subtaskId?: string, actor?: string, action?: string, target?: string, meta?: object }} request
|
|
496
|
+
*/
|
|
497
|
+
async gate(request = {}) {
|
|
498
|
+
const { verdict, source, durationMs } = await resolve(request)
|
|
499
|
+
const result = resultFor(verdict.decision)
|
|
500
|
+
const recorded = await log.append({
|
|
501
|
+
runId: request.runId ?? null,
|
|
502
|
+
subtaskId: request.subtaskId ?? null,
|
|
503
|
+
actor: request.actor ?? null,
|
|
504
|
+
kind: verdict.decision === 'deny' ? 'blocked' : request.kind,
|
|
505
|
+
action: request.action ?? request.kind,
|
|
506
|
+
target: request.target ?? null,
|
|
507
|
+
decision: verdict.decision,
|
|
508
|
+
result,
|
|
509
|
+
durationMs,
|
|
510
|
+
rule: verdict.rule,
|
|
511
|
+
source,
|
|
512
|
+
meta: {
|
|
513
|
+
...(request.meta ?? {}),
|
|
514
|
+
...(verdict.relaxedFrom ? { relaxedFrom: verdict.relaxedFrom } : {}),
|
|
515
|
+
...(verdict.decision === 'deny' ? { blockedKind: request.kind } : {}),
|
|
516
|
+
reason: verdict.reason,
|
|
517
|
+
},
|
|
518
|
+
})
|
|
519
|
+
return { ...verdict, source, eventId: recorded.ok ? recorded.event.id : null }
|
|
520
|
+
},
|
|
521
|
+
|
|
522
|
+
/**
|
|
523
|
+
* Record a human decision on an event that was held for confirmation.
|
|
524
|
+
* Approvals are how a policy gets relaxed on purpose: the trail shows the
|
|
525
|
+
* blocked/pending event, the person, and the note.
|
|
526
|
+
* @param {string} eventId - id of the held event.
|
|
527
|
+
* @param {{ actor?: string, note?: string, runId?: string, kind?: string }} [options]
|
|
528
|
+
*/
|
|
529
|
+
async approve(eventId, { actor = null, note = null, runId = null, kind = null } = {}) {
|
|
530
|
+
if (!eventId) throw new Error('approve needs the id of the event being released')
|
|
531
|
+
const recorded = await log.append({
|
|
532
|
+
runId,
|
|
533
|
+
actor,
|
|
534
|
+
kind: 'approved',
|
|
535
|
+
action: 'approve',
|
|
536
|
+
target: eventId,
|
|
537
|
+
decision: 'allow',
|
|
538
|
+
result: 'approved',
|
|
539
|
+
durationMs: 0,
|
|
540
|
+
rule: 'manual-approval',
|
|
541
|
+
source: 'human',
|
|
542
|
+
meta: { approves: eventId, note, of: kind },
|
|
543
|
+
})
|
|
544
|
+
if (!recorded.ok) throw recorded.error ?? new Error('cannot record the approval')
|
|
545
|
+
return recorded.event
|
|
546
|
+
},
|
|
547
|
+
|
|
548
|
+
/**
|
|
549
|
+
* Read and filter the log.
|
|
550
|
+
* @param {object} [filter] - runId, subtaskId, kind, decision, result, actor, target, since, until, limit, order.
|
|
551
|
+
*/
|
|
552
|
+
query,
|
|
553
|
+
|
|
554
|
+
/**
|
|
555
|
+
* Write the matching events to one deliverable file.
|
|
556
|
+
* @param {object} [options] - `format` ('jsonl' | 'csv'), `outFile`, plus any query filter.
|
|
557
|
+
* @returns {Promise<{ path: string, count: number, bytes: number, format: string, invalid: number }>}
|
|
558
|
+
*/
|
|
559
|
+
export: exportEvents,
|
|
560
|
+
}
|
|
561
|
+
return api
|
|
562
|
+
}
|