@claudexor/event-log 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joi-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @claudexor/event-log
+
+Internal package of [Claudexor](https://github.com/razzant/claudexor) — Append-only JSONL run-event log (a projection-friendly evidence ledger).
+
+Published as part of the Claudexor toolchain; it follows the monorepo's
+lockstep version and has no separate semver contract. Use the `claudexor`
+CLI (or `@claudexor/cli`) as the supported entry point.

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import type { RunEvent, RunEventType } from "@claudexor/schema";
+/**
+ * Append-only JSONL event log for a single run. Terminal output and human
+ * summaries are projections; this file is the canonical event stream.
+ *
+ * Every emitted event carries a monotonic per-run `seq` stamped here — the
+ * durable cursor for SSE resume (Last-Event-ID) and snapshot fencing
+ * (detail.lastSeq). The counter initializes from the existing file tail so a
+ * re-opened log (or an out-of-band appender like the control-api audit
+ * writer) continues the sequence instead of restarting it.
+ */
+export declare class EventLog {
+    private readonly path;
+    private readonly runId;
+    private readonly taskId;
+    /**
+     * Optional in-process sink invoked after each event is persisted. Lets a
+     * long-running service / GUI observe the live RunEvent stream without
+     * tailing the file. The file remains the canonical log; a throwing sink
+     * must never break a run, so sink errors are swallowed.
+     */
+    private readonly onEmit?;
+    /**
+     * Thread this run is a turn of, when any. Stamped on every event so the
+     * global event multiplex can route live progress to a chat surface without
+     * a reverse job lookup.
+     */
+    private readonly threadId?;
+    private nextSeq;
+    constructor(path: string, runId: string, taskId: string, 
+    /**
+     * Optional in-process sink invoked after each event is persisted. Lets a
+     * long-running service / GUI observe the live RunEvent stream without
+     * tailing the file. The file remains the canonical log; a throwing sink
+     * must never break a run, so sink errors are swallowed.
+     */
+    onEmit?: ((event: RunEvent) => void) | undefined, 
+    /**
+     * Thread this run is a turn of, when any. Stamped on every event so the
+     * global event multiplex can route live progress to a chat surface without
+     * a reverse job lookup.
+     */
+    threadId?: string | undefined);
+    /**
+     * Unregister this log as the live writer for its path. Out-of-band
+     * appenders fall back to file-tail stamping afterwards, which is safe once
+     * the owning run is terminal (nobody else holds an in-memory counter).
+     */
+    dispose(): void;
+    /** Append a typed run event. Validates against the schema before writing. */
+    emit(type: RunEventType, payload?: Record<string, unknown>): RunEvent;
+    /** Read and parse all events (skipping malformed lines, which are surfaced separately). */
+    readAll(): {
+        events: RunEvent[];
+        malformed: number;
+    };
+}
+/**
+ * Append an out-of-band event (e.g. a control-api audit record) into a run's
+ * canonical log WITHOUT corrupting the seq space: routes through the live
+ * EventLog when the run is still active (same counter, same onEmit sink), and
+ * falls back to file-tail stamping for terminal runs.
+ */
+export declare function appendRunEvent(path: string, runId: string, taskId: string, type: RunEventType, payload?: Record<string, unknown>): RunEvent;
+/**
+ * Highest `seq` already present in an events.jsonl file (0 for missing/empty).
+ * Legacy lines without seq count by position so a continued log never reuses
+ * a line number an SSE replayer may have already served as a fallback id.
+ */
+export declare function lastSeqInFile(path: string): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAIhE;;;;;;;;;GASG;AACH,qBAAa,QAAQ;IAIjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAlB5B,OAAO,CAAC,OAAO,CAAS;gBAGL,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM;IAC/B;;;;;OAKG;IACc,MAAM,CAAC,GAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,aAAA;IACnD;;;;OAIG;IACc,QAAQ,CAAC,EAAE,MAAM,YAAA;IAMpC;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAIf,6EAA6E;IAC7E,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ;IA0BzE,2FAA2F;IAC3F,OAAO,IAAI;QAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CAgBrD;AAUD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,QAAQ,CAaV;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBlD"}

package/dist/index.js

@@ -0,0 +1,170 @@
+import { RunEvent as RunEventSchema } from "@claudexor/schema";
+import { appendLine, nowIso, readTextSafe, redactSecrets } from "@claudexor/util";
+/**
+ * Append-only JSONL event log for a single run. Terminal output and human
+ * summaries are projections; this file is the canonical event stream.
+ *
+ * Every emitted event carries a monotonic per-run `seq` stamped here — the
+ * durable cursor for SSE resume (Last-Event-ID) and snapshot fencing
+ * (detail.lastSeq). The counter initializes from the existing file tail so a
+ * re-opened log (or an out-of-band appender like the control-api audit
+ * writer) continues the sequence instead of restarting it.
+ */
+export class EventLog {
+    path;
+    runId;
+    taskId;
+    onEmit;
+    threadId;
+    nextSeq;
+    constructor(path, runId, taskId, 
+    /**
+     * Optional in-process sink invoked after each event is persisted. Lets a
+     * long-running service / GUI observe the live RunEvent stream without
+     * tailing the file. The file remains the canonical log; a throwing sink
+     * must never break a run, so sink errors are swallowed.
+     */
+    onEmit, 
+    /**
+     * Thread this run is a turn of, when any. Stamped on every event so the
+     * global event multiplex can route live progress to a chat surface without
+     * a reverse job lookup.
+     */
+    threadId) {
+        this.path = path;
+        this.runId = runId;
+        this.taskId = taskId;
+        this.onEmit = onEmit;
+        this.threadId = threadId;
+        this.nextSeq = lastSeqInFile(path) + 1;
+        activeEventLogs.set(path, this);
+    }
+    /**
+     * Unregister this log as the live writer for its path. Out-of-band
+     * appenders fall back to file-tail stamping afterwards, which is safe once
+     * the owning run is terminal (nobody else holds an in-memory counter).
+     */
+    dispose() {
+        if (activeEventLogs.get(this.path) === this)
+            activeEventLogs.delete(this.path);
+    }
+    /** Append a typed run event. Validates against the schema before writing. */
+    emit(type, payload = {}) {
+        const event = RunEventSchema.parse({
+            seq: this.nextSeq++,
+            ts: nowIso(),
+            run_id: this.runId,
+            task_id: this.taskId,
+            ...(this.threadId ? { thread_id: this.threadId } : {}),
+            type,
+            payload: redactEventValue(payload),
+        });
+        appendLine(this.path, JSON.stringify(event));
+        if (this.onEmit) {
+            try {
+                this.onEmit(event);
+            }
+            catch {
+                /* sink errors must never break the canonical run */
+            }
+        }
+        // Terminal events are emitted exactly once, last (output.ready invariant
+        // tests pin this). Self-disposing here hands the seq space back to
+        // file-tail appenders without requiring every orchestrator mode to
+        // remember a finally block.
+        if (type === "run.completed" || type === "run.failed" || type === "run.blocked")
+            this.dispose();
+        return event;
+    }
+    /** Read and parse all events (skipping malformed lines, which are surfaced separately). */
+    readAll() {
+        const text = readTextSafe(this.path);
+        if (text === null)
+            return { events: [], malformed: 0 };
+        const events = [];
+        let malformed = 0;
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                events.push(RunEventSchema.parse(JSON.parse(trimmed)));
+            }
+            catch {
+                malformed += 1;
+            }
+        }
+        return { events, malformed };
+    }
+}
+/**
+ * Live writers by events.jsonl path (one daemon process hosts the
+ * orchestrator AND the control API). While a run is active its EventLog owns
+ * the in-memory seq counter; any other same-process appender stamping from
+ * the file tail would duplicate ids the moment the live counter is ahead.
+ */
+const activeEventLogs = new Map();
+/**
+ * Append an out-of-band event (e.g. a control-api audit record) into a run's
+ * canonical log WITHOUT corrupting the seq space: routes through the live
+ * EventLog when the run is still active (same counter, same onEmit sink), and
+ * falls back to file-tail stamping for terminal runs.
+ */
+export function appendRunEvent(path, runId, taskId, type, payload = {}) {
+    const live = activeEventLogs.get(path);
+    if (live)
+        return live.emit(type, payload);
+    const event = RunEventSchema.parse({
+        seq: lastSeqInFile(path) + 1,
+        ts: nowIso(),
+        run_id: runId,
+        task_id: taskId,
+        type,
+        payload: redactEventValue(payload),
+    });
+    appendLine(path, JSON.stringify(event));
+    return event;
+}
+/**
+ * Highest `seq` already present in an events.jsonl file (0 for missing/empty).
+ * Legacy lines without seq count by position so a continued log never reuses
+ * a line number an SSE replayer may have already served as a fallback id.
+ */
+export function lastSeqInFile(path) {
+    const text = readTextSafe(path);
+    if (text === null)
+        return 0;
+    let last = 0;
+    let lineNo = 0;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        lineNo += 1;
+        try {
+            const parsed = JSON.parse(trimmed);
+            const seq = typeof parsed.seq === "number" && Number.isFinite(parsed.seq) ? parsed.seq : lineNo;
+            if (seq > last)
+                last = seq;
+        }
+        catch {
+            if (lineNo > last)
+                last = lineNo;
+        }
+    }
+    return last;
+}
+function redactEventValue(value) {
+    if (typeof value === "string")
+        return redactSecrets(value);
+    if (Array.isArray(value))
+        return value.map(redactEventValue);
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        out[key] = redactEventValue(child);
+    }
+    return out;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;GASG;AACH,MAAM,OAAO,QAAQ;IAIA;IACA;IACA;IAOA;IAMA;IAlBX,OAAO,CAAS;IAExB,YACmB,IAAY,EACZ,KAAa,EACb,MAAc;IAC/B;;;;;OAKG;IACc,MAAkC;IACnD;;;;OAIG;IACc,QAAiB;QAfjB,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAQ;QACb,WAAM,GAAN,MAAM,CAAQ;QAOd,WAAM,GAAN,MAAM,CAA4B;QAMlC,aAAQ,GAAR,QAAQ,CAAS;QAElC,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,OAAO;QACL,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI;YAAE,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjF,CAAC;IAED,6EAA6E;IAC7E,IAAI,CAAC,IAAkB,EAAE,UAAmC,EAAE;QAC5D,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC;YACjC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE;YACnB,EAAE,EAAE,MAAM,EAAE;YACZ,MAAM,EAAE,IAAI,CAAC,KAAK;YAClB,OAAO,EAAE,IAAI,CAAC,MAAM;YACpB,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtD,IAAI;YACJ,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC;SACnC,CAAC,CAAC;QACH,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7C,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;YAAC,MAAM,CAAC;gBACP,oDAAoD;YACtD,CAAC;QACH,CAAC;QACD,yEAAyE;QACzE,mEAAmE;QACnE,mEAAmE;QACnE,4BAA4B;QAC5B,IAAI,IAAI,KAAK,eAAe,IAAI,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,aAAa;YAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAChG,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2FAA2F;IAC3F,OAAO;QACL,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;QACvD,MAAM,MAAM,GAAe,EAAE,CAAC;QAC9B,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO;gBAAE,SAAS;YACvB,IAAI,CAAC;gBACH,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACzD,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS,IAAI,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC/B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,EAAoB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,KAAa,EACb,MAAc,EACd,IAAkB,EAClB,UAAmC,EAAE;IAErC,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC;QACjC,GAAG,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QAC5B,EAAE,EAAE,MAAM,EAAE;QACZ,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,MAAM;QACf,IAAI;QACJ,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC;KACnC,CAAC,CAAC;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACxC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC;IAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,MAAM,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAsB,CAAC;YACxD,MAAM,GAAG,GAAG,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;YAChG,IAAI,GAAG,GAAG,IAAI;gBAAE,IAAI,GAAG,GAAG,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,MAAM,GAAG,IAAI;gBAAE,IAAI,GAAG,MAAM,CAAC;QACnC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC7D,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@claudexor/event-log",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Append-only JSONL run-event log (a projection-friendly evidence ledger).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@claudexor/schema": "1.0.0",
+    "@claudexor/util": "1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/razzant/claudexor.git",
+    "directory": "packages/event-log"
+  },
+  "homepage": "https://github.com/razzant/claudexor#readme",
+  "bugs": {
+    "url": "https://github.com/razzant/claudexor/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}