@crewhaus/event-log 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export declare const DEFAULT_ROOT_DIR = ".crewhaus/sessions";
+export type EventKind = "user_message" | "assistant_message" | "tool_use" | "tool_result" | "error" | "compaction" | "sub_agent_start" | "sub_agent_end" | "role_start" | "role_end" | "handoff" | "a2a_message" | "a2a_turn_start" | "a2a_turn_end" | "crew_done" | "cost_accrual";
+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>;
+}
+/**
+ * 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 declare function openEventLog(sessionId: string, opts?: OpenEventLogOptions): Promise<EventLog>;

package/dist/index.js

@@ -0,0 +1,110 @@
+/**
+ * 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, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { RuntimeError } from "@crewhaus/errors";
+import { assertSamePath, currentTenantContext, requireTenant } from "@crewhaus/tenancy";
+export const DEFAULT_ROOT_DIR = ".crewhaus/sessions";
+const ID_REGEX = /^sess_[0-9a-f]{16}$/;
+function validateId(sessionId) {
+    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, opts = {}) {
+    validateId(sessionId);
+    const rootDir = opts.rootDir ?? DEFAULT_ROOT_DIR;
+    const now = opts.now ?? (() => Date.now());
+    const fullPath = resolve(rootDir, `${sessionId}.jsonl`);
+    mkdirSync(rootDir, { recursive: true });
+    // When a tenant context is active, fail closed on a resolved path that
+    // escapes the tenant's sessionRoot (CWE-1230). Outside a tenant scope (the
+    // common CLI case) this is a no-op so non-tenant behaviour is unchanged.
+    function fence() {
+        if (currentTenantContext() !== undefined) {
+            assertSamePath(fullPath, requireTenant().sessionRoot);
+        }
+    }
+    fence();
+    return {
+        async append(event) {
+            fence();
+            const wire = {
+                ts: now(),
+                version: 1,
+                kind: event.kind,
+                payload: event.payload,
+            };
+            const line = `${JSON.stringify(wire)}\n`;
+            appendFileSync(fullPath, line, { mode: 0o600 });
+        },
+        read(readOpts = {}) {
+            fence();
+            return readEvents(fullPath, readOpts);
+        },
+        async close() {
+            // No persistent handle today; reserved for a future buffered writer.
+        },
+    };
+}
+async function* readEvents(fullPath, opts) {
+    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;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            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();
+    }
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/event-log",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Append-only JSONL transcript log per session",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.3",
-    "@crewhaus/tenancy": "0.1.3"
+    "@crewhaus/errors": "0.1.5",
+    "@crewhaus/tenancy": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -33,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,262 +0,0 @@
-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 { TenancyError, buildTenant, withTenant } from "@crewhaus/tenancy";
-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);
-});
-
-describe("event-log — cross-tenant fencing (CWE-1230)", () => {
-  test("inside tenantA, a log rooted under tenantB fails closed", async () => {
-    const tenantsRoot = newTempRoot();
-    const tenantA = buildTenant("tenant-a", { tenantsRoot });
-    const tenantB = buildTenant("tenant-b", { tenantsRoot });
-    // Opening a log rooted under tenantB while tenantA is active resolves a
-    // path outside tenantA's sessionRoot, so it fails closed.
-    await expect(
-      withTenant(tenantA, () => openEventLog(TEST_ID, { rootDir: tenantB.sessionRoot })),
-    ).rejects.toThrow(TenancyError);
-  });
-
-  test("inside tenantA, a log rooted under tenantA round-trips", async () => {
-    const tenantsRoot = newTempRoot();
-    const tenantA = buildTenant("tenant-a", { tenantsRoot });
-    await withTenant(tenantA, async () => {
-      const log = await openEventLog(TEST_ID, { rootDir: tenantA.sessionRoot });
-      await log.append({ kind: "user_message", payload: { ok: true } });
-      const all = await collect(log.read());
-      expect(all.length).toBe(1);
-    });
-  });
-
-  test("no active tenant — behaviour is unchanged (no fencing)", async () => {
-    const rootDir = newTempRoot();
-    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 — security invariants", () => {
-  // The header documents owner-only (0o600) append semantics, mirroring the
-  // claude-code sessionStorage precedent. Pin it down so a regression that
-  // drops `{ mode: 0o600 }` (widening the transcript to group/other) fails.
-  test("the JSONL file is created without group/other access", async () => {
-    const rootDir = newTempRoot();
-    const log = await openEventLog(TEST_ID, { rootDir });
-    await log.append({ kind: "user_message", payload: { secret: "transcript" } });
-    const mode = statSync(join(rootDir, `${TEST_ID}.jsonl`)).mode & 0o777;
-    // No bits set for group (0o070) or other (0o007).
-    expect(mode & 0o077).toBe(0);
-  });
-
-  // A hostile/corrupt log line carrying a `__proto__` key must round-trip as
-  // plain data and must NOT pollute Object.prototype (CWE-1321). readEvents
-  // only `JSON.parse`s + yields; it never merges into an existing object, so
-  // there is no pollution sink — this guards against a future refactor adding
-  // one.
-  test("a __proto__ payload does not pollute Object.prototype", async () => {
-    const rootDir = newTempRoot();
-    const log = await openEventLog(TEST_ID, { rootDir });
-    await log.append({ kind: "user_message", payload: {} });
-    writeFileSync(
-      join(rootDir, `${TEST_ID}.jsonl`),
-      `${JSON.stringify({
-        ts: 1,
-        version: 1,
-        kind: "user_message",
-        payload: JSON.parse('{"__proto__":{"polluted":true}}'),
-      })}\n`,
-    );
-    const all = await collect(log.read());
-    expect(all.length).toBe(1);
-    // The global prototype must remain unpolluted for everyone else.
-    expect(({} as Record<string, unknown>)["polluted"]).toBeUndefined();
-    expect((Object.prototype as Record<string, unknown>)["polluted"]).toBeUndefined();
-  });
-
-  // The sessionId becomes part of the on-disk path; only `sess_<16 hex>` is
-  // accepted, so traversal / absolute-path / NUL injection in the id can never
-  // reach the filesystem (CWE-22).
-  test("rejects traversal, separators, and NUL in the session id", async () => {
-    const rootDir = newTempRoot();
-    for (const bad of [
-      "sess_../../etc/passwd",
-      "sess_0123456789abcde/", // 15 hex + slash
-      "sess_0123456789abcdeg", // non-hex char
-      "sess_0123456789ABCDEF", // uppercase hex not allowed
-      "sess_0123456789abcdef0", // 17 hex (too long)
-      "sess_000000000000",
-      "../escape",
-    ]) {
-      await expect(openEventLog(bad, { rootDir })).rejects.toThrow(/invalid sessionId/);
-    }
-  });
-});

package/src/index.ts

@@ -1,168 +0,0 @@
-/**
- * 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, resolve } from "node:path";
-import { createInterface } from "node:readline";
-import { RuntimeError } from "@crewhaus/errors";
-import { assertSamePath, currentTenantContext, requireTenant } from "@crewhaus/tenancy";
-
-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 = resolve(rootDir, `${sessionId}.jsonl`);
-  mkdirSync(rootDir, { recursive: true });
-
-  // When a tenant context is active, fail closed on a resolved path that
-  // escapes the tenant's sessionRoot (CWE-1230). Outside a tenant scope (the
-  // common CLI case) this is a no-op so non-tenant behaviour is unchanged.
-  function fence(): void {
-    if (currentTenantContext() !== undefined) {
-      assertSamePath(fullPath, requireTenant().sessionRoot);
-    }
-  }
-  fence();
-
-  return {
-    async append(event: AppendEvent): Promise<void> {
-      fence();
-      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> {
-      fence();
-      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();
-  }
-}