dexto 1.1.3 → 1.1.4

package/dist/api/types.d.ts

@@ -0,0 +1,15 @@
+import { AgentEventBus } from '@dexto/core';
+/**
+ * Generic interface for subscribing to core events.
+ */
+export interface EventSubscriber {
+    /**
+     * Attach event handlers to the given event bus.
+     */
+    subscribe(eventBus: AgentEventBus): void;
+    /**
+     * Clean up event listeners and resources.
+     */
+    cleanup?(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAEzC;;OAEG;IACH,OAAO,CAAC,IAAI,IAAI,CAAC;CACpB"}

package/dist/api/types.js

@@ -0,0 +1 @@
+export {};

package/dist/api/webhook-subscriber.d.ts

@@ -0,0 +1,61 @@
+import { AgentEventBus } from '@dexto/core';
+import { EventSubscriber } from './types.js';
+import { type WebhookConfig, type WebhookDeliveryResult, type WebhookDeliveryOptions } from './webhook-types.js';
+/**
+ * Webhook event subscriber that delivers agent events via HTTP POST
+ * Mirrors WebSocketEventSubscriber but sends HTTP requests to registered webhook URLs
+ */
+export declare class WebhookEventSubscriber implements EventSubscriber {
+    private webhooks;
+    private abortController?;
+    private deliveryOptions;
+    private fetchFn;
+    constructor({ fetchFn, ...deliveryOptions }?: WebhookDeliveryOptions & {
+        fetchFn?: typeof globalThis.fetch;
+    });
+    /**
+     * Subscribe to agent events and deliver them to registered webhooks
+     */
+    subscribe(eventBus: AgentEventBus): void;
+    /**
+     * Register a new webhook endpoint
+     */
+    addWebhook(webhook: WebhookConfig): void;
+    /**
+     * Remove a webhook endpoint
+     */
+    removeWebhook(webhookId: string): boolean;
+    /**
+     * Get all registered webhooks
+     */
+    getWebhooks(): WebhookConfig[];
+    /**
+     * Get a specific webhook by ID
+     */
+    getWebhook(webhookId: string): WebhookConfig | undefined;
+    /**
+     * Test a webhook by sending a sample event
+     */
+    testWebhook(webhookId: string): Promise<WebhookDeliveryResult>;
+    /**
+     * Clean up event listeners and resources
+     */
+    cleanup(): void;
+    /**
+     * Deliver an event to all registered webhooks
+     */
+    private deliverEvent;
+    /**
+     * Deliver an event to a specific webhook with retry logic
+     */
+    private deliverToWebhook;
+    /**
+     * Send HTTP request to webhook endpoint
+     */
+    private sendWebhookRequest;
+    /**
+     * Generate HMAC signature for webhook verification
+     */
+    private generateSignature;
+}
+//# sourceMappingURL=webhook-subscriber.d.ts.map

package/dist/api/webhook-subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-subscriber.d.ts","sourceRoot":"","sources":["../../src/api/webhook-subscriber.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAmD,MAAM,aAAa,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACH,KAAK,aAAa,EAElB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC9B,MAAM,oBAAoB,CAAC;AAW5B;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,eAAe,CAAmC;IAC1D,OAAO,CAAC,OAAO,CAA0B;gBAE7B,EACR,OAAO,EACP,GAAG,eAAe,EACrB,GAAE,sBAAsB,GAAG;QAAE,OAAO,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;KAAO;IAOtE;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IA0CxC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAKxC;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAUzC;;OAEG;IACH,WAAW,IAAI,aAAa,EAAE;IAI9B;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIxD;;OAEG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAoBpE;;OAEG;IACH,OAAO,IAAI,IAAI;IAUf;;OAEG;YACW,YAAY;IA+C1B;;OAEG;YACW,gBAAgB;IAoD9B;;OAEG;YACW,kBAAkB;IA+DhC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAK5B"}

package/dist/api/webhook-subscriber.js

@@ -0,0 +1,267 @@
+import crypto from 'crypto';
+import { setMaxListeners } from 'events';
+import { logger } from '@dexto/core';
+/**
+ * Default configuration for webhook delivery
+ */
+const DEFAULT_DELIVERY_OPTIONS = {
+    maxRetries: 3,
+    timeout: 10000, // 10 seconds
+    includeSignature: true,
+};
+/**
+ * Webhook event subscriber that delivers agent events via HTTP POST
+ * Mirrors WebSocketEventSubscriber but sends HTTP requests to registered webhook URLs
+ */
+export class WebhookEventSubscriber {
+    webhooks = new Map();
+    abortController;
+    deliveryOptions;
+    fetchFn;
+    constructor({ fetchFn, ...deliveryOptions } = {}) {
+        this.deliveryOptions = { ...DEFAULT_DELIVERY_OPTIONS, ...deliveryOptions };
+        // Use native fetch (Node.js 20+) or injected implementation (tests)
+        this.fetchFn = fetchFn || fetch;
+        logger.debug('WebhookEventSubscriber initialized');
+    }
+    /**
+     * Subscribe to agent events and deliver them to registered webhooks
+     */
+    subscribe(eventBus) {
+        // Abort any previous subscription before creating a new one
+        this.abortController?.abort();
+        // Create new AbortController for this subscription
+        this.abortController = new AbortController();
+        const { signal } = this.abortController;
+        // Increase max listeners since we intentionally share this signal across multiple events
+        // This prevents the MaxListenersExceededWarning
+        const MAX_SHARED_SIGNAL_LISTENERS = 20;
+        setMaxListeners(MAX_SHARED_SIGNAL_LISTENERS, signal);
+        // Subscribe to all relevant events with abort signal (same as WebSocket subscriber)
+        const eventNames = [
+            'llmservice:thinking',
+            'llmservice:chunk',
+            'llmservice:toolCall',
+            'llmservice:toolResult',
+            'llmservice:response',
+            'llmservice:error',
+            'dexto:conversationReset',
+            'dexto:mcpServerConnected',
+            'dexto:availableToolsUpdated',
+            'dexto:toolConfirmationRequest',
+            'dexto:llmSwitched',
+            'dexto:stateChanged',
+        ];
+        eventNames.forEach((eventName) => {
+            eventBus.on(eventName, (payload) => {
+                this.deliverEvent(eventName, payload);
+            }, { signal });
+        });
+        logger.info(`Webhook subscriber active with ${this.webhooks.size} registered webhooks`);
+    }
+    /**
+     * Register a new webhook endpoint
+     */
+    addWebhook(webhook) {
+        this.webhooks.set(webhook.id, webhook);
+        logger.info(`Webhook registered: ${webhook.id} -> ${webhook.url}`);
+    }
+    /**
+     * Remove a webhook endpoint
+     */
+    removeWebhook(webhookId) {
+        const removed = this.webhooks.delete(webhookId);
+        if (removed) {
+            logger.info(`Webhook removed: ${webhookId}`);
+        }
+        else {
+            logger.warn(`Attempted to remove non-existent webhook: ${webhookId}`);
+        }
+        return removed;
+    }
+    /**
+     * Get all registered webhooks
+     */
+    getWebhooks() {
+        return Array.from(this.webhooks.values());
+    }
+    /**
+     * Get a specific webhook by ID
+     */
+    getWebhook(webhookId) {
+        return this.webhooks.get(webhookId);
+    }
+    /**
+     * Test a webhook by sending a sample event
+     */
+    async testWebhook(webhookId) {
+        const webhook = this.webhooks.get(webhookId);
+        if (!webhook) {
+            throw new Error(`Webhook not found: ${webhookId}`);
+        }
+        const testEvent = {
+            id: `evt_test_${Date.now()}`,
+            type: 'dexto:availableToolsUpdated',
+            data: {
+                tools: ['test-tool'],
+                source: 'mcp',
+            },
+            created: new Date().toISOString(),
+            apiVersion: '2025-07-03',
+        };
+        return this.deliverToWebhook(webhook, testEvent);
+    }
+    /**
+     * Clean up event listeners and resources
+     */
+    cleanup() {
+        if (this.abortController) {
+            this.abortController.abort();
+            delete this.abortController;
+        }
+        this.webhooks.clear();
+        logger.debug('Webhook event subscriber cleaned up');
+    }
+    /**
+     * Deliver an event to all registered webhooks
+     */
+    async deliverEvent(eventType, eventData) {
+        if (this.webhooks.size === 0) {
+            return; // No webhooks to deliver to
+        }
+        const webhookEvent = {
+            id: `evt_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`,
+            type: eventType,
+            data: eventData,
+            created: new Date().toISOString(),
+            apiVersion: '2025-07-03',
+        };
+        logger.debug(`Delivering webhook event: ${eventType} to ${this.webhooks.size} webhooks`);
+        // Deliver to all webhooks in parallel
+        const deliveryPromises = Array.from(this.webhooks.values()).map((webhook) => ({
+            webhook,
+            promise: this.deliverToWebhook(webhook, webhookEvent),
+        }));
+        const handleSettled = (results) => {
+            results.forEach((result, i) => {
+                if (result.status === 'rejected') {
+                    const webhook = deliveryPromises[i]?.webhook;
+                    if (webhook) {
+                        logger.error(`Webhook delivery failed for ${webhook.id}: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
+                    }
+                }
+            });
+        };
+        // For testing purposes, we can await this if needed
+        if (process.env.NODE_ENV === 'test') {
+            const results = await Promise.allSettled(deliveryPromises.map((p) => p.promise));
+            handleSettled(results);
+        }
+        else {
+            // Fire-and-forget in production
+            Promise.allSettled(deliveryPromises.map((p) => p.promise)).then(handleSettled);
+        }
+    }
+    /**
+     * Deliver an event to a specific webhook with retry logic
+     */
+    async deliverToWebhook(webhook, event) {
+        const startTime = Date.now();
+        let lastError;
+        let lastStatusCode;
+        for (let attempt = 1; attempt <= this.deliveryOptions.maxRetries; attempt++) {
+            try {
+                const result = await this.sendWebhookRequest(webhook, event, attempt);
+                if (result.success) {
+                    return result;
+                }
+                // Don't duplicate "HTTP xxx:" prefix if it's already in the error message
+                lastError = new Error(result.error || `HTTP ${result.statusCode}`);
+                lastStatusCode = result.statusCode;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                logger.warn(`Webhook delivery attempt ${attempt}/${this.deliveryOptions.maxRetries} failed for ${webhook.id}: ${lastError.message}`);
+            }
+            // Wait before retry (exponential backoff with jitter)
+            if (attempt < this.deliveryOptions.maxRetries) {
+                // Use shorter delays in test environment for faster tests
+                const baseDelay = process.env.NODE_ENV === 'test' ? 1 : 1000;
+                const exp = baseDelay * Math.pow(2, attempt - 1);
+                const jitter = exp * 0.2 * Math.random(); // ±20%
+                const backoffMs = Math.min(exp + jitter, 10000);
+                await new Promise((resolve) => setTimeout(resolve, backoffMs));
+            }
+        }
+        // All attempts failed
+        const totalTime = Date.now() - startTime;
+        const result = {
+            success: false,
+            error: lastError?.message || 'Unknown error',
+            responseTime: totalTime,
+            attempt: this.deliveryOptions.maxRetries,
+            ...(lastStatusCode !== undefined && { statusCode: lastStatusCode }),
+        };
+        logger.error(`Webhook delivery failed after ${this.deliveryOptions.maxRetries} attempts for ${webhook.id}: ${result.error}`);
+        return result;
+    }
+    /**
+     * Send HTTP request to webhook endpoint
+     */
+    async sendWebhookRequest(webhook, event, attempt) {
+        const startTime = Date.now();
+        const payload = JSON.stringify(event);
+        // Prepare headers
+        const headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': 'DextoAgent/1.0',
+            'X-Dexto-Event-Type': event.type,
+            'X-Dexto-Event-Id': event.id,
+            'X-Dexto-Delivery-Attempt': attempt.toString(),
+        };
+        // Add signature if secret is provided
+        if (webhook.secret && this.deliveryOptions.includeSignature) {
+            const signature = this.generateSignature(payload, webhook.secret);
+            headers['X-Dexto-Signature-256'] = signature;
+        }
+        try {
+            const response = await this.fetchFn(webhook.url, {
+                method: 'POST',
+                headers,
+                body: payload,
+                signal: AbortSignal.timeout(this.deliveryOptions.timeout),
+            });
+            const responseTime = Date.now() - startTime;
+            const success = response.ok;
+            const result = {
+                success,
+                statusCode: response.status,
+                responseTime,
+                attempt,
+            };
+            if (!success) {
+                result.error = `HTTP ${response.status}: ${response.statusText}`;
+            }
+            logger.debug(`Webhook delivery ${success ? 'succeeded' : 'failed'} for ${webhook.id}: ${response.status} in ${responseTime}ms`);
+            return result;
+        }
+        catch (error) {
+            const responseTime = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                error: errorMessage,
+                responseTime,
+                attempt,
+            };
+        }
+    }
+    /**
+     * Generate HMAC signature for webhook verification
+     */
+    generateSignature(payload, secret) {
+        const hmac = crypto.createHmac('sha256', secret);
+        hmac.update(payload, 'utf8');
+        return `sha256=${hmac.digest('hex')}`;
+    }
+}

package/dist/api/webhook-types.d.ts

@@ -0,0 +1,90 @@
+import type { AgentEventMap, AgentEventName } from '@dexto/core';
+/**
+ * Webhook configuration interface
+ * Represents a registered webhook endpoint
+ */
+export interface WebhookConfig {
+    /** Unique identifier for the webhook */
+    id: string;
+    /** The URL to send webhook events to */
+    url: string;
+    /** Optional secret for signature verification */
+    secret?: string;
+    /** When the webhook was registered */
+    createdAt: Date;
+    /** Optional description for the webhook */
+    description?: string;
+}
+/**
+ * Webhook event payload interface
+ * Mirrors Stripe.Event structure for familiar developer experience
+ */
+export interface DextoWebhookEvent<T extends AgentEventName = AgentEventName> {
+    /** Unique identifier for this webhook event */
+    id: string;
+    /** The type of event - provides IDE autocomplete */
+    type: T;
+    /** The event data payload - typed based on event type */
+    data: AgentEventMap[T];
+    /** When the event was created */
+    created: string;
+    /** API version for future compatibility */
+    apiVersion: string;
+}
+/**
+ * Webhook delivery attempt result
+ */
+export interface WebhookDeliveryResult {
+    /** Whether the delivery was successful */
+    success: boolean;
+    /** HTTP status code received */
+    statusCode?: number;
+    /** Error message if delivery failed */
+    error?: string;
+    /** Response time in milliseconds */
+    responseTime: number;
+    /** Number of delivery attempts */
+    attempt: number;
+}
+/**
+ * Webhook registration request body
+ */
+export interface WebhookRegistrationRequest {
+    /** The URL to send webhook events to */
+    url: string;
+    /** Optional secret for signature verification */
+    secret?: string;
+    /** Optional description for the webhook */
+    description?: string;
+}
+/**
+ * Webhook test event payload
+ */
+export interface WebhookTestEvent extends DextoWebhookEvent<'dexto:availableToolsUpdated'> {
+    /** Indicates this is a test event */
+    test: true;
+}
+/**
+ * Type-safe webhook handler function signature
+ * Provides autocomplete for event types and typed data payloads
+ */
+export type WebhookHandler<T extends AgentEventName = AgentEventName> = (event: DextoWebhookEvent<T>) => Promise<void> | void;
+/**
+ * Webhook handler mapping for type-safe event routing
+ * Provides IDE autocomplete for event names like Stripe webhooks
+ */
+export type WebhookEventHandlers = {
+    [K in AgentEventName]?: WebhookHandler<K>;
+};
+/**
+ * Webhook delivery options
+ */
+export interface WebhookDeliveryOptions {
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Include signature verification header */
+    includeSignature?: boolean;
+}
+//# sourceMappingURL=webhook-types.d.ts.map

package/dist/api/webhook-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-types.d.ts","sourceRoot":"","sources":["../../src/api/webhook-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,SAAS,EAAE,IAAI,CAAC;IAChB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc;IACxE,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,IAAI,EAAE,CAAC,CAAC;IACR,yDAAyD;IACzD,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACvB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACvC,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB,CAAC,6BAA6B,CAAC;IACtF,qCAAqC;IACrC,IAAI,EAAE,IAAI,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI,CACpE,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAC1B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE1B;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;KAC9B,CAAC,IAAI,cAAc,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;CAC5C,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B"}

package/dist/api/webhook-types.js

@@ -0,0 +1 @@
+export {};

package/dist/api/websocket-error-handler.d.ts

@@ -0,0 +1,13 @@
+import type { WebSocket } from 'ws';
+/**
+ * Standardized WebSocket error handler that mirrors HTTP error middleware
+ * Sends consistent error messages over WebSocket following the same patterns as REST API
+ *
+ * TODO: Add typed WebSocket payload interfaces to replace manual JSON structure creation
+ */
+export declare function sendWebSocketError(ws: WebSocket, error: unknown, sessionId: string): void;
+/**
+ * Helper to send validation error for WebSocket input
+ */
+export declare function sendWebSocketValidationError(ws: WebSocket, message: string, sessionId: string, context?: Record<string, unknown>): void;
+//# sourceMappingURL=websocket-error-handler.d.ts.map

package/dist/api/websocket-error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-error-handler.d.ts","sourceRoot":"","sources":["../../src/api/websocket-error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAYpC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CA8CzF;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CACxC,EAAE,EAAE,SAAS,EACb,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,IAAI,CA6BN"}

package/dist/api/websocket-error-handler.js

@@ -0,0 +1,86 @@
+import { DextoRuntimeError, DextoValidationError, ErrorType, ErrorScope, AgentErrorCode, } from '@dexto/core';
+import { ZodError } from 'zod';
+import { zodToIssues, toError } from '@dexto/core';
+import { logger } from '@dexto/core';
+/**
+ * Standardized WebSocket error handler that mirrors HTTP error middleware
+ * Sends consistent error messages over WebSocket following the same patterns as REST API
+ *
+ * TODO: Add typed WebSocket payload interfaces to replace manual JSON structure creation
+ */
+export function sendWebSocketError(ws, error, sessionId) {
+    let errorData;
+    if (error instanceof DextoRuntimeError) {
+        errorData = error.toJSON();
+    }
+    else if (error instanceof DextoValidationError) {
+        errorData = error.toJSON();
+    }
+    else if (error instanceof ZodError) {
+        const issues = zodToIssues(error);
+        const dexErr = new DextoValidationError(issues);
+        errorData = dexErr.toJSON();
+    }
+    else {
+        // Log unexpected errors with full context for debugging (mirror HTTP middleware)
+        const errorObj = toError(error);
+        const errorStack = error instanceof Error ? error.stack : undefined;
+        logger.error(`Unhandled WebSocket error: ${errorObj.message}`, {
+            error: error,
+            stack: errorStack,
+            type: typeof error,
+        });
+        // Generic error response for non-DextoError exceptions - include actual error details
+        errorData = {
+            code: 'internal_error',
+            message: errorObj.message,
+            scope: ErrorScope.AGENT,
+            type: ErrorType.SYSTEM,
+            severity: 'error',
+        };
+    }
+    // Send error event with structured data (guard against closed sockets)
+    try {
+        ws.send(JSON.stringify({
+            event: 'error',
+            data: {
+                ...errorData,
+                ...(sessionId ? { sessionId } : {}),
+            },
+        }));
+    }
+    catch (sendErr) {
+        const msg = sendErr instanceof Error ? sendErr.message : String(sendErr);
+        logger.error(`Failed to send WebSocket error frame: ${msg}`, { errorData });
+    }
+}
+/**
+ * Helper to send validation error for WebSocket input
+ */
+export function sendWebSocketValidationError(ws, message, sessionId, context) {
+    const dexErr = new DextoValidationError([
+        {
+            code: AgentErrorCode.API_VALIDATION_ERROR,
+            message,
+            scope: ErrorScope.AGENT,
+            type: ErrorType.USER,
+            severity: 'error',
+            context,
+        },
+    ]);
+    const data = dexErr.toJSON();
+    logger.error(`Sending WebSocket validation error: ${message}`, { data });
+    try {
+        ws.send(JSON.stringify({
+            event: 'error',
+            data: {
+                ...data,
+                ...(sessionId ? { sessionId } : {}),
+            },
+        }));
+    }
+    catch (sendErr) {
+        const msg = sendErr instanceof Error ? sendErr.message : String(sendErr);
+        logger.error(`Failed to send WebSocket validation error: ${msg}`, { data });
+    }
+}

package/dist/api/websocket-subscriber.d.ts

@@ -0,0 +1,22 @@
+import { WebSocketServer } from 'ws';
+import { AgentEventBus } from '@dexto/core';
+import { EventSubscriber } from './types.js';
+/**
+ * WebSocket event subscriber that broadcasts agent events to connected clients
+ */
+export declare class WebSocketEventSubscriber implements EventSubscriber {
+    private wss;
+    private connections;
+    private abortController?;
+    constructor(wss: WebSocketServer);
+    /**
+     * Subscribe to agent events and broadcast them to WebSocket clients
+     */
+    subscribe(eventBus: AgentEventBus): void;
+    /**
+     * Clean up event listeners and resources
+     */
+    cleanup(): void;
+    private broadcast;
+}
+//# sourceMappingURL=websocket-subscriber.d.ts.map

package/dist/api/websocket-subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-subscriber.d.ts","sourceRoot":"","sources":["../../src/api/websocket-subscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAa,MAAM,IAAI,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IAIhD,OAAO,CAAC,GAAG;IAHvB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,eAAe,CAAC,CAAkB;gBAEtB,GAAG,EAAE,eAAe;IAmBxC;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAyKxC;;OAEG;IACH,OAAO,IAAI,IAAI;IAiBf,OAAO,CAAC,SAAS;CAUpB"}