@termfleet/core 0.1.0

package/dist/agent-session-tail.js

@@ -0,0 +1,184 @@
+import { open, readFile, stat } from "node:fs/promises";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import { codexTranscriptPath, createClaudeSessionParser, emptyClaudeSession, listLocalAgentSubagents, parseCodexSessionJsonl, parseSubagentSessionId, resolveClaudeSubagentTranscriptPath, resolveClaudeTranscriptPath } from "./agent-session.js";
+// How many transcript lines are parsed between yields back to the event
+// loop. Keeps a multi-megabyte initial catch-up from starving sockets.
+const linesPerSlice = 1_000;
+const newlineByte = 0x0a;
+// How many trailing consumed bytes are remembered to detect in-place
+// rewrites: if the bytes immediately before our offset no longer match, the
+// file is not the one we parsed and the tail replays from the start. JSONL
+// lines share structural suffixes, so the anchor must outspan them.
+const anchorBytes = 64;
+// Incrementally tails one Claude transcript: each read() consumes only the
+// bytes appended since the previous read and feeds complete lines into a
+// persistent parser. Truncation, rotation, or an in-place rewrite resets the
+// parser and replays from the start. Reads must not run concurrently for the
+// same tail; the session watcher's read queue serializes them.
+export class ClaudeTranscriptTail {
+    options;
+    offset = 0;
+    pendingTail = Buffer.alloc(0);
+    anchor = Buffer.alloc(0);
+    parser;
+    totalLines = 0;
+    cached;
+    lastIno;
+    lastMtimeMs;
+    constructor(options) {
+        this.options = options;
+        this.parser = createClaudeSessionParser(options);
+    }
+    get transcriptPath() {
+        return this.options.transcriptPath;
+    }
+    reset() {
+        this.offset = 0;
+        this.pendingTail = Buffer.alloc(0);
+        this.anchor = Buffer.alloc(0);
+        this.parser = createClaudeSessionParser(this.options);
+        this.totalLines = 0;
+        this.cached = undefined;
+    }
+    async read() {
+        const fileStat = await stat(this.options.transcriptPath);
+        // Three rewrite/rotation signals, cheapest first: the file shrank, the
+        // inode changed (file replaced at the same path), or the mtime moved
+        // without the file growing (in-place rewrite to the same or smaller
+        // size). Appends grow the file, so they never trip the third check.
+        const rotated = this.lastIno !== undefined && fileStat.ino !== this.lastIno;
+        const rewrittenInPlace = this.lastMtimeMs !== undefined
+            && fileStat.mtimeMs !== this.lastMtimeMs
+            && fileStat.size <= this.offset;
+        if (fileStat.size < this.offset || rotated || rewrittenInPlace) {
+            this.reset();
+        }
+        let consumedLines = 0;
+        let handle;
+        try {
+            if (this.offset > 0 || fileStat.size > 0) {
+                handle = await open(this.options.transcriptPath, "r");
+            }
+            if (handle && this.offset > 0 && this.anchor.length > 0) {
+                const check = await readAt(handle, this.offset - this.anchor.length, this.anchor.length);
+                if (!check.equals(this.anchor)) {
+                    // The file at this path no longer contains what we parsed
+                    // (rotation or in-place rewrite that did not shrink it).
+                    this.reset();
+                }
+            }
+            if (handle && fileStat.size > this.offset) {
+                const appended = await readAt(handle, this.offset, fileStat.size - this.offset);
+                this.offset += appended.length;
+                const combined = this.pendingTail.length > 0 ? Buffer.concat([this.pendingTail, appended]) : appended;
+                const lastNewline = combined.lastIndexOf(newlineByte);
+                // Lines are only decoded once complete: a chunk may end mid-codepoint,
+                // so the bytes after the final newline stay buffered as bytes.
+                this.pendingTail = lastNewline === -1 ? combined : Buffer.from(combined.subarray(lastNewline + 1));
+                this.anchor = Buffer.from(combined.subarray(Math.max(0, combined.length - anchorBytes)));
+                if (lastNewline !== -1) {
+                    const lines = combined.subarray(0, lastNewline).toString("utf8").split("\n");
+                    for (const line of lines) {
+                        this.parser.feedLine(line);
+                        consumedLines += 1;
+                        if (consumedLines % linesPerSlice === 0) {
+                            await yieldToEventLoop();
+                        }
+                    }
+                    this.totalLines += consumedLines;
+                }
+            }
+        }
+        finally {
+            await handle?.close();
+        }
+        this.lastIno = fileStat.ino;
+        this.lastMtimeMs = fileStat.mtimeMs;
+        if (consumedLines === 0 && this.cached) {
+            return { consumedLines, ...this.cached };
+        }
+        const details = this.parser.finalize();
+        const signature = [
+            "tail",
+            this.totalLines,
+            details.messages.length,
+            details.timeline.length,
+            details.lastMessage?.timestamp ?? ""
+        ].join(":");
+        this.cached = { details, signature };
+        return { consumedLines, details, signature };
+    }
+}
+async function readAt(handle, offset, length) {
+    const buffer = Buffer.allocUnsafe(length);
+    let filled = 0;
+    while (filled < length) {
+        const { bytesRead } = await handle.read(buffer, filled, length - filled, offset + filled);
+        if (bytesRead === 0) {
+            break;
+        }
+        filled += bytesRead;
+    }
+    return filled === length ? buffer : buffer.subarray(0, filled);
+}
+// Tails are cached per session+transcript so repeated reads stay O(appended
+// bytes). The cache is bounded: least-recently-used tails are dropped and
+// simply re-parse from the start if read again — the deterministic signature
+// keeps that replay from re-publishing identical content.
+const maxCachedTails = 64;
+const tailCache = new Map();
+function cachedTail(options) {
+    const key = `${options.sessionId}\0${options.transcriptPath}`;
+    const existing = tailCache.get(key);
+    if (existing) {
+        tailCache.delete(key);
+        tailCache.set(key, existing);
+        return existing;
+    }
+    const tail = new ClaudeTranscriptTail(options);
+    tailCache.set(key, tail);
+    if (tailCache.size > maxCachedTails) {
+        const oldest = tailCache.keys().next().value;
+        if (oldest !== undefined) {
+            tailCache.delete(oldest);
+        }
+    }
+    return tail;
+}
+export function clearAgentSessionTailCache() {
+    tailCache.clear();
+}
+export async function readLocalAgentSessionTailed(options) {
+    if (options.sessionId.startsWith("codex:")) {
+        const transcriptPath = codexTranscriptPath(options);
+        if (!transcriptPath) {
+            throw new Error(`Codex session transcript was not found for ${options.sessionId} in ${options.cwd}`);
+        }
+        const jsonl = await readFile(transcriptPath, "utf8");
+        return { details: parseCodexSessionJsonl({ jsonl, sessionId: options.sessionId, transcriptPath }) };
+    }
+    // A subagent sidechain, addressed by its composite id: tail its file directly
+    // (no nested subagents to list).
+    const subagentRef = parseSubagentSessionId(options.sessionId);
+    if (subagentRef) {
+        const subagentPath = resolveClaudeSubagentTranscriptPath({ ...(options.home ? { home: options.home } : {}), ...subagentRef });
+        const subagentTail = cachedTail({ sessionId: options.sessionId, transcriptPath: subagentPath });
+        const { details, signature } = await subagentTail.read();
+        return { details, signature };
+    }
+    // Resolution runs on every read: if the transcript moved, the stale tail is
+    // abandoned and a fresh one replays the new file.
+    const transcriptPath = resolveClaudeTranscriptPath(options);
+    if (!transcriptPath) {
+        // A just-launched agent with no transcript yet is a live, empty chat — not a
+        // failure. Once it writes messages, the next tailed read resolves and replays.
+        return { details: emptyClaudeSession(options) };
+    }
+    const tail = cachedTail({ sessionId: options.sessionId, transcriptPath });
+    const { details, signature } = await tail.read();
+    // Re-list subagents on every read (metadata only) so a live chat surfaces
+    // subagents as they spawn — the tailed message signature wouldn't otherwise
+    // change when only a new sidechain file appears.
+    const subagents = listLocalAgentSubagents({ ...(options.home ? { home: options.home } : {}), sessionId: options.sessionId, transcriptPath });
+    return { details: subagents.length ? { ...details, subagents } : details, signature };
+}

