@cueloop/daemon 0.1.0-alpha.6 → 0.1.0-alpha.61

package/src/herdr-tab-store.ts

@@ -0,0 +1,69 @@
+/**
+ * herdr adapter scratch, kept out of the core session record: the tab cueloop
+ * opened to render each review, keyed by session id. One JSON map, atomic write.
+ * The core `ReviewSession` never mentions herdr; this side-store is the whole
+ * leak boundary.
+ */
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { herdrTabsPath } from "./paths";
+
+/** The tab and its root pane: pane id checks liveness, tab id focuses it. */
+export interface HerdrTabHandle {
+  tabId: string;
+  paneId: string;
+}
+
+/** Guard a persisted entry - both ids must be present strings, or it is dropped. */
+function isHerdrTabHandle(value: unknown): value is HerdrTabHandle {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as HerdrTabHandle).tabId === "string" &&
+    typeof (value as HerdrTabHandle).paneId === "string"
+  );
+}
+
+export class HerdrTabStore {
+  private tabs = new Map<string, HerdrTabHandle>();
+  private readonly path: string;
+
+  constructor(home: string) {
+    this.path = herdrTabsPath(home);
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(this.path, "utf8"));
+
+      if (typeof parsed !== "object" || parsed === null) return;
+      for (const [sessionId, value] of Object.entries(parsed)) {
+        if (isHerdrTabHandle(value))
+          this.tabs.set(sessionId, { tabId: value.tabId, paneId: value.paneId });
+      }
+    } catch {
+      // absent, unreadable, or malformed: start empty - a stale tab just reopens on resubmit
+    }
+  }
+
+  private persist(): void {
+    const tempPath = this.path + ".tmp";
+
+    writeFileSync(tempPath, JSON.stringify(Object.fromEntries(this.tabs), null, 2));
+    renameSync(tempPath, this.path);
+  }
+
+  get(sessionId: string): HerdrTabHandle | null {
+    return this.tabs.get(sessionId) ?? null;
+  }
+
+  set(sessionId: string, handle: HerdrTabHandle): void {
+    this.tabs.set(sessionId, handle);
+    this.persist();
+  }
+
+  delete(sessionId: string): void {
+    if (this.tabs.delete(sessionId)) this.persist();
+  }
+}

package/src/index.ts

@@ -1,8 +1,8 @@
-export * from "./api";
-export * from "./errors";
-export * from "./validate";
-export * from "./store";
-export * from "./server";
-export * from "./protocol";
-export * from "./paths";
-export { DaemonClient, DaemonClientError, type ConnectOptions } from "./client";
+/**
+ * The daemon's public surface. Consumers reach the client and the review
+ * helpers through the ./client and ./review subpaths; this barrel carries
+ * only the two names imported bare: the server and the home-dir resolver.
+ */
+
+export { DaemonServer, type DaemonOptions } from "./server";
+export { cueloopHome } from "./paths";

package/src/main.ts

@@ -2,9 +2,12 @@
 
 import { DaemonServer } from "./server";
 
-const idleExitMs = process.env.CUELOOP_IDLE_EXIT_MS ? Number(process.env.CUELOOP_IDLE_EXIT_MS) : undefined;
+const idleExitMs = process.env.CUELOOP_IDLE_EXIT_MS
+  ? Number(process.env.CUELOOP_IDLE_EXIT_MS)
+  : undefined;
 const server = new DaemonServer({ idleExitMs });
 const path = server.start();
