crewly 1.13.0 → 1.14.0

package/dist/cli/backend/src/services/messaging/thread-status-queue.service.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Thread Status Queue Service
+ *
+ * Tracks the lifecycle of every inbound message thread across platforms
+ * (Slack, GChat, Telegram, etc.). On orchestrator restart, non-terminal
+ * threads are recovered and re-enqueued so no user messages are silently dropped.
+ *
+ * Persistence is debounced and written to ~/.crewly/thread-status-queue.json
+ * using atomic file I/O to prevent corruption.
+ *
+ * @module services/messaging/thread-status-queue
+ */
+import type { ThreadStatus, ThreadStatusEntry, TrackInboundInput, ThreadStatusStats, ReplyStatus } from '../../types/thread-status.types.js';
+/**
+ * Minimal interface for SchedulerService to avoid circular imports.
+ * Used to create follow-up checks when a thread is marked as replied_to_follow_up.
+ */
+export interface ISchedulerServiceLike {
+    scheduleCheck(targetSession: string, minutes: number, message: string, type?: string, options?: {
+        label?: string;
+    }): string;
+    cancelCheck(checkId: string): void;
+}
+/**
+ * Minimal interface for EventBusService to avoid circular imports.
+ * Uses unknown for eventType/filter to avoid importing event-bus types.
+ */
+export interface IEventBusServiceLike {
+    subscribe(input: unknown): {
+        id: string;
+    };
+    unsubscribe(subscriptionId: string): boolean;
+}
+/**
+ * Minimal interface for MessageQueueService to avoid circular imports.
+ * Used during restart recovery to re-enqueue pending threads.
+ */
+export interface IMessageQueueServiceLike {
+    enqueue(input: {
+        content: string;
+        conversationId: string;
+        source: string;
+        sourceMetadata?: Record<string, unknown>;
+        targetSession?: string;
+    }): unknown;
+}
+/**
+ * Minimal interface for checking agent working status.
+ * Used during recovery to determine if delegated agents have completed.
+ */
+export interface IAgentStatusCheckerLike {
+    getAgentWorkingStatus(sessionName: string): Promise<'idle' | 'in_progress' | 'unknown'>;
+}
+/**
+ * Callback for sending platform-specific confirmation messages during recovery.
+ * e.g., "I am back online. I see your message: {preview}. Let me handle it now."
+ *
+ * @param entry - The thread entry to confirm
+ * @returns Promise resolving when the confirmation is sent
+ */
+export type RecoveryConfirmCallback = (entry: ThreadStatusEntry) => Promise<void>;
+/**
+ * Tracks active follow-up subscriptions so they can be cancelled
+ * when the user replies before the scheduled check fires.
+ */
+interface FollowUpTracking {
+    /** ID of the scheduled check */
+    scheduledCheckId: string;
+    /** ID of the event bus subscription */
+    eventSubscriptionId: string;
+}
+/**
+ * Service that maintains a persistent queue of thread statuses.
+ * Constructed with a crewly home directory path for disk persistence.
+ *
+ * Lifecycle: enqueued → delivered → replied_* (terminal or waiting_actions)
+ *
+ * @example
+ * ```typescript
+ * const svc = new ThreadStatusQueueService('/home/user/.crewly');
+ * await svc.loadPersistedState();
+ *
+ * const entry = svc.trackInbound({
+ *   source: 'slack',
+ *   threadKey: 'C123:170743.001',
+ *   conversationId: 'conv-1',
+ *   messagePreview: 'Deploy the new feature',
+ * });
+ *
+ * svc.markDelivered('C123:170743.001');
+ * svc.markReplied('C123:170743.001', 'replied_completed');
+ * ```
+ */
+export declare class ThreadStatusQueueService {
+    /** Singleton instance */
+    private static instance;
+    /** Logger for this service */
+    private logger;
+    /** All tracked thread entries, keyed by threadKey for O(1) lookup */
+    private entries;
+    /** Path to the persistence file, or null if init() has not been called */
+    private persistPath;
+    /** Debounce timer for batching persistence writes */
+    private persistTimer;
+    /** ISO timestamp of last cleanup run */
+    private lastCleanupAt;
+    /** Scheduler service for creating follow-up checks */
+    private schedulerService;
+    /** Event bus for subscribing to message:received events */
+    private eventBusService;
+    /** Tracks active follow-up subscriptions keyed by threadKey */
+    private followUpTracking;
+    /**
+     * Creates a new ThreadStatusQueueService.
+     * Use getInstance() for singleton access, or construct directly for testing.
+     *
+     * @param crewlyHome - Optional crewly home directory path for immediate initialization
+     */
+    constructor(crewlyHome?: string);
+    /**
+     * Returns the singleton instance of ThreadStatusQueueService.
+     * Call init() after this to set the persistence path.
+     *
+     * @returns The singleton instance
+     */
+    static getInstance(): ThreadStatusQueueService;
+    /**
+     * Resets the singleton instance. For testing only.
+     */
+    static resetInstance(): void;
+    /**
+     * Loads persisted state from disk.
+     * If the file doesn't exist or is corrupted, starts with an empty queue.
+     */
+    loadPersistedState(): Promise<void>;
+    /**
+     * Records a new inbound thread message with status `enqueued`.
+     * If a thread with the same threadKey already exists, the existing entry is returned.
+     *
+     * @param input - Inbound message details
+     * @returns The created (or existing) ThreadStatusEntry
+     */
+    trackInbound(input: TrackInboundInput): ThreadStatusEntry;
+    /**
+     * Transitions a thread from `enqueued` (or `error`) to `delivered`.
+     * No-op if thread is already in a terminal or later status.
+     *
+     * @param threadKey - Platform-specific thread identifier
+     * @throws Error if threadKey is not found
+     */
+    markDelivered(threadKey: string): void;
+    /**
+     * Set the SchedulerService instance for creating follow-up checks.
+     * Called during server initialization.
+     *
+     * @param service - The SchedulerService instance (or compatible interface)
+     */
+    setSchedulerService(service: ISchedulerServiceLike): void;
+    /**
+     * Set the EventBusService instance for subscribing to message events.
+     * Called during server initialization.
+     *
+     * @param service - The EventBusService instance (or compatible interface)
+     */
+    setEventBusService(service: IEventBusServiceLike): void;
+    /**
+     * Transitions a thread to one of the replied_* statuses.
+     * Sets the repliedAt timestamp.
+     *
+     * When status is `replied_to_follow_up`, automatically:
+     * 1. Creates a scheduled check (default 5 min) to verify user replied
+     * 2. Subscribes to message:received events for this thread's conversation
+     * 3. On user reply: cancels the scheduled check and transitions to replied_completed
+     *
+     * @param threadKey - Platform-specific thread identifier
+     * @param status - One of: replied_completed, replied_waiting_actions, replied_to_follow_up
+     * @throws Error if threadKey is not found or status is not a valid reply status
+     */
+    markReplied(threadKey: string, status: ReplyStatus): void;
+    /**
+     * Handles a user reply to a follow-up thread.
+     * Cancels the scheduled check, removes the event subscription,
+     * and transitions the thread to replied_completed (or re-enqueues).
+     *
+     * @param threadKey - Platform-specific thread identifier
+     */
+    handleFollowUpReply(threadKey: string): void;
+    /**
+     * Returns the active follow-up tracking for a thread, if any.
+     * Useful for testing and debugging.
+     *
+     * @param threadKey - Platform-specific thread identifier
+     * @returns The follow-up tracking info, or null
+     */
+    getFollowUpTracking(threadKey: string): FollowUpTracking | null;
+    /**
+     * Records that an agent was delegated work from this thread.
+     *
+     * @param threadKey - Platform-specific thread identifier
+     * @param agentSession - Session name of the delegated agent
+     * @throws Error if threadKey is not found
+     */
+    addDelegatedAgent(threadKey: string, agentSession: string): void;
+    /**
+     * Transitions a `replied_waiting_actions` thread to `replied_completed`
+     * when all delegated agents have finished their work.
+     *
+     * @param threadKey - Platform-specific thread identifier
+     * @throws Error if threadKey is not found
+     */
+    markDelegationsComplete(threadKey: string): void;
+    /**
+     * Returns all entries not in a terminal status. Used for restart recovery.
+     *
+     * @returns Array of non-terminal ThreadStatusEntry objects
+     */
+    getPendingThreads(): ThreadStatusEntry[];
+    /**
+     * Returns all entries matching the given status.
+     *
+     * @param status - The ThreadStatus to filter by
+     * @returns Array of matching ThreadStatusEntry objects
+     */
+    getByStatus(status: ThreadStatus): ThreadStatusEntry[];
+    /**
+     * Retrieves a specific entry by threadKey.
+     *
+     * @param threadKey - Platform-specific thread identifier
+     * @returns The entry, or null if not found
+     */
+    get(threadKey: string): ThreadStatusEntry | null;
+    /**
+     * Find a thread entry by its conversationId.
+     *
+     * Useful when the caller has a conversationId (e.g. from chat history)
+     * but not the threadKey. Scans all entries — O(n) but the set is small.
+     *
+     * @param conversationId - The conversation ID to search for
+     * @returns The most recently updated matching entry, or null
+     */
+    getByConversationId(conversationId: string): ThreadStatusEntry | null;
+    /**
+     * Finds a thread status entry by its queueMessageId.
+     * Returns the most recently updated entry if multiple match.
+     *
+     * @param queueMessageId - The queue message ID to search for
+     * @returns The most recently updated matching entry, or null
+     */
+    getByQueueMessageId(queueMessageId: string): ThreadStatusEntry | null;
+    /**
+     * Expires entries that have been in a non-terminal status longer than maxAgeMinutes.
+     * Transitions them to `expired`.
+     *
+     * @param maxAgeMinutes - Maximum age in minutes (defaults to STALE_TIMEOUT_MINUTES)
+     * @returns Number of entries expired
+     */
+    expireStale(maxAgeMinutes?: number): number;
+    /**
+     * Removes terminal entries older than retentionHours.
+     * Also enforces MAX_ENTRIES by pruning oldest terminal entries first.
+     *
+     * @param retentionHours - Hours to retain terminal entries (defaults to CLEANUP_RETENTION_HOURS)
+     * @returns Number of entries removed
+     */
+    cleanup(retentionHours?: number): number;
+    /**
+     * Returns statistics for monitoring the thread status queue.
+     *
+     * @returns Stats snapshot including total, per-status counts, and oldest pending timestamp
+     */
+    getStats(): ThreadStatusStats;
+    /**
+     * Initializes the service with a crewly home directory for persistence.
+     * Must be called before loadPersistedState() when using getInstance().
+     *
+     * @param crewlyHome - Absolute path to the crewly home directory (e.g. ~/.crewly)
+     */
+    init(crewlyHome: string): void;
+    /**
+     * Public convenience method: optionally re-inits the persist path,
+     * then loads persisted state from disk.
+     *
+     * @param crewlyHome - Optional crewly home directory to re-initialize with
+     */
+    load(crewlyHome?: string): Promise<void>;
+    /**
+     * Immediately flushes the current state to disk. Call during graceful shutdown
+     * to ensure no in-memory mutations are lost.
+     */
+    persist(): Promise<void>;
+    /**
+     * Returns all entries in the queue. Used for the thread-status API.
+     *
+     * @returns Array of all ThreadStatusEntry objects
+     */
+    getAllEntries(): ThreadStatusEntry[];
+    /**
+     * Recovers pending threads after an orchestrator restart.
+     * Loads persisted state and handles each thread based on its status:
+     *
+     * 1. **enqueued/delivered/error** — Send a "I'm back online" confirmation
+     *    via the platform, then re-enqueue for orchestrator processing.
+     * 2. **replied_to_follow_up** — Re-setup follow-up tracking (scheduled
+     *    check + event subscription) to continue waiting for user reply.
+     * 3. **replied_waiting_actions** — Check delegated agent statuses. If all
+     *    agents are done, transition to replied_completed. Otherwise keep waiting.
+     * 4. **replied_completed/expired** — Already terminal, skip.
+     *
+     * @param messageQueueService - The message queue service for re-enqueuing
+     * @param options - Optional callbacks for agent status checking and platform confirmations
+     * @returns Summary of recovery actions taken
+     */
+    recoverPendingThreads(messageQueueService: IMessageQueueServiceLike, options?: {
+        agentStatusChecker?: IAgentStatusCheckerLike;
+        confirmCallback?: RecoveryConfirmCallback;
+    }): Promise<{
+        loaded: number;
+        reEnqueued: number;
+        followUpRestored: number;
+        waitingActionsChecked: number;
+        delegationsCompleted: number;
+        expired: number;
+        cleaned: number;
+    }>;
+    /**
+     * Cleans up timers and follow-up tracking. Call on shutdown.
+     */
+    destroy(): void;
+    /**
+     * Retrieves an entry by threadKey or throws an error with a descriptive message.
+     *
+     * @param threadKey - Platform-specific thread identifier
+     * @param caller - Name of the calling method (for error messages)
+     * @returns The found entry
+     * @throws Error if entry is not found
+     */
+    private getOrThrow;
+    /**
+     * Sets up follow-up tracking for a replied_to_follow_up thread.
+     * Creates a scheduled check and an event subscription so that if
+     * the user replies, the check is cancelled and the thread is completed.
+     *
+     * @param threadKey - Platform-specific thread identifier
+     * @param entry - The thread status entry
+     */
+    private setupFollowUpTracking;
+    /**
+     * Schedules a debounced persistence write to disk.
+     * Multiple mutations within PERSIST_DEBOUNCE_MS are batched into a single write.
+     */
+    private schedulePersist;
+    /**
+     * Writes the current queue state to disk atomically.
+     */
+    private persistToDisk;
+}
+export {};
+//# sourceMappingURL=thread-status-queue.service.d.ts.map