package/dist/agent-session-watcher.d.ts

@@ -0,0 +1,36 @@
+import type { AgentSessionReadResult } from "./agent-session-tail.js";
+import type { AgentSessionDetails } from "./agent-session.js";
+export type AgentSessionWatchOptions = {
+    cwd?: string;
+    sessionId: string;
+};
+export type AgentSessionWatchEvent = {
+    details: AgentSessionDetails;
+    sessionId: string;
+    type: "update";
+} | {
+    error: string;
+    sessionId: string;
+    type: "error";
+};
+export type AgentSessionSubscription = {
+    unsubscribe(): void;
+};
+type AgentSessionListener = (event: AgentSessionWatchEvent) => void;
+type AgentSessionReader = (options: AgentSessionWatchOptions) => AgentSessionDetails | AgentSessionReadResult | Promise<AgentSessionDetails | AgentSessionReadResult>;
+export declare class AgentSessionWatcher {
+    private readonly readSession;
+    private readonly entries;
+    constructor(readSession: AgentSessionReader);
+    subscribe(options: AgentSessionWatchOptions, listener: AgentSessionListener): AgentSessionSubscription;
+    close(): void;
+    private unsubscribe;
+    private scheduleRead;
+    private scheduleRetry;
+    private readAndPublish;
+    private watchTranscript;
+    private publish;
+    private closeEntry;
+    private resetWatcher;
+}
+export {};

