@herdctl/chat 0.0.1 → 0.2.0

package/dist/session-manager/session-manager.js

@@ -0,0 +1,394 @@
+/**
+ * Session manager for chat channel conversations
+ *
+ * Provides per-channel session management for Claude conversations,
+ * enabling conversation context preservation across chat channels.
+ *
+ * This implementation is shared between Discord, Slack, and other chat platforms.
+ * Sessions are stored at .herdctl/<platform>-sessions/<agent-name>.yaml
+ */
+import { mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { stringify as stringifyYaml, parse as parseYaml } from "yaml";
+import { readFile, writeFile, rename, unlink } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { createLogger } from "@herdctl/core";
+import { ChatSessionStateSchema, createInitialSessionState, } from "./types.js";
+import { SessionStateReadError, SessionStateWriteError, SessionDirectoryCreateError, } from "./errors.js";
+// =============================================================================
+// Default Logger
+// =============================================================================
+function createDefaultLogger(platform, agentName) {
+    return createLogger(`${platform}-session:${agentName}`);
+}
+// =============================================================================
+// Session Manager Implementation
+// =============================================================================
+/**
+ * ChatSessionManager manages per-channel Claude sessions for a chat agent.
+ *
+ * Each agent has its own ChatSessionManager instance, storing session mappings
+ * in a YAML file at .herdctl/<platform>-sessions/<agent-name>.yaml
+ *
+ * Features:
+ * - Create new sessions for channels/DMs
+ * - Resume existing sessions when user sends messages
+ * - Automatic session expiry based on configurable timeout
+ * - Cleanup expired sessions on startup
+ *
+ * @example
+ * ```typescript
+ * const sessionManager = new ChatSessionManager({
+ *   platform: 'discord',
+ *   agentName: 'my-agent',
+ *   stateDir: '.herdctl',
+ *   sessionExpiryHours: 24,
+ * });
+ *
+ * // Get or create a session for a channel
+ * const { sessionId, isNew } = await sessionManager.getOrCreateSession('channel-123');
+ *
+ * // After sending/receiving a message
+ * await sessionManager.touchSession('channel-123');
+ *
+ * // Cleanup expired sessions on startup
+ * const cleanedUp = await sessionManager.cleanupExpiredSessions();
+ * ```
+ */
+export class ChatSessionManager {
+    agentName;
+    platform;
+    stateDir;
+    sessionExpiryHours;
+    logger;
+    stateFilePath;
+    // In-memory cache of session state
+    state = null;
+    constructor(options) {
+        this.platform = options.platform;
+        this.agentName = options.agentName;
+        this.stateDir = options.stateDir;
+        this.sessionExpiryHours = options.sessionExpiryHours ?? 24;
+        this.logger =
+            options.logger ?? createDefaultLogger(options.platform, options.agentName);
+        // Compute state file path: .herdctl/<platform>-sessions/<agent>.yaml
+        this.stateFilePath = join(this.stateDir, `${this.platform}-sessions`, `${this.agentName}.yaml`);
+    }
+    // ===========================================================================
+    // Public API
+    // ===========================================================================
+    /**
+     * Get or create a session for a channel/DM
+     *
+     * If an active (non-expired) session exists, returns it.
+     * Otherwise, creates a new session with a generated session ID.
+     */
+    async getOrCreateSession(channelId) {
+        const existingSession = await this.getSession(channelId);
+        if (existingSession) {
+            this.logger.info("Resuming existing session", {
+                channelId,
+                sessionId: existingSession.sessionId,
+            });
+            return {
+                sessionId: existingSession.sessionId,
+                isNew: false,
+            };
+        }
+        // Create new session
+        const sessionId = this.generateSessionId();
+        const state = await this.loadState();
+        const now = new Date().toISOString();
+        state.channels[channelId] = {
+            sessionId,
+            lastMessageAt: now,
+        };
+        await this.saveState(state);
+        this.logger.info("Created new session", { channelId, sessionId });
+        return {
+            sessionId,
+            isNew: true,
+        };
+    }
+    /**
+     * Update the last message timestamp for a session
+     */
+    async touchSession(channelId) {
+        const state = await this.loadState();
+        const session = state.channels[channelId];
+        if (!session) {
+            this.logger.warn("Attempted to touch non-existent session", {
+                channelId,
+            });
+            return;
+        }
+        session.lastMessageAt = new Date().toISOString();
+        await this.saveState(state);
+        this.logger.debug("Touched session", {
+            channelId,
+            sessionId: session.sessionId,
+        });
+    }
+    /**
+     * Get an existing session without creating one
+     *
+     * Returns null if no session exists or if the session is expired.
+     */
+    async getSession(channelId) {
+        const state = await this.loadState();
+        const session = state.channels[channelId];
+        if (!session) {
+            return null;
+        }
+        // Check if session is expired
+        if (this.isSessionExpired(session)) {
+            this.logger.info("Session expired", {
+                channelId,
+                sessionId: session.sessionId,
+                lastMessageAt: session.lastMessageAt,
+                expiryHours: this.sessionExpiryHours,
+            });
+            return null;
+        }
+        return session;
+    }
+    /**
+     * Store or update the session ID for a channel
+     *
+     * Called after a job completes to store the SDK-provided session ID.
+     */
+    async setSession(channelId, sessionId) {
+        const state = await this.loadState();
+        const now = new Date().toISOString();
+        const existingSession = state.channels[channelId];
+        state.channels[channelId] = {
+            sessionId,
+            lastMessageAt: now,
+        };
+        await this.saveState(state);
+        if (existingSession) {
+            this.logger.debug("Updated session", {
+                channelId,
+                oldSessionId: existingSession.sessionId,
+                newSessionId: sessionId,
+            });
+        }
+        else {
+            this.logger.info("Stored new session", { channelId, sessionId });
+        }
+    }
+    /**
+     * Clear a specific session
+     */
+    async clearSession(channelId) {
+        const state = await this.loadState();
+        if (!state.channels[channelId]) {
+            return false;
+        }
+        const sessionId = state.channels[channelId].sessionId;
+        delete state.channels[channelId];
+        await this.saveState(state);
+        this.logger.info("Cleared session", { channelId, sessionId });
+        return true;
+    }
+    /**
+     * Clean up all expired sessions
+     *
+     * Should be called on connector startup and periodically.
+     */
+    async cleanupExpiredSessions() {
+        const state = await this.loadState();
+        const channelIds = Object.keys(state.channels);
+        let cleanedUp = 0;
+        for (const channelId of channelIds) {
+            const session = state.channels[channelId];
+            if (this.isSessionExpired(session)) {
+                this.logger.debug("Cleaning up expired session", {
+                    channelId,
+                    sessionId: session.sessionId,
+                    lastMessageAt: session.lastMessageAt,
+                });
+                delete state.channels[channelId];
+                cleanedUp++;
+            }
+        }
+        if (cleanedUp > 0) {
+            await this.saveState(state);
+            this.logger.info("Cleaned up expired sessions", { count: cleanedUp });
+        }
+        return cleanedUp;
+    }
+    /**
+     * Get the count of active (non-expired) sessions
+     *
+     * Useful for logging during shutdown to confirm sessions are preserved.
+     */
+    async getActiveSessionCount() {
+        const state = await this.loadState();
+        let activeCount = 0;
+        for (const channelId of Object.keys(state.channels)) {
+            const session = state.channels[channelId];
+            if (!this.isSessionExpired(session)) {
+                activeCount++;
+            }
+        }
+        return activeCount;
+    }
+    // ===========================================================================
+    // Private Helpers
+    // ===========================================================================
+    /**
+     * Generate a unique session ID
+     * Format: <platform>-<agentName>-<uuid>
+     */
+    generateSessionId() {
+        return `${this.platform}-${this.agentName}-${randomUUID()}`;
+    }
+    /**
+     * Check if a session is expired
+     */
+    isSessionExpired(session) {
+        const lastMessageAt = new Date(session.lastMessageAt);
+        const now = new Date();
+        const expiryMs = this.sessionExpiryHours * 60 * 60 * 1000;
+        return now.getTime() - lastMessageAt.getTime() > expiryMs;
+    }
+    /**
+     * Load session state from disk
+     *
+     * Returns cached state if available, otherwise loads from file.
+     * Creates initial state if file doesn't exist.
+     */
+    async loadState() {
+        if (this.state) {
+            return this.state;
+        }
+        let content;
+        try {
+            content = await readFile(this.stateFilePath, "utf-8");
+        }
+        catch (error) {
+            const code = error.code;
+            // File doesn't exist - create initial state
+            if (code === "ENOENT") {
+                this.state = createInitialSessionState(this.agentName);
+                return this.state;
+            }
+            // Other read errors are fatal
+            throw new SessionStateReadError(this.agentName, this.stateFilePath, {
+                cause: error,
+            });
+        }
+        // Handle empty file
+        if (content.trim() === "") {
+            this.state = createInitialSessionState(this.agentName);
+            return this.state;
+        }
+        // Parse YAML - treat parse errors as corrupted state
+        let parsed;
+        try {
+            parsed = parseYaml(content);
+        }
+        catch (error) {
+            this.logger.warn("Corrupted session state file, creating fresh state", {
+                error: error.message,
+            });
+            this.state = createInitialSessionState(this.agentName);
+            return this.state;
+        }
+        // Validate against schema - treat validation errors as corrupted state
+        const validated = ChatSessionStateSchema.safeParse(parsed);
+        if (!validated.success) {
+            this.logger.warn("Corrupted session state file, creating fresh state", {
+                error: validated.error.message,
+            });
+            this.state = createInitialSessionState(this.agentName);
+            return this.state;
+        }
+        this.state = validated.data;
+        return this.state;
+    }
+    /**
+     * Save session state to disk atomically
+     */
+    async saveState(state) {
+        // Ensure directory exists
+        await this.ensureDirectoryExists();
+        // Update in-memory cache
+        this.state = state;
+        // Write atomically
+        const yamlContent = stringifyYaml(state, { indent: 2, lineWidth: 120 });
+        const tempPath = this.generateTempPath(this.stateFilePath);
+        try {
+            await writeFile(tempPath, yamlContent, "utf-8");
+            await this.renameWithRetry(tempPath, this.stateFilePath);
+        }
+        catch (error) {
+            // Clean up temp file on failure
+            try {
+                await unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw new SessionStateWriteError(this.agentName, this.stateFilePath, {
+                cause: error,
+            });
+        }
+    }
+    /**
+     * Ensure the sessions directory exists
+     */
+    async ensureDirectoryExists() {
+        const dir = dirname(this.stateFilePath);
+        try {
+            await mkdir(dir, { recursive: true });
+        }
+        catch (error) {
+            const code = error.code;
+            // EEXIST is fine - directory already exists
+            if (code !== "EEXIST") {
+                throw new SessionDirectoryCreateError(this.agentName, dir, {
+                    cause: error,
+                });
+            }
+        }
+    }
+    /**
+     * Generate a temp file path for atomic writes
+     */
+    generateTempPath(targetPath) {
+        const dir = dirname(targetPath);
+        const random = randomBytes(8).toString("hex");
+        const filename = `${this.agentName}.yaml`;
+        return join(dir, `.${filename}.tmp.${random}`);
+    }
+    /**
+     * Rename with retry logic for Windows compatibility
+     */
+    async renameWithRetry(oldPath, newPath, maxRetries = 3, baseDelayMs = 50) {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                await rename(oldPath, newPath);
+                return;
+            }
+            catch (error) {
+                lastError = error;
+                const code = error.code;
+                // Only retry on Windows-specific errors
+                if (code !== "EACCES" && code !== "EPERM") {
+                    throw error;
+                }
+                // Don't delay on the last attempt
+                if (attempt < maxRetries) {
+                    const delay = baseDelayMs * Math.pow(2, attempt);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+            }
+        }
+        throw lastError;
+    }
+}
+//# sourceMappingURL=session-manager.js.map

package/dist/session-manager/session-manager.js.map

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

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

@@ -0,0 +1,205 @@
+/**
+ * Type definitions for chat session management
+ *
+ * Provides interfaces for per-channel session state tracking,
+ * enabling conversation context preservation across chat channels.
+ *
+ * This module is shared between Discord, Slack, and other chat platforms.
+ */
+import { z } from "zod";
+/**
+ * Schema for individual channel session mapping
+ */
+export declare const ChannelSessionSchema: z.ZodObject<{
+    /** Claude session ID for resuming conversations */
+    sessionId: z.ZodString;
+    /** ISO timestamp when last message was sent/received */
+    lastMessageAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    lastMessageAt: string;
+}, {
+    sessionId: string;
+    lastMessageAt: string;
+}>;
+/**
+ * Schema for the entire agent's chat session state file
+ *
+ * Stored at .herdctl/<platform>-sessions/<agent-name>.yaml
+ * For example:
+ *   - .herdctl/discord-sessions/my-agent.yaml
+ *   - .herdctl/slack-sessions/my-agent.yaml
+ */
+export declare const ChatSessionStateSchema: z.ZodObject<{
+    /**
+     * Schema version. Accepts 1, 2, and 3 — all have identical structure.
+     * (1 was Discord's original, 2 was Slack's, 3 was a mistaken bump.)
+     * Only increment this when the schema shape actually changes, and add
+     * migration logic to handle older versions.
+     */
+    version: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+    /** Agent name this session state belongs to */
+    agentName: z.ZodString;
+    /** Map of channel ID to session info */
+    channels: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Claude session ID for resuming conversations */
+        sessionId: z.ZodString;
+        /** ISO timestamp when last message was sent/received */
+        lastMessageAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+        lastMessageAt: string;
+    }, {
+        sessionId: string;
+        lastMessageAt: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: 3 | 2 | 1;
+    agentName: string;
+    channels: Record<string, {
+        sessionId: string;
+        lastMessageAt: string;
+    }>;
+}, {
+    version: 3 | 2 | 1;
+    agentName: string;
+    channels: Record<string, {
+        sessionId: string;
+        lastMessageAt: string;
+    }>;
+}>;
+export type ChannelSession = z.infer<typeof ChannelSessionSchema>;
+export type ChatSessionState = z.infer<typeof ChatSessionStateSchema>;
+/**
+ * Logger interface for session manager operations
+ */
+export interface SessionManagerLogger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Options for configuring the ChatSessionManager
+ */
+export interface ChatSessionManagerOptions {
+    /**
+     * Platform identifier (e.g., "discord", "slack")
+     * Used to compute storage path and session ID prefix
+     */
+    platform: string;
+    /**
+     * Name of the agent this session manager is for
+     */
+    agentName: string;
+    /**
+     * Root path for state storage (e.g., .herdctl)
+     * Sessions will be stored at <stateDir>/<platform>-sessions/<agent-name>.yaml
+     */
+    stateDir: string;
+    /**
+     * Session expiry timeout in hours
+     * Sessions inactive for longer than this will be considered expired
+     *
+     * @default 24
+     */
+    sessionExpiryHours?: number;
+    /**
+     * Logger for session manager operations
+     *
+     * @default console-based logger using createLogger from @herdctl/core
+     */
+    logger?: SessionManagerLogger;
+}
+/**
+ * Result of getting or creating a session
+ */
+export interface SessionResult {
+    /** Claude session ID */
+    sessionId: string;
+    /** Whether this is a newly created session */
+    isNew: boolean;
+}
+/**
+ * Interface that all chat session managers must implement
+ */
+export interface IChatSessionManager {
+    /**
+     * Get or create a session for a channel
+     *
+     * If an active (non-expired) session exists, returns it.
+     * Otherwise, creates a new session.
+     *
+     * @param channelId - Channel or DM ID
+     * @returns Session info with sessionId and isNew flag
+     */
+    getOrCreateSession(channelId: string): Promise<SessionResult>;
+    /**
+     * Update the last message timestamp for a session
+     *
+     * Called after each message to keep the session active.
+     *
+     * @param channelId - Channel or DM ID
+     */
+    touchSession(channelId: string): Promise<void>;
+    /**
+     * Get an existing session without creating one
+     *
+     * Returns null if no session exists or if the session is expired.
+     *
+     * @param channelId - Channel or DM ID
+     * @returns The session if it exists and is not expired, null otherwise
+     */
+    getSession(channelId: string): Promise<ChannelSession | null>;
+    /**
+     * Store or update the session ID for a channel
+     *
+     * Called after a job completes to store the SDK-provided session ID.
+     * This enables conversation continuity by allowing subsequent requests
+     * to resume from this session.
+     *
+     * @param channelId - Channel or DM ID
+     * @param sessionId - The Claude Agent SDK session ID
+     */
+    setSession(channelId: string, sessionId: string): Promise<void>;
+    /**
+     * Clear a specific session
+     *
+     * @param channelId - Channel or DM ID
+     * @returns true if the session was cleared, false if it didn't exist
+     */
+    clearSession(channelId: string): Promise<boolean>;
+    /**
+     * Clean up all expired sessions
+     *
+     * Should be called on connector startup and periodically.
+     *
+     * @returns Number of sessions that were cleaned up
+     */
+    cleanupExpiredSessions(): Promise<number>;
+    /**
+     * Get the count of active (non-expired) sessions
+     *
+     * Useful for logging during shutdown to confirm sessions are preserved.
+     *
+     * @returns Number of active sessions
+     */
+    getActiveSessionCount(): Promise<number>;
+    /**
+     * Name of the agent this session manager is for
+     */
+    readonly agentName: string;
+    /**
+     * Platform identifier this session manager is for
+     */
+    readonly platform: string;
+}
+/**
+ * Create initial session state for a new agent
+ */
+export declare function createInitialSessionState(agentName: string): ChatSessionState;
+/**
+ * Create a new channel session
+ */
+export declare function createChannelSession(sessionId: string): ChannelSession;
+//# sourceMappingURL=types.d.ts.map

package/dist/session-manager/types.d.ts.map

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

package/dist/session-manager/types.js

@@ -0,0 +1,67 @@
+/**
+ * Type definitions for chat session management
+ *
+ * Provides interfaces for per-channel session state tracking,
+ * enabling conversation context preservation across chat channels.
+ *
+ * This module is shared between Discord, Slack, and other chat platforms.
+ */
+import { z } from "zod";
+// =============================================================================
+// Session Schema
+// =============================================================================
+/**
+ * Schema for individual channel session mapping
+ */
+export const ChannelSessionSchema = z.object({
+    /** Claude session ID for resuming conversations */
+    sessionId: z.string().min(1, "Session ID cannot be empty"),
+    /** ISO timestamp when last message was sent/received */
+    lastMessageAt: z.string().datetime({
+        message: "lastMessageAt must be a valid ISO datetime string",
+    }),
+});
+/**
+ * Schema for the entire agent's chat session state file
+ *
+ * Stored at .herdctl/<platform>-sessions/<agent-name>.yaml
+ * For example:
+ *   - .herdctl/discord-sessions/my-agent.yaml
+ *   - .herdctl/slack-sessions/my-agent.yaml
+ */
+export const ChatSessionStateSchema = z.object({
+    /**
+     * Schema version. Accepts 1, 2, and 3 — all have identical structure.
+     * (1 was Discord's original, 2 was Slack's, 3 was a mistaken bump.)
+     * Only increment this when the schema shape actually changes, and add
+     * migration logic to handle older versions.
+     */
+    version: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+    /** Agent name this session state belongs to */
+    agentName: z.string().min(1, "Agent name cannot be empty"),
+    /** Map of channel ID to session info */
+    channels: z.record(z.string(), ChannelSessionSchema),
+});
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Create initial session state for a new agent
+ */
+export function createInitialSessionState(agentName) {
+    return {
+        version: 1,
+        agentName,
+        channels: {},
+    };
+}
+/**
+ * Create a new channel session
+ */
+export function createChannelSession(sessionId) {
+    return {
+        sessionId,
+        lastMessageAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=types.js.map