@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/sessions.integration.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Integration tests for createFileSessionStore and threadKey in agent/src/runtime/sessions.ts
+ *
+ * Uses real file I/O to a process-scoped tmp file — no mocks, pure file I/O.
+ * This is an integration test by boundary rule: it exercises the real fs module.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FixedClock } from "./clock.ts";
+import { createFileSessionStore, threadKey } from "./sessions.ts";
+
+// ─── Shared store backed by a process-scoped tmp file ─────────────────────────
+
+const SESSIONS_FILE = `/tmp/shipwright-sessions-test-${process.pid}.json`;
+const store = createFileSessionStore(SESSIONS_FILE);
+
+afterEach(() => {
+  try {
+    rmSync(SESSIONS_FILE, { force: true });
+  } catch {
+    // file may not exist — safe to ignore
+  }
+});
+
+// ─── threadKey ─────────────────────────────────────────────────────────────────
+
+describe("threadKey", () => {
+  test("returns channel:ts format", () => {
+    expect(threadKey("C123", "1234567890.000100")).toBe(
+      "C123:1234567890.000100",
+    );
+  });
+
+  test("different channels produce different keys", () => {
+    expect(threadKey("C1", "ts")).not.toBe(threadKey("C2", "ts"));
+  });
+
+  test("handles DM channel prefix", () => {
+    expect(threadKey("D99999ZZ", "0000001.000001")).toBe(
+      "D99999ZZ:0000001.000001",
+    );
+  });
+
+  test("handles group channel prefix", () => {
+    expect(threadKey("GABCDEF1", "9876543.210000")).toBe(
+      "GABCDEF1:9876543.210000",
+    );
+  });
+});
+
+// ─── createFileSessionStore ────────────────────────────────────────────────────
+
+describe("createFileSessionStore — basic operations", () => {
+  test("get returns undefined for missing key", async () => {
+    expect(await store.get("no-such-key")).toBeUndefined();
+  });
+
+  test("set + get roundtrip", async () => {
+    await store.set("key1", "session-abc");
+    expect(await store.get("key1")).toBe("session-abc");
+  });
+
+  test("set overwrites existing entry", async () => {
+    await store.set("key1", "session-old");
+    await store.set("key1", "session-new");
+    expect(await store.get("key1")).toBe("session-new");
+  });
+
+  test("clear removes key", async () => {
+    await store.set("key1", "session-abc");
+    await store.clear("key1");
+    expect(await store.get("key1")).toBeUndefined();
+  });
+
+  test("clear on missing key is a no-op", async () => {
+    await expect(store.clear("does-not-exist")).resolves.toBeUndefined();
+  });
+
+  test("size returns count of stored entries", async () => {
+    expect(await store.size()).toBe(0);
+    await store.set("k1", "s1");
+    expect(await store.size()).toBe(1);
+    await store.set("k2", "s2");
+    expect(await store.size()).toBe(2);
+    await store.clear("k1");
+    expect(await store.size()).toBe(1);
+  });
+
+  test("multiple keys are independent", async () => {
+    await store.set("k1", "s1");
+    await store.set("k2", "s2");
+    expect(await store.get("k1")).toBe("s1");
+    expect(await store.get("k2")).toBe("s2");
+    await store.clear("k1");
+    expect(await store.get("k1")).toBeUndefined();
+    expect(await store.get("k2")).toBe("s2");
+  });
+
+  test("get returns undefined when constructed on a path that no longer exists", async () => {
+    await store.set("C1:ts1", "session-gone");
+    rmSync(SESSIONS_FILE, { force: true });
+    const freshStore = createFileSessionStore(SESSIONS_FILE);
+    expect(await freshStore.get("C1:ts1")).toBeUndefined();
+  });
+});
+
+// ─── Concurrent writes ──────────────────────────────────────────────────────────
+
+describe("createFileSessionStore — concurrent writes", () => {
+  test("two concurrent set() calls on different keys both persist (no clobbering)", async () => {
+    const concurrentFile = join(
+      tmpdir(),
+      `sessions-concurrent-diffkeys-${process.pid}-${Date.now()}.json`,
+    );
+    const concurrentStore = createFileSessionStore(concurrentFile);
+
+    // Fire both writes without awaiting the first before starting the second —
+    // this is the load-modify-save race: without serialization, the second
+    // set()'s load() can happen before the first set()'s save() lands, so its
+    // save() would overwrite the first write.
+    await Promise.all([
+      concurrentStore.set("keyA", "session-A"),
+      concurrentStore.set("keyB", "session-B"),
+    ]);
+
+    expect(await concurrentStore.get("keyA")).toBe("session-A");
+    expect(await concurrentStore.get("keyB")).toBe("session-B");
+    expect(await concurrentStore.size()).toBe(2);
+
+    // Also verify the on-disk file itself reflects both writes — a full
+    // round-trip, not a clobbered partial write from a stale in-memory read.
+    const onDisk = JSON.parse(readFileSync(concurrentFile, "utf8"));
+    expect(Object.keys(onDisk).sort()).toEqual(["keyA", "keyB"]);
+
+    try {
+      rmSync(concurrentFile, { force: true });
+    } catch {}
+  });
+
+  test("two concurrent set() calls on the same key both apply — final value is one of the two, file is not corrupted", async () => {
+    const concurrentFile = join(
+      tmpdir(),
+      `sessions-concurrent-samekey-${process.pid}-${Date.now()}.json`,
+    );
+    const concurrentStore = createFileSessionStore(concurrentFile);
+
+    await Promise.all([
+      concurrentStore.set("key1", "session-first"),
+      concurrentStore.set("key1", "session-second"),
+    ]);
+
+    const finalValue = await concurrentStore.get("key1");
+    expect(finalValue).toBeDefined();
+    expect(["session-first", "session-second"]).toContain(finalValue as string);
+
+    // The persisted file must be valid JSON with exactly one entry for key1 —
+    // proof the second write's load+save wasn't torn or based on a stale read
+    // that silently dropped the first write's on-disk effects.
+    const onDisk = JSON.parse(readFileSync(concurrentFile, "utf8"));
+    expect(Object.keys(onDisk)).toEqual(["key1"]);
+
+    try {
+      rmSync(concurrentFile, { force: true });
+    } catch {}
+  });
+
+  test("interleaved set/get calls on the same store apply in enqueued order", async () => {
+    const concurrentFile = join(
+      tmpdir(),
+      `sessions-concurrent-order-${process.pid}-${Date.now()}.json`,
+    );
+    const concurrentStore = createFileSessionStore(concurrentFile);
+
+    // Three concurrent sets on distinct keys plus a concurrent clear — all
+    // fired together, none awaited individually first.
+    await Promise.all([
+      concurrentStore.set("a", "1"),
+      concurrentStore.set("b", "2"),
+      concurrentStore.set("c", "3"),
+    ]);
+
+    expect(await concurrentStore.size()).toBe(3);
+    expect(await concurrentStore.get("a")).toBe("1");
+    expect(await concurrentStore.get("b")).toBe("2");
+    expect(await concurrentStore.get("c")).toBe("3");
+
+    try {
+      rmSync(concurrentFile, { force: true });
+    } catch {}
+  });
+});
+
+// ─── TTL and prune ─────────────────────────────────────────────────────────────
+
+describe("createFileSessionStore — TTL and prune", () => {
+  test("TTL-based expiry: expired entry returns undefined", async () => {
+    const shortTtlFile = join(
+      tmpdir(),
+      `sessions-ttl-${process.pid}-${Date.now()}.json`,
+    );
+    const t0 = new Date("2024-01-01T00:00:00.000Z");
+    // Fixed clock at t0 for the write — with real async file I/O, comparing
+    // against real wall-clock time (via a busy-wait) races the I/O latency
+    // itself. A second store on the same file with a clock fixed well past
+    // the TTL gives a deterministic "later" read with no timing dependency.
+    const earlyStore = createFileSessionStore(
+      shortTtlFile,
+      1000,
+      FixedClock(t0),
+    );
+    await earlyStore.set("k", "session-xyz");
+    expect(await earlyStore.get("k")).toBe("session-xyz");
+    const lateStore = createFileSessionStore(
+      shortTtlFile,
+      1000,
+      FixedClock(new Date(t0.getTime() + 5000)),
+    );
+    expect(await lateStore.get("k")).toBeUndefined();
+    try {
+      rmSync(shortTtlFile, { force: true });
+    } catch {}
+  });
+
+  test("prune removes expired entries and returns count", async () => {
+    const pruneFile = join(
+      tmpdir(),
+      `sessions-prune-${process.pid}-${Date.now()}.json`,
+    );
+    const t0 = new Date("2024-01-01T00:00:00.000Z");
+    const earlyStore = createFileSessionStore(pruneFile, 1000, FixedClock(t0));
+    await earlyStore.set("k1", "s1");
+    await earlyStore.set("k2", "s2");
+    const lateStore = createFileSessionStore(
+      pruneFile,
+      1000,
+      FixedClock(new Date(t0.getTime() + 5000)),
+    );
+    const pruned = await lateStore.prune();
+    expect(pruned).toBe(2);
+    expect(await lateStore.size()).toBe(0);
+    try {
+      rmSync(pruneFile, { force: true });
+    } catch {}
+  });
+
+  test("prune returns 0 when nothing is expired", async () => {
+    await store.set("k1", "s1");
+    await store.set("k2", "s2");
+    expect(await store.prune()).toBe(0);
+    expect(await store.size()).toBe(2);
+  });
+
+  test("legacy string format support: get returns sessionId string", async () => {
+    // Write a legacy-format file manually
+    const legacyFile = join(
+      tmpdir(),
+      `sessions-legacy-${process.pid}-${Date.now()}.json`,
+    );
+    writeFileSync(
+      legacyFile,
+      JSON.stringify({ "C1:ts1": "legacy-session-id" }),
+    );
+    const legacyStore = createFileSessionStore(legacyFile, 60_000);
+    // Legacy string entries have no TTL — always valid
+    expect(await legacyStore.get("C1:ts1")).toBe("legacy-session-id");
+    try {
+      rmSync(legacyFile, { force: true });
+    } catch {}
+  });
+});