package/dist/agent-session-watcher.js

@@ -0,0 +1,194 @@
+import { asError } from "@termfleet/core/lib/errors.js";
+import { watch } from "node:fs";
+const initialRetryDelayMs = 1_000;
+const maxRetryDelayMs = 10_000;
+// Transcript reads run one at a time: tailed reads are incremental and yield
+// to the event loop internally, and serializing them keeps two reads from
+// racing on the same transcript tail.
+const pendingReads = [];
+let drainScheduled = false;
+function enqueueSessionRead(task) {
+    pendingReads.push(task);
+    if (!drainScheduled) {
+        drainScheduled = true;
+        setImmediate(() => void drainSessionReads());
+    }
+}
+async function drainSessionReads() {
+    const task = pendingReads.shift();
+    try {
+        await task?.();
+    }
+    finally {
+        if (pendingReads.length > 0) {
+            setImmediate(() => void drainSessionReads());
+        }
+        else {
+            drainScheduled = false;
+        }
+    }
+}
+export class AgentSessionWatcher {
+    readSession;
+    entries = new Map();
+    constructor(readSession) {
+        this.readSession = readSession;
+    }
+    subscribe(options, listener) {
+        const key = watchKey(options);
+        let entry = this.entries.get(key);
+        if (!entry) {
+            entry = {
+                key,
+                listeners: new Set(),
+                options,
+                retryDelayMs: initialRetryDelayMs
+            };
+            this.entries.set(key, entry);
+        }
+        entry.listeners.add(listener);
+        this.scheduleRead(entry, 0);
+        return {
+            unsubscribe: () => {
+                this.unsubscribe(key, listener);
+            }
+        };
+    }
+    close() {
+        for (const entry of this.entries.values()) {
+            this.closeEntry(entry);
+        }
+        this.entries.clear();
+    }
+    unsubscribe(key, listener) {
+        const entry = this.entries.get(key);
+        if (!entry) {
+            return;
+        }
+        entry.listeners.delete(listener);
+        if (entry.listeners.size === 0) {
+            this.closeEntry(entry);
+            this.entries.delete(key);
+        }
+    }
+    scheduleRead(entry, delayMs) {
+        if (entry.listeners.size === 0) {
+            return;
+        }
+        if (entry.debounceTimer) {
+            clearTimeout(entry.debounceTimer);
+        }
+        entry.debounceTimer = setTimeout(() => {
+            entry.debounceTimer = undefined;
+            enqueueSessionRead(() => {
+                if (entry.listeners.size > 0) {
+                    return this.readAndPublish(entry);
+                }
+                return undefined;
+            });
+        }, delayMs);
+    }
+    scheduleRetry(entry) {
+        if (entry.listeners.size === 0 || entry.retryTimer) {
+            return;
+        }
+        const delayMs = entry.retryDelayMs;
+        entry.retryDelayMs = Math.min(entry.retryDelayMs * 2, maxRetryDelayMs);
+        entry.retryTimer = setTimeout(() => {
+            entry.retryTimer = undefined;
+            this.scheduleRead(entry, 0);
+        }, delayMs);
+    }
+    async readAndPublish(entry) {
+        let result;
+        try {
+            const raw = await this.readSession(entry.options);
+            result = "details" in raw ? raw : { details: raw };
+        }
+        catch (error) {
+            const message = asError(error).message;
+            this.resetWatcher(entry);
+            if (entry.error !== message) {
+                entry.error = message;
+                this.publish(entry, { error: message, sessionId: entry.options.sessionId, type: "error" });
+            }
+            this.scheduleRetry(entry);
+            return;
+        }
+        entry.error = undefined;
+        entry.retryDelayMs = initialRetryDelayMs;
+        this.watchTranscript(entry, result.details.transcriptPath);
+        // Tailed reads supply a cheap deterministic content signature; full
+        // re-parse paths fall back to stringifying the details. Either way the
+        // signature is tracked per entry, so entries sharing one tail dedupe
+        // independently instead of starving each other.
+        const signature = result.signature ?? JSON.stringify(result.details);
+        if (entry.lastSignature === signature) {
+            return;
+        }
+        entry.lastSignature = signature;
+        this.publish(entry, { details: result.details, sessionId: entry.options.sessionId, type: "update" });
+    }
+    watchTranscript(entry, transcriptPath) {
+        if (!transcriptPath || entry.transcriptPath === transcriptPath) {
+            return;
+        }
+        entry.watcher?.close();
+        entry.watcher = undefined;
+        try {
+            entry.watcher = watch(transcriptPath, { persistent: false }, (eventType) => {
+                if (eventType === "rename") {
+                    this.resetWatcher(entry);
+                }
+                this.scheduleRead(entry, 100);
+            });
+            entry.watcher.on("error", (error) => {
+                const message = asError(error).message;
+                this.resetWatcher(entry);
+                this.publish(entry, { error: message, sessionId: entry.options.sessionId, type: "error" });
+                this.scheduleRetry(entry);
+            });
+            entry.transcriptPath = transcriptPath;
+        }
+        catch (error) {
+            if (isFileMissing(error)) {
+                // A freshly launched, message-less chat has no transcript file yet, so
+                // watching it directly throws ENOENT — not a user-facing error. Leave
+                // transcriptPath unset and keep polling: the next read resolves the
+                // transcript by id once it is written (which may be under a different
+                // project dir than this caller's cwd implies) and installs the watcher.
+                this.scheduleRetry(entry);
+                return;
+            }
+            const message = asError(error).message;
+            this.resetWatcher(entry);
+            this.publish(entry, { error: message, sessionId: entry.options.sessionId, type: "error" });
+            this.scheduleRetry(entry);
+        }
+    }
+    publish(entry, event) {
+        for (const listener of entry.listeners) {
+            listener(event);
+        }
+    }
+    closeEntry(entry) {
+        if (entry.debounceTimer) {
+            clearTimeout(entry.debounceTimer);
+        }
+        if (entry.retryTimer) {
+            clearTimeout(entry.retryTimer);
+        }
+        entry.watcher?.close();
+    }
+    resetWatcher(entry) {
+        entry.watcher?.close();
+        entry.watcher = undefined;
+        entry.transcriptPath = undefined;
+    }
+}
+function isFileMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function watchKey(options) {
+    return `${options.sessionId}\0${options.cwd ?? ""}`;
+}