sealkeep 0.5.0

package/dist/src/activity.d.ts

@@ -0,0 +1,22 @@
+export type ActivityVerdict = {
+    active: boolean;
+    reason: string;
+};
+export type ActivityOptions = {
+    /** A file touched within this window is treated as in use. */
+    quietMs?: number;
+    now?: number;
+    /** Injected for tests; defaults to a real `lsof` probe where available. */
+    openHandles?: (path: string) => Promise<boolean | null>;
+};
+/**
+ * Reports whether any process currently holds the file open.
+ * Returns `null` when it cannot tell, which callers must treat as "assume active".
+ */
+export declare function probeOpenHandles(path: string): Promise<boolean | null>;
+/**
+ * Conservative activity check. Anything uncertain counts as active, because the
+ * cost of a false "idle" is deleting a session a user is still working in, while
+ * the cost of a false "active" is only a delayed reclamation.
+ */
+export declare function isSourceActive(path: string, options?: ActivityOptions): Promise<ActivityVerdict>;

package/dist/src/activity.js

@@ -0,0 +1,52 @@
+import { execFile } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { platform } from "node:os";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/**
+ * Reports whether any process currently holds the file open.
+ * Returns `null` when it cannot tell, which callers must treat as "assume active".
+ */
+export async function probeOpenHandles(path) {
+    if (platform() === "win32")
+        return null;
+    try {
+        const { stdout } = await run("lsof", ["-t", "--", path], { timeout: 3000 });
+        return stdout.trim().length > 0;
+    }
+    catch (error) {
+        // lsof exits non-zero with no output when nothing holds the file open.
+        const failure = error;
+        if (failure.code === 1 && (failure.stdout ?? "").trim() === "")
+            return false;
+        return null;
+    }
+}
+/**
+ * Conservative activity check. Anything uncertain counts as active, because the
+ * cost of a false "idle" is deleting a session a user is still working in, while
+ * the cost of a false "active" is only a delayed reclamation.
+ */
+export async function isSourceActive(path, options = {}) {
+    const quietMs = options.quietMs ?? 15 * 60_000;
+    const now = options.now ?? Date.now();
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch {
+        return { active: true, reason: "source is unreadable, so its state cannot be confirmed" };
+    }
+    if (!info.isFile())
+        return { active: true, reason: "source is not a regular file" };
+    const age = now - info.mtimeMs;
+    if (age < quietMs)
+        return { active: true, reason: `modified ${Math.round(age / 1000)}s ago, inside the ${Math.round(quietMs / 1000)}s quiet window` };
+    const probe = options.openHandles ?? probeOpenHandles;
+    const open = await probe(path);
+    if (open === null)
+        return { active: true, reason: "could not determine whether a process holds the file open" };
+    if (open)
+        return { active: true, reason: "a process currently holds the file open" };
+    return { active: false, reason: `idle for ${Math.round(age / 60_000)} minutes with no open handle` };
+}

package/dist/src/adapters.d.ts

