@herdctl/core 5.5.0 → 5.7.0

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

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

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

@@ -0,0 +1,188 @@
+/**
+ * Session Discovery Service
+ *
+ * Orchestrates session enumeration by tying together JSONL parsing,
+ * session attribution, and CLI session path utilities. Provides cached
+ * discovery of Claude Code sessions from the filesystem.
+ */
+import { type ChatMessage, type SessionMetadata, type SessionUsage } from "./jsonl-parser.js";
+import { type SessionOrigin } from "./session-attribution.js";
+/**
+ * A discovered session with attribution and metadata
+ */
+export interface DiscoveredSession {
+    sessionId: string;
+    workingDirectory: string;
+    mtime: string;
+    origin: SessionOrigin;
+    agentName: string | undefined;
+    resumable: boolean;
+    customName: string | undefined;
+    /** Auto-generated session name (extracted from JSONL summary field) */
+    autoName: string | undefined;
+    preview: string | undefined;
+}
+/**
+ * A group of sessions by working directory
+ */
+export interface DirectoryGroup {
+    workingDirectory: string;
+    encodedPath: string;
+    agentName: string | undefined;
+    sessionCount: number;
+    sessions: DiscoveredSession[];
+}
+/**
+ * Options for creating a SessionDiscoveryService
+ */
+export interface SessionDiscoveryOptions {
+    /** Path to ~/.claude directory. Default: path.join(os.homedir(), ".claude") */
+    claudeHomePath?: string;
+    /** Path to the .herdctl/ state directory */
+    stateDir: string;
+    /** Cache TTL in milliseconds. Default: 30_000 (30 seconds) */
+    cacheTtlMs?: number;
+}
+/**
+ * Service for discovering and enumerating Claude Code sessions.
+ *
+ * Provides cached access to session files, with attribution from job metadata
+ * and platform session files, plus custom names from the session metadata store.
+ *
+ * @example
+ * ```typescript
+ * const discovery = new SessionDiscoveryService({
+ *   stateDir: '/path/to/.herdctl',
+ * });
+ *
+ * // Get sessions for a specific agent
+ * const sessions = await discovery.getAgentSessions('my-agent', '/path/to/workspace', false);
+ *
+ * // Get all sessions grouped by directory
+ * const groups = await discovery.getAllSessions([
+ *   { name: 'agent-1', workingDirectory: '/path/to/project', dockerEnabled: false }
+ * ]);
+ * ```
+ */
+export declare class SessionDiscoveryService {
+    private readonly claudeHomePath;
+    private readonly stateDir;
+    private readonly cacheTtlMs;
+    private attributionIndex;
+    private attributionFetchedAt;
+    private directoryCache;
+    private metadataCache;
+    private readonly sessionMetadataStore;
+    /**
+     * Create a new SessionDiscoveryService
+     *
+     * @param options - Configuration options
+     */
+    constructor(options: SessionDiscoveryOptions);
+    /**
+     * Check if the attribution index cache is valid
+     */
+    private isAttributionCacheValid;
+    /**
+     * Check if a directory cache entry is valid
+     */
+    private isDirectoryCacheValid;
+    /**
+     * Get or refresh the attribution index
+     */
+    private getAttributionIndex;
+    /**
+     * List session files in a directory with their modification times
+     */
+    private listSessionFiles;
+    /**
+     * Resolve the auto-generated name for a session.
+     *
+     * Checks if the cached autoName is still valid (based on file mtime).
+     * If not, extracts a new name from the JSONL summary field.
+     *
+     * @param agentName - The agent's qualified name (use "adhoc" for unattributed sessions)
+     * @param sessionId - The session ID
+     * @param fileMtime - ISO 8601 timestamp of the session file's modification time
+     * @param workingDirectory - The session's working directory
+     * @returns Object with autoName and whether an update is needed
+     */
+    private resolveAutoName;
+    /**
+     * Get sessions for a specific agent.
+     *
+     * Returns sessions from the agent's working directory, attributed and
+     * enriched with custom names from the metadata store.
+     *
+     * @param agentName - The agent's qualified name
+     * @param workingDirectory - The agent's working directory
+     * @param dockerEnabled - Whether Docker is enabled for the agent (affects resumability)
+     * @param options - Optional settings (limit for top-N optimization)
+     * @returns Array of discovered sessions sorted by mtime descending
+     */
+    getAgentSessions(agentName: string, workingDirectory: string, dockerEnabled: boolean, options?: {
+        limit?: number;
+    }): Promise<DiscoveredSession[]>;
+    /**
+     * Get all sessions grouped by working directory.
+     *
+     * Scans the Claude projects directory and groups sessions by their
+     * working directories. Filters out temp directories and enriches
+     * sessions with attribution and custom names.
+     *
+     * When a limit is provided, only the most recent `limit` sessions
+     * (by mtime) are enriched with names, avoiding expensive JSONL parsing
+     * for sessions that won't be returned.
+     *
+     * @param agents - Array of known agents for matching sessions
+     * @param options - Optional settings (limit for top-N optimization)
+     * @returns Array of directory groups sorted by most recent session
+     */
+    getAllSessions(agents: Array<{
+        name: string;
+        workingDirectory: string;
+        dockerEnabled: boolean;
+    }>, options?: {
+        limit?: number;
+    }): Promise<DirectoryGroup[]>;
+    /**
+     * Get parsed chat messages from a session.
+     *
+     * Delegates to the JSONL parser.
+     *
+     * @param workingDirectory - The session's working directory
+     * @param sessionId - The session ID
+     * @returns Array of chat messages
+     */
+    getSessionMessages(workingDirectory: string, sessionId: string): Promise<ChatMessage[]>;
+    /**
+     * Get metadata for a session.
+     *
+     * Caches the result for efficiency when called repeatedly.
+     *
+     * @param workingDirectory - The session's working directory
+     * @param sessionId - The session ID
+     * @returns Session metadata
+     */
+    getSessionMetadata(workingDirectory: string, sessionId: string): Promise<SessionMetadata>;
+    /**
+     * Get usage data for a session.
+     *
+     * Delegates to the JSONL parser.
+     *
+     * @param workingDirectory - The session's working directory
+     * @param sessionId - The session ID
+     * @returns Session usage data
+     */
+    getSessionUsage(workingDirectory: string, sessionId: string): Promise<SessionUsage>;
+    /**
+     * Invalidate cached data.
+     *
+     * If a working directory is provided, only that directory's cache entry
+     * is cleared. Otherwise, all caches are cleared.
+     *
+     * @param workingDirectory - Optional working directory to clear cache for
+     */
+    invalidateCache(workingDirectory?: string): void;
+}
+//# sourceMappingURL=session-discovery.d.ts.map

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

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