crewly 1.12.1 → 1.13.1

package/dist/cli/backend/src/services/messaging/sub-agent-message-queue.service.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Sub-Agent Message Queue Service
+ *
+ * Buffers messages destined for sub-agents that have not yet completed
+ * initialization (agentStatus !== 'active'). Messages are flushed once
+ * the agent registers via the MCP `register_agent_status` tool.
+ *
+ * The orchestrator is excluded from this queue because it already has
+ * its own deferral mechanism via QueueProcessorService.
+ *
+ * @module sub-agent-message-queue
+ */
+/**
+ * A single queued message destined for a sub-agent.
+ */
+export interface QueuedAgentMessage {
+    /** The raw data string to write to the agent's terminal */
+    data: string;
+    /** Timestamp (ms since epoch) when the message was enqueued */
+    queuedAt: number;
+    /** The target session name */
+    sessionName: string;
+}
+/**
+ * Singleton service that holds pending messages per agent session.
+ *
+ * Messages are enqueued when a `mode: 'message'` write arrives at
+ * the terminal controller for an agent that is not yet active.
+ * They are dequeued and delivered sequentially when the agent
+ * registers (status becomes 'active').
+ */
+export declare class SubAgentMessageQueue {
+    private static instance;
+    private pendingMessages;
+    private logger;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns The SubAgentMessageQueue singleton
+     */
+    static getInstance(): SubAgentMessageQueue;
+    /**
+     * Reset the singleton instance (for testing only).
+     */
+    static resetInstance(): void;
+    /**
+     * Enqueue a message for a session that is not yet active.
+     * If the queue exceeds MAX_QUEUE_SIZE, the oldest message is dropped.
+     *
+     * @param sessionName - The target agent session name
+     * @param data - The raw data string to deliver later
+     */
+    enqueue(sessionName: string, data: string): void;
+    /**
+     * Dequeue all pending messages for a session (FIFO order).
+     * The queue is cleared after dequeuing.
+     *
+     * @param sessionName - The agent session name
+     * @returns Array of queued messages in insertion order, or empty array
+     */
+    dequeueAll(sessionName: string): QueuedAgentMessage[];
+    /**
+     * Check if there are pending messages for a session.
+     *
+     * @param sessionName - The agent session name
+     * @returns True if there are pending messages
+     */
+    hasPending(sessionName: string): boolean;
+    /**
+     * Clear all pending messages for a session (e.g. on agent stop/exit).
+     *
+     * @param sessionName - The agent session name
+     */
+    clear(sessionName: string): void;
+    /**
+     * Get the number of pending messages for a session.
+     *
+     * @param sessionName - The agent session name
+     * @returns Number of pending messages
+     */
+    getQueueSize(sessionName: string): number;
+}
+//# sourceMappingURL=sub-agent-message-queue.service.d.ts.map

package/dist/cli/backend/src/services/messaging/sub-agent-message-queue.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-agent-message-queue.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/messaging/sub-agent-message-queue.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAoB;IAChC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAqC;IAC5D,OAAO,CAAC,eAAe,CAA2C;IAClE,OAAO,CAAC,MAAM,CAAkB;IAEhC,OAAO;IAIP;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,oBAAoB;IAO1C;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IA8BhD;;;;;;OAMG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAiBrD;;;;;OAKG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAKxC;;;;OAIG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAWhC;;;;;OAKG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;CAIzC"}

package/dist/cli/backend/src/services/messaging/sub-agent-message-queue.service.js

