@herdctl/chat 0.0.1 → 0.2.0

package/dist/message-splitting.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Message splitting utilities for chat platforms
+ *
+ * Provides utilities for:
+ * - Splitting long messages to fit platform character limits
+ * - Maintaining message coherence when splitting (avoiding mid-sentence breaks)
+ * - Preserving code blocks when splitting
+ */
+/**
+ * Default delay between sending split messages (in milliseconds)
+ */
+export declare const DEFAULT_MESSAGE_DELAY_MS = 500;
+/**
+ * Minimum chunk size when splitting messages
+ * Prevents creating very small message fragments
+ */
+export declare const MIN_CHUNK_SIZE = 100;
+/**
+ * Options for splitting messages
+ */
+export interface MessageSplitOptions {
+    /**
+     * Maximum length for each message chunk
+     * Required - no default since it varies by platform
+     */
+    maxLength: number;
+    /**
+     * Whether to try to split at natural boundaries like sentences (default: true)
+     */
+    preserveBoundaries?: boolean;
+    /**
+     * Characters to use as split points, in order of preference
+     * Default: ['\n\n', '\n', '. ', '! ', '? ', ', ', ' ']
+     */
+    splitPoints?: string[];
+}
+/**
+ * Result from splitting a message
+ */
+export interface SplitResult {
+    /** Array of message chunks */
+    chunks: string[];
+    /** Whether the message was split */
+    wasSplit: boolean;
+    /** Original message length */
+    originalLength: number;
+}
+/**
+ * Default split points in order of preference
+ *
+ * We prefer to split at paragraph breaks, then sentences, then clauses, then words
+ */
+export declare const DEFAULT_SPLIT_POINTS: string[];
+/**
+ * Find the best split point within a text chunk
+ *
+ * @param text - Text to find split point in
+ * @param maxLength - Maximum length for the chunk
+ * @param splitPoints - Split points to search for, in order of preference
+ * @returns Index to split at, or maxLength if no good split point found
+ *
+ * @example
+ * ```typescript
+ * const splitIndex = findSplitPoint(longText, 2000);
+ * const firstPart = longText.slice(0, splitIndex);
+ * const secondPart = longText.slice(splitIndex);
+ * ```
+ */
+export declare function findSplitPoint(text: string, maxLength: number, splitPoints?: string[]): number;
+/**
+ * Split a message into chunks that fit within the specified max length
+ *
+ * @param content - Message content to split
+ * @param options - Split options including maxLength
+ * @returns Split result with chunks array
+ *
+ * @example
+ * ```typescript
+ * const result = splitMessage(longText, { maxLength: 2000 });
+ * for (const chunk of result.chunks) {
+ *   await channel.send(chunk);
+ * }
+ * ```
+ */
+export declare function splitMessage(content: string, options: MessageSplitOptions): SplitResult;
+/**
+ * Check if a message needs to be split
+ *
+ * @param content - Message content to check
+ * @param maxLength - Maximum message length
+ * @returns true if the message exceeds the max length
+ *
+ * @example
+ * ```typescript
+ * if (needsSplit(message, 2000)) {
+ *   const { chunks } = splitMessage(message, { maxLength: 2000 });
+ *   // Send each chunk
+ * } else {
+ *   // Send as-is
+ * }
+ * ```
+ */
+export declare function needsSplit(content: string, maxLength: number): boolean;
+/**
+ * Truncate a message to fit within the max length, adding an ellipsis
+ *
+ * @param content - Message content to truncate
+ * @param maxLength - Maximum length
+ * @param ellipsis - Ellipsis to append (default: '...')
+ * @returns Truncated message
+ *
+ * @example
+ * ```typescript
+ * const short = truncateMessage(longText, 100);
+ * // Returns: "This is a very long text that has been trun..."
+ * ```
+ */
+export declare function truncateMessage(content: string, maxLength: number, ellipsis?: string): string;
+/**
+ * Format code as a code block with optional language
+ *
+ * @param code - Code to format
+ * @param language - Optional language for syntax highlighting
+ * @returns Formatted code block
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatCodeBlock('const x = 1;', 'typescript');
+ * // Returns: "```typescript\nconst x = 1;\n```"
+ * ```
+ */
+export declare function formatCodeBlock(code: string, language?: string): string;
+//# sourceMappingURL=message-splitting.d.ts.map

package/dist/message-splitting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-splitting.d.ts","sourceRoot":"","sources":["../src/message-splitting.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;GAEG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAMlC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAElB,8BAA8B;IAC9B,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,UAA8C,CAAC;AAMhF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,MAAM,EAAyB,GAC3C,MAAM,CA4BR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,WAAW,CAoDb;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAc,GACvB,MAAM,CAOR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGvE"}

