heyspex 0.1.0 → 0.2.0

package/spexharness/src/doctrine/behaviour.mjs

@@ -0,0 +1,371 @@
+// spexharness/src/doctrine/behaviour.mjs
+//
+// DR1 addendum (owner request, 2026-09-11, mid-build on
+// [[HS-TWTC-8CMW-TASK-dr1-doctrine-corpus-reader-stream-every]]) — folds HeySpex's OWN
+// historical session logs into the Doctrine corpus, as structured BEHAVIOUR evidence
+// rather than transcript text: how sessions actually ran (tools called, gate
+// refusals/blocks, claims made/released, specs advanced), not what the owner said.
+//
+// Two sources, both aggregated (never one observation per raw event — that would be
+// tens of thousands of near-noise rows):
+//   - `heyspex-events`  — the vault's own event stream, <vault>/specs/events/*.jsonl
+//     (`{timestamp, event_kind, actor, spec_id, metadata}`; session id lives at
+//     `metadata.sessionId` or `metadata.session_id` depending on the writer).
+//   - `heyspex-sesslog` — this repo's local hook-capture sidecars under `.heyspex/`:
+//     sesslog-history.jsonl (agent.tool_called, the SAME envelope shape), plus
+//     harness-audit.jsonl, guardrail-history.jsonl, claim-history.jsonl, and
+//     intent-classifier-history.jsonl — each its own shape; see
+//     {@link normalizeBehaviourRecord}.
+// A third, OPTIONAL source — the console's Neon-indexed `/api/agent-sessions` — is
+// folded in as `heyspex-agent-sessions` when the console answers; a down/erroring
+// console is skipped with a note, never a hard failure (see {@link fetchAgentSessionsSummaries}).
+//
+// Grouping: every normalized record is bucketed by (sessionId ?? 'unknown', UTC day)
+// and rendered into ONE `kind: 'behaviour'` observation per bucket — a compact,
+// redacted, <=600-char summary (tool counts, guardrail rule names, claim/spec
+// activity) — never the raw per-event stream.
+//
+// Unlike corpus.mjs's per-line incremental sources, these are FULL-RECOMPUTE every
+// `hs doctrine extract` run: the source files are relatively small (event-stream +
+// sidecars, not multi-hundred-MB session transcripts) and aggregation naturally spans
+// many lines into one row, which does not compose with a line-offset resume. Their
+// output lands in its own file ({@link defaultBehaviourObservationsPath}), REWRITTEN
+// wholesale each run (never appended to), so a re-run never accumulates duplicate
+// summaries the way an append-only log would.
+//
+// Streaming throughout: every file is read via `node:readline` over a
+// `createReadStream`, never a whole-file `readFileSync` of the larger event-stream
+// months (2026-07/08 run tens of MB).
+
+import { createReadStream, mkdirSync, writeFileSync } from 'node:fs';
+// The ONE shared console-URL resolver ([[HS-GD45-MCPC-TASK-mcp-cloud-auth-shared-console-resolver]])
+// — replaces this module's own hard-wired `http://localhost:3000` default with
+// env → ~/.heyspex/credentials.yaml console_url → the mode-derived default (no
+// `repoRoot` here, so the admin-local discovery-file rung is never consulted).
+import { resolveConsoleUrl as resolveConsoleUrlShared } from '../../../scripts/lib/console-url-resolver.mjs';
+import { createInterface } from 'node:readline';
+import { dirname, join } from 'node:path';
+
+import { redactText } from '../redact.mjs';
+
+export const HEYSPEX_EVENTS_SOURCE = 'heyspex-events';
+export const HEYSPEX_SESSLOG_SOURCE = 'heyspex-sesslog';
+export const HEYSPEX_AGENT_SESSIONS_SOURCE = 'heyspex-agent-sessions';
+
+const MAX_SUMMARY_CHARS = 600;
+
+export function defaultVaultEventsDir(vaultRoot) {
+  return join(vaultRoot, 'specs', 'events');
+}
+
+/** The local hook-capture sidecars under `.heyspex/` this module reads (read-only — never written). */
+export function defaultSesslogFiles(repoRoot) {
+  return [
+    join(repoRoot, '.heyspex', 'sesslog-history.jsonl'),
+    join(repoRoot, '.heyspex', 'harness-audit.jsonl'),
+    join(repoRoot, '.heyspex', 'guardrail-history.jsonl'),
+    join(repoRoot, '.heyspex', 'claim-history.jsonl'),
+    join(repoRoot, '.heyspex', 'intent-classifier-history.jsonl'),
+  ];
+}
+
+export function defaultBehaviourObservationsPath(repoRoot) {
+  return join(repoRoot, '.heyspex', 'doctrine', 'behaviour-observations.jsonl');
+}
+
+/**
+ * Overwrite the behaviour-observations file wholesale (never appended — see module
+ * header: these sources are full-recompute every run, so the file always reflects
+ * exactly this run's aggregation, never a union with a stale prior run's rows).
+ * @param {string} path
+ * @param {import('./corpus.mjs').DoctrineObservation[]} observations
+ */
+export function writeBehaviourObservations(path, observations) {
+  mkdirSync(dirname(path), { recursive: true });
+  const text = observations.map((o) => JSON.stringify(o)).join('\n');
+  writeFileSync(path, observations.length ? `${text}\n` : '');
+}
+
+/** Yield one parsed JSON record per non-blank line of `filePath`. Missing file → nothing (no throw). */
+async function* streamJsonlRecords(filePath) {
+  let stream;
+  try {
+    stream = createReadStream(filePath, { encoding: 'utf8' });
+  } catch {
+    return;
+  }
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        yield JSON.parse(trimmed);
+      } catch {
+        // corrupt/partial line — skip, don't throw
+      }
+    }
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'EISDIR')) return; // missing/odd path — silently empty
+    throw err;
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Normalize one raw record — from the vault's `{timestamp, event_kind, actor,
+ * spec_id, metadata}` envelope (shared by `specs/events/*.jsonl` AND
+ * sesslog-history.jsonl/guardrail-history.jsonl, which use the SAME shape) or one of
+ * the other three sidecars' own shapes — into `{ ts, sessionId, kind, detail }`.
+ * Returns `null` for a record with no usable timestamp (nothing to bucket by day).
+ *
+ * @param {unknown} rec
+ * @returns {{ ts: string, sessionId: string|null, kind: string, detail: string }|null}
+ */
+export function normalizeBehaviourRecord(rec) {
+  if (!rec || typeof rec !== 'object') return null;
+
+  // claim-history.jsonl: { specId, agent, sessionId, sessionShort, claimedAt, releasedAt, status }
+  if (typeof rec.specId === 'string' && typeof rec.claimedAt === 'string' && rec.event_kind === undefined) {
+    return {
+      ts: rec.releasedAt ?? rec.claimedAt,
+      sessionId: typeof rec.sessionId === 'string' ? rec.sessionId : null,
+      kind: rec.releasedAt ? 'claim.released' : 'claim.acquired',
+      detail: rec.specId,
+    };
+  }
+
+  // harness-audit.jsonl: { timestamp, actor, action, target, workspace, mode }
+  if (typeof rec.action === 'string' && typeof rec.actor === 'string' && rec.event_kind === undefined) {
+    if (typeof rec.timestamp !== 'string') return null;
+    return { ts: rec.timestamp, sessionId: null, kind: `audit.${rec.action}`, detail: typeof rec.target === 'string' ? rec.target : '' };
+  }
+
+  // intent-classifier-history.jsonl: { timestamp, event_kind: 'intent_classifier.decision', decision, ... }
+  if (rec.event_kind === 'intent_classifier.decision') {
+    if (typeof rec.timestamp !== 'string') return null;
+    return { ts: rec.timestamp, sessionId: null, kind: 'intent-classifier.decision', detail: typeof rec.decision === 'string' ? rec.decision : '' };
+  }
+
+  // The shared envelope: vault specs/events/*.jsonl, sesslog-history.jsonl, guardrail-history.jsonl.
+  if (typeof rec.event_kind === 'string') {
+    if (typeof rec.timestamp !== 'string') return null;
+    const meta = rec && typeof rec.metadata === 'object' && rec.metadata ? rec.metadata : {};
+    const sessionId = typeof meta.sessionId === 'string' ? meta.sessionId : typeof meta.session_id === 'string' ? meta.session_id : null;
+    let detail = '';
+    if (rec.event_kind === 'agent.tool_called') detail = typeof meta.tool_name === 'string' ? meta.tool_name : '';
+    else if (rec.event_kind === 'guardrail.fired') detail = typeof meta.rule === 'string' ? meta.rule : '';
+    else if (typeof rec.spec_id === 'string') detail = rec.spec_id;
+    return { ts: rec.timestamp, sessionId, kind: rec.event_kind, detail };
+  }
+
+  return null;
+}
+
+function dayOf(ts) {
+  return typeof ts === 'string' && ts.length >= 10 ? ts.slice(0, 10) : 'unknown-day';
+}
+
+/**
+ * Bucket normalized records by (sessionId ?? 'unknown', UTC day).
+ * @param {Array<{ ts: string, sessionId: string|null, kind: string, detail: string }>} records
+ * @returns {Array<{ sessionId: string, day: string, kindCounts: Map<string,number>, toolCounts: Map<string,number>, guardrailCounts: Map<string,number>, specs: Set<string>, firstTs: string, lastTs: string }>}
+ */
+export function groupBehaviourRecords(records) {
+  const groups = new Map();
+  for (const r of records) {
+    if (!r || !r.ts) continue;
+    const sessionId = r.sessionId ?? 'unknown';
+    const day = dayOf(r.ts);
+    const key = `${sessionId}::${day}`;
+    let g = groups.get(key);
+    if (!g) {
+      g = { sessionId, day, kindCounts: new Map(), toolCounts: new Map(), guardrailCounts: new Map(), specs: new Set(), firstTs: r.ts, lastTs: r.ts };
+      groups.set(key, g);
+    }
+    g.kindCounts.set(r.kind, (g.kindCounts.get(r.kind) ?? 0) + 1);
+    if (r.kind === 'agent.tool_called' && r.detail) g.toolCounts.set(r.detail, (g.toolCounts.get(r.detail) ?? 0) + 1);
+    if (r.kind === 'guardrail.fired' && r.detail) g.guardrailCounts.set(r.detail, (g.guardrailCounts.get(r.detail) ?? 0) + 1);
+    if (r.detail && (r.kind.startsWith('spec.') || r.kind.startsWith('claim.') || r.kind === 'focus.set')) g.specs.add(r.detail);
+    if (r.ts < g.firstTs) g.firstTs = r.ts;
+    if (r.ts > g.lastTs) g.lastTs = r.ts;
+  }
+  return [...groups.values()];
+}
+
+function topEntries(map, limit) {
+  return [...map.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([k, v]) => `${k}×${v}`)
+    .join(', ');
+}
+
+/**
+ * Render one bucket into a compact (<=600 char) summary: tools called with counts,
+ * guardrail refusals/blocks with rule names, claims made/released and specs advanced,
+ * and the session's spec ids.
+ * @param {ReturnType<typeof groupBehaviourRecords>[number]} g
+ * @returns {string}
+ */
+export function summarizeBehaviourGroup(g) {
+  const parts = [];
+  if (g.toolCounts.size) parts.push(`tools: ${topEntries(g.toolCounts, 8)}`);
+  if (g.guardrailCounts.size) parts.push(`guardrail blocks: ${topEntries(g.guardrailCounts, 8)}`);
+  const acquired = g.kindCounts.get('claim.acquired') ?? 0;
+  const released = g.kindCounts.get('claim.released') ?? 0;
+  if (acquired || released) parts.push(`claims: ${acquired} acquired, ${released} released`);
+  const statusChanges = g.kindCounts.get('spec.status_change') ?? 0;
+  if (statusChanges) parts.push(`${statusChanges} status change(s)`);
+  const permissionEvents = [...g.kindCounts.keys()].filter((k) => k.startsWith('audit.'));
+  if (permissionEvents.length) parts.push(`audit: ${permissionEvents.map((k) => `${k}×${g.kindCounts.get(k)}`).join(', ')}`);
+  if (g.specs.size) parts.push(`specs: ${[...g.specs].slice(0, 12).join(', ')}`);
+
+  let text = `Session ${g.sessionId} on ${g.day} — ${parts.length ? parts.join('; ') : 'no notable activity'}.`;
+  if (text.length > MAX_SUMMARY_CHARS) text = `${text.slice(0, MAX_SUMMARY_CHARS - 1)}…`;
+  return text;
+}
+
+/**
+ * Build `kind: 'behaviour'` observations from a flat list of normalized records —
+ * one per (session, day) bucket, sorted deterministically (day, then session).
+ * @param {Array<{ ts: string, sessionId: string|null, kind: string, detail: string }>} records
+ * @param {{ source: string, project: string, redact?: (text: string) => string }} opts
+ * @returns {import('./corpus.mjs').DoctrineObservation[]}
+ */
+export function buildBehaviourObservations(records, { source, project, redact = redactText }) {
+  const groups = groupBehaviourRecords(records).sort((a, b) => a.day.localeCompare(b.day) || a.sessionId.localeCompare(b.sessionId));
+  return groups.map((g, i) => ({
+    id: `${source}:${project}:${g.sessionId}:${g.day}`,
+    source,
+    project,
+    session: g.sessionId,
+    ts: g.lastTs,
+    seq: i + 1,
+    kind: 'behaviour',
+    text: redact(summarizeBehaviourGroup(g)),
+  }));
+}
+
+/** Stream every `*.jsonl` file directly under `dir` (non-recursive — the vault's events dir is flat). */
+async function collectFromDir(dir) {
+  const { readdirSync } = await import('node:fs');
+  let entries = [];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return { records: [], filesRead: 0, linesRead: 0 };
+  }
+  const records = [];
+  let filesRead = 0;
+  let linesRead = 0;
+  for (const ent of entries) {
+    if (!ent.isFile() || !ent.name.endsWith('.jsonl')) continue;
+    filesRead++;
+    for await (const rec of streamJsonlRecords(join(dir, ent.name))) {
+      linesRead++;
+      const normalized = normalizeBehaviourRecord(rec);
+      if (normalized) records.push(normalized);
+    }
+  }
+  return { records, filesRead, linesRead };
+}
+
+async function collectFromFiles(paths) {
+  const records = [];
+  let filesRead = 0;
+  let linesRead = 0;
+  for (const p of paths) {
+    filesRead++;
+    for await (const rec of streamJsonlRecords(p)) {
+      linesRead++;
+      const normalized = normalizeBehaviourRecord(rec);
+      if (normalized) records.push(normalized);
+    }
+  }
+  return { records, filesRead, linesRead };
+}
+
+/**
+ * Collect + aggregate BOTH behaviour sources (`heyspex-events`, `heyspex-sesslog`).
+ * Full-recompute every call — see module header. Never throws on a missing file/dir
+ * (silently empty).
+ *
+ * @param {{ vaultEventsDir: string, sesslogFiles: string[], project: string, redact?: (text: string) => string }} opts
+ * @returns {Promise<{ observations: import('./corpus.mjs').DoctrineObservation[], countsBySource: Record<string, number>, stats: Record<string, { filesRead: number, linesRead: number }> }>}
+ */
+export async function collectBehaviourObservations({ vaultEventsDir, sesslogFiles, project, redact = redactText }) {
+  const events = await collectFromDir(vaultEventsDir);
+  const sesslog = await collectFromFiles(sesslogFiles);
+
+  const eventsObs = buildBehaviourObservations(events.records, { source: HEYSPEX_EVENTS_SOURCE, project, redact });
+  const sesslogObs = buildBehaviourObservations(sesslog.records, { source: HEYSPEX_SESSLOG_SOURCE, project, redact });
+
+  return {
+    observations: [...eventsObs, ...sesslogObs],
+    countsBySource: { [HEYSPEX_EVENTS_SOURCE]: eventsObs.length, [HEYSPEX_SESSLOG_SOURCE]: sesslogObs.length },
+    stats: {
+      [HEYSPEX_EVENTS_SOURCE]: { filesRead: events.filesRead, linesRead: events.linesRead },
+      [HEYSPEX_SESSLOG_SOURCE]: { filesRead: sesslog.filesRead, linesRead: sesslog.linesRead },
+    },
+  };
+}
+
+/**
+ * OPTIONAL third source: the console's Neon-indexed `/api/agent-sessions`. A down
+ * console, a non-2xx response, or any network failure is reported as `{ skipped: true,
+ * reason }` — never thrown — per the owner's "if it 500s, skip with a note" ask.
+ *
+ * @param {{ baseUrl?: string, project?: string, redact?: (text: string) => string, fetchFn?: typeof fetch, timeoutMs?: number }} [opts]
+ * @returns {Promise<{ observations: import('./corpus.mjs').DoctrineObservation[], skipped: boolean, reason?: string }>}
+ */
+export async function fetchAgentSessionsSummaries({
+  baseUrl = resolveConsoleUrlShared(),
+  project = 'heyspex-app',
+  redact = redactText,
+  fetchFn = typeof fetch === 'function' ? fetch : null,
+  timeoutMs = 3000,
+} = {}) {
+  if (!fetchFn) return { observations: [], skipped: true, reason: 'no fetch implementation available' };
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetchFn(`${baseUrl.replace(/\/$/, '')}/api/agent-sessions`, { signal: ac.signal });
+  } catch (err) {
+    return { observations: [], skipped: true, reason: `unreachable: ${err?.message ?? String(err)}` };
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res || !res.ok) {
+    return { observations: [], skipped: true, reason: `console responded ${res?.status ?? 'with no status'}` };
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch (err) {
+    return { observations: [], skipped: true, reason: `unparseable response: ${err?.message ?? String(err)}` };
+  }
+  const sessions = Array.isArray(body) ? body : Array.isArray(body?.sessions) ? body.sessions : [];
+  if (!sessions.length) return { observations: [], skipped: false };
+
+  const observations = sessions.map((s, i) => {
+    const sessionId = s.sessionId ?? s.id ?? `session-${i}`;
+    const ts = s.updatedAt ?? s.startedAt ?? s.createdAt ?? new Date().toISOString();
+    const specs = Array.isArray(s.specIds) ? s.specIds : Array.isArray(s.specs) ? s.specs : [];
+    let text = `Console-indexed session ${sessionId} — status ${s.status ?? 'unknown'}${specs.length ? `, specs: ${specs.slice(0, 12).join(', ')}` : ''}.`;
+    if (text.length > MAX_SUMMARY_CHARS) text = `${text.slice(0, MAX_SUMMARY_CHARS - 1)}…`;
+    return {
+      id: `${HEYSPEX_AGENT_SESSIONS_SOURCE}:${project}:${sessionId}:${dayOf(ts)}`,
+      source: HEYSPEX_AGENT_SESSIONS_SOURCE,
+      project,
+      session: sessionId,
+      ts,
+      seq: i + 1,
+      kind: 'behaviour',
+      text: redact(text),
+    };
+  });
+  return { observations, skipped: false };
+}