package/sessions.ts

@@ -0,0 +1,191 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { type Clock, SystemClock } from "./clock.ts";
+
+interface SessionEntry {
+  sessionId: string;
+  updatedAt: number; // epoch ms
+}
+
+/** On-disk format: values can be a plain string (legacy) or a SessionEntry object. */
+type SessionMap = Record<string, string | SessionEntry>;
+
+/** Default TTL: 7 days in milliseconds. Sessions older than this are pruned on load. */
+const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Key is channel:thread_ts (or channel:ts for the root of a new thread). */
+export function threadKey(channel: string, threadTs: string): string {
+  return `${channel}:${threadTs}`;
+}
+
+/**
+ * Per-file write queue: serializes async operations against the same file
+ * path so overlapping load-modify-save sequences (get/set/clear/prune) apply
+ * in enqueued order instead of racing. Without this, two concurrent set()
+ * calls can each load() the same pre-write map, then save() over one
+ * another — the second save() to land wins and the first write is silently
+ * lost even though both callers believe their write succeeded.
+ *
+ * Keyed by file path (module-level) so every createFileSessionStore() call
+ * targeting the same path shares one queue, matching the file-level
+ * contention this is meant to serialize.
+ */
+const writeQueues = new Map<string, Promise<unknown>>();
+
+function enqueue<T>(file: string, fn: () => Promise<T>): Promise<T> {
+  const prev = writeQueues.get(file) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  // Swallow so a failed op doesn't poison the chain for subsequent callers —
+  // the caller of enqueue() still observes the original rejection via `next`.
+  writeQueues.set(
+    file,
+    next.catch(() => {}),
+  );
+  return next;
+}
+
+/**
+ * Create a file-backed session store at a specific path.
+ *
+ * Module-level default store removed — callers must wire their own store
+ * via createFileSessionStore(config.paths.sessions).
+ *
+ * @param clock - Injectable clock for deterministic testing. Defaults to SystemClock.
+ */
+export function createFileSessionStore(
+  file: string,
+  ttlMs: number = DEFAULT_TTL_MS,
+  clock: Clock = SystemClock(),
+): {
+  get: (key: string) => Promise<string | undefined>;
+  set: (key: string, id: string) => Promise<void>;
+  clear: (key: string) => Promise<void>;
+  prune: () => Promise<number>;
+  size: () => Promise<number>;
+} {
+  async function load(): Promise<SessionMap> {
+    try {
+      return JSON.parse(await readFile(file, "utf8")) as SessionMap;
+    } catch {
+      return {};
+    }
+  }
+  async function save(map: SessionMap): Promise<void> {
+    await writeFile(file, JSON.stringify(map, null, 2));
+  }
+
+  /** Extract sessionId from either legacy string or SessionEntry format. */
+  function resolveId(value: string | SessionEntry): string {
+    return typeof value === "string" ? value : value.sessionId;
+  }
+
+  /** Check if entry is expired. Legacy string entries are always considered valid (no timestamp). */
+  function isExpired(value: string | SessionEntry, now: number): boolean {
+    if (typeof value === "string") return false; // legacy format, no TTL
+    return now - value.updatedAt > ttlMs;
+  }
+
+  return {
+    get: (key) =>
+      enqueue(file, async () => {
+        const map = await load();
+        const entry = map[key];
+        if (!entry) return undefined;
+        if (isExpired(entry, clock.now().getTime())) {
+          // Lazy prune: remove expired entry on access
+          delete map[key];
+          await save(map);
+          return undefined;
+        }
+        return resolveId(entry);
+      }),
+    set: (key, id) =>
+      enqueue(file, async () => {
+        const map = await load();
+        map[key] = { sessionId: id, updatedAt: clock.now().getTime() };
+        await save(map);
+      }),
+    clear: (key) =>
+      enqueue(file, async () => {
+        const map = await load();
+        delete map[key];
+        await save(map);
+      }),
+    /** Remove all expired sessions. Returns count of pruned entries. */
+    prune: () =>
+      enqueue(file, async () => {
+        const map = await load();
+        const now = clock.now().getTime();
+        let pruned = 0;
+        for (const key of Object.keys(map)) {
+          if (isExpired(map[key], now)) {
+            delete map[key];
+            pruned++;
+          }
+        }
+        if (pruned > 0) await save(map);
+        return pruned;
+      }),
+    size: () => enqueue(file, async () => Object.keys(await load()).length),
+  };
+}
+
+// ─── Periodic prune ───────────────────────────────────────────────────────────
+
+/** Default sweep interval for startSessionPruner: 6 hours. */
+export const SESSION_PRUNE_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
+/** The slice of the store startSessionPruner needs — keeps callers/tests thin. */
+interface PrunableSessionStore {
+  prune: () => Promise<number>;
+}
+
+/**
+ * One prune sweep. Never throws: a prune failure (unreadable/locked file,
+ * disk blip) is logged and swallowed, since this is pure housekeeping.
+ * Returns the number of entries removed (0 on failure).
+ */
+export async function pruneSessionsOnce(
+  store: PrunableSessionStore,
+  label: string,
+): Promise<number> {
+  try {
+    const pruned = await store.prune();
+    if (pruned > 0) {
+      console.log(`[sessions] pruned ${pruned} expired ${label} entries`);
+    }
+    return pruned;
+  } catch (err) {
+    console.warn(
+      `[sessions] prune failed for ${label}: ${String(err)} — swallowing`,
+    );
+    return 0;
+  }
+}
+
+/**
+ * Start the periodic TTL sweep for a file-backed session store.
+ *
+ * Without this, `prune()` has no production call site and entries only ever
+ * expire lazily on `get()` — which never happens for a key that is written
+ * once and never read again (DTW-1.3's per-dispatch `dev-task:{id}:{nonce}`
+ * keys, whose owning loop normally clears them but can't after an abrupt
+ * process kill). The sweep runs once immediately (clearing whatever a previous
+ * process left behind) and then on `intervalMs`.
+ *
+ * `setIntervalFn` is injectable so tests can drive the schedule deterministically.
+ */
+export function startSessionPruner(
+  store: PrunableSessionStore,
+  label: string,
+  opts?: {
+    intervalMs?: number;
+    setIntervalFn?: (fn: () => void, ms: number) => unknown;
+  },
+): void {
+  const intervalMs = opts?.intervalMs ?? SESSION_PRUNE_INTERVAL_MS;
+  const schedule =
+    opts?.setIntervalFn ??
+    ((fn: () => void, ms: number) => setInterval(fn, ms));
+  void pruneSessionsOnce(store, label);
+  schedule(() => void pruneSessionsOnce(store, label), intervalMs);
+}

