@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/telemetry.js

@@ -1,122 +1,122 @@
-// Operational telemetry: a durable trail of what the memory system did, and what it cost.
-//
-// Two gaps this closes. First, the cadences (capture, consolidation, refresh, history ingest,
-// prune, sync) run unattended and previously left no trace: a pass that silently did nothing was
-// indistinguishable from one that silently failed. Second, nothing counted model calls, so the
-// running cost of memory was invisible.
-//
-// Both live in logs/console.log - derived, gitignored, and safe to delete. The counters are
-// deliberately plain JSON rather than a database: they must never be a reason a memory write can
-// fail.
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-
-/** Rotate the run log once it passes this size. */
-export const LOG_MAX_BYTES = 2 * 1024 * 1024
-/** Keep the activity feed to this many entries. */
-export const ACTIVITY_MAX = 200
-
-export function logsDir(root) { return join(root, 'logs') }
-export function runLogPath(root) { return join(logsDir(root), 'memory.log') }
-export function metricsPath(root) { return join(root, 'state', 'metrics.json') }
-export function activityPath(root) { return join(root, 'state', 'activity.jsonl') }
-
-/** One ISO timestamp, taken once per call so a record is internally consistent. */
-function nowIso(now) { return (now ?? new Date()).toISOString() }
-
-/**
- * Append one line to the run log, rotating first when it has grown too large.
- * Best-effort by design: telemetry must never break a memory operation.
- */
-export function logRun(root, event, detail = {}, options = {}) {
-  try {
-    mkdirSync(logsDir(root), { recursive: true })
-    const path = runLogPath(root)
-    try {
-      if (existsSync(path) && statSync(path).size > (options.maxBytes ?? LOG_MAX_BYTES)) {
-        renameSync(path, path + '.1')
-      }
-    } catch {}
-    const line = JSON.stringify({ at: nowIso(options.now), event, ...detail })
-    appendFileSync(path, line + '\n')
-    return true
-  } catch { return false }
-}
-
-/** Read the tail of the run log, newest last. */
-export function readRunLog(root, limit = 50) {
-  try {
-    const lines = readFileSync(runLogPath(root), 'utf8').split('\n').filter(Boolean)
-    return lines.slice(-limit).map((line) => { try { return JSON.parse(line) } catch { return { raw: line } } })
-  } catch { return [] }
-}
-
-/** An empty counter set. */
-function emptyMetrics() {
-  return { since: undefined, events: {}, modelCalls: 0, modelPurpose: {}, savedBy: {}, lastAt: undefined }
-}
-
-export function readMetrics(root) {
-  try { return { ...emptyMetrics(), ...JSON.parse(readFileSync(metricsPath(root), 'utf8')) } }
-  catch { return emptyMetrics() }
-}
-
-function writeMetrics(root, value) {
-  try {
-    mkdirSync(join(root, 'state'), { recursive: true })
-    writeFileSync(metricsPath(root), JSON.stringify(value, null, 2) + '\n')
-  } catch {}
-}
-
-/**
- * Record one operational event.
- * @param root - store root.
- * @param event - a short event name, e.g. 'capture', 'consolidate', 'prune', 'sync'.
- * @param options.count - increment the event counter by this much (default 1).
- * @param options.modelCalls - model calls spent.
- * @param options.purpose - what a model call was for ('summary', 'consolidation', 'refresh').
- * @param options.saved - a call AVOIDED, by reason ('trivial', 'thin', 'no-pending').
- * @param options.detail - extra fields for the run log.
- * @param options.log - set false to skip the run-log line (default true).
- * @returns the record that was written.
- */
-export function record(root, event, options = {}) {
-  const at = nowIso(options.now)
-  const metrics = readMetrics(root)
-  metrics.since = metrics.since ?? at
-  metrics.lastAt = at
-  metrics.events[event] = (metrics.events[event] ?? 0) + (options.count ?? 1)
-  if (options.modelCalls) {
-    metrics.modelCalls += options.modelCalls
-    const purpose = options.purpose ?? 'other'
-    metrics.modelPurpose[purpose] = (metrics.modelPurpose[purpose] ?? 0) + options.modelCalls
-  }
-  if (options.saved) metrics.savedBy[options.saved] = (metrics.savedBy[options.saved] ?? 0) + 1
-  writeMetrics(root, metrics)
-  if (options.log !== false) logRun(root, event, { ...(options.detail ?? {}), count: options.count ?? 1 })
-  return { at, event, count: options.count ?? 1 }
-}
-
-/**
- * Append to the human-readable activity feed: what memory did, newest last.
- * Kept short and bounded, so it can be shown to an agent without flooding it.
- */
-export function noteActivity(root, text, options = {}) {
-  try {
-    mkdirSync(join(root, 'state'), { recursive: true })
-    const line = JSON.stringify({ at: nowIso(options.now), text: String(text ?? '').slice(0, 300), ...(options.detail ?? {}) })
-    appendFileSync(activityPath(root), line + '\n')
-    // compact when it has clearly outgrown the cap
-    const lines = readFileSync(activityPath(root), 'utf8').split('\n').filter(Boolean)
-    if (lines.length > ACTIVITY_MAX * 2) writeFileSync(activityPath(root), lines.slice(-ACTIVITY_MAX).join('\n') + '\n')
-    return true
-  } catch { return false }
-}
-
-/** Recent activity, newest last. */
-export function readActivity(root, limit = ACTIVITY_MAX) {
-  try {
-    return readFileSync(activityPath(root), 'utf8').split('\n').filter(Boolean).slice(-limit)
-      .map((line) => { try { return JSON.parse(line) } catch { return { text: line } } })
-  } catch { return [] }
-}
+// Operational telemetry: a durable trail of what the memory system did, and what it cost.
+//
+// Two gaps this closes. First, the cadences (capture, consolidation, refresh, history ingest,
+// prune, sync) run unattended and previously left no trace: a pass that silently did nothing was
+// indistinguishable from one that silently failed. Second, nothing counted model calls, so the
+// running cost of memory was invisible.
+//
+// Both live in logs/console.log - derived, gitignored, and safe to delete. The counters are
+// deliberately plain JSON rather than a database: they must never be a reason a memory write can
+// fail.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Rotate the run log once it passes this size. */
+export const LOG_MAX_BYTES = 2 * 1024 * 1024
+/** Keep the activity feed to this many entries. */
+export const ACTIVITY_MAX = 200
+
+export function logsDir(root) { return join(root, 'logs') }
+export function runLogPath(root) { return join(logsDir(root), 'memory.log') }
+export function metricsPath(root) { return join(root, 'state', 'metrics.json') }
+export function activityPath(root) { return join(root, 'state', 'activity.jsonl') }
+
+/** One ISO timestamp, taken once per call so a record is internally consistent. */
+function nowIso(now) { return (now ?? new Date()).toISOString() }
+
+/**
+ * Append one line to the run log, rotating first when it has grown too large.
+ * Best-effort by design: telemetry must never break a memory operation.
+ */
+export function logRun(root, event, detail = {}, options = {}) {
+  try {
+    mkdirSync(logsDir(root), { recursive: true })
+    const path = runLogPath(root)
+    try {
+      if (existsSync(path) && statSync(path).size > (options.maxBytes ?? LOG_MAX_BYTES)) {
+        renameSync(path, path + '.1')
+      }
+    } catch {}
+    const line = JSON.stringify({ at: nowIso(options.now), event, ...detail })
+    appendFileSync(path, line + '\n')
+    return true
+  } catch { return false }
+}
+
+/** Read the tail of the run log, newest last. */
+export function readRunLog(root, limit = 50) {
+  try {
+    const lines = readFileSync(runLogPath(root), 'utf8').split('\n').filter(Boolean)
+    return lines.slice(-limit).map((line) => { try { return JSON.parse(line) } catch { return { raw: line } } })
+  } catch { return [] }
+}
+
+/** An empty counter set. */
+function emptyMetrics() {
+  return { since: undefined, events: {}, modelCalls: 0, modelPurpose: {}, savedBy: {}, lastAt: undefined }
+}
+
+export function readMetrics(root) {
+  try { return { ...emptyMetrics(), ...JSON.parse(readFileSync(metricsPath(root), 'utf8')) } }
+  catch { return emptyMetrics() }
+}
+
+function writeMetrics(root, value) {
+  try {
+    mkdirSync(join(root, 'state'), { recursive: true })
+    writeFileSync(metricsPath(root), JSON.stringify(value, null, 2) + '\n')
+  } catch {}
+}
+
+/**
+ * Record one operational event.
+ * @param root - store root.
+ * @param event - a short event name, e.g. 'capture', 'consolidate', 'prune', 'sync'.
+ * @param options.count - increment the event counter by this much (default 1).
+ * @param options.modelCalls - model calls spent.
+ * @param options.purpose - what a model call was for ('summary', 'consolidation', 'refresh').
+ * @param options.saved - a call AVOIDED, by reason ('trivial', 'thin', 'no-pending').
+ * @param options.detail - extra fields for the run log.
+ * @param options.log - set false to skip the run-log line (default true).
+ * @returns the record that was written.
+ */
+export function record(root, event, options = {}) {
+  const at = nowIso(options.now)
+  const metrics = readMetrics(root)
+  metrics.since = metrics.since ?? at
+  metrics.lastAt = at
+  metrics.events[event] = (metrics.events[event] ?? 0) + (options.count ?? 1)
+  if (options.modelCalls) {
+    metrics.modelCalls += options.modelCalls
+    const purpose = options.purpose ?? 'other'
+    metrics.modelPurpose[purpose] = (metrics.modelPurpose[purpose] ?? 0) + options.modelCalls
+  }
+  if (options.saved) metrics.savedBy[options.saved] = (metrics.savedBy[options.saved] ?? 0) + 1
+  writeMetrics(root, metrics)
+  if (options.log !== false) logRun(root, event, { ...(options.detail ?? {}), count: options.count ?? 1 })
+  return { at, event, count: options.count ?? 1 }
+}
+
+/**
+ * Append to the human-readable activity feed: what memory did, newest last.
+ * Kept short and bounded, so it can be shown to an agent without flooding it.
+ */
+export function noteActivity(root, text, options = {}) {
+  try {
+    mkdirSync(join(root, 'state'), { recursive: true })
+    const line = JSON.stringify({ at: nowIso(options.now), text: String(text ?? '').slice(0, 300), ...(options.detail ?? {}) })
+    appendFileSync(activityPath(root), line + '\n')
+    // compact when it has clearly outgrown the cap
+    const lines = readFileSync(activityPath(root), 'utf8').split('\n').filter(Boolean)
+    if (lines.length > ACTIVITY_MAX * 2) writeFileSync(activityPath(root), lines.slice(-ACTIVITY_MAX).join('\n') + '\n')
+    return true
+  } catch { return false }
+}
+
+/** Recent activity, newest last. */
+export function readActivity(root, limit = ACTIVITY_MAX) {
+  try {
+    return readFileSync(activityPath(root), 'utf8').split('\n').filter(Boolean).slice(-limit)
+      .map((line) => { try { return JSON.parse(line) } catch { return { text: line } } })
+  } catch { return [] }
+}