sentinelayer-cli 0.4.5 → 0.8.0

package/src/session/store.js

@@ -0,0 +1,388 @@
+import { randomUUID } from "node:crypto";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { collectCodebaseIngest } from "../ingest/engine.js";
+import { resolveSessionPaths, resolveSessionsRoot } from "./paths.js";
+import { appendToStream } from "./stream.js";
+
+const SESSION_SCHEMA_VERSION = "1.0.0";
+const DEFAULT_TTL_SECONDS = 24 * 60 * 60;
+const RENEWAL_SECONDS = 24 * 60 * 60;
+const MAX_SESSION_LIFETIME_SECONDS = 72 * 60 * 60;
+const SESSION_STATUS_ACTIVE = "active";
+const SESSION_STATUS_EXPIRED = "expired";
+const SESSION_STATUS_ARCHIVED = "archived";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizePositiveInteger(value, fallbackValue) {
+  if (value === undefined || value === null || normalizeString(value) === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    throw new Error("Value must be a positive integer.");
+  }
+  return Math.floor(normalized);
+}
+
+function normalizeIsoTimestamp(value, fallbackIso = new Date().toISOString()) {
+  const normalized = normalizeString(value);
+  if (!normalized) {
+    return fallbackIso;
+  }
+  const epoch = Date.parse(normalized);
+  if (!Number.isFinite(epoch)) {
+    return fallbackIso;
+  }
+  return new Date(epoch).toISOString();
+}
+
+function toIsoAfterSeconds(nowIso, seconds) {
+  const nowEpoch = Date.parse(normalizeIsoTimestamp(nowIso));
+  return new Date(nowEpoch + seconds * 1000).toISOString();
+}
+
+function buildElapsedTimer(fromIso, nowIso = new Date().toISOString()) {
+  const fromEpoch = Date.parse(normalizeIsoTimestamp(fromIso, nowIso));
+  const nowEpoch = Date.parse(normalizeIsoTimestamp(nowIso, new Date().toISOString()));
+  if (!Number.isFinite(fromEpoch) || !Number.isFinite(nowEpoch) || nowEpoch <= fromEpoch) {
+    return "0m";
+  }
+  const totalSeconds = Math.floor((nowEpoch - fromEpoch) / 1000);
+  const totalMinutes = Math.floor(totalSeconds / 60);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours <= 0) {
+    return `${Math.max(0, minutes)}m`;
+  }
+  return `${hours}h ${minutes}m`;
+}
+
+async function readJsonFile(filePath, { allowMissing = true } = {}) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch (error) {
+    if (
+      allowMissing &&
+      error &&
+      typeof error === "object" &&
+      error.code === "ENOENT"
+    ) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function writeJsonFile(filePath, payload) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await fsp.writeFile(tmpPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+  await fsp.rename(tmpPath, filePath);
+}
+
+function normalizeCodebaseContext(ingest = {}) {
+  return {
+    summary:
+      ingest && typeof ingest.summary === "object" && ingest.summary
+        ? {
+            filesScanned: Number(ingest.summary.filesScanned || 0),
+            directoriesScanned: Number(ingest.summary.directoriesScanned || 0),
+            totalLoc: Number(ingest.summary.totalLoc || 0),
+            totalBytes: Number(ingest.summary.totalBytes || 0),
+          }
+        : {
+            filesScanned: 0,
+            directoriesScanned: 0,
+            totalLoc: 0,
+            totalBytes: 0,
+          },
+    frameworks: Array.isArray(ingest.frameworks) ? [...ingest.frameworks] : [],
+    entryPoints: Array.isArray(ingest.entryPoints) ? [...ingest.entryPoints] : [],
+    riskSurfaces: Array.isArray(ingest.riskSurfaces) ? [...ingest.riskSurfaces] : [],
+  };
+}
+
+async function collectSessionCodebaseContext(targetPath) {
+  const cachedIngestPath = path.join(targetPath, ".sentinelayer", "CODEBASE_INGEST.json");
+  const cachedIngest = await readJsonFile(cachedIngestPath, { allowMissing: true });
+  if (cachedIngest && typeof cachedIngest === "object") {
+    return normalizeCodebaseContext(cachedIngest);
+  }
+  const ingest = await collectCodebaseIngest({ rootPath: targetPath });
+  return normalizeCodebaseContext(ingest);
+}
+
+function normalizeSessionStatus(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (normalized === SESSION_STATUS_EXPIRED) return SESSION_STATUS_EXPIRED;
+  if (normalized === SESSION_STATUS_ARCHIVED) return SESSION_STATUS_ARCHIVED;
+  return SESSION_STATUS_ACTIVE;
+}
+
+function normalizeMetadata(raw = {}, { sessionId, targetPath, nowIso } = {}) {
+  const createdAt = normalizeIsoTimestamp(raw.createdAt, nowIso);
+  const ttlSeconds = normalizePositiveInteger(raw.ttlSeconds, DEFAULT_TTL_SECONDS);
+  const expiresAt = normalizeIsoTimestamp(raw.expiresAt, toIsoAfterSeconds(createdAt, ttlSeconds));
+  return {
+    schemaVersion: SESSION_SCHEMA_VERSION,
+    sessionId: normalizeString(raw.sessionId) || sessionId,
+    targetPath: path.resolve(normalizeString(raw.targetPath) || targetPath),
+    createdAt,
+    updatedAt: normalizeIsoTimestamp(raw.updatedAt, nowIso),
+    expiresAt,
+    ttlSeconds,
+    renewalCount: Math.max(0, Number(raw.renewalCount || 0)),
+    maxLifetimeSeconds: normalizePositiveInteger(raw.maxLifetimeSeconds, MAX_SESSION_LIFETIME_SECONDS),
+    status: normalizeSessionStatus(raw.status),
+    lastInteractionAt: normalizeIsoTimestamp(raw.lastInteractionAt, createdAt),
+    expiredAt: raw.expiredAt ? normalizeIsoTimestamp(raw.expiredAt, nowIso) : null,
+    archivedAt: raw.archivedAt ? normalizeIsoTimestamp(raw.archivedAt, nowIso) : null,
+    s3Path: normalizeString(raw.s3Path) || null,
+    archiveStatus: normalizeString(raw.archiveStatus) || "pending",
+    codebaseContext: normalizeCodebaseContext(raw.codebaseContext || {}),
+  };
+}
+
+function isExpired(metadata, nowIso = new Date().toISOString()) {
+  if (!metadata || normalizeSessionStatus(metadata.status) === SESSION_STATUS_EXPIRED) {
+    return true;
+  }
+  const expiryEpoch = Date.parse(normalizeIsoTimestamp(metadata.expiresAt, nowIso));
+  const nowEpoch = Date.parse(normalizeIsoTimestamp(nowIso, new Date().toISOString()));
+  if (!Number.isFinite(expiryEpoch) || !Number.isFinite(nowEpoch)) {
+    return false;
+  }
+  return nowEpoch >= expiryEpoch;
+}
+
+function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString()) {
+  return {
+    sessionId: metadata.sessionId,
+    sessionDir: paths.sessionDir,
+    metadataPath: paths.metadataPath,
+    streamPath: paths.streamPath,
+    createdAt: metadata.createdAt,
+    expiresAt: metadata.expiresAt,
+    elapsedTimer: buildElapsedTimer(metadata.createdAt, nowIso),
+    renewalCount: metadata.renewalCount,
+    status: metadata.status,
+    archivedAt: metadata.archivedAt,
+    s3Path: metadata.s3Path,
+    codebaseContext: metadata.codebaseContext,
+  };
+}
+
+async function loadMetadata(sessionId, { targetPath = process.cwd() } = {}) {
+  const resolvedTargetPath = path.resolve(String(targetPath || "."));
+  const paths = resolveSessionPaths(sessionId, { targetPath: resolvedTargetPath });
+  const nowIso = new Date().toISOString();
+  const raw = await readJsonFile(paths.metadataPath, { allowMissing: true });
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const metadata = normalizeMetadata(raw, {
+    sessionId: paths.sessionId,
+    targetPath: resolvedTargetPath,
+    nowIso,
+  });
+  return { metadata, paths, targetPath: resolvedTargetPath };
+}
+
+async function saveMetadata(metadata, paths) {
+  const normalized = normalizeMetadata(metadata, {
+    sessionId: paths.sessionId,
+    targetPath: metadata.targetPath,
+    nowIso: new Date().toISOString(),
+  });
+  await writeJsonFile(paths.metadataPath, normalized);
+  return normalized;
+}
+
+export async function createSession({
+  targetPath = process.cwd(),
+  ttlSeconds = DEFAULT_TTL_SECONDS,
+} = {}) {
+  const resolvedTargetPath = path.resolve(String(targetPath || "."));
+  const normalizedTtlSeconds = normalizePositiveInteger(ttlSeconds, DEFAULT_TTL_SECONDS);
+  const sessionId = randomUUID();
+  const nowIso = new Date().toISOString();
+  const paths = resolveSessionPaths(sessionId, { targetPath: resolvedTargetPath });
+  const codebaseContext = await collectSessionCodebaseContext(resolvedTargetPath);
+
+  const metadata = normalizeMetadata(
+    {
+      schemaVersion: SESSION_SCHEMA_VERSION,
+      sessionId,
+      targetPath: resolvedTargetPath,
+      createdAt: nowIso,
+      updatedAt: nowIso,
+      expiresAt: toIsoAfterSeconds(nowIso, normalizedTtlSeconds),
+      ttlSeconds: normalizedTtlSeconds,
+      renewalCount: 0,
+      maxLifetimeSeconds: MAX_SESSION_LIFETIME_SECONDS,
+      status: SESSION_STATUS_ACTIVE,
+      lastInteractionAt: nowIso,
+      expiredAt: null,
+      archivedAt: null,
+      s3Path: null,
+      archiveStatus: "pending",
+      codebaseContext,
+    },
+    {
+      sessionId,
+      targetPath: resolvedTargetPath,
+      nowIso,
+    }
+  );
+
+  await fsp.mkdir(paths.agentsDir, { recursive: true });
+  await saveMetadata(metadata, paths);
+  await fsp.writeFile(paths.streamPath, "", { encoding: "utf-8", flag: "a" });
+
+  return buildSessionPayload(metadata, paths, nowIso);
+}
+
+export async function getSession(sessionId, { targetPath = process.cwd() } = {}) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    return null;
+  }
+  return buildSessionPayload(loaded.metadata, loaded.paths);
+}
+
+export async function listActiveSessions({ targetPath = process.cwd() } = {}) {
+  const resolvedTargetPath = path.resolve(String(targetPath || "."));
+  const sessionsRoot = resolveSessionsRoot({ targetPath: resolvedTargetPath });
+  let entries = [];
+  try {
+    entries = await fsp.readdir(sessionsRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  const sessions = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const loaded = await loadMetadata(entry.name, { targetPath: resolvedTargetPath });
+    if (!loaded) continue;
+    if (isExpired(loaded.metadata)) continue;
+    if (loaded.metadata.status === SESSION_STATUS_ARCHIVED) continue;
+    sessions.push(buildSessionPayload(loaded.metadata, loaded.paths));
+  }
+
+  sessions.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  return sessions;
+}
+
+export async function renewSession(sessionId, { targetPath = process.cwd() } = {}) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    throw new Error(`Session '${sessionId}' was not found.`);
+  }
+
+  const nowIso = new Date().toISOString();
+  const createdEpoch = Date.parse(normalizeIsoTimestamp(loaded.metadata.createdAt, nowIso));
+  const expiresEpoch = Date.parse(normalizeIsoTimestamp(loaded.metadata.expiresAt, nowIso));
+  if (!Number.isFinite(createdEpoch) || !Number.isFinite(expiresEpoch)) {
+    throw new Error(`Session '${sessionId}' has invalid timestamps.`);
+  }
+
+  const maxExpiryEpoch = createdEpoch + loaded.metadata.maxLifetimeSeconds * 1000;
+  const nextExpiryEpoch = Math.min(expiresEpoch + RENEWAL_SECONDS * 1000, maxExpiryEpoch);
+  if (nextExpiryEpoch <= expiresEpoch) {
+    return buildSessionPayload(loaded.metadata, loaded.paths, nowIso);
+  }
+
+  loaded.metadata.expiresAt = new Date(nextExpiryEpoch).toISOString();
+  loaded.metadata.renewalCount = Math.max(0, Number(loaded.metadata.renewalCount || 0)) + 1;
+  loaded.metadata.updatedAt = nowIso;
+  loaded.metadata.lastInteractionAt = nowIso;
+  loaded.metadata.status = SESSION_STATUS_ACTIVE;
+  loaded.metadata.expiredAt = null;
+
+  const saved = await saveMetadata(loaded.metadata, loaded.paths);
+
+  try {
+    await appendToStream(
+      loaded.paths.sessionId,
+      {
+        event: "daemon_alert",
+        agentId: "senti",
+        payload: {
+          alert: "session_renewed",
+          expiresAt: saved.expiresAt,
+          renewalCount: saved.renewalCount,
+        },
+        ts: nowIso,
+      },
+      { targetPath: loaded.targetPath }
+    );
+  } catch {
+    // Renewal should not fail if stream event persistence is unavailable.
+  }
+
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
+export async function expireSession(sessionId, { targetPath = process.cwd() } = {}) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    throw new Error(`Session '${sessionId}' was not found.`);
+  }
+  const nowIso = new Date().toISOString();
+  loaded.metadata.status = SESSION_STATUS_EXPIRED;
+  loaded.metadata.expiredAt = nowIso;
+  loaded.metadata.updatedAt = nowIso;
+  const saved = await saveMetadata(loaded.metadata, loaded.paths);
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
+export async function archiveSession(
+  sessionId,
+  { s3Bucket, s3Prefix = "", targetPath = process.cwd() } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    throw new Error(`Session '${sessionId}' was not found.`);
+  }
+  const normalizedBucket = normalizeString(s3Bucket);
+  if (!normalizedBucket) {
+    throw new Error("archiveSession requires s3Bucket.");
+  }
+  const normalizedPrefix = normalizeString(s3Prefix).replace(/^\/+|\/+$/g, "");
+  const prefixSegment = normalizedPrefix ? `${normalizedPrefix}/` : "";
+  const s3Path = `s3://${normalizedBucket}/${prefixSegment}sessions/${loaded.paths.sessionId}/`;
+  const nowIso = new Date().toISOString();
+
+  loaded.metadata.status = SESSION_STATUS_ARCHIVED;
+  loaded.metadata.archivedAt = nowIso;
+  loaded.metadata.updatedAt = nowIso;
+  loaded.metadata.archiveStatus = "archived";
+  loaded.metadata.s3Path = s3Path;
+  const saved = await saveMetadata(loaded.metadata, loaded.paths);
+
+  await writeJsonFile(path.join(loaded.paths.sessionDir, "archive-manifest.json"), {
+    sessionId: loaded.paths.sessionId,
+    archivedAt: nowIso,
+    s3Path,
+    files: ["metadata.json", "stream.ndjson", "stream.1.ndjson", "agents/"],
+  });
+
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
+export {
+  DEFAULT_TTL_SECONDS,
+  MAX_SESSION_LIFETIME_SECONDS,
+  RENEWAL_SECONDS,
+};

