@crewhaus/event-log 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/event-log",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Append-only JSONL transcript log per session",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/event-log"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/event-log#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,172 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Event, openEventLog } from "./index";
+
+const TMP_ROOTS: string[] = [];
+function newTempRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "crewhaus-event-log-"));
+  TMP_ROOTS.push(dir);
+  return dir;
+}
+afterAll(() => {
+  for (const dir of TMP_ROOTS) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+const TEST_ID = "sess_0123456789abcdef";
+
+async function collect(events: AsyncIterable<Event>): Promise<Event[]> {
+  const out: Event[] = [];
+  for await (const ev of events) out.push(ev);
+  return out;
+}
+
+describe("event-log — round-trip", () => {
+  test("append + read returns events in insertion order with version 1", async () => {
+    const rootDir = newTempRoot();
+    let clock = 1_700_000_000_000;
+    const log = await openEventLog(TEST_ID, { rootDir, now: () => clock++ });
+    await log.append({ kind: "user_message", payload: { content: "hello" } });
+    await log.append({
+      kind: "assistant_message",
+      payload: { content: [{ type: "text", text: "hi" }] },
+    });
+    await log.append({
+      kind: "tool_use",
+      payload: { id: "tu_1", name: "Read", input: { path: "x" } },
+    });
+    await log.append({
+      kind: "tool_result",
+      payload: { toolUseId: "tu_1", content: "ok", isError: false },
+    });
+    await log.append({ kind: "error", payload: { name: "E", message: "boom" } });
+    await log.append({ kind: "compaction", payload: { kind: "snip", before: 100, after: 30 } });
+    await log.close();
+
+    const all = await collect(log.read());
+    expect(all.length).toBe(6);
+    expect(all.map((e) => e.kind)).toEqual([
+      "user_message",
+      "assistant_message",
+      "tool_use",
+      "tool_result",
+      "error",
+      "compaction",
+    ]);
+    for (const ev of all) {
+      expect(ev.version).toBe(1);
+      expect(typeof ev.ts).toBe("number");
+    }
+    // ts values should be strictly increasing because of clock++
+    for (let i = 1; i < all.length; i++) {
+      const prev = all[i - 1];
+      const curr = all[i];
+      if (prev === undefined || curr === undefined) throw new Error("unreachable");
+      expect(curr.ts).toBeGreaterThan(prev.ts);
+    }
+    expect(all[0]?.payload).toEqual({ content: "hello" });
+  });
+
+  test("read filters by since and until", async () => {
+    const rootDir = newTempRoot();
+    let clock = 100;
+    const log = await openEventLog(TEST_ID, { rootDir, now: () => clock });
+    for (let i = 0; i < 5; i++) {
+      clock = 100 + i * 10;
+      await log.append({ kind: "user_message", payload: { i } });
+    }
+    await log.close();
+
+    const all = await collect(log.read());
+    expect(all.length).toBe(5);
+    expect(all.map((e) => e.ts)).toEqual([100, 110, 120, 130, 140]);
+
+    const sinceOnly = await collect(log.read({ since: 120 }));
+    expect(sinceOnly.map((e) => e.ts)).toEqual([120, 130, 140]);
+
+    const untilOnly = await collect(log.read({ until: 120 }));
+    expect(untilOnly.map((e) => e.ts)).toEqual([100, 110, 120]);
+
+    const both = await collect(log.read({ since: 110, until: 130 }));
+    expect(both.map((e) => e.ts)).toEqual([110, 120, 130]);
+  });
+
+  test("read of a never-written log yields zero events", async () => {
+    const rootDir = newTempRoot();
+    const log = await openEventLog(TEST_ID, { rootDir });
+    const all = await collect(log.read());
+    expect(all).toEqual([]);
+  });
+
+  test("malformed line throws RuntimeError carrying the line number", async () => {
+    const rootDir = newTempRoot();
+    const log = await openEventLog(TEST_ID, { rootDir });
+    await log.append({ kind: "user_message", payload: { i: 1 } });
+    // Manually corrupt the file with a bogus trailing line.
+    writeFileSync(
+      join(rootDir, `${TEST_ID}.jsonl`),
+      `{"ts":1,"version":1,"kind":"user_message","payload":{"i":1}}\nNOT JSON\n`,
+    );
+    await expect(collect(log.read())).rejects.toThrow(/malformed JSON on line 2/);
+  });
+
+  test("ignores blank lines without bumping the line counter visibly", async () => {
+    const rootDir = newTempRoot();
+    const log = await openEventLog(TEST_ID, { rootDir });
+    await log.append({ kind: "user_message", payload: {} });
+    // Append a blank line + a real event manually.
+    writeFileSync(
+      join(rootDir, `${TEST_ID}.jsonl`),
+      `{"ts":1,"version":1,"kind":"user_message","payload":{}}\n\n{"ts":2,"version":1,"kind":"user_message","payload":{}}\n`,
+    );
+    const all = await collect(log.read());
+    expect(all.length).toBe(2);
+  });
+
+  test("rejects an invalid session id", async () => {
+    const rootDir = newTempRoot();
+    await expect(openEventLog("../escape", { rootDir })).rejects.toThrow(/invalid sessionId/);
+    await expect(openEventLog("sess_short", { rootDir })).rejects.toThrow(/invalid sessionId/);
+  });
+
+  test("creates the root directory if it does not exist", async () => {
+    const rootDir = join(newTempRoot(), "deep", "nested", "dir");
+    const log = await openEventLog(TEST_ID, { rootDir });
+    await log.append({ kind: "user_message", payload: { ok: true } });
+    const all = await collect(log.read());
+    expect(all.length).toBe(1);
+  });
+});
+
+describe("event-log — T7 load", () => {
+  test("10 000 appends round-trip cleanly", async () => {
+    const rootDir = newTempRoot();
+    const log = await openEventLog(TEST_ID, { rootDir });
+
+    const COUNT = 10_000;
+    const start = performance.now();
+    for (let i = 0; i < COUNT; i++) {
+      await log.append({ kind: "user_message", payload: { i, padding: "x".repeat(20) } });
+    }
+    const appendMs = performance.now() - start;
+    expect(appendMs).toBeLessThan(15_000);
+
+    const fullPath = join(rootDir, `${TEST_ID}.jsonl`);
+    expect(statSync(fullPath).size).toBeGreaterThan(COUNT * 60);
+
+    const readStart = performance.now();
+    const all = await collect(log.read());
+    const readMs = performance.now() - readStart;
+    expect(all.length).toBe(COUNT);
+    for (let i = 0; i < COUNT; i++) {
+      const ev = all[i];
+      if (ev === undefined) throw new Error("unreachable");
+      expect((ev.payload as { i: number }).i).toBe(i);
+    }
+    // Read should be substantially faster than the append loop.
+    expect(readMs).toBeLessThan(5_000);
+  }, 30_000);
+});

package/src/index.ts

@@ -0,0 +1,155 @@
+/**
+ * Catalog R7 `event-log` — append-only JSONL transcript per session.
+ *
+ * One event per line at `<rootDir>/<sessionId>.jsonl` (default rootDir
+ * `.crewhaus/sessions`). Every line is a self-describing JSON object:
+ * `{ ts, version: 1, kind, payload }`. The schema-version field is
+ * stamped onto every event so future migrations can fan out on it.
+ *
+ * Append semantics: each `append()` calls `appendFileSync(...)` with
+ * mode 0o600 (owner-only) per the
+ * `claude-code/utils/sessionStorage.ts` precedent. Synchronous append on
+ * POSIX is atomic per line (when `len < PIPE_BUF`), so concurrent runs
+ * cannot interleave partial JSON. The API is async to keep the door open
+ * for a future buffered-writer optimisation; today it resolves
+ * immediately.
+ *
+ * Read semantics: `read({ since?, until? })` opens a fresh read stream
+ * via `node:readline`, parses each line as JSON, and yields events in
+ * insertion order (filtered by epoch `ts` if either bound is supplied).
+ * Missing files yield zero events. A malformed line throws
+ * `RuntimeError` carrying the line number — event logs must round-trip
+ * cleanly.
+ *
+ * Reference: `claude-code/utils/sessionStorage.ts`,
+ * `AI-Harness-Systems.md` §append-only event history.
+ */
+import { appendFileSync, createReadStream, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { RuntimeError } from "@crewhaus/errors";
+
+export const DEFAULT_ROOT_DIR = ".crewhaus/sessions";
+const ID_REGEX = /^sess_[0-9a-f]{16}$/;
+
+export type EventKind =
+  | "user_message"
+  | "assistant_message"
+  | "tool_use"
+  | "tool_result"
+  | "error"
+  | "compaction"
+  | "sub_agent_start"
+  | "sub_agent_end"
+  // Section 22 — CRW (multi-agent crew) lifecycle events. Single durable
+  // sessionId across an entire crew run; every role's turn writes here.
+  | "role_start"
+  | "role_end"
+  | "handoff"
+  | "a2a_message"
+  // a2a_turn_start / a2a_turn_end bracket the nested inline `runChatLoop`
+  // an A2A peer call drives. Because every role in a crew shares one
+  // session JSONL, the peer's `user_message` + `assistant_message`
+  // events land in the parent's log; on a later role's `resume`,
+  // `replayMessageHistory` uses these markers to skip the peer's nested
+  // transcript and keep the parent's `tool_use → tool_result` pair
+  // immediately adjacent (Claude API requires it). Symmetric to
+  // `sub_agent_start/end` for Section-13 sub-agents.
+  | "a2a_turn_start"
+  | "a2a_turn_end"
+  | "crew_done";
+
+export type Event = {
+  readonly ts: number;
+  readonly version: 1;
+  readonly kind: EventKind;
+  readonly payload: unknown;
+};
+
+export type AppendEvent = Pick<Event, "kind" | "payload">;
+
+export type OpenEventLogOptions = {
+  readonly rootDir?: string;
+  readonly now?: () => number;
+};
+
+export interface EventLog {
+  append(event: AppendEvent): Promise<void>;
+  read(opts?: { since?: number; until?: number }): AsyncIterable<Event>;
+  close(): Promise<void>;
+}
+
+function validateId(sessionId: string): void {
+  if (!ID_REGEX.test(sessionId)) {
+    throw new RuntimeError(`event-log: invalid sessionId "${sessionId}" — expected sess_<16 hex>`);
+  }
+}
+
+/**
+ * Open (or implicitly create) the JSONL log for `sessionId`. Creates the
+ * parent directory on demand. Subsequent `append()` calls write
+ * synchronously to the file; `read()` opens its own read stream so it
+ * sees a consistent snapshot of the bytes already on disk.
+ */
+export async function openEventLog(
+  sessionId: string,
+  opts: OpenEventLogOptions = {},
+): Promise<EventLog> {
+  validateId(sessionId);
+  const rootDir = opts.rootDir ?? DEFAULT_ROOT_DIR;
+  const now = opts.now ?? (() => Date.now());
+  const fullPath = join(rootDir, `${sessionId}.jsonl`);
+  mkdirSync(rootDir, { recursive: true });
+
+  return {
+    async append(event: AppendEvent): Promise<void> {
+      const wire: Event = {
+        ts: now(),
+        version: 1,
+        kind: event.kind,
+        payload: event.payload,
+      };
+      const line = `${JSON.stringify(wire)}\n`;
+      appendFileSync(fullPath, line, { mode: 0o600 });
+    },
+
+    read(readOpts: { since?: number; until?: number } = {}): AsyncIterable<Event> {
+      return readEvents(fullPath, readOpts);
+    },
+
+    async close(): Promise<void> {
+      // No persistent handle today; reserved for a future buffered writer.
+    },
+  };
+}
+
+async function* readEvents(
+  fullPath: string,
+  opts: { since?: number; until?: number },
+): AsyncIterable<Event> {
+  if (!existsSync(fullPath)) return;
+  const stream = createReadStream(fullPath, { encoding: "utf8" });
+  const rl = createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
+  let lineNumber = 0;
+  try {
+    for await (const raw of rl) {
+      lineNumber += 1;
+      if (raw === "") continue;
+      let parsed: Event;
+      try {
+        parsed = JSON.parse(raw) as Event;
+      } catch (err) {
+        throw new RuntimeError(
+          `event-log: malformed JSON on line ${lineNumber} of ${fullPath}`,
+          err,
+        );
+      }
+      if (opts.since !== undefined && parsed.ts < opts.since) continue;
+      if (opts.until !== undefined && parsed.ts > opts.until) continue;
+      yield parsed;
+    }
+  } finally {
+    rl.close();
+    stream.close();
+  }
+}