@groundtrack/hooks 0.1.25 → 0.1.27

package/dist/session-import/discovery.js

@@ -1,45 +1,71 @@
 import { execFileSync } from "node:child_process";
-import { closeSync, existsSync, lstatSync, openSync, readSync, readdirSync, realpathSync, } from "node:fs";
+import { createReadStream, existsSync, lstatSync, readdirSync, realpathSync, statSync, } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
+import { StringDecoder } from "node:string_decoder";
 import { isSessionRecord } from "./canonical.js";
-function initialRecords(path, maxRecords, maxBytes = 1024 * 1024) {
-    const file = openSync(path, "r");
-    try {
-        const chunks = [];
-        let offset = 0;
-        let newlineCount = 0;
-        while (offset < maxBytes && newlineCount < maxRecords) {
-            const chunk = Buffer.alloc(Math.min(64 * 1024, maxBytes - offset));
-            const read = readSync(file, chunk, 0, chunk.length, offset);
-            if (read === 0)
-                break;
-            const bytes = chunk.subarray(0, read);
-            chunks.push(bytes);
-            offset += read;
-            for (const byte of bytes) {
-                if (byte === 10 && ++newlineCount >= maxRecords)
-                    break;
-            }
-        }
-        return Buffer.concat(chunks)
-            .toString("utf8")
-            .split(/\r?\n/, maxRecords)
-            .flatMap((line) => {
-            if (!line.trim())
-                return [];
+import { createSessionDecompressor, isCompressedSession } from "./compression.js";
+async function initialRecords(path, maxRecords, maxBytes = 1024 * 1024) {
+    const input = createReadStream(path);
+    const source = isCompressedSession(path) ? input.pipe(createSessionDecompressor()) : input;
+    // `pipe()` does not forward upstream errors to the destination. Surface them on
+    // the stream being iterated so the catch below handles a vanished or unreadable
+    // file instead of crashing on an unhandled 'error' event.
+    input.on("error", (error) => source.destroy(error));
+    const decoder = new StringDecoder("utf8");
+    const records = [];
+    let pending = "";
+    let lineCount = 0;
+    let bytes = 0;
+    const consume = (line) => {
+        const nextCount = lineCount + 1;
+        const nextBytes = bytes + Buffer.byteLength(line) + 1;
+        if (nextCount > maxRecords || nextBytes > maxBytes)
+            return false;
+        lineCount = nextCount;
+        bytes = nextBytes;
+        if (line.trim()) {
             try {
                 const record = JSON.parse(line);
-                return isSessionRecord(record) ? [record] : [];
+                if (isSessionRecord(record))
+                    records.push(record);
             }
             catch {
-                return [];
+                // Ignore malformed lines, matching the previous behavior.
             }
-        });
+        }
+        return true;
+    };
+    try {
+        for await (const chunk of source) {
+            pending += decoder.write(chunk);
+            let newline = pending.indexOf("\n");
+            while (newline >= 0) {
+                const line = pending.slice(0, newline).replace(/\r$/, "");
+                pending = pending.slice(newline + 1);
+                if (!consume(line))
+                    return records;
+                newline = pending.indexOf("\n");
+            }
+            // Stop before buffering a line that cannot fit in the byte budget.
+            if (bytes + Buffer.byteLength(pending) > maxBytes)
+                return records;
+        }
+        pending += decoder.end();
+        if (pending.trim())
+            consume(pending.replace(/\r$/, ""));
+    }
+    catch {
+        // A truncated or corrupt compression stream should not abort discovery.
     }
     finally {
-        closeSync(file);
+        // `pipe()` does not destroy the source when the destination is destroyed.
+        // Close both ends explicitly so an early-stopped `.jsonl.zst` read does not
+        // leak a file descriptor.
+        source.destroy();
+        input.destroy();
     }
+    return records;
 }
 function walkJsonl(root) {
     if (!existsSync(root))
@@ -50,13 +76,35 @@ function walkJsonl(root) {
             const path = resolve(directory, entry.name);
             if (entry.isDirectory())
                 visit(path);
-            else if (entry.isFile() && entry.name.toLowerCase().endsWith(".jsonl"))
+            else if (entry.isFile() &&
+                (entry.name.toLowerCase().endsWith(".jsonl") ||
+                    entry.name.toLowerCase().endsWith(".jsonl.zst")))
                 result.push(path);
         }
     };
     visit(root);
     return result.sort();
 }
+/**
+ * A metadata-only snapshot of the session files. This is the cheap half of a
+ * watch pass: it walks directories and calls stat, but never opens a session.
+ */
+export function statSessionFiles(format, home) {
+    const result = new Map();
+    if (format.discovery !== "files")
+        return result;
+    for (const path of format.sessionRoots(home).flatMap(walkJsonl)) {
+        try {
+            const stat = statSync(path);
+            if (stat.isFile())
+                result.set(path, { size: stat.size, mtimeMs: stat.mtimeMs });
+        }
+        catch {
+            // A file can disappear between readdir and stat; the next pass will retry it.
+        }
+    }
+    return result;
+}
 export function normalizeRepositoryUrl(value) {
     const trimmed = value
         .trim()
@@ -116,10 +164,13 @@ function isInside(candidate, root) {
     const child = relative(root, resolve(candidate));
     return child === "" || (!child.startsWith(`..${sep}`) && child !== "..");
 }
-export function discoverSessions(options) {
+export async function discoverSessions(options) {
     const nowMs = options.nowMs ?? Date.now();
     const liveWindowMs = options.liveWindowMs ?? 5 * 60_000;
     const included = [];
+    const metadataByPath = new Map();
+    let cacheHits = 0;
+    let cacheMisses = 0;
     const discoveryContext = {
         sessionHome: options.home,
         userHome: options.userHome ?? homedir(),
@@ -127,20 +178,33 @@ export function discoverSessions(options) {
         env: options.env ?? process.env,
         platform: options.platform ?? process.platform,
     };
-    const discovered = options.format.discovery === "custom"
-        ? options.format.discoverCandidates(discoveryContext)
-        : (() => {
+    const format = options.format;
+    const discovered = format.discovery === "custom"
+        ? format.discoverCandidates(discoveryContext)
+        : await (async () => {
             const candidates = [];
             const rejected = [];
-            for (const path of options.format.sessionRoots(options.home).flatMap(walkJsonl)) {
-                const metadata = options.format.parseDiscoveryMetadata(initialRecords(path, options.format.discoveryRecordLimit));
-                if (metadata)
+            for (const path of format.sessionRoots(options.home).flatMap(walkJsonl)) {
+                const cached = options.metadataCache?.get(path);
+                if (cached)
+                    cacheHits += 1;
+                else
+                    cacheMisses += 1;
+                const metadata = cached ??
+                    format.parseDiscoveryMetadata(await initialRecords(path, format.discoveryRecordLimit));
+                if (metadata) {
                     candidates.push({ path, metadata });
+                    metadataByPath.set(path, metadata);
+                }
                 else
                     rejected.push({ path, reason: "invalid_metadata" });
             }
             return { included: candidates, skipped: rejected };
         })();
+    if (format.discovery === "custom") {
+        for (const candidate of discovered.included)
+            metadataByPath.set(candidate.path, candidate.metadata);
+    }
     const skipped = [...discovered.skipped];
     const repositoryRootsByCwd = new Map();
     const repositoryIdentitiesByRoot = new Map();
@@ -236,16 +300,27 @@ export function discoverSessions(options) {
                 (options.allRepositories ? soleRemote(repositoryIdentityForCwd(metadata.cwd)) : null));
         included.push({
             ...candidate,
+            modifiedAt: candidate.modifiedAt ?? new Date(modifiedAtMs),
             metadata: { ...metadata, repositoryUrl: attributedRemote },
         });
     }
     if (!options.format.materializeCandidates)
-        return { included, skipped, failed: [] };
+        return {
+            included,
+            skipped,
+            failed: [],
+            metadataByPath,
+            cacheHits,
+            cacheMisses,
+        };
     const materialized = options.format.materializeCandidates(included, discoveryContext);
     return {
         included: [...materialized.included],
         skipped,
         failed: [...materialized.failed],
+        metadataByPath,
+        cacheHits,
+        cacheMisses,
         cleanup: materialized.cleanup,
     };
 }

package/dist/session-import/prune.js

@@ -4,6 +4,7 @@ import { stat } from "node:fs/promises";
 import { createInterface } from "node:readline";
 import { Transform } from "node:stream";
 import { CANONICAL_IMPORT_MAX_RECORD_BYTES } from "./canonical.js";
+import { createSessionDecompressor, isCompressedSession } from "./compression.js";
 import { createSessionNormalizationAccumulator } from "./normalize.js";
 async function scanSession(path, format, discoveryMetadata, onEntry) {
     const before = await stat(path);
@@ -12,6 +13,7 @@ async function scanSession(path, format, discoveryMetadata, onEntry) {
         hash.update(`${format.sourceHashSeed(discoveryMetadata)}\0`);
     const encoder = new TextEncoder();
     let entryBytes = 0;
+    let originalBytes = 0;
     const accumulator = createSessionNormalizationAccumulator(format.createNormalizer(discoveryMetadata), {
         discoveryMetadata,
         onEntry: (entry) => {
@@ -24,24 +26,40 @@ async function scanSession(path, format, discoveryMetadata, onEntry) {
     });
     const hashingStream = new Transform({
         transform(chunk, _encoding, callback) {
+            originalBytes += chunk.length;
             hash.update(chunk);
             callback(null, chunk);
         },
     });
-    const input = createReadStream(path);
+    const rawInput = createReadStream(path);
+    const input = isCompressedSession(path) ? rawInput.pipe(createSessionDecompressor()) : rawInput;
+    // `pipe()` does not forward upstream errors. Move an error from the file stream
+    // to the decoder, then to the hashing stream that readline is consuming, so the
+    // loop below observes it instead of the process crashing.
+    rawInput.on("error", (error) => input.destroy(error));
+    input.on("error", (error) => hashingStream.destroy(error));
     input.pipe(hashingStream);
     const lines = createInterface({ input: hashingStream, crlfDelay: Infinity });
-    for await (const line of lines) {
-        if (!line.trim())
-            continue;
-        let record;
-        try {
-            record = JSON.parse(line);
+    try {
+        for await (const line of lines) {
+            if (!line.trim())
+                continue;
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                record = null;
+            }
+            accumulator.add(record);
         }
-        catch {
-            record = null;
-        }
-        accumulator.add(record);
+    }
+    finally {
+        lines.close();
+        hashingStream.destroy();
+        input.destroy();
+        if (input !== rawInput)
+            rawInput.destroy();
     }
     const after = await stat(path);
     if (before.size !== after.size || before.mtimeMs !== after.mtimeMs)
@@ -52,7 +70,7 @@ async function scanSession(path, format, discoveryMetadata, onEntry) {
         throw new Error(`Canonical session metadata is too large: ${path}`);
     return {
         sourceContentHash: hash.digest("hex"),
-        originalBytes: before.size,
+        originalBytes,
         prunedBytes: headerBytes.byteLength + entryBytes,
         metadata: header,
     };

package/dist/session-import/receipts.d.ts

@@ -4,7 +4,7 @@ type Receipt = Readonly<{
     sessionId: string;
     importedAt: string;
 }>;
-type ReceiptFile = {
+export type ReceiptFile = {
     version: 1;
     receipts: Record<string, Receipt>;
 };

package/dist/session-import/sync.d.ts

@@ -0,0 +1,32 @@
+import type { SessionImportFormat } from "./format.js";
+import { type ReceiptFile } from "./receipts.js";
+import type { SetupEnvironment } from "../setup/agents.js";
+import type { AgentSessionCandidate, AgentSessionPlan, ImportVisibility } from "./types.js";
+export type PreparedSession = AgentSessionPlan & Readonly<{
+    candidate: AgentSessionCandidate;
+    receiptKey: string | null;
+    alreadyImported: boolean;
+}>;
+export declare function formatBytes(bytes: number): string;
+export declare function prepareSession(input: {
+    candidate: AgentSessionCandidate;
+    format: SessionImportFormat;
+    apiBaseUrl: string;
+    apiKey: string | null;
+    receiptScope?: string;
+    visibility: ImportVisibility;
+    receipts: ReceiptFile;
+}): Promise<PreparedSession>;
+export declare function uploadPreparedSession(input: {
+    prepared: PreparedSession;
+    format: SessionImportFormat;
+    apiBaseUrl: string;
+    apiKey: string;
+    visibility: ImportVisibility;
+    context: SetupEnvironment;
+    receipts: ReceiptFile;
+    fetch?: typeof globalThis.fetch;
+}): Promise<{
+    duplicate: boolean;
+    sessionId: string;
+}>;

package/dist/session-import/sync.js

@@ -0,0 +1,55 @@
+import { CANONICAL_IMPORT_MAX_BYTES } from "./canonical.js";
+import { uploadAgentSession } from "./client.js";
+import { pruneSession } from "./prune.js";
+import { receiptKey, saveReceipt } from "./receipts.js";
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 ** 2)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 ** 3)
+        return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+    return `${(bytes / 1024 ** 3).toFixed(2)} GB`;
+}
+export async function prepareSession(input) {
+    const pruned = await pruneSession(input.candidate.path, input.format, {
+        emitBytes: false,
+        metadata: input.candidate.metadata,
+    });
+    if (pruned.prunedBytes > CANONICAL_IMPORT_MAX_BYTES)
+        throw new Error(`Pruned session exceeds ${formatBytes(CANONICAL_IMPORT_MAX_BYTES)}`);
+    const key = input.apiKey
+        ? receiptKey({
+            apiBaseUrl: input.apiBaseUrl,
+            apiKey: input.apiKey,
+            receiptScope: input.receiptScope,
+            source: input.format.source,
+            sourceContentHash: pruned.sourceContentHash,
+            visibility: input.visibility,
+        })
+        : null;
+    return {
+        ...pruned,
+        candidate: input.candidate,
+        receiptKey: key,
+        alreadyImported: Boolean(key && input.receipts.receipts[key]),
+    };
+}
+export async function uploadPreparedSession(input) {
+    if (!input.prepared.receiptKey)
+        throw new Error("A session cannot be uploaded without a receipt key.");
+    const session = await pruneSession(input.prepared.candidate.path, input.format, {
+        plan: input.prepared,
+        metadata: input.prepared.candidate.metadata,
+    });
+    const result = await uploadAgentSession({
+        apiBaseUrl: input.apiBaseUrl,
+        apiKey: input.apiKey,
+        source: input.format.source,
+        session,
+        visibility: input.visibility,
+        fetch: input.fetch,
+    });
+    saveReceipt(input.context, input.receipts, input.prepared.receiptKey, result.sessionId);
+    return result;
+}

package/dist/session-import/types.d.ts

@@ -12,6 +12,9 @@ export type AgentSessionMetadata = Readonly<{
     repositoryCommitSha: string | null;
     originator: string | null;
     isSubagent: boolean;
+    /** Codex paginated rollouts point at the previous page's thread id. */
+    historyBaseThreadId?: string | null;
+    historyMode?: string | null;
     startedAt?: Date | null;
     endedAt?: Date | null;
 }>;

package/dist/session-import/watch-lock.d.ts

@@ -0,0 +1,17 @@
+import type { SetupEnvironment } from "../setup/agents.js";
+import type { AgentSessionSource } from "./types.js";
+export type WatchLock = Readonly<{
+    path: string;
+    release(): void;
+}>;
+/**
+ * A PID lock with stale detection.
+ *
+ * Creation is atomic (`open(..., "wx")`). Stale takeover never unlinks the
+ * observed path directly: it renames the lock to a unique quarantine name,
+ * verifies that the quarantined file is the same stale owner, and only then
+ * removes it. If another process replaced the lock between observation and
+ * takeover, the moved lock is restored and acquisition retries. This prevents
+ * two starters from both removing each other's fresh lock.
+ */
+export declare function acquireWatchLock(context: SetupEnvironment, source: AgentSessionSource): WatchLock;

package/dist/session-import/watch-lock.js

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { watchLockPath } from "./watch-state.js";
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function readOwner(path) {
+    try {
+        if (lstatSync(path).isSymbolicLink())
+            throw new Error(`Refusing to use a symbolic link as the watch lock: ${path}`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        return readFileSync(path, "utf8").trim();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+/**
+ * A PID lock with stale detection.
+ *
+ * Creation is atomic (`open(..., "wx")`). Stale takeover never unlinks the
+ * observed path directly: it renames the lock to a unique quarantine name,
+ * verifies that the quarantined file is the same stale owner, and only then
+ * removes it. If another process replaced the lock between observation and
+ * takeover, the moved lock is restored and acquisition retries. This prevents
+ * two starters from both removing each other's fresh lock.
+ */
+export function acquireWatchLock(context, source) {
+    const path = watchLockPath(context, source);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const owner = `${process.pid}:${randomUUID()}`;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            try {
+                writeFileSync(fd, `${owner}\n`);
+            }
+            finally {
+                closeSync(fd);
+            }
+            if (readOwner(path) !== owner)
+                throw new Error(`The Groundtrack watch lock changed during acquisition: ${path}`);
+            return {
+                path,
+                release() {
+                    try {
+                        if (readOwner(path) === owner)
+                            rmSync(path, { force: true });
+                    }
+                    catch {
+                        // The lock was already removed or replaced; never remove another owner's file.
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const observed = readOwner(path);
+        if (observed === null)
+            continue;
+        const pid = Number(observed.split(":", 1)[0]);
+        if (Number.isSafeInteger(pid) && pid > 0 && processAlive(pid))
+            throw new Error(`Another groundtrack watch is already running (pid ${pid}).`);
+        const quarantine = `${path}.stale-${process.pid}-${randomUUID()}`;
+        try {
+            renameSync(path, quarantine);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        const moved = readOwner(quarantine);
+        if (moved !== observed) {
+            // We raced with a fresh owner and moved its lock. Put it back if possible;
+            // never delete a lock that does not match the stale owner we observed.
+            try {
+                renameSync(quarantine, path);
+            }
+            catch {
+                throw new Error(`The Groundtrack watch lock changed during stale takeover. Retry when no other watch is running: ${path}`);
+            }
+            continue;
+        }
+        rmSync(quarantine, { force: true });
+    }
+    throw new Error(`Could not acquire the Groundtrack watch lock: ${path}`);
+}

package/dist/session-import/watch-state.d.ts

@@ -0,0 +1,47 @@
+import { type SetupEnvironment } from "../setup/agents.js";
+import type { AgentSessionMetadata, AgentSessionSource } from "./types.js";
+export type WatchFileStatus = "active" | "imported";
+export type SerializedMetadata = Readonly<{
+    externalSessionId: string;
+    timestamp: string | null;
+    cwd: string | null;
+    repositoryUrl: string | null;
+    repositoryBranch: string | null;
+    repositoryCommitSha: string | null;
+    originator: string | null;
+    isSubagent: boolean;
+    historyBaseThreadId?: string | null;
+    historyMode?: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+}>;
+export type WatchFileState = {
+    size: number;
+    mtimeMs: number;
+    sessionId: string;
+    metadata: SerializedMetadata;
+    status: WatchFileStatus;
+    contentHash?: string;
+    receiptKey?: string;
+    importedAt?: string;
+};
+export type WatchSessionState = {
+    pages: string[];
+    fingerprint: string;
+    status: WatchFileStatus;
+    contentHash?: string;
+    receiptKey?: string;
+    importedAt?: string;
+};
+export type WatchState = {
+    version: 1;
+    files: Record<string, WatchFileState>;
+    sessions: Record<string, WatchSessionState>;
+};
+export declare function watchStatePath(context: SetupEnvironment, source: AgentSessionSource): string;
+export declare function watchLockPath(context: SetupEnvironment, source: AgentSessionSource): string;
+export declare function emptyWatchState(): WatchState;
+export declare function serializeMetadata(metadata: AgentSessionMetadata): SerializedMetadata;
+export declare function deserializeMetadata(metadata: SerializedMetadata): AgentSessionMetadata;
+export declare function readWatchState(context: SetupEnvironment, source: AgentSessionSource): WatchState;
+export declare function writeWatchState(context: SetupEnvironment, source: AgentSessionSource, state: WatchState): void;