+
 if (path === null) {
   // another daemon already owns this home; the client will attach to it
   console.log("cueloop daemon already running for this home");

package/src/paths.ts

@@ -18,6 +18,10 @@ export function sessionsDir(home = cueloopHome()): string {
   return join(home, "sessions");
 }
 
+export function reportsDir(home = cueloopHome()): string {
+  return join(home, "reports");
+}
+
 export function pidPath(home = cueloopHome()): string {
   return join(home, "cueloop.pid");
 }
@@ -25,3 +29,8 @@ export function pidPath(home = cueloopHome()): string {
 export function lockPath(home = cueloopHome()): string {
   return join(home, "cueloop.lock");
 }
+
+/** Adapter scratch: herdr tab handles keyed by session id, kept out of the core session record. */
+export function herdrTabsPath(home = cueloopHome()): string {
+  return join(home, "herdr-tabs.json");
+}

package/src/protocol.ts

@@ -1,5 +1,5 @@
 /**
- * Wire protocol (#14): newline-delimited JSON over the unix socket.
+ * Wire protocol: newline-delimited JSON over the unix socket.
  * Requests: { id, method, params }  Responses: { id, result } | { id, error }
  * Events (push, after events.subscribe): { event, sessionId }
  */
@@ -25,16 +25,60 @@ export type Frame = Response | EventFrame;
 
 /** Incremental NDJSON splitter; tolerates partial writes. */
 export class LineBuffer {
-  private buf = "";
+  private buffered = "";
 
   push(chunk: string, onLine: (line: string) => void): void {
-    this.buf += chunk;
+    this.buffered += chunk;
     for (;;) {
-      const nl = this.buf.indexOf("\n");
-      if (nl === -1) return;
-      const line = this.buf.slice(0, nl).trim();
-      this.buf = this.buf.slice(nl + 1);
+      const newlineIndex = this.buffered.indexOf("\n");
+
+      if (newlineIndex === -1) return;
+      const line = this.buffered.slice(0, newlineIndex).trim();
+
+      this.buffered = this.buffered.slice(newlineIndex + 1);
       if (line) onLine(line);
     }
   }
 }
+
+/** The surface both Bun.listen and Bun.connect sockets satisfy. */
+interface WritableSocket {
+  write(data: Buffer): number;
+}
+
+/**
+ * Outbound writes honoring socket backpressure. A frame larger than the
+ * kernel buffer is written partially by the socket; the unwritten tail must
+ * wait for the drain callback or the frame truncates mid-line and the NDJSON
+ * stream corrupts for good. Frames never reorder: while a tail is pending,
+ * new writes append behind it.
+ */
+export class BackpressureWriter {
+  private pending: Buffer | null = null;
+
+  constructor(private socket: WritableSocket) {}
+
+  write(data: string): void {
+    const bytes = Buffer.from(data, "utf8");
+
+    if (this.pending) {
+      this.pending = Buffer.concat([this.pending, bytes]);
+
+      return;
+    }
+    const written = Math.max(0, this.socket.write(bytes));
+
+    if (written < bytes.length) this.pending = bytes.subarray(written);
+  }
+
+  /** Call from the socket's drain handler. */
+  drain(): void {
+    if (!this.pending) return;
+    const tail = this.pending;
+
+    this.pending = null;
+    const written = Math.max(0, this.socket.write(tail));
+
+    if (written < tail.length) this.pending = tail.subarray(written);
+  }
+}

package/src/retention.test.ts

@@ -0,0 +1,182 @@
+/** Retention: the cleanup period defaults to 30, honors [cleanup] period_days, and prune drops only the sessions and reports past the window. */
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ReviewSession, SessionStatus } from "@cueloop/schema";
+import { SessionStore } from "./store";
+import { reportsDir } from "./paths";
+import {
+  DEFAULT_CLEANUP_PERIOD_DAYS,
+  LATEST_REPORT_FILENAME,
+  isExpired,
+  parseRefineState,
+  pruneExpiredReports,
+  pruneExpiredSessions,
+  resolveCleanupPeriodDays,
+} from "./retention";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const NOW_MS = Date.parse("2026-08-26T00:00:00Z");
+
+function tempDir(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), prefix));
+}
+
+function daysAgo(days: number): string {
+  return new Date(NOW_MS - days * DAY_MS).toISOString();
+}
+
+function session(id: string, createdAt: string, status: SessionStatus = "resolved"): ReviewSession {
+  return {
+    schemaVersion: "1",
+    id,
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "", meta: {} },
+    revisions: [],
+    annotations: [],
+    verdict: null,
+    status,
+    createdAt,
+  };
+}
+
+describe("resolveCleanupPeriodDays", () => {
+  test("defaults to 30 when no config file is present", () => {
+    // Arrange
+    const missing = join(tempDir("cueloop-retention-"), "config.toml");
+
+    // Act
+    const days = resolveCleanupPeriodDays({ CUELOOP_CONFIG: missing } as NodeJS.ProcessEnv);
+
+    // Assert
+    expect(days).toBe(DEFAULT_CLEANUP_PERIOD_DAYS);
+  });
+
+  test("honors [cleanup] period_days", () => {
+    // Arrange
+    const path = join(tempDir("cueloop-retention-"), "config.toml");
+
+    writeFileSync(path, "[cleanup]\nperiod_days = 7\n");
+
+    // Act
+    const days = resolveCleanupPeriodDays({ CUELOOP_CONFIG: path } as NodeJS.ProcessEnv);
+
+    // Assert
+    expect(days).toBe(7);
+  });
+
+  test("falls back to the default when the value is not a number", () => {
+    // Arrange
+    const path = join(tempDir("cueloop-retention-"), "config.toml");
+
+    writeFileSync(path, '[cleanup]\nperiod_days = "soon"\n');
+
+    // Act
+    const days = resolveCleanupPeriodDays({ CUELOOP_CONFIG: path } as NodeJS.ProcessEnv);
+
+    // Assert
+    expect(days).toBe(DEFAULT_CLEANUP_PERIOD_DAYS);
+  });
+});
+
+describe("parseRefineState", () => {
+  test("reads the analyzed fingerprint map", () => {
+    // Assert
+    expect([...parseRefineState({ analyzed: { ses_a: "1:2:x" } })]).toEqual([["ses_a", "1:2:x"]]);
+  });
+
+  test("returns an empty map for the legacy or malformed shape", () => {
+    // Assert
+    expect(parseRefineState({ seenSessionIds: ["ses_a"] }).size).toBe(0);
+    expect(parseRefineState({ analyzed: { ses_a: 5 } }).size).toBe(0);
+    expect(parseRefineState(null).size).toBe(0);
+  });
+});
+
+describe("isExpired", () => {
+  test("is true past the window and false inside it", () => {
+    // Assert
+    expect(isExpired(daysAgo(40), 30, NOW_MS)).toBe(true);
+    expect(isExpired(daysAgo(10), 30, NOW_MS)).toBe(false);
+  });
+
+  test("a period of zero disables expiry", () => {
+    // Assert
+    expect(isExpired(daysAgo(999), 0, NOW_MS)).toBe(false);
+  });
+});
+
+describe("pruneExpiredSessions", () => {
+  test("deletes resolved sessions past the window and keeps recent ones", () => {
+    // Arrange
+    const home = tempDir("cueloop-retention-home-");
+    const store = new SessionStore(home);
+
+    store.upsert(session("ses_old", daysAgo(40)));
+    store.upsert(session("ses_new", daysAgo(2)));
+
+    // Act
+    const pruned = pruneExpiredSessions(store, 30, NOW_MS);
+
+    // Assert
+    expect(pruned).toEqual(["ses_old"]);
+    expect(store.get("ses_old")).toBeUndefined();
+    expect(store.get("ses_new")).toBeDefined();
+  });
+
+  test("never deletes an active pending session however old", () => {
+    // Arrange
+    const home = tempDir("cueloop-retention-home-");
+    const store = new SessionStore(home);
+
+    store.upsert(session("ses_active", daysAgo(400), "pending"));
+
+    // Act
+    const pruned = pruneExpiredSessions(store, 30, NOW_MS);
+
+    // Assert
+    expect(pruned).toEqual([]);
+    expect(store.get("ses_active")).toBeDefined();
+  });
+
+  test("a period of zero prunes nothing", () => {
+    // Arrange
+    const home = tempDir("cueloop-retention-home-");
+    const store = new SessionStore(home);
+
+    store.upsert(session("ses_old", daysAgo(999)));
+
+    // Act
+    const pruned = pruneExpiredSessions(store, 0, NOW_MS);
+
+    // Assert
+    expect(pruned).toEqual([]);
+    expect(store.get("ses_old")).toBeDefined();
+  });
+});
+
+describe("pruneExpiredReports", () => {
+  test("removes timestamped reports past the window but keeps the latest report", () => {
+    // Arrange
+    const home = tempDir("cueloop-retention-home-");
+    const directory = reportsDir(home);
+
+    mkdirSync(directory, { recursive: true });
+    const latest = join(directory, LATEST_REPORT_FILENAME);
+    const stale = join(directory, "refine-2026-06-01T00-00-00-000Z.md");
+    const fresh = join(directory, "refine-2026-08-25T00-00-00-000Z.md");
+
+    for (const path of [latest, stale, fresh]) writeFileSync(path, "report");
+    const staleSeconds = (NOW_MS - 60 * DAY_MS) / 1000;
+
+    utimesSync(stale, staleSeconds, staleSeconds);
+
+    // Act
+    const pruned = pruneExpiredReports(directory, 30, NOW_MS);
+
+    // Assert
+    expect(pruned).toEqual(["refine-2026-06-01T00-00-00-000Z.md"]);
+  });
+});