package/dist/cli/backend/src/services/messaging/thread-status-queue.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-status-queue.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/messaging/thread-status-queue.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EAEjB,WAAW,EACZ,MAAM,oCAAoC,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,aAAa,CACX,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3B,MAAM,CAAC;IACV,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,KAAK,EAAE;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACzC,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC,CAAC;CACzF;AAED;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAKlF;;;GAGG;AACH,UAAU,gBAAgB;IACxB,gCAAgC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,wBAAwB;IACnC,yBAAyB;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2B;IAElD,8BAA8B;IAC9B,OAAO,CAAC,MAAM,CAAkG;IAEhH,qEAAqE;IACrE,OAAO,CAAC,OAAO,CAA6C;IAE5D,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAAuB;IAE1C,qDAAqD;IACrD,OAAO,CAAC,YAAY,CAA8C;IAElE,wCAAwC;IACxC,OAAO,CAAC,aAAa,CAAoC;IAEzD,sDAAsD;IACtD,OAAO,CAAC,gBAAgB,CAAsC;IAE9D,2DAA2D;IAC3D,OAAO,CAAC,eAAe,CAAqC;IAE5D,+DAA+D;IAC/D,OAAO,CAAC,gBAAgB,CAA4C;IAEpE;;;;;OAKG;gBACS,UAAU,CAAC,EAAE,MAAM;IAS/B;;;;;OAKG;IACH,MAAM,CAAC,WAAW,IAAI,wBAAwB;IAO9C;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAO5B;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCzC;;;;;;OAMG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,iBAAiB;IAkCzD;;;;;;OAMG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAetC;;;;;OAKG;IACH,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAIzD;;;;;OAKG;IACH,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAIvD;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAwBzD;;;;;;OAMG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IA8B5C;;;;;;OAMG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAI/D;;;;;;OAMG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAgBhE;;;;;;OAMG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAahD;;;;OAIG;IACH,iBAAiB,IAAI,iBAAiB,EAAE;IAUxC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,iBAAiB,EAAE;IAUtD;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAIhD;;;;;;;;OAQG;IACH,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAYrE;;;;;;OAMG;IACH,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAYrE;;;;;;OAMG;IACH,WAAW,CAAC,aAAa,GAAE,MAAsD,GAAG,MAAM;IAuB1F;;;;;;OAMG;IACH,OAAO,CAAC,cAAc,GAAE,MAAwD,GAAG,MAAM;IAqCzF;;;;OAIG;IACH,QAAQ,IAAI,iBAAiB;IA8B7B;;;;;OAKG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;OAKG;IACG,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9C;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B;;;;OAIG;IACH,aAAa,IAAI,iBAAiB,EAAE;IAIpC;;;;;;;;;;;;;;;OAeG;IACG,qBAAqB,CACzB,mBAAmB,EAAE,wBAAwB,EAC7C,OAAO,CAAC,EAAE;QACR,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;QAC7C,eAAe,CAAC,EAAE,uBAAuB,CAAC;KAC3C,GACA,OAAO,CAAC;QACT,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;QACzB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IA2GF;;OAEG;IACH,OAAO,IAAI,IAAI;IAsBf;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAgD7B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;YACW,aAAa;CAe5B"}