@@ -0,0 +1,212 @@
+/**
+ * The agents whose sessions Sealkeep archives.
+ *
+ * Deliberately narrower than `SetupAgentId`: every id here needs a transcript
+ * root the watcher can follow *and* a native restore root (`NATIVE_ROOTS` in
+ * restore.ts), and an id with neither would produce an agent the watcher
+ * queues and the restorer cannot put back.
+ */
+export type AgentId = "codex" | "claude";
+/**
+ * Every agent first-run setup can find on this machine.
+ *
+ * A superset of `AgentId`, because finding an agent and reporting where its
+ * hooks live costs nothing but a `stat`, while archiving it needs an adapter
+ * that knows its session store. Reporting the difference is the point — see
+ * `archivable` below.
+ */
+export type SetupAgentId = AgentId | "cursor" | "gemini" | "windsurf" | "antigravity";
+export type AgentInstall = {
+    agent: AgentId;
+    root: string;
+    transcriptRoots: string[];
+    detected: boolean;
+};
+/** Every id `detectSetupAgents` reports on, in the order a setup page should show them. */
+export declare const SETUP_AGENT_IDS: SetupAgentId[];
+/** The subset with a session adapter. Mirrors `AgentId` at runtime for schema use. */
+export declare const ARCHIVING_AGENT_IDS: readonly ["codex", "claude"];
+/** Narrows a setup id to an archiving one, so callers prove the subset rather than casting to it. */
+export declare function isArchivingAgent(agent: SetupAgentId): agent is AgentId;
+/** Detect only well-known local roots; it never reads transcript contents. */
+export declare function detectAgents(home?: string): Promise<AgentInstall[]>;
+export type TranscriptCandidate = {
+    agent: AgentId;
+    path: string;
+    bytes: number;
+    modifiedAt: string;
+    /**
+     * The project this session ran in, when its metadata says — null when
+     * nothing does. Optional because a candidate is valid before resolution
+     * (`walkJsonl` and `measureSessions` never need it); everything
+     * `findTranscripts` returns has both fields resolved.
+     */
+    project?: string | null;
+    /** The working directory behind `project`, best-effort. See the decode caveat on `claudeProjectFromPath`. */
+    projectPath?: string | null;
+};
+export type ProjectIdentity = {
+    project: string | null;
+    projectPath: string | null;
+};
+/**
+ * Claude Code names each transcript directory after the session's cwd with the
+ * separators flattened to dashes ("/Users/x/repo" → "-Users-x-repo"). The
+ * decode is lossy by construction — a dash that was part of a directory name
+ * is indistinguishable from one that was a separator — so `project` is the
+ * final segment, which is the part a person recognises, and `projectPath` is
+ * the naive re-expansion, kept because "which /Users/… did this come from" is
+ * still worth answering approximately.
+ */
+export declare function claudeProjectFromPath(path: string): ProjectIdentity;
+export declare function codexProjectFromRollout(path: string, modifiedAt: string): Promise<ProjectIdentity>;
+/**
+ * Lists metadata for recent transcripts, never their conversations. The one
+ * read into a file is the codex rollout's first line, which is the session's
+ * own metadata record — what was said in the session stays unread.
+ */
+export declare function findTranscripts(agent: AgentId, home?: string, limit?: number): Promise<TranscriptCandidate[]>;
+/**
+ * The one command a Sealkeep hook ever runs, built in one place.
+ *
+ * Detection matches installed hooks on the `hook enqueue --agent <id>` part of
+ * it, so the command and the thing that recognises it can never disagree about
+ * what a Sealkeep hook looks like.
+ */
+export declare function hookCommand(agent: SetupAgentId, executable?: string, dataDir?: string): string;
+/** The substring that identifies a Sealkeep hook for one agent, wherever it is written. */
+export declare function hookMarker(agent: SetupAgentId): string;
+/**
+ * Returns a reviewable config fragment. It is intentionally not installed into
+ * an agent's settings: users must review and merge it themselves. The hook only
+ * enqueues local work, so it needs no recovery phrase and no network access.
+ */
+export declare function hookConfig(agent: AgentId, executable?: string, dataDir?: string): {
+    description: string;
+    hooks: {
+        SessionEnd: {
+            hooks: {
+                type: string;
+                command: string;
+                timeout: number;
+                statusMessage: string;
+            }[];
+        }[];
+        PostCompact: {
+            hooks: {
+                type: string;
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+        SessionStart: {
+            matcher: string;
+            hooks: {
+                type: "command";
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+    };
+    _vaultlineNote: string;
+} | {
+    hooks: {
+        SessionEnd: {
+            hooks: {
+                type: string;
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+        SessionStart: {
+            matcher: string;
+            hooks: {
+                type: "command";
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+        PostCompact?: undefined;
+    };
+    _vaultlineNote: string;
+    description?: undefined;
+};
+/**
+ * What first-run setup knows about one agent.
+ *
+ * `status` is the single field a page should branch on; the rest is the
+ * evidence behind it, so nothing has to be re-derived by a second reader.
+ */
+export type AgentHookStatus = 
+/** No root directory: this agent is not on the machine. */
+"not-installed"
+/** Sealkeep's hook is already in this agent's config. */
+ | "hooked"
+/** Found, but its hook file can neither be written nor created. */
+ | "found-but-unwritable"
+/** Found and writable, but this build cannot process a hook from it. */
+ | "found-but-unsupported"
+/** Found and writable, but its config is a format this build cannot merge into. */
+ | "manual-merge-required"
+/** Found, writable, and hookable right now. */
+ | "ready";
+export type AgentDetection = {
+    agent: SetupAgentId;
+    label: string;
+    detected: boolean;
+    root: string;
+    hookFile: string;
+    hookFileFormat: "json" | "toml";
+    hookFileExists: boolean;
+    hookFileWritable: boolean;
+    hooksInstalled: boolean;
+    /** True when Sealkeep can archive this agent's sessions, not merely find it. */
+    archivable: boolean;
+    /** Disk this agent's transcripts occupy right now. Zero for anything not archivable. */
+    sessionBytes: number;
+    sessionCount: number;
+    status: AgentHookStatus;
+    /** Why the status is what it is, whenever it is not simply "ready". */
+    note: string | null;
+};
+export declare function detectSetupAgents(home?: string): Promise<AgentDetection[]>;
+export type HookInstallOutcome = {
+    agent: SetupAgentId;
+    /** True only when the agent's own config now carries the hook. */
+    installed: boolean;
+    hookFile: string;
+    /** True when the hook was already there and nothing was written. */
+    alreadyInstalled: boolean;
+    /** The copy taken before the agent's config was edited, when one was needed. */
+    backupPath: string | null;
+    /** A reviewable document under the vault, for a config this build will not edit. */
+    fragmentPath: string | null;
+    /** Why `installed` is false. Null when it is true. */
+    reason: string | null;
+};
+/**
+ * Installs Sealkeep's hook into the agents it can, and says why for the rest.
+ *
+ * Idempotent by construction: a second call finds its own marker and writes
+ * nothing. Nothing here reports `installed: true` unless the agent's own config
+ * now contains the command — a fragment written for manual review is reported
+ * as what it is.
+ */
+export declare function installAgentHooks(agents: readonly SetupAgentId[], options: {
+    dataDir: string;
+    home?: string;
+    executable?: string;
+}): Promise<HookInstallOutcome[]>;
+/** A normalized archive intent. Sealkeep reads lifecycle metadata only, never transcript bodies. */
+export type HookEvent = {
+    agent: AgentId;
+    event: string;
+    sourcePath: string;
+    sessionId?: string;
+};
+/**
+ * Accepts Codex `SessionEnd`/`PostCompact` and Claude `SessionEnd` payloads. Unknown
+ * vendor fields are ignored rather than parsed, so a schema change cannot break preservation.
+ */
+export declare function hookEventFromStdin(agent: AgentId, stdin: string): Promise<HookEvent>;
+export declare function transcriptPathFromHook(stdin: string, agent?: AgentId): Promise<string>;