package/src/session/stream.js

@@ -0,0 +1,325 @@
+import fsp from "node:fs/promises";
+import process from "node:process";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { createAgentEvent, normalizeAgentEvent } from "../events/schema.js";
+import { resolveSessionPaths } from "./paths.js";
+
+const DEFAULT_POLL_MS = 500;
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+const DEFAULT_LOCK_STALE_MS = 30_000;
+const DEFAULT_LOCK_POLL_MS = 25;
+const DEFAULT_MAX_STREAM_EVENTS = 10_000;
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeIsoTimestamp(value, fallbackIso = new Date().toISOString()) {
+  const normalized = normalizeString(value);
+  if (!normalized) {
+    return fallbackIso;
+  }
+  const epoch = Date.parse(normalized);
+  if (!Number.isFinite(epoch)) {
+    return fallbackIso;
+  }
+  return new Date(epoch).toISOString();
+}
+
+function normalizePositiveInteger(value, fallbackValue) {
+  if (value === undefined || value === null || normalizeString(value) === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    throw new Error("Value must be a positive integer.");
+  }
+  return Math.floor(normalized);
+}
+
+async function readSessionMetadata(paths) {
+  try {
+    const raw = await fsp.readFile(paths.metadataPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function writeSessionMetadata(paths, metadata = {}) {
+  await fsp.mkdir(paths.sessionDir, { recursive: true });
+  const tmpPath = `${paths.metadataPath}.${process.pid}.${Date.now()}.tmp`;
+  await fsp.writeFile(tmpPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
+  await fsp.rename(tmpPath, paths.metadataPath);
+}
+
+function isSessionExpired(metadata = {}, nowIso = new Date().toISOString()) {
+  const status = normalizeString(metadata.status).toLowerCase();
+  if (status === "expired" || status === "archived") {
+    return true;
+  }
+  const nowEpoch = Date.parse(normalizeIsoTimestamp(nowIso, new Date().toISOString()));
+  const expiryEpoch = Date.parse(normalizeIsoTimestamp(metadata.expiresAt, nowIso));
+  if (!Number.isFinite(nowEpoch) || !Number.isFinite(expiryEpoch)) {
+    return false;
+  }
+  return nowEpoch >= expiryEpoch;
+}
+
+function materializeCanonicalEvent(sessionId, event = {}) {
+  const strictNormalized = normalizeAgentEvent(event, { allowLegacy: false });
+  if (strictNormalized) {
+    if (strictNormalized.sessionId) {
+      return strictNormalized;
+    }
+    return createAgentEvent({
+      ...strictNormalized,
+      sessionId,
+    });
+  }
+
+  if (!event || typeof event !== "object" || Array.isArray(event)) {
+    throw new Error("appendToStream requires a valid event payload.");
+  }
+
+  const payload = {
+    ...event,
+    sessionId: normalizeString(event.sessionId) || sessionId,
+  };
+  return createAgentEvent(payload);
+}
+
+async function acquireLock(lockPath, {
+  timeoutMs = DEFAULT_LOCK_TIMEOUT_MS,
+  staleMs = DEFAULT_LOCK_STALE_MS,
+  pollMs = DEFAULT_LOCK_POLL_MS,
+} = {}) {
+  const start = Date.now();
+  while (true) {
+    try {
+      await fsp.mkdir(lockPath);
+      return;
+    } catch (error) {
+      const code = error && typeof error === "object" ? error.code : "";
+      // Windows can raise EPERM/EACCES during lock contention when another writer
+      // is creating/removing the lock directory at the same time.
+      if (!(code === "EEXIST" || code === "EPERM" || code === "EACCES")) {
+        throw error;
+      }
+
+      try {
+        const stat = await fsp.stat(lockPath);
+        const ageMs = Date.now() - Number(stat.mtimeMs || 0);
+        if (Number.isFinite(ageMs) && ageMs > staleMs) {
+          await fsp.rm(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        // If stat/remove fails, continue waiting.
+      }
+
+      if (Date.now() - start >= timeoutMs) {
+        throw new Error("Timed out waiting for session stream lock.");
+      }
+      await sleep(pollMs);
+    }
+  }
+}
+
+async function releaseLock(lockPath) {
+  await fsp.rm(lockPath, { recursive: true, force: true }).catch(() => {});
+}
+
+async function readEventsFromFile(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    if (!raw) {
+      return [];
+    }
+    const events = [];
+    for (const line of raw.split(/\r?\n/)) {
+      if (!line.trim()) {
+        continue;
+      }
+      try {
+        const parsed = JSON.parse(line);
+        const normalized = normalizeAgentEvent(parsed, { allowLegacy: false });
+        if (normalized) {
+          events.push(normalized);
+        }
+      } catch {
+        // Ignore malformed historical lines.
+      }
+    }
+    return events;
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+
+async function readAllEvents(paths) {
+  const [rotated, current] = await Promise.all([
+    readEventsFromFile(paths.rotatedStreamPath),
+    readEventsFromFile(paths.streamPath),
+  ]);
+  return [...rotated, ...current];
+}
+
+async function rotateStreamIfNeeded(paths, maxEvents) {
+  const raw = await fsp.readFile(paths.streamPath, "utf-8").catch((error) => {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  });
+  const lines = raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (lines.length <= maxEvents) {
+    return;
+  }
+
+  const overflowCount = lines.length - maxEvents;
+  const overflowLines = lines.slice(0, overflowCount);
+  const retainedLines = lines.slice(overflowCount);
+
+  await fsp.mkdir(paths.sessionDir, { recursive: true });
+  if (overflowLines.length > 0) {
+    await fsp.appendFile(paths.rotatedStreamPath, `${overflowLines.join("\n")}\n`, "utf-8");
+  }
+  const retainedPayload = retainedLines.length > 0 ? `${retainedLines.join("\n")}\n` : "";
+  await fsp.writeFile(paths.streamPath, retainedPayload, "utf-8");
+}
+
+function filterBySince(events = [], since) {
+  const normalizedSince = normalizeString(since);
+  if (!normalizedSince) {
+    return events;
+  }
+  const sinceEpoch = Date.parse(normalizedSince);
+  if (!Number.isFinite(sinceEpoch)) {
+    return events;
+  }
+  return events.filter((event) => {
+    const eventEpoch = Date.parse(normalizeIsoTimestamp(event.ts, "1970-01-01T00:00:00.000Z"));
+    return Number.isFinite(eventEpoch) && eventEpoch >= sinceEpoch;
+  });
+}
+
+export async function appendToStream(
+  sessionId,
+  event,
+  { targetPath = process.cwd(), maxEvents = DEFAULT_MAX_STREAM_EVENTS } = {}
+) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  const metadata = await readSessionMetadata(paths);
+  if (!metadata) {
+    throw new Error(`Session '${paths.sessionId}' was not found.`);
+  }
+  if (isSessionExpired(metadata)) {
+    throw new Error(`Session '${paths.sessionId}' is expired and does not accept new events.`);
+  }
+
+  const canonicalEvent = materializeCanonicalEvent(paths.sessionId, event);
+  const nowIso = new Date().toISOString();
+  const normalizedMaxEvents = normalizePositiveInteger(maxEvents, DEFAULT_MAX_STREAM_EVENTS);
+
+  await acquireLock(paths.lockPath);
+  try {
+    await fsp.mkdir(paths.sessionDir, { recursive: true });
+    await fsp.appendFile(paths.streamPath, `${JSON.stringify(canonicalEvent)}\n`, "utf-8");
+    await rotateStreamIfNeeded(paths, normalizedMaxEvents);
+
+    metadata.lastInteractionAt = nowIso;
+    metadata.updatedAt = nowIso;
+    await writeSessionMetadata(paths, metadata);
+  } finally {
+    await releaseLock(paths.lockPath);
+  }
+
+  return canonicalEvent;
+}
+
+export async function readStream(
+  sessionId,
+  { tail = 20, since = null, targetPath = process.cwd() } = {}
+) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  const events = await readAllEvents(paths);
+  const filtered = filterBySince(events, since);
+  const normalizedTail = Number(tail);
+  if (!Number.isFinite(normalizedTail) || normalizedTail <= 0) {
+    return filtered;
+  }
+  return filtered.slice(-Math.floor(normalizedTail));
+}
+
+export async function* tailStream(
+  sessionId,
+  {
+    onEvent = null,
+    signal = null,
+    pollMs = DEFAULT_POLL_MS,
+    targetPath = process.cwd(),
+    since = null,
+    replayTail = 0,
+  } = {}
+) {
+  const normalizedPollMs = normalizePositiveInteger(pollMs, DEFAULT_POLL_MS);
+  let allEvents = await readStream(sessionId, { tail: 0, since, targetPath });
+  let cursor = allEvents.length;
+
+  const replayCount = Math.max(0, Math.floor(Number(replayTail) || 0));
+  if (replayCount > 0) {
+    const replayEvents = allEvents.slice(-replayCount);
+    for (const event of replayEvents) {
+      if (typeof onEvent === "function") {
+        await onEvent(event);
+      }
+      yield event;
+    }
+  }
+
+  while (true) {
+    if (signal && signal.aborted) {
+      return;
+    }
+
+    allEvents = await readStream(sessionId, { tail: 0, since, targetPath });
+    if (allEvents.length < cursor) {
+      cursor = 0;
+    }
+    if (allEvents.length > cursor) {
+      for (const event of allEvents.slice(cursor)) {
+        if (typeof onEvent === "function") {
+          await onEvent(event);
+        }
+        yield event;
+      }
+      cursor = allEvents.length;
+    }
+
+    try {
+      await sleep(normalizedPollMs, null, signal ? { signal } : undefined);
+    } catch (error) {
+      if (error && typeof error === "object" && error.name === "AbortError") {
+        return;
+      }
+      throw error;
+    }
+  }
+}
+
+export { DEFAULT_MAX_STREAM_EVENTS };