@herdctl/core 5.6.0 → 5.7.1

package/dist/state/session-metadata.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Session Metadata Store
+ *
+ * Manages user-customizable metadata for Claude Code sessions.
+ * Metadata is stored sparsely in .herdctl/session-metadata/{agent-qualified-name}.json
+ * Files are only created when the first custom name is set for an agent.
+ */
+import { z } from "zod";
+/**
+ * Schema for a single session's metadata entry
+ */
+export declare const SessionMetadataEntrySchema: z.ZodObject<{
+    customName: z.ZodOptional<z.ZodString>;
+    /** Auto-generated session name (extracted from JSONL summary) */
+    autoName: z.ZodOptional<z.ZodString>;
+    /** ISO 8601 timestamp of when autoName was extracted (for cache invalidation) */
+    autoNameMtime: z.ZodOptional<z.ZodString>;
+    /** First user message preview (truncated to 100 chars) */
+    preview: z.ZodOptional<z.ZodString>;
+    /** ISO 8601 timestamp of when preview was extracted (for cache invalidation) */
+    previewMtime: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    customName?: string | undefined;
+    autoName?: string | undefined;
+    autoNameMtime?: string | undefined;
+    preview?: string | undefined;
+    previewMtime?: string | undefined;
+}, {
+    customName?: string | undefined;
+    autoName?: string | undefined;
+    autoNameMtime?: string | undefined;
+    preview?: string | undefined;
+    previewMtime?: string | undefined;
+}>;
+/**
+ * Schema for the entire metadata file for an agent
+ */
+export declare const SessionMetadataFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    agentName: z.ZodString;
+    sessions: z.ZodRecord<z.ZodString, z.ZodObject<{
+        customName: z.ZodOptional<z.ZodString>;
+        /** Auto-generated session name (extracted from JSONL summary) */
+        autoName: z.ZodOptional<z.ZodString>;
+        /** ISO 8601 timestamp of when autoName was extracted (for cache invalidation) */
+        autoNameMtime: z.ZodOptional<z.ZodString>;
+        /** First user message preview (truncated to 100 chars) */
+        preview: z.ZodOptional<z.ZodString>;
+        /** ISO 8601 timestamp of when preview was extracted (for cache invalidation) */
+        previewMtime: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        customName?: string | undefined;
+        autoName?: string | undefined;
+        autoNameMtime?: string | undefined;
+        preview?: string | undefined;
+        previewMtime?: string | undefined;
+    }, {
+        customName?: string | undefined;
+        autoName?: string | undefined;
+        autoNameMtime?: string | undefined;
+        preview?: string | undefined;
+        previewMtime?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    sessions: Record<string, {
+        customName?: string | undefined;
+        autoName?: string | undefined;
+        autoNameMtime?: string | undefined;
+        preview?: string | undefined;
+        previewMtime?: string | undefined;
+    }>;
+    agentName: string;
+}, {
+    version: 1;
+    sessions: Record<string, {
+        customName?: string | undefined;
+        autoName?: string | undefined;
+        autoNameMtime?: string | undefined;
+        preview?: string | undefined;
+        previewMtime?: string | undefined;
+    }>;
+    agentName: string;
+}>;
+export type SessionMetadataEntry = z.infer<typeof SessionMetadataEntrySchema>;
+export type SessionMetadataFile = z.infer<typeof SessionMetadataFileSchema>;
+/**
+ * Store for managing user-customizable session metadata.
+ *
+ * Provides operations for getting/setting custom names for sessions.
+ * Data is sparse - files are only created when metadata is first set.
+ *
+ * @example
+ * ```typescript
+ * const store = new SessionMetadataStore('/path/to/.herdctl');
+ *
+ * // Set a custom name for a session
+ * await store.setCustomName('my-agent', 'session-123', 'Feature Work');
+ *
+ * // Get the custom name
+ * const name = await store.getCustomName('my-agent', 'session-123');
+ * // Returns: 'Feature Work'
+ *
+ * // Remove custom name
+ * await store.removeCustomName('my-agent', 'session-123');
+ * ```
+ */
+export declare class SessionMetadataStore {
+    private readonly metadataDir;
+    private readonly cache;
+    /**
+     * Create a new SessionMetadataStore
+     *
+     * @param stateDir - Path to the .herdctl state directory
+     */
+    constructor(stateDir: string);
+    /**
+     * Get the file path for an agent's metadata
+     */
+    private getFilePath;
+    /**
+     * Load metadata for an agent from disk (or cache)
+     */
+    private loadMetadata;
+    /**
+     * Save metadata for an agent to disk
+     */
+    private saveMetadata;
+    /**
+     * Create a new empty metadata file structure
+     */
+    private createEmptyMetadata;
+    /**
+     * Get custom name for a session
+     *
+     * @param agentName - The agent's qualified name
+     * @param sessionId - The session ID
+     * @returns The custom name if set, undefined otherwise
+     */
+    getCustomName(agentName: string, sessionId: string): Promise<string | undefined>;
+    /**
+     * Set custom name for a session
+     *
+     * Creates the metadata file if it doesn't exist.
+     *
+     * @param agentName - The agent's qualified name
+     * @param sessionId - The session ID
+     * @param name - The custom name to set
+     */
+    setCustomName(agentName: string, sessionId: string, name: string): Promise<void>;
+    /**
+     * Remove custom name for a session
+     *
+     * If this was the only metadata for the session, the session entry is removed.
+     * If this was the only session with metadata, the file is kept but empty
+     * (to avoid repeatedly creating/deleting files).
+     *
+     * @param agentName - The agent's qualified name
+     * @param sessionId - The session ID
+     */
+    removeCustomName(agentName: string, sessionId: string): Promise<void>;
+    /**
+     * Get all metadata for an agent's sessions
+     *
+     * Useful for batch operations or displaying metadata for all sessions.
+     *
+     * @param agentName - The agent's qualified name
+     * @returns The full metadata file, or null if no metadata exists
+     */
+    getAgentMetadata(agentName: string): Promise<SessionMetadataFile | null>;
+    /**
+     * Get auto-generated name and its mtime for a session
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param sessionId - The session ID
+     * @returns Object with autoName and autoNameMtime, or undefined if not cached
+     */
+    getAutoName(agentName: string, sessionId: string): Promise<{
+        autoName?: string;
+        autoNameMtime?: string;
+    } | undefined>;
+    /**
+     * Set auto-generated name for a session
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param sessionId - The session ID
+     * @param autoName - The auto-generated name to set
+     * @param mtime - ISO 8601 timestamp of the session file when the name was extracted
+     */
+    setAutoName(agentName: string, sessionId: string, autoName: string, mtime: string): Promise<void>;
+    /**
+     * Batch set auto-generated names for multiple sessions
+     *
+     * More efficient than calling setAutoName repeatedly since it performs
+     * a single file write for all updates.
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param entries - Array of { sessionId, autoName, mtime } objects
+     */
+    batchSetAutoNames(agentName: string, entries: Array<{
+        sessionId: string;
+        autoName: string;
+        mtime: string;
+    }>): Promise<void>;
+    /**
+     * Get cached preview and its mtime for a session
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param sessionId - The session ID
+     * @returns Object with preview and previewMtime, or undefined if not cached
+     */
+    getPreview(agentName: string, sessionId: string): Promise<{
+        preview?: string;
+        previewMtime?: string;
+    } | undefined>;
+    /**
+     * Set preview for a session
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param sessionId - The session ID
+     * @param preview - The first user message preview text
+     * @param mtime - ISO 8601 timestamp of the session file when the preview was extracted
+     */
+    setPreview(agentName: string, sessionId: string, preview: string, mtime: string): Promise<void>;
+    /**
+     * Batch set previews for multiple sessions
+     *
+     * More efficient than calling setPreview repeatedly since it performs
+     * a single file write for all updates.
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param entries - Array of { sessionId, preview, mtime } objects
+     */
+    batchSetPreviews(agentName: string, entries: Array<{
+        sessionId: string;
+        preview: string;
+        mtime: string;
+    }>): Promise<void>;
+}
+//# sourceMappingURL=session-metadata.d.ts.map

