@ngockhoale/ukit 3.3.2 → 3.4.0

package/src/index/sessionHistoryExtractor.js

@@ -0,0 +1,359 @@
+// sessionHistoryExtractor.js — bounded session-history signal extractor (BL-013).
+//
+// Reads the transcript tail (<=16KiB by default) carried on hook/bridge payloads
+// (`transcriptPath`, ukit-bridge.js:217,228) and emits bounded counters/enums:
+//
+//   { priorAttemptCount, sameSymptomReask, correctionEvents, fixLoopCount,
+//     degraded, reason? }
+//
+// Detection is deliberately heuristic + bounded (SPEC §14):
+//   * Route markers — any tail entry carrying `requestKey`/`routeFingerprint`
+//     (top-level or nested under route/ukit/metadata/message) is a prior route
+//     record; markers matching the current requestKey OR routeFingerprint count
+//     as prior attempts, and a failure-valued outcome counts a fix-loop round.
+//   * Re-ask — a user entry after the last matched marker (or >=2 matched
+//     markers) means the same route was asked again.
+//   * Corrections — explicit correction markers (`ukit-correction`/`correction`
+//     kinds) plus bounded correction phrasing in user text.
+//
+// Contracts (SPEC FR-001 + §10):
+//   * NEVER THROWS. Missing/unreadable transcript → zeroed struct with
+//     degraded:true + reason; malformed lines are skipped, never fatal.
+//   * BOUNDED: tail-only read (<=maxBytes, hard ceiling 4MiB like
+//     transcript-tail.mjs), counters clamp at 99, ≤50ms wall budget.
+//   * PRIVACY: output is counters/enums only — no transcript text may ever
+//     reach route state, decisions.tsv, or any receipt through this module.
+//
+// Two entry points share one classifier: extractHistorySignals (sync) for
+// callers outside deadline-guarded hook blocks, extractHistorySignalsAsync for
+// the hook path where every fs call must be async (BUG-C21-04 posture — a
+// stalled mount must not park the event loop under an armed deadline).
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+
+// SPEC §14: the history extraction bound is a 16KiB tail. The ceiling mirrors
+// transcript-tail.mjs's hard cap so one number describes a UKit tail scan.
+export const DEFAULT_HISTORY_MAX_BYTES = 16 * 1024;
+const HISTORY_MAX_BYTES_CEILING = 4 * 1024 * 1024;
+
+const COUNTER_MAX = 99;
+
+// Outcome fields probed on markers, in priority order. A marker without an
+// outcome field counts as an attempt but never as a failed round.
+const OUTCOME_FIELDS = ['outcome', 'verdict', 'status', 'result'];
+const FAILURE_PATTERN = /fail|error|timeout|abort|crash|block/i;
+
+// Object containers probed for marker keys — top-level plus the bounded nests
+// writers may use. `message` is included so stamped user-prompt entries
+// ({type:'user', message:{content, ukit:{requestKey}}}) still match.
+const MARKER_PROBE_KEYS = ['ukit', 'route', 'routeRecord', 'routeMeta', 'metadata', 'meta', 'message'];
+
+const USER_ENTRY_TYPES = new Set(['user', 'human']);
+const CORRECTION_TYPES = new Set(['ukit-correction', 'correction', 'user-correction']);
+
+// Bounded correction phrasing — explicit pushback patterns only; frustration
+// noise stays out of the counter by design (GAP M12 failure-mode note).
+const CORRECTION_PATTERN = /\b(?:no[,.!]?\s+that'?s|that'?s not|not what i|wrong|you (?:said|did|were|meant)|still (?:fail|failing|broken|wrong|crash|not working)|didn'?t work|incorrect|try again)\b/i;
+
+// User message text is scanned only this far — long pasted diffs/logs in a
+// user entry never extend the classification surface.
+const USER_TEXT_SCAN_CHARS = 4096;
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function boundedCap(maxBytes) {
+  const requested = Number.isFinite(maxBytes) && maxBytes > 0
+    ? Math.floor(maxBytes)
+    : DEFAULT_HISTORY_MAX_BYTES;
+  return Math.min(requested, HISTORY_MAX_BYTES_CEILING);
+}
+
+function degradedResult(reason) {
+  return {
+    priorAttemptCount: 0,
+    sameSymptomReask: false,
+    correctionEvents: 0,
+    fixLoopCount: 0,
+    degraded: true,
+    reason,
+  };
+}
+
+function zeroedResult() {
+  return {
+    priorAttemptCount: 0,
+    sameSymptomReask: false,
+    correctionEvents: 0,
+    fixLoopCount: 0,
+    degraded: false,
+  };
+}
+
+function clampCounter(value) {
+  const count = Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+  return Math.min(count, COUNTER_MAX);
+}
+
+// --- bounded tail read -------------------------------------------------------
+
+// A tail read almost certainly starts mid-record: drop everything before the
+// first complete line. Malformed or non-object lines are skipped — consumers
+// count only well-formed bounded events.
+function tailTextToEntries(text, truncated) {
+  let payload = text;
+  if (truncated) {
+    const firstBreak = payload.indexOf('\n');
+    payload = firstBreak >= 0 ? payload.slice(firstBreak + 1) : '';
+  }
+  const entries = [];
+  for (const line of payload.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (isPlainObject(parsed)) entries.push(parsed);
+    } catch {
+      // partial/corrupt line — skipped, never fatal
+    }
+  }
+  return entries;
+}
+
+async function readTailEntriesAsync(filePath, cap) {
+  const stat = await fsp.stat(filePath);
+  if (!stat.isFile()) {
+    throw new Error('not-a-file');
+  }
+  if (stat.size <= 0) {
+    return { entries: [], bytesRead: 0 };
+  }
+  const start = Math.max(0, stat.size - cap);
+  const length = Math.min(cap, stat.size);
+  const buffer = Buffer.allocUnsafe(length);
+  const handle = await fsp.open(filePath, 'r');
+  let bytesRead = 0;
+  try {
+    const result = await handle.read(buffer, 0, length, start);
+    bytesRead = result.bytesRead;
+  } finally {
+    try { await handle.close(); } catch {}
+  }
+  return {
+    entries: tailTextToEntries(buffer.toString('utf8', 0, bytesRead), start > 0),
+    bytesRead,
+  };
+}
+
+function readTailEntriesSync(filePath, cap) {
+  const stat = fs.statSync(filePath);
+  if (!stat.isFile()) {
+    throw new Error('not-a-file');
+  }
+  if (stat.size <= 0) {
+    return { entries: [], bytesRead: 0 };
+  }
+  const start = Math.max(0, stat.size - cap);
+  const length = Math.min(cap, stat.size);
+  const buffer = Buffer.allocUnsafe(length);
+  const fd = fs.openSync(filePath, 'r');
+  let bytesRead = 0;
+  try {
+    bytesRead = fs.readSync(fd, buffer, 0, length, start);
+  } finally {
+    try { fs.closeSync(fd); } catch {}
+  }
+  return {
+    entries: tailTextToEntries(buffer.toString('utf8', 0, bytesRead), start > 0),
+    bytesRead,
+  };
+}
+
+// --- bounded classification --------------------------------------------------
+
+// Probe order for marker keys + outcomes: the entry itself first, then the
+// bounded nests. Returns the first non-empty string found.
+function probeField(entry, names) {
+  if (!isPlainObject(entry)) return null;
+  for (const name of names) {
+    const direct = nonEmptyString(entry[name]);
+    if (direct) return direct;
+  }
+  for (const nestKey of MARKER_PROBE_KEYS) {
+    const nested = entry[nestKey];
+    if (!isPlainObject(nested)) continue;
+    for (const name of names) {
+      const value = nonEmptyString(nested[name]);
+      if (value) return value;
+    }
+  }
+  return null;
+}
+
+function markerKeysOf(entry) {
+  const requestKey = probeField(entry, ['requestKey']);
+  const routeFingerprint = probeField(entry, ['routeFingerprint', 'fingerprint']);
+  return requestKey || routeFingerprint ? { requestKey, routeFingerprint } : null;
+}
+
+function markerOutcome(entry) {
+  return probeField(entry, OUTCOME_FIELDS);
+}
+
+function isFailedOutcome(outcome) {
+  return typeof outcome === 'string' && FAILURE_PATTERN.test(outcome);
+}
+
+function isCorrectionMarker(entry) {
+  if (!isPlainObject(entry)) return false;
+  if (CORRECTION_TYPES.has(entry.type)) return true;
+  if (entry.event === 'correction' || entry.kind === 'correction') return true;
+  if (isPlainObject(entry.event) && entry.event.kind === 'correction') return true;
+  if (isPlainObject(entry.ukit) && entry.ukit.kind === 'correction') return true;
+  return false;
+}
+
+function isUserEntry(entry) {
+  if (!isPlainObject(entry)) return false;
+  if (USER_ENTRY_TYPES.has(entry.type)) return true;
+  if (isPlainObject(entry.message) && entry.message.role === 'user') return true;
+  return false;
+}
+
+// Bounded user text: string content, or the text blocks of a content array.
+// Tool-result/thinking blocks are ignored — only user-authored text feeds the
+// correction heuristic.
+function userTextOf(entry) {
+  if (!isUserEntry(entry)) return null;
+  const content = entry.message?.content ?? entry.text ?? entry.content;
+  let text = '';
+  if (typeof content === 'string') {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content
+      .map((block) => (isPlainObject(block) && block.type === 'text' ? String(block.text ?? '') : ''))
+      .filter(Boolean)
+      .join('\n');
+  }
+  return text ? text.slice(0, USER_TEXT_SCAN_CHARS) : null;
+}
+
+function computeHistorySignals(entries, { routeFingerprint = null, requestKey = null } = {}) {
+  const result = zeroedResult();
+  let attempts = 0;
+  let failedAttempts = 0;
+  let corrections = 0;
+  let lastMatchedIndex = -1;
+  let userAfterLastMatch = false;
+
+  entries.forEach((entry, index) => {
+    const marker = markerKeysOf(entry);
+    if (marker) {
+      const matches = Boolean(
+        (marker.requestKey && requestKey && marker.requestKey === requestKey)
+        || (marker.routeFingerprint && routeFingerprint && marker.routeFingerprint === routeFingerprint),
+      );
+      if (matches) {
+        attempts += 1;
+        lastMatchedIndex = index;
+        if (isFailedOutcome(markerOutcome(entry))) {
+          failedAttempts += 1;
+        }
+      }
+    }
+
+    const userText = userTextOf(entry);
+    if (isCorrectionMarker(entry) || (userText !== null && CORRECTION_PATTERN.test(userText))) {
+      corrections += 1;
+    }
+
+    if (lastMatchedIndex >= 0 && index > lastMatchedIndex && userText !== null) {
+      userAfterLastMatch = true;
+    }
+  });
+
+  result.priorAttemptCount = clampCounter(attempts);
+  result.fixLoopCount = clampCounter(failedAttempts);
+  result.correctionEvents = clampCounter(corrections);
+  // A re-ask on the same route shape: either the route resolved more than once
+  // in the tail, or a user prompt followed the last matched attempt (the
+  // current prompt is appended before the hook runs).
+  result.sameSymptomReask = attempts > 0 && (attempts >= 2 || userAfterLastMatch);
+  return result;
+}
+
+// --- public contract ---------------------------------------------------------
+
+// Coerce arbitrary input into the historySignals route-field shape. Non-object
+// input yields null so callers can emit the additive nullable field honestly.
+export function normalizeHistorySignals(value) {
+  if (!isPlainObject(value)) return null;
+  const normalized = {
+    priorAttemptCount: clampCounter(value.priorAttemptCount),
+    sameSymptomReask: Boolean(value.sameSymptomReask),
+    correctionEvents: clampCounter(value.correctionEvents),
+    fixLoopCount: clampCounter(value.fixLoopCount),
+    degraded: Boolean(value.degraded),
+  };
+  const reason = nonEmptyString(value.reason);
+  if (reason) normalized.reason = reason.slice(0, 120);
+  return normalized;
+}
+
+// SPEC §8: extractHistorySignals({transcriptPath, routeFingerprint, requestKey,
+// maxBytes?}) → bounded counters, never throws. Sync reader — the ≤50ms wall
+// budget assumes a healthy filesystem; deadline-guarded hook code must use the
+// async twin so a stalled mount cannot park the event loop.
+export function extractHistorySignals({
+  transcriptPath,
+  routeFingerprint = null,
+  requestKey = null,
+  maxBytes,
+} = {}) {
+  try {
+    const normalizedPath = nonEmptyString(transcriptPath);
+    if (!normalizedPath) {
+      return degradedResult('missing-transcript-path');
+    }
+    let tail;
+    try {
+      tail = readTailEntriesSync(normalizedPath, boundedCap(maxBytes));
+    } catch {
+      return degradedResult('transcript-unreadable');
+    }
+    return computeHistorySignals(tail.entries, { routeFingerprint, requestKey });
+  } catch {
+    return degradedResult('extract-failed');
+  }
+}
+
+// Async twin of extractHistorySignals — identical classification, fsp-based
+// bounded read for deadline-guarded hook code (skill-router.sh).
+export async function extractHistorySignalsAsync({
+  transcriptPath,
+  routeFingerprint = null,
+  requestKey = null,
+  maxBytes,
+} = {}) {
+  try {
+    const normalizedPath = nonEmptyString(transcriptPath);
+    if (!normalizedPath) {
+      return degradedResult('missing-transcript-path');
+    }
+    let tail;
+    try {
+      tail = await readTailEntriesAsync(normalizedPath, boundedCap(maxBytes));
+    } catch {
+      return degradedResult('transcript-unreadable');
+    }
+    return computeHistorySignals(tail.entries, { routeFingerprint, requestKey });
+  } catch {
+    return degradedResult('extract-failed');
+  }
+}