package/dist/message-splitting.js

@@ -0,0 +1,188 @@
+/**
+ * Message splitting utilities for chat platforms
+ *
+ * Provides utilities for:
+ * - Splitting long messages to fit platform character limits
+ * - Maintaining message coherence when splitting (avoiding mid-sentence breaks)
+ * - Preserving code blocks when splitting
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Default delay between sending split messages (in milliseconds)
+ */
+export const DEFAULT_MESSAGE_DELAY_MS = 500;
+/**
+ * Minimum chunk size when splitting messages
+ * Prevents creating very small message fragments
+ */
+export const MIN_CHUNK_SIZE = 100;
+// =============================================================================
+// Default Split Points
+// =============================================================================
+/**
+ * Default split points in order of preference
+ *
+ * We prefer to split at paragraph breaks, then sentences, then clauses, then words
+ */
+export const DEFAULT_SPLIT_POINTS = ["\n\n", "\n", ". ", "! ", "? ", ", ", " "];
+// =============================================================================
+// Message Splitting Functions
+// =============================================================================
+/**
+ * Find the best split point within a text chunk
+ *
+ * @param text - Text to find split point in
+ * @param maxLength - Maximum length for the chunk
+ * @param splitPoints - Split points to search for, in order of preference
+ * @returns Index to split at, or maxLength if no good split point found
+ *
+ * @example
+ * ```typescript
+ * const splitIndex = findSplitPoint(longText, 2000);
+ * const firstPart = longText.slice(0, splitIndex);
+ * const secondPart = longText.slice(splitIndex);
+ * ```
+ */
+export function findSplitPoint(text, maxLength, splitPoints = DEFAULT_SPLIT_POINTS) {
+    // If text fits, no split needed
+    if (text.length <= maxLength) {
+        return text.length;
+    }
+    // Try each split point in order of preference
+    for (const splitPoint of splitPoints) {
+        // Search backwards from maxLength to find the last occurrence of this split point
+        const searchText = text.slice(0, maxLength);
+        const lastIndex = searchText.lastIndexOf(splitPoint);
+        // If found and results in a reasonable chunk size
+        if (lastIndex > MIN_CHUNK_SIZE) {
+            // Include the split point in the first chunk (e.g., keep the period with the sentence)
+            return lastIndex + splitPoint.length;
+        }
+    }
+    // No good split point found - fall back to hard split at maxLength
+    // But try to avoid splitting in the middle of a word
+    const hardSplitIndex = text.lastIndexOf(" ", maxLength);
+    if (hardSplitIndex > MIN_CHUNK_SIZE) {
+        return hardSplitIndex + 1; // Include the space in the first chunk
+    }
+    // Last resort: hard split at maxLength
+    return maxLength;
+}
+/**
+ * Split a message into chunks that fit within the specified max length
+ *
+ * @param content - Message content to split
+ * @param options - Split options including maxLength
+ * @returns Split result with chunks array
+ *
+ * @example
+ * ```typescript
+ * const result = splitMessage(longText, { maxLength: 2000 });
+ * for (const chunk of result.chunks) {
+ *   await channel.send(chunk);
+ * }
+ * ```
+ */
+export function splitMessage(content, options) {
+    const { maxLength, preserveBoundaries = true, splitPoints = DEFAULT_SPLIT_POINTS, } = options;
+    const originalLength = content.length;
+    // If content fits in one message, return as-is
+    if (content.length <= maxLength) {
+        return {
+            chunks: [content],
+            wasSplit: false,
+            originalLength,
+        };
+    }
+    const chunks = [];
+    let remaining = content;
+    while (remaining.length > 0) {
+        if (remaining.length <= maxLength) {
+            // Remaining text fits in one message
+            chunks.push(remaining.trim());
+            break;
+        }
+        // Find the best split point
+        let splitIndex;
+        if (preserveBoundaries) {
+            splitIndex = findSplitPoint(remaining, maxLength, splitPoints);
+        }
+        else {
+            // Simple split at maxLength
+            splitIndex = maxLength;
+        }
+        // Extract the chunk and trim
+        const chunk = remaining.slice(0, splitIndex).trim();
+        if (chunk.length > 0) {
+            chunks.push(chunk);
+        }
+        // Update remaining text
+        remaining = remaining.slice(splitIndex).trim();
+    }
+    return {
+        chunks,
+        wasSplit: chunks.length > 1,
+        originalLength,
+    };
+}
+/**
+ * Check if a message needs to be split
+ *
+ * @param content - Message content to check
+ * @param maxLength - Maximum message length
+ * @returns true if the message exceeds the max length
+ *
+ * @example
+ * ```typescript
+ * if (needsSplit(message, 2000)) {
+ *   const { chunks } = splitMessage(message, { maxLength: 2000 });
+ *   // Send each chunk
+ * } else {
+ *   // Send as-is
+ * }
+ * ```
+ */
+export function needsSplit(content, maxLength) {
+    return content.length > maxLength;
+}
+/**
+ * Truncate a message to fit within the max length, adding an ellipsis
+ *
+ * @param content - Message content to truncate
+ * @param maxLength - Maximum length
+ * @param ellipsis - Ellipsis to append (default: '...')
+ * @returns Truncated message
+ *
+ * @example
+ * ```typescript
+ * const short = truncateMessage(longText, 100);
+ * // Returns: "This is a very long text that has been trun..."
+ * ```
+ */
+export function truncateMessage(content, maxLength, ellipsis = "...") {
+    if (content.length <= maxLength) {
+        return content;
+    }
+    const truncatedLength = maxLength - ellipsis.length;
+    return content.slice(0, truncatedLength) + ellipsis;
+}
+/**
+ * Format code as a code block with optional language
+ *
+ * @param code - Code to format
+ * @param language - Optional language for syntax highlighting
+ * @returns Formatted code block
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatCodeBlock('const x = 1;', 'typescript');
+ * // Returns: "```typescript\nconst x = 1;\n```"
+ * ```
+ */
+export function formatCodeBlock(code, language) {
+    const langTag = language ?? "";
+    return `\`\`\`${langTag}\n${code}\n\`\`\``;
+}
+//# sourceMappingURL=message-splitting.js.map

