sealkeep 0.9.0 → 0.11.0

package/dist/src/adapters.d.ts

@@ -26,6 +26,7 @@ export type AgentInstall = {
 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"];
+export declare const HOOK_LIFECYCLE_VERSION = 3;
 /** 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. */
@@ -42,11 +43,14 @@ export type TranscriptCandidate = {
      * `findTranscripts` returns has both fields resolved.
      */
     project?: string | null;
+    /** Stable, opaque identity used for access decisions. `project` remains display-only. */
+    projectKey?: string | null;
     /** The working directory behind `project`, best-effort. See the decode caveat on `claudeProjectFromPath`. */
     projectPath?: string | null;
 };
 export type ProjectIdentity = {
     project: string | null;
+    projectKey: string | null;
     projectPath: string | null;
 };
 /**
@@ -58,14 +62,30 @@ export type ProjectIdentity = {
  * the naive re-expansion, kept because "which /Users/… did this come from" is
  * still worth answering approximately.
  */
+/**
+ * Which archiving agent wrote a transcript, judged by where it lives. A file
+ * under `~/.claude/projects` is Claude's; under `~/.codex/sessions` (or its
+ * archived sibling) it is Codex's. This is what lets a hand-sealed
+ * `sealkeep archive <file>` carry the same agent — and therefore the same
+ * project derivation — as the watcher would have given it, instead of the
+ * "custom" label that leaves the session untagged and invisible to every
+ * project-scoped recall.
+ */
+export declare function agentForTranscriptPath(path: string, home?: string): AgentId | null;
 export declare function claudeProjectFromPath(path: string): ProjectIdentity;
+/** The project for a session's recorded cwd: the git remote's repo name, else the folder name. */
+export declare function projectFromCwd(cwd: string): Promise<ProjectIdentity>;
+export declare function claudeProjectFromTranscript(path: string, modifiedAt: string): Promise<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[]>;
+export declare function findTranscripts(agent: AgentId, home?: string, limit?: number, options?: {
+    exclude?: (path: string) => boolean;
+    includeProjects?: boolean;
+}): Promise<TranscriptCandidate[]>;
 /**
  * The one command a Sealkeep hook ever runs, built in one place.
  *
@@ -105,10 +125,38 @@ export declare function hookConfig(agent: AgentId, executable?: string, dataDir?
                 type: "command";
                 command: string;
                 timeout: number;
+                async: boolean;
             }[];
         }[];
+        UserPromptSubmit: {
+            hooks: ({
+                additionalContextLimit?: number | undefined;
+                type: "command";
+                command: string;
+                timeout: number;
+            } | {
+                type: "command";
+                command: string;
+                timeout: number;
+                async: boolean;
+            })[];
+        }[];
+        PostToolUse: {
+            matcher: string;
+            hooks: ({
+                additionalContextLimit?: number | undefined;
+                type: "command";
+                command: string;
+                timeout: number;
+            } | {
+                type: "command";
+                command: string;
+                timeout: number;
+                async: boolean;
+            })[];
+        }[];
     };
-    _vaultlineNote: string;
+    _sealkeepNote: string;
 } | {
     hooks: {
         SessionEnd: {
@@ -124,11 +172,39 @@ export declare function hookConfig(agent: AgentId, executable?: string, dataDir?
                 type: "command";
                 command: string;
                 timeout: number;
+                async: boolean;
             }[];
         }[];
+        UserPromptSubmit: {
+            hooks: ({
+                additionalContextLimit?: number | undefined;
+                type: "command";
+                command: string;
+                timeout: number;
+            } | {
+                type: "command";
+                command: string;
+                timeout: number;
+                async: boolean;
+            })[];
+        }[];
+        PostToolUse: {
+            matcher: string;
+            hooks: ({
+                additionalContextLimit?: number | undefined;
+                type: "command";
+                command: string;
+                timeout: number;
+            } | {
+                type: "command";
+                command: string;
+                timeout: number;
+                async: boolean;
+            })[];
+        }[];
         PostCompact?: undefined;
     };
-    _vaultlineNote: string;
+    _sealkeepNote: string;
     description?: undefined;
 };
 /**
@@ -140,8 +216,12 @@ export declare function hookConfig(agent: AgentId, executable?: string, dataDir?
 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. */
+/** Sealkeep's complete lifecycle is configured and active in this agent. */
  | "hooked"
+/** Sealkeep's lifecycle is configured, but the user disabled at least one Codex handler. */
+ | "hooked-but-disabled"
+/** Sealkeep's lifecycle is configured, but Codex has not trusted its exact current definitions. */
+ | "hooked-awaiting-review"
 /** 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. */
@@ -159,7 +239,26 @@ export type AgentDetection = {
     hookFileFormat: "json" | "toml";
     hookFileExists: boolean;
     hookFileWritable: boolean;
+    /** The complete current Sealkeep lifecycle is present in the agent's config. */
     hooksInstalled: boolean;
+    /** Present lifecycle handlers will actually be dispatched by the agent. */
+    hooksActive: boolean;
+    /**
+     * The one data directory every owned lifecycle command routes to, or null
+     * when the commands are absent or disagree. Presence alone says nothing about
+     * WHICH vault a hook feeds; this is what does.
+     */
+    hooksDataDir: string | null;
+    /**
+     * The complete lifecycle is present but routes to a data directory other
+     * than the one asked about. Only ever true when `detectSetupAgents` was given
+     * a data directory to compare against. A hook in this state reports
+     * "installed" and "active" while injecting and capturing nothing for this
+     * vault — the exact silent failure the fail-open hook contract cannot surface.
+     */
+    hooksAimedElsewhere: boolean;
+    /** Per-handler execution problems, never inferred from command presence alone. */
+    hookIssues: AgentHookIssue[];
     /** 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. */
@@ -169,7 +268,12 @@ export type AgentDetection = {
     /** 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 AgentHookIssue = {
+    event: string;
+    action: "enqueue" | "rehydrate" | "context" | "context-sync";
+    reason: "disabled" | "untrusted" | "modified";
+};
+export declare function detectSetupAgents(home?: string, dataDir?: string): Promise<AgentDetection[]>;
 export type HookInstallOutcome = {
     agent: SetupAgentId;
     /** True only when the agent's own config now carries the hook. */
@@ -177,12 +281,16 @@ export type HookInstallOutcome = {
     hookFile: string;
     /** True when the hook was already there and nothing was written. */
     alreadyInstalled: boolean;
+    /** True only when the agent will dispatch every configured Sealkeep handler. */
+    active: 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;
+    /** A consent/review action still needed after a successful config write. */
+    attention: string | null;
 };
 /**
  * Installs Sealkeep's hook into the agents it can, and says why for the rest.
@@ -197,6 +305,36 @@ export declare function installAgentHooks(agents: readonly SetupAgentId[], optio
     home?: string;
     executable?: string;
 }): Promise<HookInstallOutcome[]>;
+/**
+ * Upgrades only hook files that already contain a Sealkeep archive hook.
+ *
+ * This is the package-upgrade path: an earlier explicit install is continuing
+ * to consent to Sealkeep-owned lifecycle entries, but a machine that never
+ * installed them is left completely untouched. The daemon calls this once at
+ * startup, so upgrading the package does not require revisiting setup.
+ */
+export declare function upgradeOwnedAgentHooks(options: {
+    dataDir: string;
+    home?: string;
+    executable?: string;
+}): Promise<HookInstallOutcome[]>;
+export type HookRemoveOutcome = {
+    agent: AgentId;
+    hookFile: string;
+    removed: boolean;
+    backupPath: string | null;
+    reason: string | null;
+};
+/**
+ * Removes Sealkeep-owned lifecycle handlers and nothing else.
+ *
+ * This is intentionally structural rather than a text replacement: if a user
+ * placed their own handler beside Sealkeep's in one matcher group, their
+ * handler and matcher survive. The original file is backed up before a write.
+ */
+export declare function removeOwnedAgentHooks(options: {
+    home?: string;
+}): Promise<HookRemoveOutcome[]>;
 /** A normalized archive intent. Sealkeep reads lifecycle metadata only, never transcript bodies. */
 export type HookEvent = {
     agent: AgentId;
@@ -204,9 +342,41 @@ export type HookEvent = {
     sourcePath: string;
     sessionId?: string;
 };
+/** The lifecycle event a hook payload names; undefined when it names none or is not JSON. */
+export declare function hookEventNameOf(stdin: string): string | undefined;
 /**
  * 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>;
+/**
+ * The project an archive belongs to: what the seal recorded, or failing that
+ * what its path implies.
+ *
+ * Deriving it from the path is guesswork that only works inside an agent's own
+ * directories — a rehearsal of a company setup archived six sessions into a
+ * shared project and every one of them came back "no project", so membership
+ * could never bind and `rewrap --project` re-keyed nothing while reporting
+ * that the archives "belong to another project". Records written since carry
+ * the answer; older ones still fall back to the path.
+ */
+export declare function projectIdentityOfRecord(record: {
+    source: {
+        path: string;
+        agent: string;
+        project?: string;
+        projectKey?: string;
+    };
+    createdAt: string;
+}): Promise<ProjectIdentity>;
+/** Backward-compatible display-label helper. Access-control callers use projectIdentityOfRecord. */
+export declare function projectOfRecord(record: {
+    source: {
+        path: string;
+        agent: string;
+        project?: string;
+        projectKey?: string;
+    };
+    createdAt: string;
+}): Promise<string | null>;