@herdctl/slack 0.0.1 → 0.2.0

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

@@ -0,0 +1,154 @@
+/**
+ * Type definitions for Slack session management
+ *
+ * Provides interfaces for per-channel session state tracking,
+ * enabling conversation context preservation across Slack channels.
+ */
+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 Slack session state file
+ *
+ * Stored at .herdctl/slack-sessions/<agent-name>.yaml
+ */
+export declare const SlackSessionStateSchema: z.ZodObject<{
+    /** Version for future schema migrations */
+    version: z.ZodLiteral<2>;
+    /** 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, {
+    agentName: string;
+    version: 2;
+    channels: Record<string, {
+        sessionId: string;
+        lastMessageAt: string;
+    }>;
+}, {
+    agentName: string;
+    version: 2;
+    channels: Record<string, {
+        sessionId: string;
+        lastMessageAt: string;
+    }>;
+}>;
+export type ChannelSession = z.infer<typeof ChannelSessionSchema>;
+export type SlackSessionState = z.infer<typeof SlackSessionStateSchema>;
+/**
+ * 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 SessionManager
+ */
+export interface SessionManagerOptions {
+    /** Name of the agent this session manager is for */
+    agentName: string;
+    /** Root path for state storage (e.g., .herdctl) */
+    stateDir: string;
+    /** Session expiry timeout in hours (default: 24) */
+    sessionExpiryHours?: number;
+    /** Logger for session manager operations */
+    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 Slack session managers must implement
+ *
+ * Keyed by channelId (matching Discord's approach)
+ */
+export interface ISessionManager {
+    /**
+     * Get or create a session for a channel
+     *
+     * @param channelId - Slack channel ID (conversation key)
+     */
+    getOrCreateSession(channelId: string): Promise<SessionResult>;
+    /**
+     * Update the last message timestamp for a session
+     *
+     * @param channelId - Slack channel ID
+     */
+    touchSession(channelId: string): Promise<void>;
+    /**
+     * Get an existing session without creating one
+     *
+     * @param channelId - Slack channel ID
+     * @returns 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
+     *
+     * @param channelId - Slack channel ID
+     * @param sessionId - The Claude Agent SDK session ID
+     */
+    setSession(channelId: string, sessionId: string): Promise<void>;
+    /**
+     * Clear a specific session
+     *
+     * @param channelId - Slack channel ID
+     * @returns true if cleared, false if it didn't exist
+     */
+    clearSession(channelId: string): Promise<boolean>;
+    /**
+     * Clean up all expired sessions
+     *
+     * @returns Number of sessions cleaned up
+     */
+    cleanupExpiredSessions(): Promise<number>;
+    /**
+     * Get the count of active (non-expired) sessions
+     */
+    getActiveSessionCount(): Promise<number>;
+    /** Name of the agent this session manager is for */
+    readonly agentName: string;
+}
+/**
+ * Create initial session state for a new agent
+ */
+export declare function createInitialSessionState(agentName: string): SlackSessionState;
+/**
+ * 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":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,oBAAoB;IAC/B,mDAAmD;;IAGnD,wDAAwD;;;;;;;;EAIxD,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;IAClC,2CAA2C;;IAG3C,+CAA+C;;IAG/C,wCAAwC;;QArBxC,mDAAmD;;QAGnD,wDAAwD;;;;;;;;;;;;;;;;;;;;;;;EAoBxD,CAAC;AAMH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAElB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IAEjB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAElB,8CAA8C;IAC9C,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE9D;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAE9D;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAElD;;;;OAIG;IACH,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1C;;OAEG;IACH,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAMD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,GAChB,iBAAiB,CAMnB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAKtE"}

package/dist/session-manager/types.js

@@ -0,0 +1,57 @@
+/**
+ * Type definitions for Slack session management
+ *
+ * Provides interfaces for per-channel session state tracking,
+ * enabling conversation context preservation across Slack channels.
+ */
+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 Slack session state file
+ *
+ * Stored at .herdctl/slack-sessions/<agent-name>.yaml
+ */
+export const SlackSessionStateSchema = z.object({
+    /** Version for future schema migrations */
+    version: z.literal(2),
+    /** 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: 2,
+        agentName,
+        channels: {},
+    };
+}
+/**
+ * Create a new channel session
+ */
+export function createChannelSession(sessionId) {
+    return {
+        sessionId,
+        lastMessageAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/session-manager/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,mDAAmD;IACnD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,4BAA4B,CAAC;IAE1D,wDAAwD;IACxD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC;QACjC,OAAO,EAAE,mDAAmD;KAC7D,CAAC;CACH,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,2CAA2C;IAC3C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAErB,+CAA+C;IAC/C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,4BAA4B,CAAC;IAE1D,wCAAwC;IACxC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,oBAAoB,CAAC;CACrD,CAAC,CAAC;AAmHH,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAAiB;IAEjB,OAAO;QACL,OAAO,EAAE,CAAC;QACV,SAAS;QACT,QAAQ,EAAE,EAAE;KACb,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO;QACL,SAAS;QACT,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACxC,CAAC;AACJ,CAAC"}

package/dist/slack-connector.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Slack Connector
+ *
+ * Single Bolt App instance with channel->agent routing.
+ * Uses Socket Mode for connection (no public URL needed).
+ *
+ * Key design:
+ * - ONE connector shared across all agents (not N connectors)
+ * - Channel->agent routing via channelAgentMap
+ * - Channel-based conversations (channelId as session key, matching Discord)
+ * - Hourglass emoji reaction as typing indicator
+ */
+import { EventEmitter } from "node:events";
+import type { SlackConnectorOptions, SlackConnectorState, SlackFileUploadParams, ISlackConnector, SlackConnectorEventMap, SlackConnectorEventName } from "./types.js";
+export declare class SlackConnector extends EventEmitter implements ISlackConnector {
+    private readonly botToken;
+    private readonly appToken;
+    private readonly channelAgentMap;
+    private readonly channelConfigs;
+    private readonly sessionManagers;
+    private readonly logger;
+    private app;
+    private commandHandler;
+    private status;
+    private connectedAt;
+    private disconnectedAt;
+    private reconnectAttempts;
+    private lastError;
+    private botUserId;
+    private botUsername;
+    private messagesReceived;
+    private messagesSent;
+    private messagesIgnored;
+    constructor(options: SlackConnectorOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getState(): SlackConnectorState;
+    uploadFile(params: SlackFileUploadParams): Promise<{
+        fileId: string;
+    }>;
+    private registerEventHandlers;
+    /**
+     * Try to execute a prefix command. Returns true if a command was handled.
+     */
+    private tryExecuteCommand;
+    private buildMessageEvent;
+    emit<K extends SlackConnectorEventName>(event: K, payload: SlackConnectorEventMap[K]): boolean;
+    on<K extends SlackConnectorEventName>(event: K, listener: (payload: SlackConnectorEventMap[K]) => void): this;
+    once<K extends SlackConnectorEventName>(event: K, listener: (payload: SlackConnectorEventMap[K]) => void): this;
+    off<K extends SlackConnectorEventName>(event: K, listener: (payload: SlackConnectorEventMap[K]) => void): this;
+}
+//# sourceMappingURL=slack-connector.d.ts.map

package/dist/slack-connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack-connector.d.ts","sourceRoot":"","sources":["../src/slack-connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EACV,qBAAqB,EACrB,mBAAmB,EAKnB,qBAAqB,EACrB,eAAe,EAEf,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAoBpB,qBAAa,cAAe,SAAQ,YAAa,YAAW,eAAe;IACzE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;IACjE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAI9C,OAAO,CAAC,GAAG,CAAa;IAGxB,OAAO,CAAC,cAAc,CAA+B;IAGrD,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,WAAW,CAAuB;IAG1C,OAAO,CAAC,gBAAgB,CAAa;IACrC,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,eAAe,CAAa;gBAExB,OAAO,EAAE,qBAAqB;IAepC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmFxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsCjC,WAAW,IAAI,OAAO;IAItB,QAAQ,IAAI,mBAAmB;IAyBzB,UAAU,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA4B5E,OAAO,CAAC,qBAAqB;IA4K7B;;OAEG;YACW,iBAAiB;IAkD/B,OAAO,CAAC,iBAAiB;IAiEhB,IAAI,CAAC,CAAC,SAAS,uBAAuB,EAC7C,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACjC,OAAO;IAID,EAAE,CAAC,CAAC,SAAS,uBAAuB,EAC3C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,GACrD,IAAI;IAIE,IAAI,CAAC,CAAC,SAAS,uBAAuB,EAC7C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,GACrD,IAAI;IAIE,GAAG,CAAC,CAAC,SAAS,uBAAuB,EAC5C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,GACrD,IAAI;CAGR"}