@tea-agent/loop-agent 0.11.0 → 0.12.0

package/dist/worker/observability/event-history.js

@@ -0,0 +1,216 @@
+import { open as openFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { getTaskPoolRoot } from "../pool/run-store.js";
+import { isSafeObservabilityIdentifier } from "./event-store.js";
+import { parseWorkerEventLine } from "./events.js";
+/** History REST page size defaults (distinct from Task run history 20/100 and SSE line offsets). */
+export const EVENT_HISTORY_DEFAULT_LIMIT = 50;
+export const EVENT_HISTORY_MAX_LIMIT = 200;
+/** Hard cap on bytes scanned from the end of a JSONL history file (AC-R4-02). */
+export const EVENT_HISTORY_MAX_SCAN_BYTES = 4 * 1024 * 1024;
+const CURSOR_PREFIX = "v1.";
+export function clampEventHistoryLimit(limit) {
+    if (limit === undefined || limit === null || !Number.isFinite(limit)) {
+        return EVENT_HISTORY_DEFAULT_LIMIT;
+    }
+    const n = Math.trunc(Number(limit));
+    if (!Number.isFinite(n) || n < 1)
+        return EVENT_HISTORY_DEFAULT_LIMIT;
+    if (n > EVENT_HISTORY_MAX_LIMIT)
+        return EVENT_HISTORY_MAX_LIMIT;
+    return n;
+}
+export function encodeEventHistoryCursor(beforeByte) {
+    const payload = Buffer.from(JSON.stringify({ b: Math.max(0, Math.trunc(beforeByte)) }), "utf-8").toString("base64url");
+    return `${CURSOR_PREFIX}${payload}`;
+}
+export function decodeEventHistoryCursor(cursor) {
+    if (cursor === undefined || cursor === null || cursor === "")
+        return null;
+    if (!cursor.startsWith(CURSOR_PREFIX))
+        return null;
+    try {
+        const raw = Buffer.from(cursor.slice(CURSOR_PREFIX.length), "base64url").toString("utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            Array.isArray(parsed) ||
+            !("b" in parsed)) {
+            return null;
+        }
+        const b = parsed.b;
+        if (typeof b !== "number" || !Number.isFinite(b) || b < 0)
+            return null;
+        return { beforeByte: Math.trunc(b) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Pool global observability events (newest-first page).
+ * History cursor semantics: `cursor` / `nextCursor` are opaque; do not confuse with
+ * SSE/run `after` integer line offsets.
+ */
+export async function listPoolEventHistory(repoRoot, options = {}) {
+    const filePath = path.join(getTaskPoolRoot(path.resolve(repoRoot)), "observability", "events.jsonl");
+    return readEventHistoryFile(filePath, options);
+}
+/**
+ * Batch-scoped observability events under observability/batches/<id>/events.jsonl.
+ */
+export async function listBatchEventHistory(repoRoot, batchRunId, options = {}) {
+    const limit = clampEventHistoryLimit(options.limit);
+    if (!isSafeObservabilityIdentifier(batchRunId)) {
+        return {
+            events: [],
+            limit,
+            source: "missing",
+            ...(options.cursor ? { cursor: options.cursor } : {}),
+        };
+    }
+    const filePath = path.join(getTaskPoolRoot(path.resolve(repoRoot)), "observability", "batches", batchRunId, "events.jsonl");
+    return readEventHistoryFile(filePath, options);
+}
+/**
+ * Bounded tail scan of a JSONL events file. Does not load the entire file into memory
+ * or split unbounded content: reads at most EVENT_HISTORY_MAX_SCAN_BYTES from the end
+ * (or from before the cursor window).
+ */
+export async function readEventHistoryFile(filePath, options = {}) {
+    const limit = clampEventHistoryLimit(options.limit);
+    const inputCursor = typeof options.cursor === "string" && options.cursor.length > 0
+        ? options.cursor
+        : undefined;
+    const decoded = decodeEventHistoryCursor(inputCursor);
+    let fileSize;
+    try {
+        const s = await stat(filePath);
+        if (!s.isFile()) {
+            return emptyPage(limit, inputCursor, "missing");
+        }
+        fileSize = s.size;
+    }
+    catch {
+        return emptyPage(limit, inputCursor, "missing");
+    }
+    if (fileSize === 0) {
+        return emptyPage(limit, inputCursor, "ok");
+    }
+    const beforeByte = decoded !== null ? Math.min(decoded.beforeByte, fileSize) : fileSize;
+    if (beforeByte <= 0) {
+        return emptyPage(limit, inputCursor, "ok");
+    }
+    const scanEnd = beforeByte;
+    const scanStart = Math.max(0, scanEnd - EVENT_HISTORY_MAX_SCAN_BYTES);
+    const truncated = scanStart > 0;
+    const { lines } = await readBoundedJsonlTail(filePath, {
+        beforeByte,
+        maxBytes: EVENT_HISTORY_MAX_SCAN_BYTES,
+    });
+    const parsed = [];
+    let corruptLineCount = 0;
+    for (const line of lines) {
+        if (line.startByte >= beforeByte)
+            continue;
+        const event = parseWorkerEventLine(line.text);
+        if (!event) {
+            corruptLineCount += 1;
+            continue;
+        }
+        parsed.push({ event, startByte: line.startByte });
+    }
+    // Newest first within the scanned window (file order is chronological append).
+    parsed.reverse();
+    const pageItems = parsed.slice(0, limit);
+    const hasMoreInScan = parsed.length > limit;
+    const oldest = pageItems[pageItems.length - 1];
+    const continuationByte = oldest?.startByte ?? lines[0]?.startByte ?? (truncated ? scanStart : undefined);
+    const nextCursor = continuationByte !== undefined && (hasMoreInScan || truncated)
+        ? encodeEventHistoryCursor(continuationByte)
+        : undefined;
+    return {
+        events: pageItems.map((item) => item.event),
+        limit,
+        source: "ok",
+        ...(inputCursor ? { cursor: inputCursor } : {}),
+        ...(nextCursor ? { nextCursor } : {}),
+        ...(truncated ? { truncated: true } : {}),
+        ...(corruptLineCount > 0 ? { corruptLineCount } : {}),
+    };
+}
+function emptyPage(limit, cursor, source) {
+    return {
+        events: [],
+        limit,
+        source,
+        ...(cursor ? { cursor } : {}),
+    };
+}
+export async function readBoundedJsonlTail(filePath, options = {}) {
+    let fileSize;
+    try {
+        const s = await stat(filePath);
+        if (!s.isFile())
+            return { lines: [], truncated: false };
+        fileSize = s.size;
+    }
+    catch {
+        return { lines: [], truncated: false };
+    }
+    const scanEnd = Math.min(options.beforeByte ?? fileSize, fileSize);
+    if (scanEnd <= 0)
+        return { lines: [], truncated: false };
+    const maxBytes = Math.max(1, options.maxBytes ?? EVENT_HISTORY_MAX_SCAN_BYTES);
+    const scanStart = Math.max(0, scanEnd - maxBytes);
+    const buffer = Buffer.alloc(scanEnd - scanStart);
+    const handle = await openFile(filePath, "r");
+    let bytesRead = 0;
+    try {
+        ({ bytesRead } = await handle.read(buffer, 0, buffer.length, scanStart));
+    }
+    finally {
+        await handle.close();
+    }
+    let lines = splitCompleteLines(buffer.subarray(0, bytesRead), scanStart, scanStart > 0, scanEnd < fileSize);
+    const maxLines = options.maxLines;
+    const lineTruncated = maxLines !== undefined && lines.length > maxLines;
+    if (lineTruncated) {
+        lines = lines.slice(-maxLines);
+    }
+    return {
+        lines,
+        truncated: scanStart > 0 || lineTruncated,
+    };
+}
+/**
+ * Split a byte window into complete UTF-8 lines with absolute start offsets.
+ * When truncated from the left, drop the first partial line.
+ */
+function splitCompleteLines(chunk, chunkStartByte, leftTruncated, rightTruncated) {
+    const lines = [];
+    let start = 0;
+    if (leftTruncated) {
+        const firstNl = chunk.indexOf(0x0a);
+        if (firstNl < 0)
+            return [];
+        start = firstNl + 1;
+    }
+    while (start < chunk.length) {
+        const nl = chunk.indexOf(0x0a, start);
+        if (nl < 0 && rightTruncated)
+            break;
+        const end = nl < 0 ? chunk.length : nl;
+        let line = chunk.subarray(start, end);
+        if (line.at(-1) === 0x0d)
+            line = line.subarray(0, line.length - 1);
+        const text = line.toString("utf-8");
+        if (text.trim().length > 0) {
+            lines.push({ text, startByte: chunkStartByte + start });
+        }
+        if (nl < 0)
+            break;
+        start = nl + 1;
+    }
+    return lines;
+}