package/dist/state/session-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-metadata.d.ts","sourceRoot":"","sources":["../../src/state/session-metadata.ts"],"names":[],"mappings":"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"}

package/dist/state/session-metadata.js

@@ -0,0 +1,377 @@
+/**
+ * Session Metadata Store
+ *
+ * Manages user-customizable metadata for Claude Code sessions.
+ * Metadata is stored sparsely in .herdctl/session-metadata/{agent-qualified-name}.json
+ * Files are only created when the first custom name is set for an agent.
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { createLogger } from "../utils/logger.js";
+import { atomicWriteJson } from "./utils/atomic.js";
+import { safeReadJson } from "./utils/reads.js";
+const logger = createLogger("SessionMetadataStore");
+// =============================================================================
+// Schemas
+// =============================================================================
+/**
+ * Schema for a single session's metadata entry
+ */
+export const SessionMetadataEntrySchema = z.object({
+    customName: z.string().optional(),
+    /** Auto-generated session name (extracted from JSONL summary) */
+    autoName: z.string().optional(),
+    /** ISO 8601 timestamp of when autoName was extracted (for cache invalidation) */
+    autoNameMtime: z.string().optional(),
+    /** First user message preview (truncated to 100 chars) */
+    preview: z.string().optional(),
+    /** ISO 8601 timestamp of when preview was extracted (for cache invalidation) */
+    previewMtime: z.string().optional(),
+    // Future: pinned, archived, tags
+});
+/**
+ * Schema for the entire metadata file for an agent
+ */
+export const SessionMetadataFileSchema = z.object({
+    version: z.literal(1),
+    agentName: z.string(),
+    sessions: z.record(z.string(), SessionMetadataEntrySchema),
+});
+// =============================================================================
+// SessionMetadataStore
+// =============================================================================
+/**
+ * Store for managing user-customizable session metadata.
+ *
+ * Provides operations for getting/setting custom names for sessions.
+ * Data is sparse - files are only created when metadata is first set.
+ *
+ * @example
+ * ```typescript
+ * const store = new SessionMetadataStore('/path/to/.herdctl');
+ *
+ * // Set a custom name for a session
+ * await store.setCustomName('my-agent', 'session-123', 'Feature Work');
+ *
+ * // Get the custom name
+ * const name = await store.getCustomName('my-agent', 'session-123');
+ * // Returns: 'Feature Work'
+ *
+ * // Remove custom name
+ * await store.removeCustomName('my-agent', 'session-123');
+ * ```
+ */
+export class SessionMetadataStore {
+    metadataDir;
+    cache;
+    /**
+     * Create a new SessionMetadataStore
+     *
+     * @param stateDir - Path to the .herdctl state directory
+     */
+    constructor(stateDir) {
+        this.metadataDir = join(stateDir, "session-metadata");
+        this.cache = new Map();
+    }
+    /**
+     * Get the file path for an agent's metadata
+     */
+    getFilePath(agentName) {
+        return join(this.metadataDir, `${agentName}.json`);
+    }
+    /**
+     * Load metadata for an agent from disk (or cache)
+     */
+    async loadMetadata(agentName) {
+        // Check cache first
+        const cached = this.cache.get(agentName);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const filePath = this.getFilePath(agentName);
+        const result = await safeReadJson(filePath);
+        if (!result.success) {
+            // File not found is expected for sparse storage
+            if (result.error.code === "ENOENT") {
+                return null;
+            }
+            logger.warn(`Failed to read metadata file for ${agentName}: ${result.error.message}`);
+            return null;
+        }
+        // Validate the file structure
+        const parseResult = SessionMetadataFileSchema.safeParse(result.data);
+        if (!parseResult.success) {
+            logger.warn(`Corrupted metadata file for ${agentName}: ${parseResult.error.message}. Returning null.`);
+            return null;
+        }
+        // Cache and return
+        this.cache.set(agentName, parseResult.data);
+        return parseResult.data;
+    }
+    /**
+     * Save metadata for an agent to disk
+     */
+    async saveMetadata(agentName, metadata) {
+        // Ensure directory exists
+        await mkdir(this.metadataDir, { recursive: true });
+        const filePath = this.getFilePath(agentName);
+        await atomicWriteJson(filePath, metadata);
+        // Update cache
+        this.cache.set(agentName, metadata);
+        logger.debug(`Saved metadata for agent ${agentName}`, {
+            sessionCount: Object.keys(metadata.sessions).length,
+        });
+    }
+    /**
+     * Create a new empty metadata file structure
+     */
+    createEmptyMetadata(agentName) {
+        return {
+            version: 1,
+            agentName,
+            sessions: {},
+        };
+    }
+    /**
+     * Get custom name for a session
+     *
+     * @param agentName - The agent's qualified name
+     * @param sessionId - The session ID
+     * @returns The custom name if set, undefined otherwise
+     */
+    async getCustomName(agentName, sessionId) {
+        const metadata = await this.loadMetadata(agentName);
+        if (!metadata) {
+            return undefined;
+        }
+        return metadata.sessions[sessionId]?.customName;
+    }
+    /**
+     * Set custom name for a session
+     *
+     * Creates the metadata file if it doesn't exist.
+     *
+     * @param agentName - The agent's qualified name
+     * @param sessionId - The session ID
+     * @param name - The custom name to set
+     */
+    async setCustomName(agentName, sessionId, name) {
+        let metadata = await this.loadMetadata(agentName);
+        if (!metadata) {
+            metadata = this.createEmptyMetadata(agentName);
+        }
+        // Get or create the session entry
+        const sessionEntry = metadata.sessions[sessionId] ?? {};
+        // Update the custom name
+        metadata.sessions[sessionId] = {
+            ...sessionEntry,
+            customName: name,
+        };
+        await this.saveMetadata(agentName, metadata);
+        logger.debug(`Set custom name for session ${sessionId}`, {
+            agentName,
+            customName: name,
+        });
+    }
+    /**
+     * Remove custom name for a session
+     *
+     * If this was the only metadata for the session, the session entry is removed.
+     * If this was the only session with metadata, the file is kept but empty
+     * (to avoid repeatedly creating/deleting files).
+     *
+     * @param agentName - The agent's qualified name
+     * @param sessionId - The session ID
+     */
+    async removeCustomName(agentName, sessionId) {
+        const metadata = await this.loadMetadata(agentName);
+        if (!metadata) {
+            // No metadata file exists, nothing to remove
+            return;
+        }
+        const sessionEntry = metadata.sessions[sessionId];
+        if (!sessionEntry) {
+            // No entry for this session, nothing to remove
+            return;
+        }
+        // Remove the customName
+        delete sessionEntry.customName;
+        // If the session entry is now empty, remove it entirely
+        if (Object.keys(sessionEntry).length === 0) {
+            delete metadata.sessions[sessionId];
+        }
+        else {
+            metadata.sessions[sessionId] = sessionEntry;
+        }
+        await this.saveMetadata(agentName, metadata);
+        logger.debug(`Removed custom name for session ${sessionId}`, { agentName });
+    }
+    /**
+     * Get all metadata for an agent's sessions
+     *
+     * Useful for batch operations or displaying metadata for all sessions.
+     *
+     * @param agentName - The agent's qualified name
+     * @returns The full metadata file, or null if no metadata exists
+     */
+    async getAgentMetadata(agentName) {
+        return this.loadMetadata(agentName);
+    }
+    /**
+     * Get auto-generated name and its mtime for a session
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param sessionId - The session ID
+     * @returns Object with autoName and autoNameMtime, or undefined if not cached
+     */
+    async getAutoName(agentName, sessionId) {
+        const metadata = await this.loadMetadata(agentName);
+        if (!metadata) {
+            return undefined;
+        }
+        const entry = metadata.sessions[sessionId];
+        if (!entry) {
+            return undefined;
+        }
+        return {
+            autoName: entry.autoName,
+            autoNameMtime: entry.autoNameMtime,
+        };
+    }
+    /**
+     * Set auto-generated name for a session
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param sessionId - The session ID
+     * @param autoName - The auto-generated name to set
+     * @param mtime - ISO 8601 timestamp of the session file when the name was extracted
+     */
+    async setAutoName(agentName, sessionId, autoName, mtime) {
+        let metadata = await this.loadMetadata(agentName);
+        if (!metadata) {
+            metadata = this.createEmptyMetadata(agentName);
+        }
+        // Get or create the session entry
+        const sessionEntry = metadata.sessions[sessionId] ?? {};
+        // Update the auto name fields
+        metadata.sessions[sessionId] = {
+            ...sessionEntry,
+            autoName,
+            autoNameMtime: mtime,
+        };
+        await this.saveMetadata(agentName, metadata);
+        logger.debug(`Set auto name for session ${sessionId}`, {
+            agentName,
+            autoName,
+        });
+    }
+    /**
+     * Batch set auto-generated names for multiple sessions
+     *
+     * More efficient than calling setAutoName repeatedly since it performs
+     * a single file write for all updates.
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param entries - Array of { sessionId, autoName, mtime } objects
+     */
+    async batchSetAutoNames(agentName, entries) {
+        if (entries.length === 0) {
+            return;
+        }
+        let metadata = await this.loadMetadata(agentName);
+        if (!metadata) {
+            metadata = this.createEmptyMetadata(agentName);
+        }
+        // Apply all updates
+        for (const { sessionId, autoName, mtime } of entries) {
+            const sessionEntry = metadata.sessions[sessionId] ?? {};
+            metadata.sessions[sessionId] = {
+                ...sessionEntry,
+                autoName,
+                autoNameMtime: mtime,
+            };
+        }
+        await this.saveMetadata(agentName, metadata);
+        logger.debug(`Batch set auto names for ${entries.length} sessions`, {
+            agentName,
+        });
+    }
+    /**
+     * Get cached preview and its mtime for a session
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param sessionId - The session ID
+     * @returns Object with preview and previewMtime, or undefined if not cached
+     */
+    async getPreview(agentName, sessionId) {
+        const metadata = await this.loadMetadata(agentName);
+        if (!metadata) {
+            return undefined;
+        }
+        const entry = metadata.sessions[sessionId];
+        if (!entry) {
+            return undefined;
+        }
+        return {
+            preview: entry.preview,
+            previewMtime: entry.previewMtime,
+        };
+    }
+    /**
+     * Set preview for a session
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param sessionId - The session ID
+     * @param preview - The first user message preview text
+     * @param mtime - ISO 8601 timestamp of the session file when the preview was extracted
+     */
+    async setPreview(agentName, sessionId, preview, mtime) {
+        let metadata = await this.loadMetadata(agentName);
+        if (!metadata) {
+            metadata = this.createEmptyMetadata(agentName);
+        }
+        const sessionEntry = metadata.sessions[sessionId] ?? {};
+        metadata.sessions[sessionId] = {
+            ...sessionEntry,
+            preview,
+            previewMtime: mtime,
+        };
+        await this.saveMetadata(agentName, metadata);
+        logger.debug(`Set preview for session ${sessionId}`, {
+            agentName,
+            preview,
+        });
+    }
+    /**
+     * Batch set previews for multiple sessions
+     *
+     * More efficient than calling setPreview repeatedly since it performs
+     * a single file write for all updates.
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param entries - Array of { sessionId, preview, mtime } objects
+     */
+    async batchSetPreviews(agentName, entries) {
+        if (entries.length === 0) {
+            return;
+        }
+        let metadata = await this.loadMetadata(agentName);
+        if (!metadata) {
+            metadata = this.createEmptyMetadata(agentName);
+        }
+        for (const { sessionId, preview, mtime } of entries) {
+            const sessionEntry = metadata.sessions[sessionId] ?? {};
+            metadata.sessions[sessionId] = {
+                ...sessionEntry,
+                preview,
+                previewMtime: mtime,
+            };
+        }
+        await this.saveMetadata(agentName, metadata);
+        logger.debug(`Batch set previews for ${entries.length} sessions`, {
+            agentName,
+        });
+    }
+}
+//# sourceMappingURL=session-metadata.js.map

package/dist/state/session-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-metadata.js","sourceRoot":"","sources":["../../src/state/session-metadata.ts"],"names":[],"mappings":"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"}