@termfleet/core 0.1.0

package/dist/agent-session-index.js

@@ -0,0 +1,527 @@
+import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
+import { agentHome, geminiContentText, isCodexInjectedContext } from "./agent-session.js";
+// Read enough of each end of a transcript to recover the first user message
+// (title) and the last message (preview) without paging in multi-MB files.
+const EDGE_BYTES = 64 * 1024;
+// The directory walk + per-file stat is the bulk of the cost (thousands of
+// files). Cache the sorted candidate list briefly so back-to-back list/paging
+// requests don't re-walk — critical on a busy provider whose synchronous
+// snapshot observation already saturates the event loop and would otherwise
+// starve a from-scratch rebuild past the console proxy's timeout.
+const CANDIDATE_TTL_MS = 20_000;
+const indexCache = new Map();
+const candidateCache = new Map();
+export async function buildAgentSessionIndex(options = {}) {
+    const home = options.home ?? agentHome();
+    const limit = normalizeLimit(options.limit);
+    const offset = normalizeCursor(options.cursor);
+    const query = options.query?.trim().toLowerCase();
+    const candidates = candidatesFor(home, options.nowMs);
+    pruneCache(candidates);
+    // Search scans the full history (not just the page), matching parsed
+    // title/preview/cwd. It parses every candidate — bounded by the per-row
+    // mtime cache, so the first query is the only slow one — and runs in a
+    // worker thread, off the provider event loop.
+    if (query) {
+        const matched = [];
+        for (const candidate of candidates) {
+            const row = rowForCandidate(candidate);
+            if (row && rowMatchesQuery(row, query))
+                matched.push(row);
+        }
+        const page = matched.slice(offset, offset + limit);
+        const nextOffset = offset + page.length;
+        return {
+            nextCursor: nextOffset < matched.length ? String(nextOffset) : null,
+            rows: page,
+            total: matched.length
+        };
+    }
+    // Backfill from later candidates when one drops out (its transcript was reaped
+    // within the candidate cache's lifetime), so a page is never short while more
+    // rows exist — and advance the cursor by candidates CONSUMED, not by row count,
+    // so the next page resumes correctly past the skipped ones.
+    const rows = [];
+    let index = offset;
+    for (; index < candidates.length && rows.length < limit; index++) {
+        const candidate = candidates[index];
+        if (!candidate)
+            continue;
+        const row = rowForCandidate(candidate);
+        if (row)
+            rows.push(row);
+    }
+    return {
+        nextCursor: index < candidates.length ? String(index) : null,
+        rows,
+        total: candidates.length
+    };
+}
+function rowMatchesQuery(row, query) {
+    return row.title.toLowerCase().includes(query)
+        || (row.aiTitle ?? "").toLowerCase().includes(query)
+        || row.preview.toLowerCase().includes(query)
+        || (row.cwd ?? "").toLowerCase().includes(query);
+}
+// Warm the candidate + row caches off the request path (e.g. at provider
+// startup), so the first browser request serves from cache instead of paying
+// the full walk while the event loop is busy.
+export async function warmAgentSessionIndex(options = {}) {
+    await buildAgentSessionIndex({ ...(options.home ? { home: options.home } : {}), limit: 1 });
+}
+function candidatesFor(home, nowMs) {
+    const now = nowMs ?? Date.now();
+    const cached = candidateCache.get(home);
+    if (cached && now - cached.builtAtMs < CANDIDATE_TTL_MS) {
+        return cached.candidates;
+    }
+    const candidates = collectCandidates(home);
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs || a.transcriptPath.localeCompare(b.transcriptPath));
+    candidateCache.set(home, { builtAtMs: now, candidates });
+    return candidates;
+}
+function collectCandidates(home) {
+    const candidates = [];
+    for (const transcriptPath of walkJsonl(join(home, ".claude", "projects"))) {
+        const mtimeMs = mtimeOf(transcriptPath);
+        if (mtimeMs !== undefined)
+            candidates.push({ mtimeMs, provider: "claude", transcriptPath });
+    }
+    for (const transcriptPath of walkJsonl(join(home, ".codex", "sessions"))) {
+        const mtimeMs = mtimeOf(transcriptPath);
+        if (mtimeMs !== undefined)
+            candidates.push({ mtimeMs, provider: "codex", transcriptPath });
+    }
+    // Gemini: one-file-per-session JSONL under ~/.gemini/tmp/<slug>/chats/. The
+    // per-project logs.json is a user-prompt log, not a transcript — walkJsonl skips
+    // it (only *.jsonl). See docs/architecture/gemini-sessions.md.
+    for (const transcriptPath of walkJsonl(join(home, ".gemini", "tmp"))) {
+        const mtimeMs = mtimeOf(transcriptPath);
+        if (mtimeMs !== undefined)
+            candidates.push({ mtimeMs, provider: "gemini", transcriptPath });
+    }
+    return candidates;
+}
+// mtime-keyed: a transcript is only re-read when its file changes, so steady
+// state re-list calls just stat directories and reuse cached rows.
+function rowForCandidate(candidate) {
+    const cached = indexCache.get(candidate.transcriptPath);
+    if (cached && cached.mtimeMs === candidate.mtimeMs) {
+        return cached.row;
+    }
+    const row = parseIndexRow(candidate);
+    if (row) {
+        indexCache.set(candidate.transcriptPath, { mtimeMs: candidate.mtimeMs, row });
+    }
+    return row;
+}
+function parseIndexRow(candidate) {
+    const edges = readEdges(candidate.transcriptPath);
+    if (!edges)
+        return undefined;
+    const { provider } = candidate;
+    const scan = provider === "codex"
+        ? scanCodexEdges(edges.head, edges.tail)
+        : provider === "gemini"
+            ? scanGeminiEdges(edges.head, edges.tail)
+            : scanClaudeEdges(edges.head, edges.tail);
+    // Claude transcript filenames are the session id, so recover it from the path
+    // when the head did not carry one. Codex/Gemini ids live inside the file (Gemini
+    // in its header). Gemini's cwd isn't in the transcript — resolve it from the
+    // tmp/<slug> path via projects.json.
+    const sessionId = scan.sessionId || (provider === "claude" ? basename(candidate.transcriptPath).replace(/\.jsonl$/, "") : "");
+    if (!sessionId)
+        return undefined;
+    const cwd = scan.cwd ?? (provider === "gemini" ? geminiCwdForPath(candidate.transcriptPath) : undefined);
+    const titleText = scan.title || scan.preview;
+    const titleKind = scan.title ? scan.titleKind : scan.previewKind;
+    const subagents = provider === "claude" ? countSubagents(candidate.transcriptPath, sessionId) : undefined;
+    return {
+        ...(scan.aiTitle ? { aiTitle: scan.aiTitle } : {}),
+        ...(cwd ? { cwd } : {}),
+        preview: scan.preview,
+        previewKind: scan.previewKind,
+        previewRole: scan.previewRole,
+        provider,
+        sessionId: `${provider}:${sessionId}`,
+        ...(subagents ? { subagents } : {}),
+        title: titleText,
+        titleKind,
+        transcriptPath: candidate.transcriptPath,
+        updatedAt: new Date(candidate.mtimeMs).toISOString()
+    };
+}
+// Claude stores each Task-tool subagent transcript at
+// <project>/<sessionId>/subagents/agent-*.jsonl. Count those files (by name,
+// no content read) so the list can show a session's fan-out. Re-counted only
+// when the parent transcript's mtime changes (it bumps whenever a Task spawns),
+// which keeps the count fresh without a content read or its own walk.
+function countSubagents(transcriptPath, sessionId) {
+    const dir = join(dirname(transcriptPath), sessionId, "subagents");
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    let count = 0;
+    for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith(".jsonl"))
+            count += 1;
+    }
+    return count > 0 ? { count } : undefined;
+}
+function scanClaudeEdges(head, tail) {
+    let sessionId = "";
+    let cwd;
+    let title = "";
+    let titleKind = "message";
+    let aiTitle;
+    for (const entry of parseLines(head)) {
+        if (!sessionId && typeof entry.sessionId === "string")
+            sessionId = entry.sessionId;
+        if (!cwd && typeof entry.cwd === "string")
+            cwd = entry.cwd;
+        if (entry.type === "ai-title" && typeof entry.aiTitle === "string" && entry.aiTitle.trim()) {
+            aiTitle = entry.aiTitle.trim();
+        }
+        if (title || entry.type !== "user")
+            continue;
+        const message = entry.message;
+        if (!message || typeof message !== "object" || Array.isArray(message))
+            continue;
+        // The first turn is often a slash command or injected context. That is a
+        // real message — classify it (command / context / message) so the list can
+        // style it, never discard it as "not real".
+        const raw = claudeMessageText(message.content, true);
+        if (raw) {
+            const classified = classifyMessage(raw);
+            title = classified.text;
+            titleKind = classified.kind;
+        }
+    }
+    let preview = "";
+    let previewKind = "message";
+    let previewRole = "assistant";
+    for (const entry of parseLines(tail)) {
+        if (entry.type === "ai-title" && typeof entry.aiTitle === "string" && entry.aiTitle.trim()) {
+            aiTitle = entry.aiTitle.trim();
+        }
+        if (entry.type !== "assistant" && entry.type !== "user")
+            continue;
+        const role = entry.type;
+        const message = entry.message;
+        if (!message || typeof message !== "object" || Array.isArray(message))
+            continue;
+        const raw = claudeMessageText(message.content, role === "user");
+        if (!raw)
+            continue;
+        const classified = classifyMessage(raw);
+        preview = classified.text;
+        previewKind = classified.kind;
+        previewRole = role;
+    }
+    return { ...(aiTitle ? { aiTitle } : {}), ...(cwd ? { cwd } : {}), preview, previewKind, previewRole, sessionId, title, titleKind };
+}
+function scanCodexEdges(head, tail) {
+    let sessionId = "";
+    let cwd;
+    let title = "";
+    let titleKind = "message";
+    for (const entry of parseLines(head)) {
+        const payload = entry.payload && typeof entry.payload === "object" ? entry.payload : undefined;
+        if (entry.type === "session_meta" && payload) {
+            if (typeof payload.id === "string")
+                sessionId = payload.id;
+            if (typeof payload.cwd === "string")
+                cwd = payload.cwd;
+            continue;
+        }
+        if (title || !payload)
+            continue;
+        if (codexMessageRole(entry, payload) === "user") {
+            const raw = codexMessageText(entry, payload);
+            // Codex prepends synthetic user turns (AGENTS.md instructions, the
+            // environment context block) before the real first human message. Skip
+            // them so the title is the human's opening line, not harness boilerplate.
+            if (raw && !isCodexInjectedContext(raw)) {
+                const classified = classifyMessage(raw);
+                title = classified.text;
+                titleKind = classified.kind;
+            }
+        }
+    }
+    let preview = "";
+    let previewKind = "message";
+    let previewRole = "assistant";
+    for (const entry of parseLines(tail)) {
+        const payload = entry.payload && typeof entry.payload === "object" ? entry.payload : undefined;
+        if (!payload)
+            continue;
+        const role = codexMessageRole(entry, payload);
+        if (!role)
+            continue;
+        const raw = codexMessageText(entry, payload);
+        if (!raw)
+            continue;
+        const classified = classifyMessage(raw);
+        preview = classified.text;
+        previewKind = classified.kind;
+        previewRole = role;
+    }
+    return { ...(cwd ? { cwd } : {}), preview, previewKind, previewRole, sessionId, title, titleKind };
+}
+// Claude Code wraps slash commands and injected context in XML-ish tags. We
+// keep the inner text (a `/pm` command, a caveat — all real conversation) and
+// only drop the tag markers so the one-line title/preview reads cleanly.
+const WRAPPER_TAGS = /<\/?(?:system-reminder|local-command-caveat|local-command-stdout|local-command-stderr|command-name|command-message|command-args|command-contents|bash-input|bash-stdout|bash-stderr)>/g;
+function unwrapTags(text) {
+    return text.replace(WRAPPER_TAGS, " ").replace(/\s+/g, " ").trim();
+}
+const CONTEXT_BLOCKS = /<(system-reminder|local-command-caveat|local-command-stdout|local-command-stderr)>[\s\S]*?<\/\1>/g;
+// Classify a message into command / injected-context / real-message and produce
+// its display text. A slash command shows its name+args; pure injected context
+// shows its unwrapped text; a human message with some injected context shows the
+// human part. Mirrors the client copy in frontend/agent-chat/conversation-index.
+function classifyMessage(raw) {
+    const commandName = innerTag(raw, "command-name");
+    const commandMessage = innerTag(raw, "command-message");
+    const commandArgs = innerTag(raw, "command-args");
+    if (commandName || commandMessage || commandArgs) {
+        const text = [commandName || commandMessage, commandArgs].filter(Boolean).join(" ").replace(/\s+/g, " ").trim();
+        return { kind: "command", text: text || unwrapTags(raw) };
+    }
+    const human = unwrapTags(raw.replace(CONTEXT_BLOCKS, " "));
+    if (human)
+        return { kind: "message", text: human };
+    return { kind: "context", text: unwrapTags(raw) };
+}
+function innerTag(raw, tag) {
+    const match = raw.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`));
+    return match?.[1]?.replace(/\s+/g, " ").trim() ?? "";
+}
+// Only text blocks count as conversational, matching the transcript parser:
+// tool calls and results never become titles or previews.
+function claudeMessageText(content, userOnly) {
+    if (typeof content === "string")
+        return content.trim();
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const record = block;
+        if (record.type !== "text") {
+            // A user turn that carries a tool_result is not a real user message.
+            if (userOnly)
+                return "";
+            continue;
+        }
+        if (typeof record.text === "string" && record.text.trim())
+            parts.push(record.text);
+    }
+    return parts.join("\n\n").trim();
+}
+function codexMessageRole(entry, payload) {
+    if (entry.type === "response_item" && payload.type === "message") {
+        const role = typeof payload.role === "string" ? payload.role : "assistant";
+        if (role === "user")
+            return "user";
+        if (role === "assistant")
+            return "assistant";
+        return undefined;
+    }
+    if (entry.type === "event_msg") {
+        if (payload.type === "user_message")
+            return "user";
+        if (payload.type === "agent_message")
+            return "assistant";
+    }
+    return undefined;
+}
+function codexMessageText(entry, payload) {
+    if (entry.type === "event_msg") {
+        return typeof payload.message === "string" ? payload.message.trim() : "";
+    }
+    const content = payload.content;
+    if (typeof content === "string")
+        return content.trim();
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((item) => (item && typeof item === "object" && typeof item.text === "string"
+        ? item.text
+        : ""))
+        .filter(Boolean)
+        .join("\n\n")
+        .trim();
+}
+// A tail slice can begin mid-line; parse failures on the partial first line are
+// simply skipped.
+// Gemini transcript edge scan. Header line carries sessionId; user messages have
+// content:[{text}], gemini messages have content:<string>; $set/info lines skipped.
+// cwd is NOT in the transcript (resolved from the tmp/<slug> path in parseIndexRow).
+function scanGeminiEdges(head, tail) {
+    let sessionId = "";
+    let title = "";
+    let titleKind = "message";
+    for (const entry of parseLines(head)) {
+        if (!sessionId && typeof entry.sessionId === "string")
+            sessionId = entry.sessionId;
+        if (title || entry.type !== "user")
+            continue;
+        const raw = geminiContentText(entry.content);
+        if (raw) {
+            const classified = classifyMessage(raw);
+            title = classified.text;
+            titleKind = classified.kind;
+        }
+    }
+    let preview = "";
+    let previewKind = "message";
+    let previewRole = "assistant";
+    for (const entry of parseLines(tail)) {
+        if (entry.type !== "user" && entry.type !== "gemini")
+            continue;
+        const raw = geminiContentText(entry.content);
+        if (!raw)
+            continue;
+        const classified = classifyMessage(raw);
+        preview = classified.text;
+        previewKind = classified.kind;
+        previewRole = entry.type === "user" ? "user" : "assistant";
+    }
+    return { preview, previewKind, previewRole, sessionId, title, titleKind };
+}
+// Gemini stores cwd→slug in ~/.gemini/projects.json; reverse it to label a
+// transcript (…/.gemini/tmp/<slug>/chats/…) with its working directory. Cached per
+// .gemini dir (projects.json changes rarely).
+const geminiProjectsCache = new Map();
+function geminiCwdForPath(transcriptPath) {
+    const marker = `${sep}.gemini${sep}tmp${sep}`;
+    const at = transcriptPath.indexOf(marker);
+    if (at < 0)
+        return undefined;
+    const slug = transcriptPath.slice(at + marker.length).split(sep)[0];
+    if (!slug)
+        return undefined;
+    return geminiSlugToCwd(`${transcriptPath.slice(0, at)}${sep}.gemini`)[slug];
+}
+function geminiSlugToCwd(geminiDir) {
+    const cached = geminiProjectsCache.get(geminiDir);
+    if (cached)
+        return cached;
+    const slugToCwd = {};
+    try {
+        const raw = JSON.parse(readFileSync(join(geminiDir, "projects.json"), "utf8"));
+        const projects = raw.projects;
+        if (projects && typeof projects === "object") {
+            for (const [cwd, slug] of Object.entries(projects)) {
+                if (typeof slug === "string")
+                    slugToCwd[slug] = cwd;
+            }
+        }
+    }
+    catch { /* no projects.json — gemini rows just lack cwd */ }
+    geminiProjectsCache.set(geminiDir, slugToCwd);
+    return slugToCwd;
+}
+function* parseLines(text) {
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            yield JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+    }
+}
+function readEdges(transcriptPath) {
+    let fd;
+    try {
+        fd = openSync(transcriptPath, "r");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const size = statSync(transcriptPath).size;
+        const head = readSlice(fd, 0, Math.min(EDGE_BYTES, size));
+        if (size <= EDGE_BYTES) {
+            return { head, tail: head };
+        }
+        return { head, tail: readSlice(fd, size - EDGE_BYTES, EDGE_BYTES) };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readSlice(fd, position, length) {
+    if (length <= 0)
+        return "";
+    const buffer = Buffer.alloc(length);
+    const bytesRead = readSync(fd, buffer, 0, length, position);
+    return buffer.toString("utf8", 0, bytesRead);
+}
+function mtimeOf(transcriptPath) {
+    try {
+        return statSync(transcriptPath).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pruneCache(candidates) {
+    const seen = new Set(candidates.map((candidate) => candidate.transcriptPath));
+    for (const key of indexCache.keys()) {
+        if (!seen.has(key))
+            indexCache.delete(key);
+    }
+}
+function normalizeLimit(limit) {
+    if (limit === undefined)
+        return 50;
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new Error("Agent session index limit must be a positive integer.");
+    }
+    return Math.min(limit, 200);
+}
+function normalizeCursor(cursor) {
+    if (cursor === undefined || cursor === null || cursor === "")
+        return 0;
+    const offset = Number(cursor);
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new Error(`Invalid agent session index cursor: ${cursor}`);
+    }
+    return offset;
+}
+function* walkJsonl(root) {
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory()) {
+            // Claude writes Task-tool subagent transcripts under
+            // <session>/subagents/agent-*.jsonl. They are sidechains, not resumable
+            // sessions, and they carry the PARENT session id — so indexing them
+            // collides on the dedup key and overwrites the real session's row with a
+            // subagent's older mtime and prompt. Never treat them as candidates.
+            if (entry.name === "subagents")
+                continue;
+            yield* walkJsonl(path);
+        }
+        else if (entry.isFile() && path.endsWith(".jsonl")) {
+            yield path;
+        }
+    }
+}

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

@@ -0,0 +1,33 @@
+import { type AgentSessionDetails, type ClaudeAgentSessionDetails } from "./agent-session.js";
+export type AgentSessionReadResult = {
+    details: AgentSessionDetails;
+    signature?: string;
+};
+export declare class ClaudeTranscriptTail {
+    private readonly options;
+    private offset;
+    private pendingTail;
+    private anchor;
+    private parser;
+    private totalLines;
+    private cached?;
+    private lastIno?;
+    private lastMtimeMs?;
+    constructor(options: {
+        sessionId: string;
+        transcriptPath: string;
+    });
+    get transcriptPath(): string;
+    private reset;
+    read(): Promise<{
+        consumedLines: number;
+        details: ClaudeAgentSessionDetails;
+        signature: string;
+    }>;
+}
+export declare function clearAgentSessionTailCache(): void;
+export declare function readLocalAgentSessionTailed(options: {
+    cwd: string;
+    home?: string;
+    sessionId: string;
+}): Promise<AgentSessionReadResult>;