@mrclrchtr/supi-debug 11.0.1 → 11.1.0

package/skills/gather-retrospectives/scripts/collect.mjs

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { displayPage, readEvidence, summarize } from "./snapshot.mjs";
+
+const help = `Collect stored Agent Run retrospectives without modifying sessions.
+Usage: node collect.mjs --output <new-file.json> [collection options]
+       node collect.mjs --read <evidence.json> [display options]
+  --workspace <path>     Include sessions in this directory tree (default: cwd)
+  --all-workspaces       Explicitly include other projects; replaces --workspace
+  --sessions-dir <path>  Override PI storage discovery
+  --source <name>        supi-agent or supi-review (default: both, not a topic filter)
+  --since <date|Nd>      Inclusive ISO date/time or number of days ago
+  --max-sessions <n>     Bound session scans (default: 5000)
+  --output <path>        Save all matching reports; existing files are preserved
+  --read <path>          Read a saved snapshot without accessing session storage
+  --refs <ref,ref>       Select report references from --read (default: all)
+  --limit <1..100>       Maximum reports displayed per response (default: 20)
+  --offset <number>      Report offset within the selection (default: 0)
+  --text-offset <number> UTF-16 offset within an oversized report (--read only)
+  --help                Show this help
+Only persisted supi-debug-event / agent-run-retrospective entries are collected.
+Interactive reports and quoted tool results are excluded. Stdout is bounded to
+16 KB. Follow nextCommand until display.complete; oversized text is continued
+with explicit textRange offsets. coverage.complete describes the scan, not display.
+Storage precedence: flag, PI_CODING_AGENT_SESSION_DIR, project/global sessionDir,
+then <PI_CODING_AGENT_DIR or ~/.pi/agent>/sessions. Relative paths use cwd.
+`;
+
+function localPath(path) {
+  return resolve(
+    path === "~" ? homedir() : path.startsWith("~/") ? join(homedir(), path.slice(2)) : path,
+  );
+}
+
+async function canonicalPath(path) {
+  const absolute = localPath(path);
+  try {
+    return await realpath(absolute);
+  } catch (error) {
+    if (error.code === "ENOENT") return absolute;
+    throw error;
+  }
+}
+
+async function settings(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw new Error(`Cannot read settings: ${path}`, { cause: error });
+  }
+}
+
+async function sessionDirectory(explicit) {
+  if (explicit) return localPath(explicit);
+  if (process.env.PI_CODING_AGENT_SESSION_DIR)
+    return localPath(process.env.PI_CODING_AGENT_SESSION_DIR);
+  const agentDir = localPath(process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi/agent"));
+  const project = await settings(join(process.cwd(), ".pi/settings.json"));
+  if (typeof project.sessionDir === "string") return localPath(project.sessionDir);
+  const global = await settings(join(agentDir, "settings.json"));
+  return typeof global.sessionDir === "string"
+    ? localPath(global.sessionDir)
+    : join(agentDir, "sessions");
+}
+
+function integer(value, name, min, max) {
+  const parsed = Number(value);
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+    throw new Error(`${name} must be an integer from ${min} through ${max}.`);
+  }
+  return parsed;
+}
+
+function sinceTimestamp(value) {
+  if (!value) return null;
+  if (/^\d+d$/.test(value)) {
+    const days = integer(value.slice(0, -1), "--since days", 0, 36500);
+    return Date.now() - days * 86400000;
+  }
+  const parsed = /^\d{4}-\d{2}-\d{2}(?:T.*)?$/.test(value) ? Date.parse(value) : Number.NaN;
+  if (
+    !Number.isFinite(parsed) ||
+    (value.length === 10 && new Date(parsed).toISOString().slice(0, 10) !== value)
+  ) {
+    throw new Error("--since must be an ISO date/time or a duration such as 30d.");
+  }
+  return parsed;
+}
+
+function readOptions(values, display) {
+  const collectionFlags = [
+    "workspace",
+    "all-workspaces",
+    "sessions-dir",
+    "source",
+    "since",
+    "max-sessions",
+    "output",
+  ];
+  if (collectionFlags.some((key) => values[key] !== undefined))
+    throw new Error("--read cannot be combined with collection options.");
+  if (display.refs?.some((ref) => !/^R-[a-f0-9]{16}$/.test(ref)))
+    throw new Error("--refs must contain comma-separated report references.");
+  return { read: localPath(values.read), display };
+}
+
+async function options() {
+  const { values } = parseArgs({
+    options: {
+      workspace: { type: "string" },
+      "all-workspaces": { type: "boolean" },
+      "sessions-dir": { type: "string" },
+      source: { type: "string" },
+      since: { type: "string" },
+      limit: { type: "string", default: "20" },
+      offset: { type: "string", default: "0" },
+      "max-sessions": { type: "string" },
+      output: { type: "string" },
+      read: { type: "string" },
+      refs: { type: "string" },
+      "text-offset": { type: "string" },
+      help: { type: "boolean" },
+    },
+  });
+  if (values.help) return null;
+  const display = {
+    limit: integer(values.limit, "--limit", 1, 100),
+    offset: integer(values.offset, "--offset", 0, Number.MAX_SAFE_INTEGER),
+    textOffset: integer(values["text-offset"] ?? "0", "--text-offset", 0, Number.MAX_SAFE_INTEGER),
+    refs: values.refs?.split(",") ?? null,
+  };
+  if (values.read) return readOptions(values, display);
+  if (values.refs !== undefined || values["text-offset"] !== undefined)
+    throw new Error("--refs and --text-offset require --read.");
+  if (!values.output) throw new Error("--output must name a new JSON evidence file.");
+  if (values.workspace && values["all-workspaces"])
+    throw new Error("Choose --workspace or --all-workspaces, not both.");
+  if (values.source && !["supi-agent", "supi-review"].includes(values.source)) {
+    throw new Error(
+      "--source must be supi-agent or supi-review; topic relevance is assessed separately.",
+    );
+  }
+  return {
+    workspace: values["all-workspaces"]
+      ? null
+      : await canonicalPath(values.workspace || process.cwd()),
+    sessionsDir: await sessionDirectory(values["sessions-dir"]),
+    source: values.source ?? null,
+    since: sinceTimestamp(values.since),
+    maxSessions: integer(values["max-sessions"] ?? "5000", "--max-sessions", 1, 100000),
+    output: localPath(values.output),
+    display,
+  };
+}
+
+function within(directory, path) {
+  const child = relative(directory, path);
+  return child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute(child);
+}
+
+function recordFailure(coverage, path, code) {
+  coverage.readFailures++;
+  if (coverage.failures.length < 10) coverage.failures.push({ path, code });
+}
+
+async function directoryEntries(directory, config, coverage) {
+  try {
+    return await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (directory === config.sessionsDir)
+      throw new Error(`Cannot list session storage: ${directory}`, { cause: error });
+    recordFailure(coverage, directory, error.code ?? "READ_FAILED");
+    return [];
+  }
+}
+
+function discoverEntry(entry, directory, state) {
+  const path = join(directory, entry.name);
+  if (entry.isSymbolicLink()) state.coverage.ignoredSymlinks++;
+  else if (entry.isDirectory()) state.pending.push(path);
+  else if (entry.isFile() && entry.name.endsWith(".jsonl")) state.files.push(path);
+}
+
+async function discover(config, coverage) {
+  const files = [];
+  const pending = [config.sessionsDir];
+  while (pending.length) {
+    const directory = pending.pop();
+    const entries = await directoryEntries(directory, config, coverage);
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      discoverEntry(entry, directory, { files, pending, coverage });
+      if (files.length > config.maxSessions) {
+        coverage.sessionLimitReached = true;
+        return files.slice(0, config.maxSessions);
+      }
+    }
+  }
+  return files;
+}
+
+function parseEntry(line, coverage) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    coverage.malformedEntries++;
+    return null;
+  }
+}
+
+function assessment(entry) {
+  if (entry?.type !== "custom" || entry.customType !== "supi-debug-event") return null;
+  const event = entry.data;
+  if (event?.category !== "agent-run-retrospective") return null;
+  const data = event.data;
+  if (
+    !["supi-agent", "supi-review"].includes(event.source) ||
+    !Number.isFinite(event.timestamp) ||
+    Math.abs(event.timestamp) > 8.64e15 ||
+    !["completed", "failed"].includes(data?.status) ||
+    (data.text !== undefined && typeof data.text !== "string")
+  )
+    return null;
+  return { event, data };
+}
+
+// Project only known sanitized assessment fields; never copy whole entries or rawData.
+function report(entry, context) {
+  const parsed = assessment(entry);
+  if (!parsed) return null;
+  const { event, data } = parsed;
+  const report = {
+    timestamp: event.timestamp,
+    source: event.source,
+    status: data.status,
+    text: data.text,
+    ...context,
+    entryId: typeof entry.id === "string" ? entry.id : null,
+  };
+  for (const key of ["runKey", "caller", "batchId", "taskId", "label", "conversationId"]) {
+    if (typeof data[key] === "string") report[key] = data[key];
+  }
+  const identity = report.runKey
+    ? [report.source, report.runKey]
+    : [report.source, report.timestamp, report.status, report.text, report.entryId];
+  report.ref = `R-${createHash("sha256").update(JSON.stringify(identity)).digest("hex").slice(0, 16)}`;
+  return report;
+}
+
+async function readHeader(line, path, state) {
+  const session = parseEntry(line, state.coverage);
+  if (session?.type !== "session" || typeof session.cwd !== "string" || !isAbsolute(session.cwd)) {
+    recordFailure(state.coverage, path, "INVALID_SESSION_HEADER");
+    return null;
+  }
+  const cwd = await canonicalPath(session.cwd);
+  if (state.config.workspace && !within(state.config.workspace, cwd)) return null;
+  state.coverage.scopedSessions++;
+  return session;
+}
+
+function collectLine(line, context, state) {
+  if (!line.trim()) return;
+  const { config, coverage, reports } = state;
+  const entry = parseEntry(line, coverage);
+  if (
+    entry?.type !== "custom" ||
+    entry.customType !== "supi-debug-event" ||
+    entry.data?.category !== "agent-run-retrospective"
+  )
+    return;
+  const item = report(entry, context);
+  if (!item) {
+    coverage.malformedEntries++;
+    return;
+  }
+  if (
+    (config.source && item.source !== config.source) ||
+    (config.since !== null && item.timestamp < config.since)
+  )
+    return;
+  coverage.matchingEvents++;
+  if (reports.has(item.ref)) coverage.duplicateEvents++;
+  else reports.set(item.ref, item);
+}
+
+/** Split JSONL only on LF; readline also splits valid JSON string content at U+2028/U+2029. */
+async function* jsonLines(input) {
+  let pending = "";
+  for await (const chunk of input) {
+    pending += chunk;
+    let index = pending.indexOf("\n");
+    while (index !== -1) {
+      yield pending.slice(0, index);
+      pending = pending.slice(index + 1);
+      index = pending.indexOf("\n");
+    }
+  }
+  if (pending) yield pending;
+}
+
+async function scanSession(path, state) {
+  const { coverage } = state;
+  coverage.scannedSessions++;
+  const input = createReadStream(path, { encoding: "utf8" });
+  const lines = jsonLines(input);
+  let lineNumber = 0;
+  let session;
+  try {
+    for await (const line of lines) {
+      lineNumber++;
+      if (lineNumber === 1) {
+        session = await readHeader(line, path, state);
+        if (!session) break;
+        continue;
+      }
+      collectLine(
+        line,
+        { sessionFile: path, sessionId: session.id, cwd: session.cwd, line: lineNumber },
+        state,
+      );
+    }
+    if (lineNumber === 0) recordFailure(coverage, path, "EMPTY_SESSION");
+  } catch (error) {
+    recordFailure(coverage, path, error.code ?? "READ_FAILED");
+  } finally {
+    input.destroy();
+  }
+}
+
+async function collect(config) {
+  const coverage = {
+    scannedSessions: 0,
+    scopedSessions: 0,
+    matchingEvents: 0,
+    duplicateEvents: 0,
+    malformedEntries: 0,
+    ignoredSymlinks: 0,
+    sessionLimitReached: false,
+    readFailures: 0,
+    failures: [],
+  };
+  const reports = new Map();
+  const files = await discover(config, coverage);
+  for (const file of files) await scanSession(file, { config, coverage, reports });
+  const sorted = [...reports.values()].sort(
+    (a, b) => b.timestamp - a.timestamp || a.ref.localeCompare(b.ref),
+  );
+  const { display: _display, output: _output, ...filters } = config;
+  return {
+    version: 1,
+    filters,
+    coverage: {
+      ...coverage,
+      complete:
+        !coverage.sessionLimitReached &&
+        coverage.ignoredSymlinks === 0 &&
+        coverage.readFailures === 0 &&
+        coverage.malformedEntries === 0,
+      uniqueReports: sorted.length,
+    },
+    limitations: [
+      "Structured persisted retrospectives only; interactive reports are excluded.",
+      "Stored text is best-effort sanitized, not guaranteed free of sensitive task details.",
+      "Successful-task selection and optional logging prevent population failure-rate estimates.",
+      "Source identifies the producer, not the topic; suggestions are not verified improvements.",
+    ],
+    records: sorted,
+  };
+}
+
+try {
+  const config = await options();
+  if (!config) process.stdout.write(help);
+  else {
+    const evidence = config.read ? await readEvidence(config.read) : await collect(config);
+    const evidenceFile = config.read ?? config.output;
+    if (!config.read) {
+      evidence.summary = summarize(evidence.records);
+      await writeFile(evidenceFile, `${JSON.stringify(evidence, null, 2)}\n`, {
+        flag: "wx",
+        mode: 0o600,
+      });
+    }
+    process.stdout.write(
+      `${JSON.stringify(displayPage(evidence, evidenceFile, config.display, fileURLToPath(import.meta.url)))}\n`,
+    );
+  }
+} catch (error) {
+  process.stderr.write(`Retrospective collection failed: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/skills/gather-retrospectives/scripts/snapshot.mjs

@@ -0,0 +1,183 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, relative } from "node:path";
+
+/** Count deduplicated reports, not independent experiments or all sessions scanned. */
+export function summarize(records) {
+  const bySource = { "supi-agent": 0, "supi-review": 0 };
+  const byStatus = { completed: 0, failed: 0 };
+  let earliest = Infinity;
+  let latest = -Infinity;
+  for (const record of records) {
+    bySource[record.source]++;
+    byStatus[record.status]++;
+    earliest = Math.min(earliest, record.timestamp);
+    latest = Math.max(latest, record.timestamp);
+  }
+  return {
+    reports: records.length,
+    containingSessions: new Set(records.map((record) => record.sessionFile)).size,
+    bySource,
+    byStatus,
+    earliest: records.length ? new Date(earliest).toISOString() : null,
+    latest: records.length ? new Date(latest).toISOString() : null,
+  };
+}
+
+/** Snapshot reads never discover storage or open original session files. */
+export async function readEvidence(path) {
+  const evidence = JSON.parse(await readFile(path, "utf8"));
+  if (
+    evidence.version !== 1 ||
+    !evidence.filters ||
+    !evidence.coverage ||
+    !Array.isArray(evidence.records) ||
+    typeof evidence.filters.sessionsDir !== "string" ||
+    !evidence.records.every(
+      (record) =>
+        /^R-[a-f0-9]{16}$/.test(record.ref) &&
+        ["supi-agent", "supi-review"].includes(record.source) &&
+        ["completed", "failed"].includes(record.status) &&
+        Number.isFinite(record.timestamp) &&
+        Math.abs(record.timestamp) <= 8.64e15 &&
+        typeof record.sessionFile === "string" &&
+        isAbsolute(record.sessionFile) &&
+        Number.isSafeInteger(record.line) &&
+        record.line > 0 &&
+        (record.text === undefined || typeof record.text === "string"),
+    )
+  )
+    throw new Error("Invalid retrospective snapshot; collect a new evidence file.");
+  return evidence;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+const fits = (value) => Buffer.byteLength(JSON.stringify(value)) + 1 <= 16_000;
+
+function selectRecords(allRecords, options) {
+  const refs = options.refs ? new Set(options.refs) : null;
+  if (refs && [...refs].some((ref) => !allRecords.some((record) => record.ref === ref)))
+    throw new Error("Unknown report reference in --refs.");
+  const records = refs ? allRecords.filter((record) => refs.has(record.ref)) : allRecords;
+  if (options.offset > records.length)
+    throw new Error("--offset exceeds the number of selected reports.");
+  const initialText = records[options.offset]?.text ?? "";
+  if (
+    options.textOffset &&
+    (options.textOffset >= initialText.length ||
+      safeTextEnd(initialText, options.textOffset) !== options.textOffset)
+  )
+    throw new Error("--text-offset must address unread text at a Unicode boundary.");
+
+  return records;
+}
+
+function createRenderer(evidence, records, { evidenceFile, options, scriptFile }) {
+  const { filters, coverage, records: allRecords } = evidence;
+  const { failures: _failures, ...counts } = coverage;
+  const summary = summarize(allRecords);
+  return (items, offset, textOffset = 0) => {
+    const complete = offset === records.length;
+    const args = [process.execPath, scriptFile, "--read", evidenceFile];
+    if (options.refs) args.push("--refs", options.refs.join(","));
+    args.push("--limit", String(options.limit), "--offset", String(offset));
+    if (textOffset) args.push("--text-offset", String(textOffset));
+    return {
+      evidenceFile,
+      sessionsDir: filters.sessionsDir,
+      scope: {
+        workspace: filters.workspace,
+        source: filters.source,
+        since: filters.since === null ? null : new Date(filters.since).toISOString(),
+      },
+      coverage: counts,
+      summary,
+      display: {
+        selectedReports: records.length,
+        displayedReports: items.length,
+        remainingReports: records.length - offset,
+        complete,
+        nextOffset: complete ? null : offset,
+        nextTextOffset: complete ? null : textOffset,
+      },
+      records: items,
+      nextCommand: complete ? null : args.map(shellQuote).join(" "),
+    };
+  };
+}
+
+/** Fit escaped JSON bytes, preserving Unicode and making forward progress on long assessments. */
+function fragmentPage(record, item, { offset, textOffset, render, evidenceFile }) {
+  const text = record.text ?? "";
+  let low = textOffset + 1;
+  let high = text.length;
+  let best;
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2);
+    const end = safeTextEnd(text, middle);
+    const fragment = {
+      ...item,
+      text: text.slice(textOffset, end),
+      textRange: { start: textOffset, end, total: text.length },
+    };
+    const page = render(
+      [fragment],
+      end === text.length ? offset + 1 : offset,
+      end === text.length ? 0 : end,
+    );
+    if (end > textOffset && fits(page)) {
+      best = page;
+      low = middle + 1;
+    } else high = middle - 1;
+  }
+  if (!best)
+    throw new Error(`Display metadata exceeds 16 KB; full evidence is in ${evidenceFile}.`);
+  return best;
+}
+
+/** Display a frozen selection with resumable report and UTF-16 text cursors. */
+export function displayPage(evidence, evidenceFile, options, scriptFile) {
+  const records = selectRecords(evidence.records, options);
+  const { filters } = evidence;
+  const render = createRenderer(evidence, records, { evidenceFile, options, scriptFile });
+  const items = [];
+  let offset = options.offset;
+  let textOffset = options.textOffset;
+  let display = render(items, offset, textOffset);
+  while (offset < records.length && items.length < options.limit) {
+    const record = records[offset];
+    const item = {
+      ref: record.ref,
+      source: record.source,
+      date: new Date(record.timestamp).toISOString(),
+      status: record.status,
+      file: relative(filters.sessionsDir, record.sessionFile),
+      line: record.line,
+      text: record.text?.slice(textOffset),
+    };
+    if (textOffset)
+      item.textRange = { start: textOffset, end: record.text.length, total: record.text.length };
+    const candidate = render([...items, item], offset + 1);
+    if (fits(candidate)) {
+      items.push(item);
+      offset++;
+      textOffset = 0;
+      display = candidate;
+      continue;
+    }
+    // Defer whole reports rather than splitting them merely to fill a response.
+    if (items.length) break;
+    return fragmentPage(record, item, { offset, textOffset, render, evidenceFile });
+  }
+  if (!fits(display))
+    throw new Error(`Display metadata exceeds 16 KB; full evidence is in ${evidenceFile}.`);
+  return display;
+}
+
+function safeTextEnd(text, end) {
+  const before = text.charCodeAt(end - 1);
+  const after = text.charCodeAt(end);
+  return before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff ? end - 1 : end;
+}

package/src/command.ts

@@ -54,7 +54,7 @@ async function sendPersistedDebugReport(
           })
         : await readSessionDebugEvents(sessionFile, filters);
     const output = truncateDebugOutput(
-      formatDebugEvents(persisted.events, false, false, persisted.persistedEventCount).join("\n"),
+      formatDebugEvents(persisted.events, false, false, persisted).join("\n"),
     );
     pi.sendMessage({
       customType: DEBUG_REPORT_TYPE,
@@ -63,10 +63,12 @@ async function sendPersistedDebugReport(
       details: createDebugMessageDetails(persisted.events, {
         sessionFile: query.sessionFile,
         persistedEventCount: persisted.persistedEventCount,
+        invalidEventCount: persisted.invalidEventCount,
+        malformedLineCount: persisted.malformedLineCount,
         eventCount: persisted.events.length,
         emptyReason:
           persisted.events.length === 0
-            ? persisted.persistedEventCount === 0
+            ? persisted.persistedEventCount === 0 && persisted.malformedLineCount === 0
               ? "no-persisted-events"
               : "no-matches"
             : undefined,

package/src/config.ts

@@ -14,6 +14,7 @@ export interface DebugConfig extends Record<string, unknown> {
   enabled: boolean;
   agentAccess: DebugAgentAccess;
   maxEvents: number;
+  agentRunRetrospectivesEnabled: boolean;
 }
 
 export const DEBUG_DEFAULTS: DebugConfig = { ...DEBUG_REGISTRY_DEFAULTS };
@@ -27,7 +28,7 @@ export function normalizeMaxEvents(value: string | number): number {
   return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : DEBUG_DEFAULTS.maxEvents;
 }
 
-function normalizeEnabled(value: unknown): boolean {
+function normalizeBoolean(value: unknown, fallback: boolean): boolean {
   if (typeof value === "boolean") {
     return value;
   }
@@ -51,20 +52,24 @@ function normalizeEnabled(value: unknown): boolean {
     ) {
       return false;
     }
-    return DEBUG_DEFAULTS.enabled;
+    return fallback;
   }
 
   if (value === 1) return true;
   if (value === 0) return false;
-  return DEBUG_DEFAULTS.enabled;
+  return fallback;
 }
 
 export function loadDebugConfig(cwd: string): DebugConfig {
   const config = loadSupiConfig(DEBUG_SECTION, cwd, DEBUG_DEFAULTS);
   return {
-    enabled: normalizeEnabled(config.enabled),
+    enabled: normalizeBoolean(config.enabled, DEBUG_DEFAULTS.enabled),
     agentAccess: normalizeAgentAccess(String(config.agentAccess)),
     maxEvents: normalizeMaxEvents(config.maxEvents),
+    agentRunRetrospectivesEnabled: normalizeBoolean(
+      config.agentRunRetrospectivesEnabled,
+      DEBUG_DEFAULTS.agentRunRetrospectivesEnabled,
+    ),
   };
 }