@codebolt/codeboltjs 5.0.6 → 5.0.7

package/dist/core/Codebolt.d.ts

@@ -97,19 +97,19 @@ declare class Codebolt {
     };
     mail: {
         registerAgent: (params: import("@codebolt/types/sdk").IRegisterAgentParams) => Promise<import("@codebolt/types/sdk").IRegisterAgentResponse>;
-        listAgents: () => Promise<import("../modules/mail").IListAgentsResponse>;
-        getAgent: (params: import("../modules/mail").IGetAgentParams) => Promise<import("../modules/mail").IGetAgentResponse>;
-        createThread: (params: import("../modules/mail").ICreateThreadParams) => Promise<import("../modules/mail").ICreateThreadResponse>;
-        findOrCreateThread: (params: import("../modules/mail").IFindOrCreateThreadParams) => Promise<import("../modules/mail").IFindOrCreateThreadResponse>;
-        listThreads: (params?: import("../modules/mail").IListThreadsParams) => Promise<import("../modules/mail").IListThreadsResponse>;
-        getThread: (params: import("../modules/mail").IGetThreadParams) => Promise<import("../modules/mail").IGetThreadResponse>;
-        updateThreadStatus: (params: import("../modules/mail").IUpdateThreadStatusParams) => Promise<import("../modules/mail").IUpdateThreadStatusResponse>;
-        archiveThread: (params: import("../modules/mail").IArchiveThreadParams) => Promise<import("../modules/mail").IArchiveThreadResponse>;
+        listAgents: () => Promise<import("@codebolt/types/sdk").IListAgentsResponse>;
+        getAgent: (params: import("@codebolt/types/sdk").IGetAgentParams) => Promise<import("@codebolt/types/sdk").IGetAgentResponse>;
+        createThread: (params: import("@codebolt/types/sdk").ICreateThreadParams) => Promise<import("@codebolt/types/sdk").ICreateThreadResponse>;
+        findOrCreateThread: (params: import("@codebolt/types/sdk").IFindOrCreateThreadParams) => Promise<import("@codebolt/types/sdk").IFindOrCreateThreadResponse>;
+        listThreads: (params?: import("@codebolt/types/sdk").IListThreadsParams) => Promise<import("@codebolt/types/sdk").IListThreadsResponse>;
+        getThread: (params: import("@codebolt/types/sdk").IGetThreadParams) => Promise<import("@codebolt/types/sdk").IGetThreadResponse>;
+        updateThreadStatus: (params: import("@codebolt/types/sdk").IUpdateThreadStatusParams) => Promise<import("@codebolt/types/sdk").IUpdateThreadStatusResponse>;
+        archiveThread: (params: import("@codebolt/types/sdk").IArchiveThreadParams) => Promise<import("@codebolt/types/sdk").IArchiveThreadResponse>;
         fetchInbox: (params: import("@codebolt/types/sdk").IFetchInboxParams) => Promise<import("@codebolt/types/sdk").IFetchInboxResponse>;
         sendMessage: (params: import("@codebolt/types/sdk").ISendMessageParams) => Promise<import("@codebolt/types/sdk").ISendMessageResponse>;
         replyMessage: (params: import("@codebolt/types/sdk").IReplyMessageParams) => Promise<import("@codebolt/types/sdk").IReplyMessageResponse>;
-        getMessage: (params: import("../modules/mail").IGetMessageParams) => Promise<import("../modules/mail").IGetMessageResponse>;
-        getMessages: (params: import("../modules/mail").IGetMessagesParams) => Promise<import("../modules/mail").IGetMessagesResponse>;
+        getMessage: (params: import("@codebolt/types/sdk").IGetMessageParams) => Promise<import("@codebolt/types/sdk").IGetMessageResponse>;
+        getMessages: (params: import("@codebolt/types/sdk").IGetMessagesParams) => Promise<import("@codebolt/types/sdk").IGetMessagesResponse>;
         markRead: (params: import("@codebolt/types/sdk").IMarkReadParams) => Promise<import("@codebolt/types/sdk").IMarkReadResponse>;
         acknowledge: (params: import("@codebolt/types/sdk").IAcknowledgeParams) => Promise<import("@codebolt/types/sdk").IAcknowledgeResponse>;
         search: (params: import("@codebolt/types/sdk").ISearchParams) => Promise<import("@codebolt/types/sdk").ISearchResponse>;
@@ -165,27 +165,21 @@ declare class Codebolt {
             instanceId: string;
         }>;
         closeBrowserInstance: (instanceId: string) => Promise<boolean>;
-        executeOnInstance: (instanceId: string, operation: string, params: any) => Promise<any>;
+        executeOnInstance: (instanceId: string, operation: import("@codebolt/types/sdk").BrowserOperationType, params: import("@codebolt/types/sdk").BrowserOperationParams) => Promise<import("@codebolt/types/sdk").BrowserOperationResponse>;
     };
     chat: {
         getChatHistory: (threadId: string) => Promise<import("@codebolt/types/sdk").ChatMessage>;
-        setRequestHandler: (handler: (request: any, response: (data: any) => void) => Promise<void> | void) => void;
-        sendMessage: (message: string, payload?: any) => void;
+        setRequestHandler: (handler: (request: import("@codebolt/types/sdk").ChatRequest, response: (data: import("@codebolt/types/sdk").ChatResponseData) => void) => Promise<void> | void) => void;
+        sendMessage: (message: string, payload?: object) => void;
         waitforReply: (message: string) => Promise<import("@codebolt/types/sdk").UserMessage>;
-        processStarted: (onStopClicked?: (message: any) => void) => {
-            stopProcess: () => void;
-            cleanup: () => void;
-        } | {
-            stopProcess: () => void;
-            cleanup?: undefined;
-        };
+        processStarted: (onStopClicked?: (message: import("@codebolt/types/sdk").StopProcessMessage) => void) => import("@codebolt/types/sdk").ProcessControl | import("@codebolt/types/sdk").ProcessControlWithCleanup;
         stopProcess: () => void;
         processFinished: () => void;
         sendConfirmationRequest: (confirmationMessage: string, buttons?: string[], withFeedback?: boolean) => Promise<string>;
         askQuestion: (question: string, buttons?: string[], withFeedback?: boolean) => Promise<string>;
         sendNotificationEvent: (notificationMessage: string, type: "debug" | "git" | "planner" | "browser" | "editor" | "terminal" | "preview") => void;
-        checkForSteeringMessage: () => any;
-        onSteeringMessageReceived: () => Promise<any>;
+        checkForSteeringMessage: () => import("@codebolt/types/sdk").SteeringMessage | null;
+        onSteeringMessageReceived: () => Promise<import("@codebolt/types/sdk").SteeringMessage | null>;
     };
     terminal: {
         eventEmitter: {
@@ -207,7 +201,7 @@ declare class Codebolt {
             prependOnceListener<K>(eventName: string | symbol, listener: (...args: any[]) => void): /*elided*/ any;
             eventNames(): (string | symbol)[];
         };
-        executeCommand: (command: string, returnEmptyStringOnSuccess?: boolean) => Promise<any>;
+        executeCommand: (command: string, returnEmptyStringOnSuccess?: boolean) => Promise<import("@codebolt/types/sdk").CommandOutput | import("@codebolt/types/sdk").CommandError | import("@codebolt/types/sdk").CommandFinish>;
         executeCommandRunUntilError: (command: string, executeInMain?: boolean) => Promise<import("@codebolt/types/sdk").CommandError>;
         executeCommandRunUntilInterrupt: (command: string, executeInMain?: boolean) => Promise<import("@codebolt/types/sdk").CommandError>;
         sendManualInterrupt(): Promise<import("@codebolt/types/sdk").TerminalInterruptResponse>;
@@ -296,7 +290,7 @@ declare class Codebolt {
         getTaskSummary: (taskId: string) => Promise<string | undefined>;
     };
     thread: {
-        createThread: (options: any) => Promise<import("@codebolt/types/app-to-agent-ws-schema").CreateThreadResponse>;
+        createThread: (options: import("@codebolt/types/agent-to-app-ws-schema").CreateThreadOptions) => Promise<import("@codebolt/types/app-to-agent-ws-schema").CreateThreadResponse>;
         createAndStartThread: (options: import("@codebolt/types/agent-to-app-ws-schema").CreateAndStartThreadOptions) => Promise<import("@codebolt/types/app-to-agent-ws-schema").StartThreadResponse>;
         createThreadInBackground: (options: import("@codebolt/types/agent-to-app-ws-schema").CreateAndStartThreadOptions) => Promise<import("@codebolt/types/app-to-agent-ws-schema").ThreadAgentStartedResponse | import("@codebolt/types/app-to-agent-ws-schema").ThreadAgentStartFailedResponse>;
         getThreadList: (options?: import("@codebolt/types/agent-to-app-ws-schema").GetThreadListOptions) => Promise<import("@codebolt/types/app-to-agent-ws-schema").ListThreadsResponse>;
@@ -306,8 +300,8 @@ declare class Codebolt {
         deleteThread: (threadId: string) => Promise<import("@codebolt/types/app-to-agent-ws-schema").DeleteThreadResponse>;
         updateThreadStatus: (threadId: string, status: string) => Promise<import("@codebolt/types/app-to-agent-ws-schema").UpdateThreadStatusResponse>;
         getThreadMessages: (options: import("@codebolt/types/agent-to-app-ws-schema").GetThreadMessagesOptions) => Promise<import("@codebolt/types/app-to-agent-ws-schema").GetThreadMessagesResponse>;
-        getThreadFileChanges: (threadId: string) => Promise<any>;
-        getThreadFileChangesSummary: (threadId: string) => Promise<any>;
+        getThreadFileChanges: (threadId: string) => Promise<import("@codebolt/types/sdk").ThreadFileChangesResponse>;
+        getThreadFileChangesSummary: (threadId: string) => Promise<import("@codebolt/types/sdk").ThreadFileChangesSummaryResponse>;
     };
     vectordb: {
         getVector: (key: string) => Promise<import("@codebolt/types/sdk").GetVectorResponse>;
@@ -390,25 +384,11 @@ declare class Codebolt {
             status?: string;
             planId?: string;
         }) => Promise<any>;
-        updateActionPlan: (planId: string, updateData: any) => Promise<any>;
-        addTaskToActionPlan: (planId: string, task: {
-            name: string;
-            description?: string;
-            priority?: string;
-            taskType?: string;
-            [key: string]: any;
-        }) => Promise<any>;
-        addGroupToActionPlan: (planId: string, group: {
-            type: "parallelGroup" | "loopGroup" | "ifGroup" | "waitUntilGroup";
-            name?: string;
-            groupItems?: Record<string, any[]>;
-            loopTasks?: any[];
-            ifTasks?: any[];
-            waitTasks?: any[];
-            [key: string]: any;
-        }) => Promise<any>;
+        updateActionPlan: (planId: string, updateData: import("@codebolt/types/sdk").ActionPlanUpdateData) => Promise<any>;
+        addTaskToActionPlan: (planId: string, task: import("@codebolt/types/sdk").ActionPlanTask) => Promise<any>;
+        addGroupToActionPlan: (planId: string, group: import("@codebolt/types/sdk").ActionPlanGroup) => Promise<any>;
         startTaskStep: (planId: string, taskId: string) => Promise<any>;
-        startTaskStepWithListener: (planId: string, taskId: string, onResponse: (response: any) => void) => () => void;
+        startTaskStepWithListener: (planId: string, taskId: string, onResponse: (response: import("@codebolt/types/sdk").TaskStepResponse) => void) => (() => void);
     };
     todo: {
         addTodo: (params: {
@@ -433,7 +413,11 @@ declare class Codebolt {
         importTodos: (params: {
             data: string;
             format?: "json" | "markdown";
-            mergeStrategy?: "replace" | "merge";
+            mergeStrategy? /**
+             * @method isReady
+             * @description Checks if the Codebolt instance is ready for use.
+             * @returns {boolean} True if the instance is ready, false otherwise.
+             */: "replace" | "merge";
             listId?: string;
         }) => Promise<import("@codebolt/types/sdk").ImportTodosResponse>;
     };
@@ -875,27 +859,43 @@ declare class Codebolt {
         }) => Promise<import("@codebolt/types/sdk").UpdateProfileResponse>;
     };
     orchestrator: {
-        listOrchestrators: () => Promise<import("../modules/orchestrator").OrchestratorResponse>;
-        getOrchestrator: (orchestratorId: string) => Promise<import("../modules/orchestrator").OrchestratorResponse>;
-        getOrchestratorSettings: (orchestratorId: string) => Promise<import("../modules/orchestrator").OrchestratorResponse>;
-        createOrchestrator: (data: import("../modules/orchestrator").CreateOrchestratorParams) => Promise<import("../modules/orchestrator").OrchestratorResponse>;
-        updateOrchestrator: (orchestratorId: string, data: import("../modules/orchestrator").UpdateOrchestratorParams) => Promise<import("../modules/orchestrator").OrchestratorResponse>;
-        updateOrchestratorSettings: (orchestratorId: string, settings: import("../modules/orchestrator").UpdateOrchestratorSettingsParams) => Promise<import("../modules/orchestrator").OrchestratorResponse>;
-        deleteOrchestrator: (orchestratorId: string) => Promise<import("../modules/orchestrator").OrchestratorResponse>;
-        updateOrchestratorStatus: (orchestratorId: string, status: "idle" | "running" | "paused") => Promise<import("../modules/orchestrator").OrchestratorResponse>;
-        updateCodeboltJs: () => Promise<import("../modules/orchestrator").OrchestratorResponse>;
+        listOrchestrators: () => Promise<import("@codebolt/types/sdk").OrchestratorResponse>;
+        getOrchestrator: (orchestratorId: string) => Promise<import("@codebolt/types/sdk").OrchestratorResponse>;
+        getOrchestratorSettings: (orchestratorId: string) => Promise<import("@codebolt/types/sdk").OrchestratorResponse>;
+        createOrchestrator: (data: import("@codebolt/types/sdk").CreateOrchestratorParams) => Promise<import("@codebolt/types/sdk").OrchestratorResponse>;
+        updateOrchestrator: (orchestratorId: string, data: import("@codebolt/types/sdk").UpdateOrchestratorParams) => Promise<import("@codebolt/types/sdk").OrchestratorResponse>;
+        updateOrchestratorSettings: (orchestratorId: string, settings: import("@codebolt/types/sdk").UpdateOrchestratorSettingsParams) => Promise<import("@codebolt/types/sdk").OrchestratorResponse>;
+        deleteOrchestrator: (orchestratorId: string) => Promise<import("@codebolt/types/sdk").OrchestratorResponse>;
+        updateOrchestratorStatus: (orchestratorId: string, status: import("@codebolt/types/sdk").OrchestratorStatus) => Promise<import("@codebolt/types/sdk").OrchestratorResponse>;
+        updateCodeboltJs: () => Promise<import("@codebolt/types/sdk").OrchestratorResponse>;
     };
     backgroundChildThreads: {
-        addRunningAgent: (threadId: string, data: any, groupId?: string) => void;
+        addRunningAgent: (threadId: string, data: import("@codebolt/types/sdk").BackgroundAgentData, groupId?: string) => void;
         getRunningAgentCount: () => number;
-        checkForBackgroundAgentCompletion: () => any[] | null;
-        onBackgroundAgentCompletion: () => Promise<any>;
-        checkForBackgroundGroupedAgentCompletion: () => any;
-        onBackgroundGroupedAgentCompletion: () => Promise<any>;
-        waitForAnyExternalEvent: () => Promise<{
-            type: string;
-            data: any;
-        }>;
+        checkForBackgroundAgentCompletion: () => import("@codebolt/types/sdk").BackgroundAgentCompletion[] | null;
+        onBackgroundAgentCompletion: () => Promise<import("@codebolt/types/sdk").BackgroundAgentCompletion[] | null>;
+        checkForBackgroundGroupedAgentCompletion: () => import("@codebolt/types/sdk").BackgroundAgentCompletion | null;
+        onBackgroundGroupedAgentCompletion: () => Promise<import("@codebolt/types/sdk").BackgroundAgentCompletion | null>;
+        waitForAnyExternalEvent: () => Promise<import("@codebolt/types/sdk").BackgroundExternalEvent>;
+    };
+    agentEventQueue: {
+        addEvent: (params: import("../types/agentEventQueue").AddEventInput) => Promise<import("../types/agentEventQueue").AgentEventQueueResponse<import("../types/agentEventQueue").AddEventResponseData>>;
+        sendAgentMessage: (params: import("../types/agentEventQueue").SendAgentMessageInput) => Promise<import("../types/agentEventQueue").AgentEventQueueResponse<import("../types/agentEventQueue").AddEventResponseData>>;
+        getQueueStats: () => Promise<import("../types/agentEventQueue").AgentEventQueueResponse<import("../types/agentEventQueue").QueueStatsResponseData>>;
+        clearQueue: (agentId?: string) => Promise<import("../types/agentEventQueue").AgentEventQueueResponse>;
+        _acknowledgeEvent: (eventId: string, success?: boolean, errorMessage?: string) => Promise<import("../types/agentEventQueue").AgentEventQueueResponse>;
+        _fetchPendingFromBackend: (params?: import("../types/agentEventQueue").GetPendingEventsInput) => Promise<import("../types/agentEventQueue").AgentEventMessage[]>;
+        getPendingQueueEvents: (maxDepth?: number) => Promise<import("../types/agentEventQueue").AgentEventMessage[]>;
+        waitForNextQueueEvent: (maxDepth?: number) => Promise<import("../types/agentEventQueue").AgentEventMessage | import("../types/agentEventQueue").AgentEventMessage[]>;
+        onQueueEvent: (handler: import("../types/agentEventQueue").QueueEventHandler) => (() => void);
+        acknowledgeEvent: (eventId: string, success?: boolean, errorMessage?: string) => Promise<import("../types/agentEventQueue").AgentEventQueueResponse>;
+        getLocalCacheSize: () => number;
+        peekLocalCache: () => import("../types/agentEventQueue").AgentEventMessage[];
+        clearLocalCache: () => void;
+        checkForPendingExternalEvent: () => import("../modules/agentEventQueue").UnifiedExternalEvent | null;
+        getPendingExternalEvents: () => import("../modules/agentEventQueue").UnifiedExternalEvent[];
+        getPendingExternalEventCount: () => number;
+        waitForAnyExternalEvent: () => Promise<import("../modules/agentEventQueue").UnifiedExternalEvent>;
     };
     /**
      * User message utilities for accessing current user message and context

package/dist/core/Codebolt.js

@@ -64,6 +64,7 @@ const contextRuleEngine_1 = __importDefault(require("../modules/contextRuleEngin
 const agentPortfolio_1 = __importDefault(require("../modules/agentPortfolio"));
 const orchestrator_1 = __importDefault(require("../modules/orchestrator"));
 const backgroundChildThreads_1 = __importDefault(require("../modules/backgroundChildThreads"));
+const agentEventQueue_1 = __importDefault(require("../modules/agentEventQueue"));
 /**
  * @class Codebolt
  * @description This class provides a unified interface to interact with various modules.
@@ -137,6 +138,7 @@ class Codebolt {
         this.agentPortfolio = agentPortfolio_1.default;
         this.orchestrator = orchestrator_1.default;
         this.backgroundChildThreads = backgroundChildThreads_1.default;
+        this.agentEventQueue = agentEventQueue_1.default;
         /**
          * User message utilities for accessing current user message and context
          */

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export declare const openNewBrowserInstance: (options?: import("./types/libFunct
     instanceId: string;
 }>;
 export declare const closeBrowserInstance: (instanceId: string) => Promise<boolean>;
-export declare const executeOnInstance: (instanceId: string, operation: string, params: any) => Promise<any>;
+export declare const executeOnInstance: (instanceId: string, operation: import("@codebolt/types/dist/codeboltjstypes/libFunctionTypes/browser").BrowserOperationType, params: import("@codebolt/types/dist/codeboltjstypes/libFunctionTypes/browser").BrowserOperationParams) => Promise<import("@codebolt/types/dist/codeboltjstypes/libFunctionTypes/browser").BrowserOperationResponse>;
 export { agentNotifications, browserNotifications, chatNotifications, codeutilsNotifications, crawlerNotifications, dbmemoryNotifications, fsNotifications, gitNotifications, historyNotifications, llmNotifications, mcpNotifications, searchNotifications, systemNotifications, terminalNotifications, todoNotifications, notificationFunctions, type NotificationFunctions } from './notificationfunctions';
 export { StartSubagentTaskRequestNotify, StartSubagentTaskResponseNotify, SubagentTaskCompletedNotify } from './notificationfunctions/agent';
 export { AgentInitNotify, AgentCompletionNotify } from './notificationfunctions/system';

package/dist/modules/actionPlan.d.ts

@@ -1,3 +1,5 @@
+import type { ActionPlanUpdateData, ActionPlanTask, ActionPlanGroup, TaskStepResponse } from '@codebolt/types/sdk';
+export type { ActionPlanUpdateData, ActionPlanTask, ActionPlanGroup, TaskStepResponse };
 declare const codeboltActionPlan: {
     /**
      * Get all action plans
@@ -35,35 +37,21 @@ declare const codeboltActionPlan: {
      * @param updateData - Data to update in the action plan
      * @returns Promise with updated action plan
      */
-    updateActionPlan: (planId: string, updateData: any) => Promise<any>;
+    updateActionPlan: (planId: string, updateData: ActionPlanUpdateData) => Promise<any>;
     /**
      * Add a task to an action plan
      * @param planId - The ID of the action plan
      * @param task - Task data to add (name, description, priority, taskType, etc.)
      * @returns Promise with added task and updated action plan
      */
-    addTaskToActionPlan: (planId: string, task: {
-        name: string;
-        description?: string;
-        priority?: string;
-        taskType?: string;
-        [key: string]: any;
-    }) => Promise<any>;
+    addTaskToActionPlan: (planId: string, task: ActionPlanTask) => Promise<any>;
     /**
      * Add a group to an action plan
      * @param planId - The ID of the action plan
      * @param group - Group data to add (type, name, groupItems/loopTasks/ifTasks/waitTasks, etc.)
      * @returns Promise with added group and updated action plan
      */
-    addGroupToActionPlan: (planId: string, group: {
-        type: "parallelGroup" | "loopGroup" | "ifGroup" | "waitUntilGroup";
-        name?: string;
-        groupItems?: Record<string, any[]>;
-        loopTasks?: any[];
-        ifTasks?: any[];
-        waitTasks?: any[];
-        [key: string]: any;
-    }) => Promise<any>;
+    addGroupToActionPlan: (planId: string, group: ActionPlanGroup) => Promise<any>;
     /**
      * Start/execute a task step in an action plan
      * @param planId - The ID of the action plan
@@ -78,6 +66,6 @@ declare const codeboltActionPlan: {
      * @param onResponse - Callback function that will be called when receiving responses for this task
      * @returns Cleanup function to remove the event listener
      */
-    startTaskStepWithListener: (planId: string, taskId: string, onResponse: (response: any) => void) => () => void;
+    startTaskStepWithListener: (planId: string, taskId: string, onResponse: (response: TaskStepResponse) => void) => (() => void);
 };
 export default codeboltActionPlan;

package/dist/modules/agentEventQueue.d.ts

@@ -6,6 +6,17 @@
 import type { AgentEventMessage, AddEventInput, SendAgentMessageInput, GetPendingEventsInput, AgentEventQueueResponse, AddEventResponseData, QueueStatsResponseData, QueueEventHandler } from '../types/agentEventQueue';
 export type { AgentEventMessage, AddEventInput, SendAgentMessageInput, AckEventInput, GetPendingEventsInput, AgentEventQueueResponse, AddEventResponseData, GetPendingEventsResponseData, QueueStatsResponseData, QueueEventHandler } from '../types/agentEventQueue';
 export { AgentEventType, AgentEventStatus, AgentEventPriority } from '../types/agentEventQueue';
+/**
+ * Types of external events that can be received
+ */
+export type ExternalEventType = 'agentQueueEvent' | 'backgroundAgentCompletion' | 'backgroundGroupedAgentCompletion';
+/**
+ * Unified external event structure
+ */
+export interface UnifiedExternalEvent {
+    type: ExternalEventType;
+    data: any;
+}
 declare const agentEventQueue: {
     /**
      * Add an event to a target agent's queue
@@ -92,5 +103,36 @@ declare const agentEventQueue: {
      * Clear the local event cache (does not affect backend)
      */
     clearLocalCache: () => void;
+    /**
+     * Check for any pending external events without waiting.
+     * Returns the first pending event or null if none available.
+     *
+     * @returns {UnifiedExternalEvent | null} The first pending event or null
+     */
+    checkForPendingExternalEvent: () => UnifiedExternalEvent | null;
+    /**
+     * Get all pending external events.
+     * Returns all pending events and clears the cache.
+     *
+     * @returns {UnifiedExternalEvent[]} Array of pending events
+     */
+    getPendingExternalEvents: () => UnifiedExternalEvent[];
+    /**
+     * Get the count of pending external events.
+     *
+     * @returns {number} Number of pending events
+     */
+    getPendingExternalEventCount: () => number;
+    /**
+     * Waits for any external event from multiple sources:
+     * - Agent queue events (from local cache or WebSocket)
+     * - Background agent completions
+     * - Grouped agent completions
+     *
+     * Returns the first event that occurs from any source.
+     *
+     * @returns {Promise<UnifiedExternalEvent>} A promise that resolves with the event type and data
+     */
+    waitForAnyExternalEvent: () => Promise<UnifiedExternalEvent>;
 };
 export default agentEventQueue;

package/dist/modules/agentEventQueue.js

@@ -18,15 +18,17 @@ Object.defineProperty(exports, "AgentEventPriority", { enumerable: true, get: fu
 // ============================================================================
 // Local Event Cache
 // ============================================================================
-/** Local cache for events received via WebSocket */
+/** Local cache for agent events received via WebSocket */
 const localEventCache = new Map();
+/** Unified cache for all external events (queue events, background completions, grouped completions) */
+const pendingExternalEvents = [];
 /** Registered event handlers */
 const eventHandlers = new Set();
 /** Event emitter for waiting promises */
 const events_1 = require("events");
 const eventEmitter = new events_1.EventEmitter();
 // ============================================================================
-// WebSocket Subscription
+// WebSocket Subscriptions
 // ============================================================================
 // Subscribe to agentEvent messages from WebSocket
 const agentEventSubscription = websocket_1.default.messageManager.subscribe('agentEvent');
@@ -35,8 +37,11 @@ agentEventSubscription.on('message', (message) => {
     if (event && event.eventId) {
         // Store in local cache
         localEventCache.set(event.eventId, event);
+        // Also push to unified external events cache
+        pendingExternalEvents.push({ type: 'agentQueueEvent', data: event });
         // Notify waiting promises
         eventEmitter.emit('newEvent', event);
+        eventEmitter.emit('externalEvent', { type: 'agentQueueEvent', data: event });
         // Call registered handlers
         for (const handler of eventHandlers) {
             try {
@@ -48,6 +53,33 @@ agentEventSubscription.on('message', (message) => {
         }
     }
 });
+// Subscribe to background agent completion messages
+const backgroundAgentSubscription = websocket_1.default.messageManager.subscribe('startThreadResponse');
+backgroundAgentSubscription.on('message', (message) => {
+    if (message.threadId) {
+        const externalEvent = { type: 'backgroundAgentCompletion', data: message };
+        pendingExternalEvents.push(externalEvent);
+        eventEmitter.emit('externalEvent', externalEvent);
+    }
+});
+// Subscribe to ThreadCompleted as an alternative message type
+const threadCompletedSubscription = websocket_1.default.messageManager.subscribe('ThreadCompleted');
+threadCompletedSubscription.on('message', (message) => {
+    if (message.threadId) {
+        const externalEvent = { type: 'backgroundAgentCompletion', data: message };
+        pendingExternalEvents.push(externalEvent);
+        eventEmitter.emit('externalEvent', externalEvent);
+    }
+});
+// Subscribe to grouped agent completion messages
+const groupedAgentSubscription = websocket_1.default.messageManager.subscribe('backgroundGroupedAgentCompletion');
+groupedAgentSubscription.on('message', (message) => {
+    if (message.threadId) {
+        const externalEvent = { type: 'backgroundGroupedAgentCompletion', data: message };
+        pendingExternalEvents.push(externalEvent);
+        eventEmitter.emit('externalEvent', externalEvent);
+    }
+});
 // ============================================================================
 // Agent Event Queue Module
 // ============================================================================
@@ -66,7 +98,7 @@ const agentEventQueue = {
             type: 'agentEventQueue.addEventForAgent',
             requestId,
             params
-        }, 'agentEventQueueResponse');
+        }, 'agentEventQueue.addEventForAgentResponse');
     },
     /**
      * Send an inter-agent message (convenience wrapper)
@@ -79,7 +111,7 @@ const agentEventQueue = {
             type: 'agentEventQueue.sendAgentMessage',
             requestId,
             params
-        }, 'agentEventQueueResponse');
+        }, 'agentEventQueue.sendAgentMessageResponse');
     },
     /**
      * Get queue statistics
@@ -91,7 +123,7 @@ const agentEventQueue = {
             type: 'agentEventQueue.getQueueStats',
             requestId,
             params: {}
-        }, 'agentEventQueueResponse');
+        }, 'agentEventQueue.getQueueStatsResponse');
     },
     /**
      * Clear the queue for an agent
@@ -104,7 +136,7 @@ const agentEventQueue = {
             type: 'agentEventQueue.clearQueue',
             requestId,
             params: { agentId }
-        }, 'agentEventQueueResponse');
+        }, 'agentEventQueue.clearQueueResponse');
     },
     // ========================================================================
     // Internal Acknowledgement Helper
@@ -125,7 +157,7 @@ const agentEventQueue = {
                 success,
                 errorMessage
             }
-        }, 'agentEventQueueResponse');
+        }, 'agentEventQueue.ackEventResponse');
     },
     /**
      * Fetch pending events from backend
@@ -133,15 +165,37 @@ const agentEventQueue = {
      */
     _fetchPendingFromBackend: async (params = {}) => {
         const requestId = (0, crypto_1.randomUUID)();
-        const response = await websocket_1.default.messageManager.sendAndWaitForResponse({
-            type: 'agentEventQueue.getPendingEvents',
-            requestId,
-            params
-        }, 'agentEventQueueResponse');
-        if (response.success && response.data) {
-            return response.data.events;
+        try {
+            const response = await websocket_1.default.messageManager.sendAndWaitForResponse({
+                type: 'agentEventQueue.getPendingEvents',
+                requestId,
+                params
+            }, 'agentEventQueue.getPendingEventsResponse');
+            console.log('[AgentEventQueue] Backend response:', JSON.stringify(response, null, 2));
+            if (response.success && response.data) {
+                // Handle case where data itself is the array
+                if (Array.isArray(response.data)) {
+                    return response.data;
+                }
+                // Handle case where events are nested under data.events
+                const events = response.data.events;
+                if (Array.isArray(events)) {
+                    return events;
+                }
+                console.warn('[AgentEventQueue] response.data.events is not an array:', typeof events, events);
+                return [];
+            }
+            // Handle case where events are at response root level (not nested under data)
+            const responseAny = response;
+            if (response.success && Array.isArray(responseAny.events)) {
+                return responseAny.events;
+            }
+            return [];
+        }
+        catch (error) {
+            console.error('[AgentEventQueue] Error fetching pending events from backend:', error);
+            return [];
         }
-        return [];
     },
     // ========================================================================
     // Local Event Management Functions
@@ -157,6 +211,7 @@ const agentEventQueue = {
     getPendingQueueEvents: async (maxDepth) => {
         const events = [];
         const eventIds = Array.from(localEventCache.keys());
+        console.log('[AgentEventQueue] getPendingQueueEvents - localEventCache size:', localEventCache.size);
         // Determine how many events to process
         const limit = maxDepth !== undefined ? Math.min(maxDepth, eventIds.length) : eventIds.length;
         // Get events from local cache
@@ -164,16 +219,27 @@ const agentEventQueue = {
             const eventId = eventIds[i];
             const event = localEventCache.get(eventId);
             if (event) {
+                console.log('[AgentEventQueue] Local cache event:', eventId, 'has eventId field:', !!event.eventId);
                 events.push(event);
             }
         }
         // If no local events, try fetching from backend
         if (events.length === 0) {
             const backendEvents = await agentEventQueue._fetchPendingFromBackend({ limit: maxDepth });
+            console.log('[AgentEventQueue] getPendingQueueEvents - backendEvents:', Array.isArray(backendEvents) ? `array of ${backendEvents.length}` : typeof backendEvents, JSON.stringify(backendEvents, null, 2));
+            // Ensure backendEvents is an array
+            if (!Array.isArray(backendEvents)) {
+                console.error('[AgentEventQueue] backendEvents is not an array, returning empty array');
+                return [];
+            }
             // Acknowledge backend events
             for (const event of backendEvents) {
                 try {
-                    await agentEventQueue._acknowledgeEvent(event.eventId, true);
+                    const ackResponse = await agentEventQueue._acknowledgeEvent(event.eventId, true);
+                    console.log(`[AgentEventQueue] Ack response for ${event.eventId}:`, JSON.stringify(ackResponse));
+                    if (!ackResponse.success) {
+                        console.error(`[AgentEventQueue] Failed to acknowledge event ${event.eventId}:`, ackResponse.message);
+                    }
                 }
                 catch (error) {
                     console.error(`[AgentEventQueue] Error acknowledging event ${event.eventId}:`, error);
@@ -283,6 +349,92 @@ const agentEventQueue = {
      */
     clearLocalCache: () => {
         localEventCache.clear();
+    },
+    // ========================================================================
+    // Unified External Event Handling
+    // ========================================================================
+    /**
+     * Check for any pending external events without waiting.
+     * Returns the first pending event or null if none available.
+     *
+     * @returns {UnifiedExternalEvent | null} The first pending event or null
+     */
+    checkForPendingExternalEvent: () => {
+        if (pendingExternalEvents.length > 0) {
+            return pendingExternalEvents.shift() || null;
+        }
+        return null;
+    },
+    /**
+     * Get all pending external events.
+     * Returns all pending events and clears the cache.
+     *
+     * @returns {UnifiedExternalEvent[]} Array of pending events
+     */
+    getPendingExternalEvents: () => {
+        const events = [...pendingExternalEvents];
+        pendingExternalEvents.length = 0;
+        return events;
+    },
+    /**
+     * Get the count of pending external events.
+     *
+     * @returns {number} Number of pending events
+     */
+    getPendingExternalEventCount: () => {
+        return pendingExternalEvents.length;
+    },
+    /**
+     * Waits for any external event from multiple sources:
+     * - Agent queue events (from local cache or WebSocket)
+     * - Background agent completions
+     * - Grouped agent completions
+     *
+     * Returns the first event that occurs from any source.
+     *
+     * @returns {Promise<UnifiedExternalEvent>} A promise that resolves with the event type and data
+     */
+    waitForAnyExternalEvent: async () => {
+        var _a;
+        // Check if there are already pending events
+        if (pendingExternalEvents.length > 0) {
+            const event = pendingExternalEvents.shift();
+            // If it's an agent queue event, acknowledge it
+            if (event.type === 'agentQueueEvent' && ((_a = event.data) === null || _a === void 0 ? void 0 : _a.eventId)) {
+                try {
+                    await agentEventQueue._acknowledgeEvent(event.data.eventId, true);
+                    localEventCache.delete(event.data.eventId);
+                }
+                catch (error) {
+                    console.error(`[AgentEventQueue] Error acknowledging event ${event.data.eventId}:`, error);
+                }
+            }
+            return event;
+        }
+        // Wait for the next external event
+        return new Promise((resolve) => {
+            const handler = async (event) => {
+                var _a;
+                eventEmitter.removeListener('externalEvent', handler);
+                // Remove from pending queue (it was added by the subscription)
+                const index = pendingExternalEvents.findIndex(e => e === event);
+                if (index !== -1) {
+                    pendingExternalEvents.splice(index, 1);
+                }
+                // If it's an agent queue event, acknowledge it
+                if (event.type === 'agentQueueEvent' && ((_a = event.data) === null || _a === void 0 ? void 0 : _a.eventId)) {
+                    try {
+                        await agentEventQueue._acknowledgeEvent(event.data.eventId, true);
+                        localEventCache.delete(event.data.eventId);
+                    }
+                    catch (error) {
+                        console.error(`[AgentEventQueue] Error acknowledging event ${event.data.eventId}:`, error);
+                    }
+                }
+                resolve(event);
+            };
+            eventEmitter.once('externalEvent', handler);
+        });
     }
 };
 exports.default = agentEventQueue;