package/src/retention.ts

@@ -0,0 +1,122 @@
+import { readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import * as v from "valibot";
+import type { SessionStore } from "./store";
+
+export const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
+export const LATEST_REPORT_FILENAME = "report.md";
+export const TIMESTAMPED_REPORT_PREFIX = "refine-";
+
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+
+const CleanupConfigSchema = v.object({
+  cleanup: v.optional(v.object({ period_days: v.optional(v.number()) })),
+});
+
+const RefineStateSchema = v.object({
+  analyzed: v.optional(v.record(v.string(), v.string()), {}),
+});
+
+export type RefineState = v.InferOutput<typeof RefineStateSchema>;
+
+export function parseRefineState(raw: unknown): Map<string, string> {
+  const parsed = v.safeParse(RefineStateSchema, raw);
+
+  if (!parsed.success) return new Map();
+
+  return new Map(Object.entries(parsed.output.analyzed));
+}
+
+function userConfigPath(env: NodeJS.ProcessEnv): string {
+  const explicit = env.CUELOOP_CONFIG;
+
+  if (explicit && explicit.trim()) return explicit;
+  const xdgConfigHome = env.XDG_CONFIG_HOME;
+  const base = xdgConfigHome && xdgConfigHome.trim() ? xdgConfigHome : join(homedir(), ".config");
+
+  return join(base, "cueloop", "config.toml");
+}
+
+function readConfiguredPeriodDays(path: string): number | undefined {
+  let raw: unknown;
+
+  try {
+    raw = Bun.TOML.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+  const parsed = v.safeParse(CleanupConfigSchema, raw);
+
+  if (!parsed.success) return undefined;
+  const value = parsed.output.cleanup?.period_days;
+
+  return value !== undefined && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+export function resolveCleanupPeriodDays(env: NodeJS.ProcessEnv = process.env): number {
+  return readConfiguredPeriodDays(userConfigPath(env)) ?? DEFAULT_CLEANUP_PERIOD_DAYS;
+}
+
+export function isExpired(createdAt: string, periodDays: number, nowMs: number): boolean {
+  if (periodDays <= 0) return false;
+  const createdMs = Date.parse(createdAt);
+
+  if (Number.isNaN(createdMs)) return false;
+
+  return nowMs - createdMs > periodDays * MILLISECONDS_PER_DAY;
+}
+
+export function pruneExpiredSessions(
+  store: SessionStore,
+  periodDays: number,
+  nowMs: number,
+): string[] {
+  if (periodDays <= 0) return [];
+  const pruned: string[] = [];
+
+  for (const session of store.list()) {
+    if (session.status !== "resolved") continue;
+    if (isExpired(session.createdAt, periodDays, nowMs) && store.delete(session.id)) {
+      pruned.push(session.id);
+    }
+  }
+
+  return pruned;
+}
+
+export function timestampedReportFilename(nowMs: number): string {
+  const stamp = new Date(nowMs).toISOString().replace(/[:.]/g, "-");
+
+  return `${TIMESTAMPED_REPORT_PREFIX}${stamp}.md`;
+}
+
+export function pruneExpiredReports(
+  reportsDirectory: string,
+  periodDays: number,
+  nowMs: number,
+): string[] {
+  if (periodDays <= 0) return [];
+  let entries: string[];
+
+  try {
+    entries = readdirSync(reportsDirectory);
+  } catch {
+    return [];
+  }
+  const cutoffMs = nowMs - periodDays * MILLISECONDS_PER_DAY;
+  const pruned: string[] = [];
+
+  for (const entry of entries) {
+    if (entry === LATEST_REPORT_FILENAME) continue;
+    if (!entry.startsWith(TIMESTAMPED_REPORT_PREFIX)) continue;
+    const path = join(reportsDirectory, entry);
+
+    if (statSync(path).mtimeMs < cutoffMs) {
+      rmSync(path, { force: true });
+      pruned.push(entry);
+    }
+  }
+
+  return pruned;
+}