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