observe-mod

1// Logs every event this plugin can see to JSONL.
2//   <dir>/events-<sessionId>-<part>.jsonl   one line per event: seq, time, event, caller, keys, origin
3//   <dir>/samples-<sessionId>.jsonl         the first `e` of each event name (clipped)
4// <dir> is $MODS_LAB_DIR, or <plugin root>/log when unset.
5
6const CLIP = 1500
7const PART_BYTES = 3 * 1024 * 1024 // $.fs.read / write reject over 4 MiB
8
9let dir: string | undefined
10let sid = 'unknown'
11let part = 0
12let seq = 0
13let buf: unknown[] = []
14let samples: unknown[] = []
15const seen = new Set<string>()
16let flushing = false
17
18function clip(v: unknown): unknown {
19  try {
20    const s = JSON.stringify(v)
21    if (s === undefined) return String(v)
22    return s.length > CLIP ? s.slice(0, CLIP) + '...<clipped>' : JSON.parse(s)
23  } catch (err) {
24    return `<unserializable: ${String(err)}>`
25  }
26}
27
28async function append($: any, path: string, lines: unknown[]): Promise<number> {
29  let prev = ''
30  try { prev = await $.fs.read(path) } catch { prev = '' }
31  const next = prev + lines.map((l) => JSON.stringify(l)).join('\n') + '\n'
32  await $.fs.write(path, next)
33  return next.length
34}
35
36async function flush($: any): Promise<void> {
37  if (flushing || dir === undefined) return
38  if (buf.length === 0 && samples.length === 0) return
39  flushing = true
40  try {
41    const lines = buf; buf = []
42    const firsts = samples; samples = []
43    if (lines.length > 0) {
44      const size = await append($, `${dir}/events-${sid}-${part}.jsonl`, lines)
45      if (size > PART_BYTES) part += 1
46    }
47    if (firsts.length > 0) await append($, `${dir}/samples-${sid}.jsonl`, firsts)
48  } finally {
49    flushing = false
50  }
51}
52
53export function register(on: any): void {
54  // Registered first, so it is this plugin's outermost hook. It must not touch `$`:
55  // at engine.create `$` is still empty.
56  on('*', ($: any, e: any, next: any) => {
57    const ev = String(next.event)
58    seq += 1
59    const entry: Record<string, unknown> = {
60      n: seq,
61      t: Date.now(),
62      ev,
63      by: next.origin,
64      keys: e !== null && typeof e === 'object' ? Object.keys(e) : typeof e,
65    }
66    if (e && typeof e === 'object' && 'origin' in e) entry.origin = clip(e.origin)
67    if (ev === 'ui.render') entry.component = e?.component
68    if (ev.startsWith('tool.')) entry.tool = e?.tool
69    buf.push(entry)
70    if (!seen.has(ev)) {
71      seen.add(ev)
72      samples.push({ n: seq, ev, by: next.origin, e: clip(e) })
73    }
74    return next(e)
75  })
76
77  on('session.start', async ($: any, e: any, next: any) => {
78    dir = (await $.env.get('MODS_LAB_DIR')) ?? `${$.plugin.root}/log`
79    sid = await $.session.id()
80    $.clock.every(1000, () => { void flush($) })
81    return next(e)
82  })
83
84  on('session.end', async ($: any, e: any, next: any) => {
85    await flush($)
86    return next(e)
87  })
88}
89