@@ -0,0 +1,136 @@
+/**
+ * Sub-Agent Message Queue Service
+ *
+ * Buffers messages destined for sub-agents that have not yet completed
+ * initialization (agentStatus !== 'active'). Messages are flushed once
+ * the agent registers via the MCP `register_agent_status` tool.
+ *
+ * The orchestrator is excluded from this queue because it already has
+ * its own deferral mechanism via QueueProcessorService.
+ *
+ * @module sub-agent-message-queue
+ */
+import { LoggerService } from '../core/logger.service.js';
+import { SUB_AGENT_QUEUE_CONSTANTS } from '../../constants.js';
+/**
+ * Singleton service that holds pending messages per agent session.
+ *
+ * Messages are enqueued when a `mode: 'message'` write arrives at
+ * the terminal controller for an agent that is not yet active.
+ * They are dequeued and delivered sequentially when the agent
+ * registers (status becomes 'active').
+ */
+export class SubAgentMessageQueue {
+    static instance = null;
+    pendingMessages = new Map();
+    logger;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('SubAgentMessageQueue');
+    }
+    /**
+     * Get the singleton instance.
+     *
+     * @returns The SubAgentMessageQueue singleton
+     */
+    static getInstance() {
+        if (!SubAgentMessageQueue.instance) {
+            SubAgentMessageQueue.instance = new SubAgentMessageQueue();
+        }
+        return SubAgentMessageQueue.instance;
+    }
+    /**
+     * Reset the singleton instance (for testing only).
+     */
+    static resetInstance() {
+        SubAgentMessageQueue.instance = null;
+    }
+    /**
+     * Enqueue a message for a session that is not yet active.
+     * If the queue exceeds MAX_QUEUE_SIZE, the oldest message is dropped.
+     *
+     * @param sessionName - The target agent session name
+     * @param data - The raw data string to deliver later
+     */
+    enqueue(sessionName, data) {
+        let queue = this.pendingMessages.get(sessionName);
+        if (!queue) {
+            queue = [];
+            this.pendingMessages.set(sessionName, queue);
+        }
+        // Drop oldest if at capacity
+        if (queue.length >= SUB_AGENT_QUEUE_CONSTANTS.MAX_QUEUE_SIZE) {
+            const dropped = queue.shift();
+            this.logger.warn('Queue at capacity, dropping oldest message', {
+                sessionName,
+                droppedAt: dropped?.queuedAt,
+                queueSize: queue.length,
+            });
+        }
+        queue.push({
+            data,
+            queuedAt: Date.now(),
+            sessionName,
+        });
+        this.logger.info('Message queued for sub-agent', {
+            sessionName,
+            queueSize: queue.length,
+            dataLength: data.length,
+        });
+    }
+    /**
+     * Dequeue all pending messages for a session (FIFO order).
+     * The queue is cleared after dequeuing.
+     *
+     * @param sessionName - The agent session name
+     * @returns Array of queued messages in insertion order, or empty array
+     */
+    dequeueAll(sessionName) {
+        const queue = this.pendingMessages.get(sessionName);
+        if (!queue || queue.length === 0) {
+            return [];
+        }
+        const messages = [...queue];
+        this.pendingMessages.delete(sessionName);
+        this.logger.info('Dequeued all messages for sub-agent', {
+            sessionName,
+            count: messages.length,
+        });
+        return messages;
+    }
+    /**
+     * Check if there are pending messages for a session.
+     *
+     * @param sessionName - The agent session name
+     * @returns True if there are pending messages
+     */
+    hasPending(sessionName) {
+        const queue = this.pendingMessages.get(sessionName);
+        return !!queue && queue.length > 0;
+    }
+    /**
+     * Clear all pending messages for a session (e.g. on agent stop/exit).
+     *
+     * @param sessionName - The agent session name
+     */
+    clear(sessionName) {
+        const queue = this.pendingMessages.get(sessionName);
+        if (queue && queue.length > 0) {
+            this.logger.info('Clearing queued messages for session', {
+                sessionName,
+                droppedCount: queue.length,
+            });
+        }
+        this.pendingMessages.delete(sessionName);
+    }
+    /**
+     * Get the number of pending messages for a session.
+     *
+     * @param sessionName - The agent session name
+     * @returns Number of pending messages
+     */
+    getQueueSize(sessionName) {
+        const queue = this.pendingMessages.get(sessionName);
+        return queue ? queue.length : 0;
+    }
+}
+//# sourceMappingURL=sub-agent-message-queue.service.js.map

package/dist/cli/backend/src/services/messaging/sub-agent-message-queue.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-agent-message-queue.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/messaging/sub-agent-message-queue.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAmB,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAc/D;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAoB;IACxB,MAAM,CAAC,QAAQ,GAAgC,IAAI,CAAC;IACpD,eAAe,GAAG,IAAI,GAAG,EAAgC,CAAC;IAC1D,MAAM,CAAkB;IAEhC;QACC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,qBAAqB,CAAC,sBAAsB,CAAC,CAAC;IACzF,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,WAAW;QACjB,IAAI,CAAC,oBAAoB,CAAC,QAAQ,EAAE,CAAC;YACpC,oBAAoB,CAAC,QAAQ,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC5D,CAAC;QACD,OAAO,oBAAoB,CAAC,QAAQ,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,aAAa;QACnB,oBAAoB,CAAC,QAAQ,GAAG,IAAI,CAAC;IACtC,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,WAAmB,EAAE,IAAY;QACxC,IAAI,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,KAAK,GAAG,EAAE,CAAC;YACX,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QAED,6BAA6B;QAC7B,IAAI,KAAK,CAAC,MAAM,IAAI,yBAAyB,CAAC,cAAc,EAAE,CAAC;YAC9D,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,4CAA4C,EAAE;gBAC9D,WAAW;gBACX,SAAS,EAAE,OAAO,EAAE,QAAQ;gBAC5B,SAAS,EAAE,KAAK,CAAC,MAAM;aACvB,CAAC,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,IAAI,CAAC;YACV,IAAI;YACJ,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE;YACpB,WAAW;SACX,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE;YAChD,WAAW;YACX,SAAS,EAAE,KAAK,CAAC,MAAM;YACvB,UAAU,EAAE,IAAI,CAAC,MAAM;SACvB,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,WAAmB;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,EAAE,CAAC;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAEzC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,qCAAqC,EAAE;YACvD,WAAW;YACX,KAAK,EAAE,QAAQ,CAAC,MAAM;SACtB,CAAC,CAAC;QAEH,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,WAAmB;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACpD,OAAO,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAmB;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACpD,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sCAAsC,EAAE;gBACxD,WAAW;gBACX,YAAY,EAAE,KAAK,CAAC,MAAM;aAC1B,CAAC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,WAAmB;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACpD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACjC,CAAC"}

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":"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"}