package/sessions.unit.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Unit tests for the periodic session-store prune wiring in agent/src/runtime/sessions.ts.
+ *
+ * Pure logic over an injected store double and an injected setInterval — no file
+ * I/O and no real timers, so this is a unit test (the file-backed store itself is
+ * covered in sessions.integration.test.ts).
+ *
+ * Regression context (DTW-1.3 review): before this wiring, `prune()` had zero
+ * production call sites, so entries only ever expired lazily on `get()` — which
+ * never happens for a per-dispatch `dev-task:{id}:{nonce}` key that is written
+ * once and never read again.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  pruneSessionsOnce,
+  SESSION_PRUNE_INTERVAL_MS,
+  startSessionPruner,
+} from "./sessions.ts";
+
+describe("pruneSessionsOnce", () => {
+  test("returns the store's pruned count", async () => {
+    const store = { prune: async () => 3 };
+    expect(await pruneSessionsOnce(store, "sessions.json")).toBe(3);
+  });
+
+  test("swallows a prune failure and reports 0 — housekeeping never crashes a caller", async () => {
+    const store = {
+      prune: async () => {
+        throw new Error("file unreadable");
+      },
+    };
+    expect(await pruneSessionsOnce(store, "sessions.json")).toBe(0);
+  });
+});
+
+describe("startSessionPruner", () => {
+  test("sweeps once immediately and schedules a repeat on the default interval", async () => {
+    let pruneCalls = 0;
+    const store = {
+      prune: async () => {
+        pruneCalls += 1;
+        return 1;
+      },
+    };
+    const scheduled: Array<{ fn: () => void; ms: number }> = [];
+
+    startSessionPruner(store, "sessions.json", {
+      setIntervalFn: (fn, ms) => {
+        scheduled.push({ fn, ms });
+        return 0;
+      },
+    });
+
+    // The startup sweep clears whatever a previous (possibly killed) process
+    // stranded, without waiting a full interval.
+    expect(pruneCalls).toBe(1);
+    expect(scheduled).toHaveLength(1);
+    expect(scheduled[0]?.ms).toBe(SESSION_PRUNE_INTERVAL_MS);
+
+    // ...and each timer fire is another sweep.
+    scheduled[0]?.fn();
+    expect(pruneCalls).toBe(2);
+  });
+
+  test("honors an explicit interval", () => {
+    const store = { prune: async () => 0 };
+    const intervals: number[] = [];
+    startSessionPruner(store, "sessions.json", {
+      intervalMs: 1234,
+      setIntervalFn: (_fn, ms) => {
+        intervals.push(ms);
+        return 0;
+      },
+    });
+    expect(intervals).toEqual([1234]);
+  });
+
+  test("a throwing store does not propagate out of the scheduled sweep", () => {
+    const store = {
+      prune: async () => {
+        throw new Error("boom");
+      },
+    };
+    const scheduled: Array<() => void> = [];
+    startSessionPruner(store, "sessions.json", {
+      setIntervalFn: (fn) => {
+        scheduled.push(fn);
+        return 0;
+      },
+    });
+    expect(() => scheduled[0]?.()).not.toThrow();
+  });
+});