package/dist/message-splitting.js.map

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

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

@@ -0,0 +1,59 @@
+/**
+ * Error classes for chat session management
+ *
+ * Provides typed errors for session persistence and retrieval failures.
+ * These error classes are shared between Discord, Slack, and other chat platforms.
+ */
+/**
+ * Error codes for session manager operations
+ */
+export declare enum SessionErrorCode {
+    STATE_READ_FAILED = "SESSION_STATE_READ_FAILED",
+    STATE_WRITE_FAILED = "SESSION_STATE_WRITE_FAILED",
+    DIRECTORY_CREATE_FAILED = "SESSION_DIRECTORY_CREATE_FAILED",
+    SESSION_NOT_FOUND = "SESSION_NOT_FOUND",
+    SESSION_EXPIRED = "SESSION_EXPIRED",
+    INVALID_STATE = "SESSION_INVALID_STATE"
+}
+/**
+ * Base error class for session manager operations
+ */
+export declare class SessionManagerError extends Error {
+    readonly code: SessionErrorCode;
+    readonly agentName: string;
+    constructor(message: string, code: SessionErrorCode, agentName: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when session state file cannot be read
+ */
+export declare class SessionStateReadError extends SessionManagerError {
+    readonly path: string;
+    constructor(agentName: string, path: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when session state file cannot be written
+ */
+export declare class SessionStateWriteError extends SessionManagerError {
+    readonly path: string;
+    constructor(agentName: string, path: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when session directory cannot be created
+ */
+export declare class SessionDirectoryCreateError extends SessionManagerError {
+    readonly path: string;
+    constructor(agentName: string, path: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Type guard to check if an error is a SessionManagerError
+ */
+export declare function isSessionManagerError(error: unknown): error is SessionManagerError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/session-manager/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,oBAAY,gBAAgB;IAC1B,iBAAiB,8BAA8B;IAC/C,kBAAkB,+BAA+B;IACjD,uBAAuB,oCAAoC;IAC3D,iBAAiB,sBAAsB;IACvC,eAAe,oBAAoB;IACnC,aAAa,0BAA0B;CACxC;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAgB,IAAI,EAAE,gBAAgB,CAAC;IACvC,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAGhC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAO9B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,mBAAmB;IAC5D,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAG3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAW9B;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,mBAAmB;IAC7D,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAG3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAW9B;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,mBAAmB;IAClE,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAG3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAW9B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,mBAAmB,CAE9B"}

package/dist/session-manager/errors.js

@@ -0,0 +1,71 @@
+/**
+ * Error classes for chat session management
+ *
+ * Provides typed errors for session persistence and retrieval failures.
+ * These error classes are shared between Discord, Slack, and other chat platforms.
+ */
+/**
+ * Error codes for session manager operations
+ */
+export var SessionErrorCode;
+(function (SessionErrorCode) {
+    SessionErrorCode["STATE_READ_FAILED"] = "SESSION_STATE_READ_FAILED";
+    SessionErrorCode["STATE_WRITE_FAILED"] = "SESSION_STATE_WRITE_FAILED";
+    SessionErrorCode["DIRECTORY_CREATE_FAILED"] = "SESSION_DIRECTORY_CREATE_FAILED";
+    SessionErrorCode["SESSION_NOT_FOUND"] = "SESSION_NOT_FOUND";
+    SessionErrorCode["SESSION_EXPIRED"] = "SESSION_EXPIRED";
+    SessionErrorCode["INVALID_STATE"] = "SESSION_INVALID_STATE";
+})(SessionErrorCode || (SessionErrorCode = {}));
+/**
+ * Base error class for session manager operations
+ */
+export class SessionManagerError extends Error {
+    code;
+    agentName;
+    constructor(message, code, agentName, options) {
+        super(message, options);
+        this.name = "SessionManagerError";
+        this.code = code;
+        this.agentName = agentName;
+    }
+}
+/**
+ * Error thrown when session state file cannot be read
+ */
+export class SessionStateReadError extends SessionManagerError {
+    path;
+    constructor(agentName, path, options) {
+        super(`Failed to read session state for agent '${agentName}' from '${path}'`, SessionErrorCode.STATE_READ_FAILED, agentName, options);
+        this.name = "SessionStateReadError";
+        this.path = path;
+    }
+}
+/**
+ * Error thrown when session state file cannot be written
+ */
+export class SessionStateWriteError extends SessionManagerError {
+    path;
+    constructor(agentName, path, options) {
+        super(`Failed to write session state for agent '${agentName}' to '${path}'`, SessionErrorCode.STATE_WRITE_FAILED, agentName, options);
+        this.name = "SessionStateWriteError";
+        this.path = path;
+    }
+}
+/**
+ * Error thrown when session directory cannot be created
+ */
+export class SessionDirectoryCreateError extends SessionManagerError {
+    path;
+    constructor(agentName, path, options) {
+        super(`Failed to create session directory for agent '${agentName}' at '${path}'`, SessionErrorCode.DIRECTORY_CREATE_FAILED, agentName, options);
+        this.name = "SessionDirectoryCreateError";
+        this.path = path;
+    }
+}
+/**
+ * Type guard to check if an error is a SessionManagerError
+ */
+export function isSessionManagerError(error) {
+    return error instanceof SessionManagerError;
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/session-manager/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,CAAN,IAAY,gBAOX;AAPD,WAAY,gBAAgB;IAC1B,mEAA+C,CAAA;IAC/C,qEAAiD,CAAA;IACjD,+EAA2D,CAAA;IAC3D,2DAAuC,CAAA;IACvC,uDAAmC,CAAA;IACnC,2DAAuC,CAAA;AACzC,CAAC,EAPW,gBAAgB,KAAhB,gBAAgB,QAO3B;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IACvB,SAAS,CAAS;IAElC,YACE,OAAe,EACf,IAAsB,EACtB,SAAiB,EACjB,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,mBAAmB;IAC5C,IAAI,CAAS;IAE7B,YACE,SAAiB,EACjB,IAAY,EACZ,OAA2B;QAE3B,KAAK,CACH,2CAA2C,SAAS,WAAW,IAAI,GAAG,EACtE,gBAAgB,CAAC,iBAAiB,EAClC,SAAS,EACT,OAAO,CACR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,mBAAmB;IAC7C,IAAI,CAAS;IAE7B,YACE,SAAiB,EACjB,IAAY,EACZ,OAA2B;QAE3B,KAAK,CACH,4CAA4C,SAAS,SAAS,IAAI,GAAG,EACrE,gBAAgB,CAAC,kBAAkB,EACnC,SAAS,EACT,OAAO,CACR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,mBAAmB;IAClD,IAAI,CAAS;IAE7B,YACE,SAAiB,EACjB,IAAY,EACZ,OAA2B;QAE3B,KAAK,CACH,iDAAiD,SAAS,SAAS,IAAI,GAAG,EAC1E,gBAAgB,CAAC,uBAAuB,EACxC,SAAS,EACT,OAAO,CACR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAc;IAEd,OAAO,KAAK,YAAY,mBAAmB,CAAC;AAC9C,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * Session manager module for chat platforms
+ *
+ * Provides per-channel session management for Claude conversations.
+ * This module is shared between Discord, Slack, and other chat platforms.
+ */
+export { ChatSessionManager } from "./session-manager.js";
+export { ChannelSessionSchema, ChatSessionStateSchema, type ChannelSession, type ChatSessionState, type SessionManagerLogger, type ChatSessionManagerOptions, type SessionResult, type IChatSessionManager, createInitialSessionState, createChannelSession, } from "./types.js";
+export { SessionErrorCode, SessionManagerError, SessionStateReadError, SessionStateWriteError, SessionDirectoryCreateError, isSessionManagerError, } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session-manager/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAEL,oBAAoB,EACpB,sBAAsB,EAEtB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EAExB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist/session-manager/index.js

@@ -0,0 +1,14 @@
+/**
+ * Session manager module for chat platforms
+ *
+ * Provides per-channel session management for Claude conversations.
+ * This module is shared between Discord, Slack, and other chat platforms.
+ */
+export { ChatSessionManager } from "./session-manager.js";
+export { 
+// Schemas
+ChannelSessionSchema, ChatSessionStateSchema, 
+// Factory functions
+createInitialSessionState, createChannelSession, } from "./types.js";
+export { SessionErrorCode, SessionManagerError, SessionStateReadError, SessionStateWriteError, SessionDirectoryCreateError, isSessionManagerError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session-manager/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO;AACL,UAAU;AACV,oBAAoB,EACpB,sBAAsB;AAQtB,oBAAoB;AACpB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,123 @@
+/**
+ * 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 { type ChatSessionManagerOptions, type IChatSessionManager, type SessionResult, type ChannelSession } from "./types.js";
+/**
+ * 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 declare class ChatSessionManager implements IChatSessionManager {
+    readonly agentName: string;
+    readonly platform: string;
+    private readonly stateDir;
+    private readonly sessionExpiryHours;
+    private readonly logger;
+    private readonly stateFilePath;
+    private state;
+    constructor(options: ChatSessionManagerOptions);
+    /**
+     * 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.
+     */
+    getOrCreateSession(channelId: string): Promise<SessionResult>;
+    /**
+     * Update the last message timestamp for a session
+     */
+    touchSession(channelId: string): Promise<void>;
+    /**
+     * Get an existing session without creating one
+     *
+     * Returns null if no session exists or if the session is expired.
+     */
+    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.
+     */
+    setSession(channelId: string, sessionId: string): Promise<void>;
+    /**
+     * Clear a specific session
+     */
+    clearSession(channelId: string): Promise<boolean>;
+    /**
+     * Clean up all expired sessions
+     *
+     * Should be called on connector startup and periodically.
+     */
+    cleanupExpiredSessions(): Promise<number>;
+    /**
+     * Get the count of active (non-expired) sessions
+     *
+     * Useful for logging during shutdown to confirm sessions are preserved.
+     */
+    getActiveSessionCount(): Promise<number>;
+    /**
+     * Generate a unique session ID
+     * Format: <platform>-<agentName>-<uuid>
+     */
+    private generateSessionId;
+    /**
+     * Check if a session is expired
+     */
+    private isSessionExpired;
+    /**
+     * Load session state from disk
+     *
+     * Returns cached state if available, otherwise loads from file.
+     * Creates initial state if file doesn't exist.
+     */
+    private loadState;
+    /**
+     * Save session state to disk atomically
+     */
+    private saveState;
+    /**
+     * Ensure the sessions directory exists
+     */
+    private ensureDirectoryExists;
+    /**
+     * Generate a temp file path for atomic writes
+     */
+    private generateTempPath;
+    /**
+     * Rename with retry logic for Windows compatibility
+     */
+    private renameWithRetry;
+}
+//# sourceMappingURL=session-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../src/session-manager/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,EACL,KAAK,yBAAyB,EAE9B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,cAAc,EAIpB,MAAM,YAAY,CAAC;AAsBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAC5D,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAGvC,OAAO,CAAC,KAAK,CAAiC;gBAElC,OAAO,EAAE,yBAAyB;IAoB9C;;;;;OAKG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAkCnE;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBpD;;;;OAIG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAsBnE;;;;OAIG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBrE;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAevD;;;;OAIG;IACG,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC;IA0B/C;;;;OAIG;IACG,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC;IAkB9C;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;;;;OAKG;YACW,SAAS;IAuDvB;;OAEG;YACW,SAAS;IA4BvB;;OAEG;YACW,qBAAqB;IAenC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;OAEG;YACW,eAAe;CA+B9B"}