session-steward 0.4.0 → 0.5.0

package/lib/providers/codex/index.mjs

@@ -1,3 +1,4 @@
+import { readSessionEvents } from "./events.mjs";
 import {
   assertDeepCleanupSupported,
   diagnoseStorageCompatibility,
@@ -38,6 +39,7 @@ export const codexProvider = Object.freeze({
   loadSessionStore,
   planSessionDeletion,
   preflightSessionDeletion,
+  readSessionEvents,
   restoreSessionDeletionBackup,
   verifySessionDeletion,
 });

package/lib/server.mjs

@@ -6,6 +6,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { getProvider, listProviders } from "./providers/index.mjs";
+import {
+  DEFAULT_SESSION_EVENT_LIMIT,
+  MAX_SESSION_EVENT_LIMIT,
+} from "./session-event-reader.mjs";
 import { createProviderSettings } from "./settings.mjs";
 import { classifyInstalledVersion } from "./version-support.mjs";
 
@@ -174,6 +178,35 @@ function getPositiveInteger(value, fallback, maximum = Number.MAX_SAFE_INTEGER)
   return Math.min(parsed, maximum);
 }
 
+function getSessionEventLimit(value) {
+  if (value === null) return DEFAULT_SESSION_EVENT_LIMIT;
+  if (!/^\d+$/u.test(value)) {
+    throw new Error(`limit must be between 1 and ${MAX_SESSION_EVENT_LIMIT}.`);
+  }
+
+  const limit = Number(value);
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_SESSION_EVENT_LIMIT) {
+    throw new Error(`limit must be between 1 and ${MAX_SESSION_EVENT_LIMIT}.`);
+  }
+
+  return limit;
+}
+
+function getSessionId(value) {
+  if (
+    typeof value !== "string"
+    || value.length === 0
+    || value.length > 512
+    || value.trim() !== value
+    || value.includes("\0")
+    || /[\\/]/u.test(value)
+  ) {
+    throw new Error("Enter a valid session ID.");
+  }
+
+  return value;
+}
+
 function getInactiveBeforeMs(value) {
   if (value === null || value === "") {
     return null;
@@ -811,10 +844,38 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
         return;
       }
 
+      if (request.method === "GET" && requestUrl.pathname === "/api/session-events") {
+        const controller = new AbortController();
+        const abortRead = () => controller.abort();
+        request.once("aborted", abortRead);
+        response.once("close", () => {
+          if (!response.writableEnded) abortRead();
+        });
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const provider = getProvider(providerId);
+        const id = getSessionId(requestUrl.searchParams.get("id"));
+        const result = await provider.readSessionEvents({
+          ...providerOptions(providerId, settings.getHome(providerId)),
+          id,
+          limit: getSessionEventLimit(requestUrl.searchParams.get("limit")),
+          signal: controller.signal,
+        });
+
+        if (controller.signal.aborted) return;
+
+        if (!result) {
+          sendJson(response, 404, { error: "Session not found." });
+          return;
+        }
+
+        sendJson(response, 200, result);
+        return;
+      }
+
       if (request.method === "GET" && requestUrl.pathname.startsWith("/api/sessions/")) {
         const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
         const provider = getProvider(providerId);
-        const id = decodeURIComponent(requestUrl.pathname.slice("/api/sessions/".length));
+        const id = getSessionId(decodeURIComponent(requestUrl.pathname.slice("/api/sessions/".length)));
         const record = await provider.getSessionRecord({
           ...providerOptions(providerId, settings.getHome(providerId)),
           id,

package/lib/session-event-reader.mjs

@@ -0,0 +1,126 @@
+import {
+  SESSION_EVENT_READ_MODE,
+  SESSION_EVENT_WINDOW_END,
+} from "./session-events.mjs";
+
+export const DEFAULT_SESSION_EVENT_LIMIT = 100;
+export const MAX_SESSION_EVENT_LIMIT = 1_000;
+
+const MAX_PENDING_SESSION_EVENTS = 2_048;
+const MAX_UNMAPPED_SESSION_EVENT_TYPES = 128;
+const SESSION_EVENT_READ_MODES = new Set(Object.values(SESSION_EVENT_READ_MODE));
+const WRAPPED_CONTEXT_PATTERN = /^<([A-Za-z][\w:.-]*[_-][\w:.-]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>\s*/u;
+
+export function isInjectedSessionAsk(value) {
+  if (typeof value !== "string") return false;
+  let remaining = value.trim();
+  if (!remaining) return false;
+  if (/^#{1,6}\s+[^\n]*\binstructions?\b/iu.test(remaining)) return true;
+  let matched = false;
+
+  while (remaining) {
+    const match = WRAPPED_CONTEXT_PATTERN.exec(remaining);
+    if (!match) return false;
+    matched = true;
+    remaining = remaining.slice(match[0].length).trimStart();
+  }
+
+  return matched;
+}
+
+export function createSessionEventReadState({
+  limit = DEFAULT_SESSION_EVENT_LIMIT,
+  mode = SESSION_EVENT_READ_MODE.RECENT,
+} = {}) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_SESSION_EVENT_LIMIT) {
+    throw new TypeError(`limit must be between 1 and ${MAX_SESSION_EVENT_LIMIT}.`);
+  }
+
+  if (!SESSION_EVENT_READ_MODES.has(mode)) {
+    throw new TypeError(`Unsupported session event read mode: ${mode}`);
+  }
+
+  const events = new Array(limit);
+  const pending = new Map();
+  const pendingIds = new WeakMap();
+  let length = 0;
+  let start = 0;
+
+  function untrack(event) {
+    const pendingId = pendingIds.get(event);
+    if (pendingId && pending.get(pendingId) === event) pending.delete(pendingId);
+  }
+
+  return {
+    add(event, { pendingId = null } = {}) {
+      if (pendingId) {
+        pending.delete(pendingId);
+        pending.set(pendingId, event);
+        pendingIds.set(event, pendingId);
+
+        while (pending.size > MAX_PENDING_SESSION_EVENTS) {
+          pending.delete(pending.keys().next().value);
+        }
+      }
+
+      if (length < limit) {
+        events[(start + length) % limit] = event;
+        length += 1;
+      } else if (mode === SESSION_EVENT_READ_MODE.RECENT) {
+        untrack(events[start]);
+        events[start] = event;
+        start = (start + 1) % limit;
+      }
+
+      return mode === SESSION_EVENT_READ_MODE.PREVIEW && length === limit;
+    },
+    resolve(pendingId, update, { consume = true } = {}) {
+      const event = pending.get(pendingId);
+      if (!event) return false;
+      if (consume) pending.delete(pendingId);
+      update(event);
+      return true;
+    },
+    values() {
+      return Array.from({ length }, (_, index) => events[(start + index) % limit]);
+    },
+    window({ complete, stoppedEarly }) {
+      return {
+        complete,
+        end: stoppedEarly
+          ? SESSION_EVENT_WINDOW_END.OLDEST
+          : complete
+            ? SESSION_EVENT_WINDOW_END.NEWEST
+            : SESSION_EVENT_WINDOW_END.PARTIAL,
+        outcomesMayBeUnresolved: stoppedEarly || !complete,
+      };
+    },
+  };
+}
+
+export function createUnmappedSessionEventTracker() {
+  const counts = new Map();
+  let other = 0;
+
+  return {
+    add(type) {
+      const normalizedType = typeof type === "string" && type.trim()
+        ? type.trim()
+        : "unknown";
+      if (counts.has(normalizedType)) {
+        counts.set(normalizedType, counts.get(normalizedType) + 1);
+      } else if (counts.size < MAX_UNMAPPED_SESSION_EVENT_TYPES) {
+        counts.set(normalizedType, 1);
+      } else {
+        other += 1;
+      }
+    },
+    values(limit = 5) {
+      const entries = [...counts].map(([type, count]) => ({ count, type }));
+      if (other > 0) entries.push({ count: other, type: "other unmapped types" });
+      return entries
+        .sort((left, right) => right.count - left.count || left.type.localeCompare(right.type))
+        .slice(0, limit);
+    },
+  };
+}

package/lib/session-events.mjs

@@ -0,0 +1,307 @@
+export const SESSION_EVENT_KIND = Object.freeze({
+  ASK: "ask",
+  DECIDED: "decided",
+  EDIT: "edit",
+  PLAN: "plan",
+  RAN: "ran",
+  SAID: "said",
+  SUMMARY: "summary",
+});
+
+export const SESSION_EVENT_COVERAGE_THRESHOLD = 90;
+
+export const SESSION_EVENT_READ_MODE = Object.freeze({
+  PREVIEW: "preview",
+  RECENT: "recent",
+});
+
+export const SESSION_EVENT_REASON = Object.freeze({
+  NO_RECOGNIZED_EVENTS: "no-recognized-events",
+  NO_TRANSCRIPT_PATH: "no-transcript-path",
+  TRANSCRIPT_MISSING: "transcript-missing",
+});
+
+export const SESSION_EVENT_WINDOW_END = Object.freeze({
+  NEWEST: "newest",
+  OLDEST: "oldest",
+  PARTIAL: "partial",
+});
+
+const SESSION_EVENT_KINDS = new Set(Object.values(SESSION_EVENT_KIND));
+const SESSION_EVENT_REASONS = new Set(Object.values(SESSION_EVENT_REASON));
+const SESSION_EVENT_WINDOW_ENDS = new Set(Object.values(SESSION_EVENT_WINDOW_END));
+
+function nullableBoolean(value, field) {
+  if (value === null || typeof value === "boolean") return value;
+  throw new TypeError(`${field} must be a boolean or null.`);
+}
+
+function nullableCount(value, field) {
+  if (value === null || (Number.isInteger(value) && value >= 0)) return value;
+  throw new TypeError(`${field} must be a non-negative integer or null.`);
+}
+
+function nullableString(value, field) {
+  if (value === null || typeof value === "string") return value;
+  throw new TypeError(`${field} must be a string or null.`);
+}
+
+function requiredCount(value, field) {
+  if (Number.isInteger(value) && value >= 0) return value;
+  throw new TypeError(`${field} must be a non-negative integer.`);
+}
+
+function requiredBoolean(value, field) {
+  if (typeof value === "boolean") return value;
+  throw new TypeError(`${field} must be a boolean.`);
+}
+
+function requiredString(value, field) {
+  if (typeof value === "string") return value;
+  throw new TypeError(`${field} must be a string.`);
+}
+
+function unmappedTypeEntries(value) {
+  if (!Array.isArray(value)) {
+    throw new TypeError("coverage.unmappedTypes must be an array.");
+  }
+
+  return value.map((entry) => ({
+    count: requiredCount(entry?.count, "coverage.unmappedTypes.count"),
+    type: requiredString(entry?.type, "coverage.unmappedTypes.type"),
+  }));
+}
+
+function sessionEventBase({ atMs, kind, sequence }) {
+  if (!SESSION_EVENT_KINDS.has(kind)) {
+    throw new TypeError(`Unsupported session event kind: ${kind}`);
+  }
+
+  if (atMs !== null && !Number.isFinite(atMs)) {
+    throw new TypeError("atMs must be a finite number or null.");
+  }
+
+  return {
+    atMs,
+    kind,
+    sequence: requiredCount(sequence, "sequence"),
+  };
+}
+
+export function createSessionEvent({
+  added = null,
+  answer = null,
+  applied = null,
+  atMs = null,
+  command = null,
+  error = null,
+  failed = null,
+  files = [],
+  injected = false,
+  kind,
+  question = null,
+  removed = null,
+  sequence,
+  steps = [],
+  text = null,
+  unclassified = false,
+  unextracted = false,
+  workdir = null,
+} = {}) {
+  const base = sessionEventBase({ atMs, kind, sequence });
+
+  if (kind === SESSION_EVENT_KIND.ASK) {
+    return {
+      atMs: base.atMs,
+      injected: requiredBoolean(injected, "injected"),
+      kind: base.kind,
+      sequence: base.sequence,
+      text: requiredString(text, "text"),
+    };
+  }
+
+  if (kind === SESSION_EVENT_KIND.DECIDED) {
+    return {
+      answer: nullableString(answer, "answer"),
+      atMs: base.atMs,
+      kind: base.kind,
+      question: requiredString(question, "question"),
+      sequence: base.sequence,
+    };
+  }
+
+  if (kind === SESSION_EVENT_KIND.EDIT) {
+    if (!Array.isArray(files) || files.some((file) => typeof file !== "string")) {
+      throw new TypeError("files must be an array of strings.");
+    }
+
+    return {
+      added: nullableCount(added, "added"),
+      applied: nullableBoolean(applied, "applied"),
+      atMs: base.atMs,
+      files: [...files],
+      kind: base.kind,
+      removed: nullableCount(removed, "removed"),
+      sequence: base.sequence,
+    };
+  }
+
+  if (kind === SESSION_EVENT_KIND.PLAN) {
+    if (!Array.isArray(steps)) {
+      throw new TypeError("steps must be an array.");
+    }
+
+    return {
+      atMs: base.atMs,
+      kind: base.kind,
+      sequence: base.sequence,
+      steps: steps.map((step) => ({
+        status: requiredString(step?.status, "step.status"),
+        text: requiredString(step?.text, "step.text"),
+      })),
+    };
+  }
+
+  if (kind === SESSION_EVENT_KIND.RAN) {
+    return {
+      atMs: base.atMs,
+      command: nullableString(command, "command"),
+      error: nullableString(error, "error"),
+      failed: nullableBoolean(failed, "failed"),
+      kind: base.kind,
+      sequence: base.sequence,
+      unclassified: requiredBoolean(unclassified, "unclassified"),
+      unextracted: requiredBoolean(unextracted, "unextracted"),
+      workdir: nullableString(workdir, "workdir"),
+    };
+  }
+
+  return {
+    atMs: base.atMs,
+    kind: base.kind,
+    sequence: base.sequence,
+    text: requiredString(text, "text"),
+  };
+}
+
+export function createSessionEventCoverage({
+  duplicates = 0,
+  oversized = 0,
+  recognized = 0,
+  skipped = 0,
+  total = 0,
+  unmapped = 0,
+  unmappedTypes = [],
+  unparseable = 0,
+} = {}) {
+  return {
+    duplicates: requiredCount(duplicates, "coverage.duplicates"),
+    oversized: requiredCount(oversized, "coverage.oversized"),
+    recognized: requiredCount(recognized, "coverage.recognized"),
+    skipped: requiredCount(skipped, "coverage.skipped"),
+    total: requiredCount(total, "coverage.total"),
+    unmapped: requiredCount(unmapped, "coverage.unmapped"),
+    unmappedTypes: unmappedTypeEntries(unmappedTypes),
+    unparseable: requiredCount(unparseable, "coverage.unparseable"),
+  };
+}
+
+export function sessionEventCoveragePercent(coverage) {
+  const normalizedCoverage = createSessionEventCoverage(coverage);
+  const considered = normalizedCoverage.total - normalizedCoverage.skipped;
+  if (considered === 0) return 100;
+  return Math.round((normalizedCoverage.recognized / considered) * 100);
+}
+
+export function createSessionEventHeader({
+  cwd = null,
+  git = null,
+  model = null,
+  origin = null,
+  provider,
+  version = null,
+} = {}) {
+  let normalizedGit = null;
+
+  if (git !== null) {
+    if (typeof git !== "object" || Array.isArray(git)) {
+      throw new TypeError("git must be an object or null.");
+    }
+
+    normalizedGit = {
+      branch: nullableString(git.branch ?? null, "git.branch"),
+      commit: nullableString(git.commit ?? null, "git.commit"),
+      repository: nullableString(git.repository ?? null, "git.repository"),
+    };
+  }
+
+  return {
+    cwd: nullableString(cwd, "cwd"),
+    git: normalizedGit,
+    model: nullableString(model, "model"),
+    origin: nullableString(origin, "origin"),
+    provider: requiredString(provider, "provider"),
+    version: nullableString(version, "version"),
+  };
+}
+
+export function createSessionEventsResult({
+  coverage,
+  events = [],
+  header,
+  reason = null,
+  window = {},
+} = {}) {
+  const normalizedCoverage = createSessionEventCoverage(coverage);
+
+  if (
+    normalizedCoverage.recognized
+      + normalizedCoverage.skipped
+      + normalizedCoverage.unmapped
+      + normalizedCoverage.unparseable
+      + normalizedCoverage.oversized
+    !== normalizedCoverage.total
+  ) {
+    throw new TypeError("Session event coverage counts must add up to the total.");
+  }
+
+  if (!Array.isArray(events)) {
+    throw new TypeError("events must be an array.");
+  }
+
+  if (reason !== null && !SESSION_EVENT_REASONS.has(reason)) {
+    throw new TypeError(`Unsupported session event reason: ${reason}`);
+  }
+
+  if (reason !== null && events.length > 0) {
+    throw new TypeError("A session event reason requires an empty event list.");
+  }
+
+  const complete = window.complete ?? true;
+  const end = window.end ?? SESSION_EVENT_WINDOW_END.NEWEST;
+  const outcomesMayBeUnresolved = window.outcomesMayBeUnresolved ?? false;
+
+  if (typeof complete !== "boolean") {
+    throw new TypeError("window.complete must be a boolean.");
+  }
+
+  if (end !== null && !SESSION_EVENT_WINDOW_ENDS.has(end)) {
+    throw new TypeError(`Unsupported session event window end: ${end}`);
+  }
+
+  if (typeof outcomesMayBeUnresolved !== "boolean") {
+    throw new TypeError("window.outcomesMayBeUnresolved must be a boolean.");
+  }
+
+  return {
+    coverage: normalizedCoverage,
+    events: [...events],
+    header: createSessionEventHeader(header),
+    reason,
+    window: {
+      complete,
+      end,
+      outcomesMayBeUnresolved,
+    },
+  };
+}

package/lib/storage/jsonl.mjs

@@ -4,6 +4,11 @@ import { promises as fs } from "node:fs";
 import readline from "node:readline";
 import { finished } from "node:stream/promises";
 
+export const DEFAULT_JSONL_MAX_LINE_BYTES = 8 * 1024 * 1024;
+
+const JSONL_READ_CHUNK_BYTES = 64 * 1024;
+const JSONL_STARTING_LINE_BYTES = 4 * 1024;
+
 function parseLine(raw, index) {
   try {
     return { index, parsed: JSON.parse(raw), raw };
@@ -35,6 +40,149 @@ export async function* readJsonlEntries(filePath) {
   }
 }
 
+function appendLineBytes(state, bytes, maxLineBytes) {
+  if (state.oversized || bytes.length === 0) return;
+
+  if (state.length + bytes.length > maxLineBytes) {
+    state.length = 0;
+    state.oversized = true;
+    return;
+  }
+
+  const requiredBytes = state.length + bytes.length;
+  if (state.buffer.length < requiredBytes) {
+    const capacity = Math.min(
+      maxLineBytes,
+      Math.max(requiredBytes, state.buffer.length * 2),
+    );
+    const buffer = Buffer.allocUnsafe(capacity);
+    state.buffer.copy(buffer, 0, 0, state.length);
+    state.buffer = buffer;
+  }
+
+  bytes.copy(state.buffer, state.length);
+  state.length += bytes.length;
+}
+
+function createLineState(maxLineBytes) {
+  return {
+    buffer: Buffer.allocUnsafe(Math.min(JSONL_STARTING_LINE_BYTES, maxLineBytes)),
+    length: 0,
+    oversized: false,
+  };
+}
+
+function resetLineState(state) {
+  state.length = 0;
+  state.oversized = false;
+}
+
+function snapshotEntry(state, index) {
+  if (state.oversized) {
+    return {
+      index,
+      oversized: true,
+      parsed: null,
+      raw: null,
+    };
+  }
+
+  let bytes = state.buffer.subarray(0, state.length);
+  if (bytes.at(-1) === 13) bytes = bytes.subarray(0, -1);
+  if (bytes.length === 0) return null;
+
+  const entry = parseLine(bytes.toString("utf8"), index);
+  return {
+    index: entry.index,
+    oversized: false,
+    parsed: entry.parsed,
+    raw: entry.raw,
+  };
+}
+
+export async function visitJsonlSnapshotEntries(
+  filePath,
+  visit,
+  { maxLineBytes = DEFAULT_JSONL_MAX_LINE_BYTES } = {},
+) {
+  if (!Number.isSafeInteger(maxLineBytes) || maxLineBytes < 1) {
+    throw new TypeError("maxLineBytes must be a positive integer.");
+  }
+
+  const handle = await fs.open(filePath, "r");
+
+  try {
+    const { size: snapshotBytes } = await handle.stat();
+    let complete = true;
+    let index = 0;
+    let offset = 0;
+    const buffer = Buffer.allocUnsafe(Math.min(JSONL_READ_CHUNK_BYTES, Math.max(1, snapshotBytes)));
+    const state = createLineState(maxLineBytes);
+    let stoppedEarly = false;
+
+    async function flushLine() {
+      const entry = snapshotEntry(state, index);
+      resetLineState(state);
+      if (!entry) return true;
+      index += 1;
+      return (await visit(entry)) !== false;
+    }
+
+    while (offset < snapshotBytes) {
+      const requestedBytes = Math.min(JSONL_READ_CHUNK_BYTES, snapshotBytes - offset);
+      let bytesRead;
+
+      try {
+        ({ bytesRead } = await handle.read(buffer, 0, requestedBytes, offset));
+      } catch (error) {
+        if (error?.code === "ENOENT") {
+          complete = false;
+          break;
+        }
+
+        throw error;
+      }
+
+      if (bytesRead === 0) {
+        complete = false;
+        break;
+      }
+
+      offset += bytesRead;
+      let start = 0;
+
+      while (start < bytesRead) {
+        const newline = buffer.indexOf(10, start);
+        const end = newline === -1 || newline >= bytesRead ? bytesRead : newline;
+        appendLineBytes(state, buffer.subarray(start, end), maxLineBytes);
+
+        if (newline === -1 || newline >= bytesRead) break;
+
+        if (!(await flushLine())) {
+          stoppedEarly = true;
+          break;
+        }
+
+        start = newline + 1;
+      }
+
+      if (stoppedEarly) break;
+    }
+
+    if (!stoppedEarly && (state.oversized || state.length > 0)) {
+      if (!(await flushLine())) stoppedEarly = true;
+    }
+
+    return {
+      complete: complete && !stoppedEarly,
+      snapshotBytes,
+      stoppedEarly,
+    };
+  } finally {
+    await handle.close();
+  }
+}
+
 export async function inspectJsonlMatches(filePath, matches, { sampleLimit = 100 } = {}) {
   let count = 0;
   const samples = [];