@bradygaster/squad-sdk 0.6.2 → 0.8.0

package/dist/runtime/cost-tracker.js

@@ -0,0 +1,157 @@
+/**
+ * Cost Tracker
+ *
+ * Accumulates cost and token data across a squad run with per-agent and
+ * per-session breakdowns. Wires into EventBus for real-time updates.
+ *
+ * @module runtime/cost-tracker
+ */
+// ============================================================================
+// CostTracker
+// ============================================================================
+/**
+ * Accumulates cost/token data across the squad run.
+ *
+ * Can be wired to an EventBus to receive live usage events or fed
+ * data manually via `recordUsage()`.
+ */
+export class CostTracker {
+    agents = new Map();
+    sessions = new Map();
+    unsubscribe = null;
+    /**
+     * Record a single usage event.
+     */
+    recordUsage(opts) {
+        const agentKey = opts.agentName ?? 'unknown';
+        // Per-agent
+        const agent = this.agents.get(agentKey);
+        if (agent) {
+            agent.inputTokens += opts.inputTokens;
+            agent.outputTokens += opts.outputTokens;
+            agent.estimatedCost += opts.estimatedCost;
+            agent.turnCount += 1;
+            agent.model = opts.model;
+            if (opts.isFallback)
+                agent.fallbackCount += 1;
+        }
+        else {
+            this.agents.set(agentKey, {
+                agentName: agentKey,
+                model: opts.model,
+                inputTokens: opts.inputTokens,
+                outputTokens: opts.outputTokens,
+                estimatedCost: opts.estimatedCost,
+                turnCount: 1,
+                fallbackCount: opts.isFallback ? 1 : 0,
+            });
+        }
+        // Per-session
+        const session = this.sessions.get(opts.sessionId);
+        if (session) {
+            session.inputTokens += opts.inputTokens;
+            session.outputTokens += opts.outputTokens;
+            session.estimatedCost += opts.estimatedCost;
+            session.turnCount += 1;
+        }
+        else {
+            this.sessions.set(opts.sessionId, {
+                sessionId: opts.sessionId,
+                agentName: opts.agentName,
+                inputTokens: opts.inputTokens,
+                outputTokens: opts.outputTokens,
+                estimatedCost: opts.estimatedCost,
+                turnCount: 1,
+            });
+        }
+    }
+    /** Record a model fallback for an agent (increments fallback counter). */
+    recordFallback(agentName) {
+        const agent = this.agents.get(agentName);
+        if (agent) {
+            agent.fallbackCount += 1;
+        }
+    }
+    /** Get the full cost summary. */
+    getSummary() {
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let totalEstimatedCost = 0;
+        for (const entry of this.agents.values()) {
+            totalInputTokens += entry.inputTokens;
+            totalOutputTokens += entry.outputTokens;
+            totalEstimatedCost += entry.estimatedCost;
+        }
+        return {
+            totalInputTokens,
+            totalOutputTokens,
+            totalEstimatedCost,
+            agents: new Map(this.agents),
+            sessions: new Map(this.sessions),
+        };
+    }
+    /** Get formatted summary string suitable for terminal output. */
+    formatSummary() {
+        const summary = this.getSummary();
+        const lines = [];
+        lines.push('=== Squad Cost Summary ===');
+        lines.push(`Total input tokens:  ${summary.totalInputTokens.toLocaleString()}`);
+        lines.push(`Total output tokens: ${summary.totalOutputTokens.toLocaleString()}`);
+        lines.push(`Estimated cost:      $${summary.totalEstimatedCost.toFixed(4)}`);
+        if (summary.agents.size > 0) {
+            lines.push('');
+            lines.push('--- By Agent ---');
+            for (const [name, entry] of summary.agents) {
+                lines.push(`  ${name}: ${entry.inputTokens.toLocaleString()}in / ${entry.outputTokens.toLocaleString()}out` +
+                    ` ($${entry.estimatedCost.toFixed(4)}) [${entry.turnCount} turns, model: ${entry.model}` +
+                    `${entry.fallbackCount > 0 ? `, ${entry.fallbackCount} fallbacks` : ''}]`);
+            }
+        }
+        if (summary.sessions.size > 0) {
+            lines.push('');
+            lines.push('--- By Session ---');
+            for (const [id, entry] of summary.sessions) {
+                lines.push(`  ${id}: ${entry.inputTokens.toLocaleString()}in / ${entry.outputTokens.toLocaleString()}out` +
+                    ` ($${entry.estimatedCost.toFixed(4)}) [${entry.turnCount} turns]`);
+            }
+        }
+        return lines.join('\n');
+    }
+    /** Clear all accumulated data. */
+    reset() {
+        this.agents.clear();
+        this.sessions.clear();
+    }
+    /**
+     * Wire into an EventBus to receive real-time `session:message` events
+     * that carry usage payloads. Returns an unsubscribe function.
+     */
+    wireToEventBus(bus) {
+        const handler = (event) => {
+            const payload = event.payload;
+            if (!payload)
+                return;
+            // Accept events with usage data in the payload
+            if (typeof payload.inputTokens === 'number' &&
+                typeof payload.outputTokens === 'number') {
+                this.recordUsage({
+                    sessionId: event.sessionId ?? 'unknown',
+                    agentName: event.agentName,
+                    model: payload.model ?? 'unknown',
+                    inputTokens: payload.inputTokens,
+                    outputTokens: payload.outputTokens,
+                    estimatedCost: payload.estimatedCost ?? 0,
+                    isFallback: payload.isFallback ?? false,
+                });
+            }
+        };
+        this.unsubscribe = bus.subscribe('session:message', handler);
+        return () => {
+            if (this.unsubscribe) {
+                this.unsubscribe();
+                this.unsubscribe = null;
+            }
+        };
+    }
+}
+//# sourceMappingURL=cost-tracker.js.map

package/dist/runtime/cost-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-tracker.js","sourceRoot":"","sources":["../../src/runtime/cost-tracker.ts"],"names":[],"mappings":"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"}

package/dist/runtime/event-bus.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Cross-Session Event Bus (M0-5, Issue #77)
+ *
+ * Pub/sub event bus for session lifecycle events with cross-session aggregation.
+ * Enables the coordinator to observe all agent sessions from a single subscription point.
+ * Decouples event producers (sessions) from consumers (coordinator, Ralph, UI).
+ *
+ * @module runtime/event-bus
+ */
+/**
+ * Core lifecycle events emitted by Squad sessions.
+ * All lifecycle events are persistent and logged for debugging.
+ */
+export type SquadLifecycleEvent = 'session:created' | 'session:idle' | 'session:error' | 'session:destroyed';
+/**
+ * Additional operational events for coordination and monitoring.
+ */
+export type SquadOperationalEvent = 'session:message' | 'session:tool_call' | 'agent:milestone' | 'coordinator:routing' | 'pool:health';
+/**
+ * All event types supported by the event bus.
+ */
+export type SquadEventType = SquadLifecycleEvent | SquadOperationalEvent;
+/**
+ * Base event structure with required metadata.
+ * All events include a timestamp for chronological ordering and debugging.
+ */
+export interface SquadEvent {
+    /** Event type identifier */
+    type: SquadEventType;
+    /** Session ID that originated this event (optional for pool-level events) */
+    sessionId?: string;
+    /** Agent name associated with this event (optional) */
+    agentName?: string;
+    /** Event-specific payload data */
+    payload: unknown;
+    /** Timestamp when event was created */
+    timestamp: Date;
+}
+/**
+ * Handler function for processing events.
+ * Handlers may be synchronous or asynchronous.
+ * Errors in handlers are isolated and do not affect other handlers.
+ */
+export type EventHandler = (event: SquadEvent) => void | Promise<void>;
+/**
+ * Unsubscribe function returned from subscription methods.
+ * Call this function to remove the handler from the event bus.
+ */
+export type UnsubscribeFn = () => void;
+/**
+ * Cross-session event aggregation bus.
+ *
+ * Key features:
+ * - Subscribe to specific event types or all events
+ * - Async/sync handler support with error isolation
+ * - No race conditions — handlers run in subscription order
+ * - Lifecycle events: session:created, session:idle, session:error, session:destroyed
+ * - Cross-session aggregation — single subscription point for all sessions
+ *
+ * Usage:
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Subscribe to specific event
+ * const unsubscribe = bus.subscribe('session:created', (event) => {
+ *   console.log('New session:', event.sessionId);
+ * });
+ *
+ * // Subscribe to all events
+ * const unsubscribeAll = bus.subscribeAll((event) => {
+ *   console.log('Event:', event.type);
+ * });
+ *
+ * // Emit event
+ * await bus.emit({
+ *   type: 'session:created',
+ *   sessionId: 'abc-123',
+ *   agentName: 'Ralph',
+ *   payload: { model: 'claude-sonnet-4.5' },
+ *   timestamp: new Date()
+ * });
+ *
+ * // Clean up
+ * unsubscribe();
+ * unsubscribeAll();
+ * ```
+ */
+export declare class EventBus {
+    private handlers;
+    private allHandlers;
+    private errorHandlers;
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @param type - Event type to listen for
+     * @param handler - Handler function to call when event occurs
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```typescript
+     * const bus = new EventBus();
+     * const unsubscribe = bus.subscribe('session:created', (event) => {
+     *   console.log('Session created:', event.sessionId);
+     * });
+     *
+     * // Later, remove subscription
+     * unsubscribe();
+     * ```
+     */
+    subscribe(type: SquadEventType, handler: EventHandler): UnsubscribeFn;
+    /**
+     * Subscribe to all events regardless of type.
+     * Useful for logging, monitoring, or debugging.
+     *
+     * @param handler - Handler function to call for every event
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```typescript
+     * const bus = new EventBus();
+     * const unsubscribe = bus.subscribeAll((event) => {
+     *   console.log(`[${event.type}] ${event.sessionId || 'global'}`);
+     * });
+     * ```
+     */
+    subscribeAll(handler: EventHandler): UnsubscribeFn;
+    /**
+     * Unsubscribe a handler from a specific event type.
+     *
+     * @param type - Event type to unsubscribe from
+     * @param handler - Handler function to remove
+     */
+    unsubscribe(type: SquadEventType, handler: EventHandler): void;
+    /**
+     * Register an error handler for handler execution failures.
+     * Error handlers are called when a subscribed handler throws an error.
+     *
+     * @param handler - Error handler function
+     * @returns Unsubscribe function to remove this error handler
+     */
+    onError(handler: (error: Error, event: SquadEvent) => void): UnsubscribeFn;
+    /**
+     * Emit an event to all matching subscribers.
+     * Handlers are called in subscription order with error isolation.
+     * One handler failure does not prevent other handlers from executing.
+     *
+     * @param event - Event to emit
+     * @returns Promise that resolves when all handlers complete
+     *
+     * @example
+     * ```typescript
+     * await bus.emit({
+     *   type: 'session:created',
+     *   sessionId: 'abc-123',
+     *   agentName: 'Ralph',
+     *   payload: { model: 'claude-sonnet-4.5' },
+     *   timestamp: new Date()
+     * });
+     * ```
+     */
+    emit(event: SquadEvent): Promise<void>;
+    /**
+     * Execute a single handler with error isolation.
+     * Catches and reports handler errors without propagating them.
+     *
+     * @param handler - Handler function to execute
+     * @param event - Event to pass to handler
+     */
+    private executeHandler;
+    /**
+     * Remove all handlers and reset the event bus.
+     * Useful for cleanup in tests or when shutting down.
+     */
+    clear(): void;
+    /**
+     * Get count of handlers for a specific event type.
+     * Useful for debugging and testing.
+     *
+     * @param type - Event type to count handlers for
+     * @returns Number of handlers subscribed to this event type
+     */
+    getHandlerCount(type: SquadEventType): number;
+    /**
+     * Get count of wildcard handlers.
+     *
+     * @returns Number of handlers subscribed to all events
+     */
+    getAllHandlerCount(): number;
+}
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/runtime/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/runtime/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,iBAAiB,GACjB,cAAc,GACd,eAAe,GACf,mBAAmB,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,mBAAmB,GACnB,iBAAiB,GACjB,qBAAqB,GACrB,aAAa,CAAC;AAElB;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,mBAAmB,GAAG,qBAAqB,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,IAAI,EAAE,cAAc,CAAC;IACrB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC;AAMvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAqD;IACrE,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,aAAa,CAA6D;IAElF;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,GAAG,aAAa;IASrE;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa;IAKlD;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAS9D;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,aAAa;IAK1E;;;;;;;;;;;;;;;;;;OAkBG;IACG,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB5C;;;;;;OAMG;YACW,cAAc;IA2B5B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;;OAMG;IACH,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM;IAI7C;;;;OAIG;IACH,kBAAkB,IAAI,MAAM;CAG7B"}

package/dist/runtime/event-bus.js

@@ -0,0 +1,218 @@
+/**
+ * Cross-Session Event Bus (M0-5, Issue #77)
+ *
+ * Pub/sub event bus for session lifecycle events with cross-session aggregation.
+ * Enables the coordinator to observe all agent sessions from a single subscription point.
+ * Decouples event producers (sessions) from consumers (coordinator, Ralph, UI).
+ *
+ * @module runtime/event-bus
+ */
+// ============================================================================
+// Event Bus Implementation
+// ============================================================================
+/**
+ * Cross-session event aggregation bus.
+ *
+ * Key features:
+ * - Subscribe to specific event types or all events
+ * - Async/sync handler support with error isolation
+ * - No race conditions — handlers run in subscription order
+ * - Lifecycle events: session:created, session:idle, session:error, session:destroyed
+ * - Cross-session aggregation — single subscription point for all sessions
+ *
+ * Usage:
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Subscribe to specific event
+ * const unsubscribe = bus.subscribe('session:created', (event) => {
+ *   console.log('New session:', event.sessionId);
+ * });
+ *
+ * // Subscribe to all events
+ * const unsubscribeAll = bus.subscribeAll((event) => {
+ *   console.log('Event:', event.type);
+ * });
+ *
+ * // Emit event
+ * await bus.emit({
+ *   type: 'session:created',
+ *   sessionId: 'abc-123',
+ *   agentName: 'Ralph',
+ *   payload: { model: 'claude-sonnet-4.5' },
+ *   timestamp: new Date()
+ * });
+ *
+ * // Clean up
+ * unsubscribe();
+ * unsubscribeAll();
+ * ```
+ */
+export class EventBus {
+    handlers = new Map();
+    allHandlers = new Set();
+    errorHandlers = new Set();
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @param type - Event type to listen for
+     * @param handler - Handler function to call when event occurs
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```typescript
+     * const bus = new EventBus();
+     * const unsubscribe = bus.subscribe('session:created', (event) => {
+     *   console.log('Session created:', event.sessionId);
+     * });
+     *
+     * // Later, remove subscription
+     * unsubscribe();
+     * ```
+     */
+    subscribe(type, handler) {
+        if (!this.handlers.has(type)) {
+            this.handlers.set(type, new Set());
+        }
+        this.handlers.get(type).add(handler);
+        return () => this.unsubscribe(type, handler);
+    }
+    /**
+     * Subscribe to all events regardless of type.
+     * Useful for logging, monitoring, or debugging.
+     *
+     * @param handler - Handler function to call for every event
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```typescript
+     * const bus = new EventBus();
+     * const unsubscribe = bus.subscribeAll((event) => {
+     *   console.log(`[${event.type}] ${event.sessionId || 'global'}`);
+     * });
+     * ```
+     */
+    subscribeAll(handler) {
+        this.allHandlers.add(handler);
+        return () => this.allHandlers.delete(handler);
+    }
+    /**
+     * Unsubscribe a handler from a specific event type.
+     *
+     * @param type - Event type to unsubscribe from
+     * @param handler - Handler function to remove
+     */
+    unsubscribe(type, handler) {
+        this.handlers.get(type)?.delete(handler);
+        // Clean up empty handler sets
+        if (this.handlers.get(type)?.size === 0) {
+            this.handlers.delete(type);
+        }
+    }
+    /**
+     * Register an error handler for handler execution failures.
+     * Error handlers are called when a subscribed handler throws an error.
+     *
+     * @param handler - Error handler function
+     * @returns Unsubscribe function to remove this error handler
+     */
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    /**
+     * Emit an event to all matching subscribers.
+     * Handlers are called in subscription order with error isolation.
+     * One handler failure does not prevent other handlers from executing.
+     *
+     * @param event - Event to emit
+     * @returns Promise that resolves when all handlers complete
+     *
+     * @example
+     * ```typescript
+     * await bus.emit({
+     *   type: 'session:created',
+     *   sessionId: 'abc-123',
+     *   agentName: 'Ralph',
+     *   payload: { model: 'claude-sonnet-4.5' },
+     *   timestamp: new Date()
+     * });
+     * ```
+     */
+    async emit(event) {
+        const typeHandlers = this.handlers.get(event.type) ?? new Set();
+        const allPromises = [];
+        // Execute type-specific handlers
+        for (const handler of typeHandlers) {
+            allPromises.push(this.executeHandler(handler, event));
+        }
+        // Execute wildcard handlers
+        for (const handler of this.allHandlers) {
+            allPromises.push(this.executeHandler(handler, event));
+        }
+        // Wait for all handlers to complete
+        // Errors are isolated and won't throw from here
+        await Promise.all(allPromises);
+    }
+    /**
+     * Execute a single handler with error isolation.
+     * Catches and reports handler errors without propagating them.
+     *
+     * @param handler - Handler function to execute
+     * @param event - Event to pass to handler
+     */
+    async executeHandler(handler, event) {
+        try {
+            const result = handler(event);
+            if (result instanceof Promise) {
+                await result;
+            }
+        }
+        catch (error) {
+            // Isolate handler errors — one failure shouldn't crash others
+            const wrappedError = error instanceof Error ? error : new Error(String(error));
+            // Notify error handlers
+            for (const errorHandler of this.errorHandlers) {
+                try {
+                    errorHandler(wrappedError, event);
+                }
+                catch (errorHandlerError) {
+                    // Error handler itself failed — log to console as last resort
+                    console.error('EventBus error handler failed:', errorHandlerError);
+                }
+            }
+            // If no error handlers registered, log to console
+            if (this.errorHandlers.size === 0) {
+                console.error(`EventBus handler error for ${event.type}:`, wrappedError);
+            }
+        }
+    }
+    /**
+     * Remove all handlers and reset the event bus.
+     * Useful for cleanup in tests or when shutting down.
+     */
+    clear() {
+        this.handlers.clear();
+        this.allHandlers.clear();
+        this.errorHandlers.clear();
+    }
+    /**
+     * Get count of handlers for a specific event type.
+     * Useful for debugging and testing.
+     *
+     * @param type - Event type to count handlers for
+     * @returns Number of handlers subscribed to this event type
+     */
+    getHandlerCount(type) {
+        return this.handlers.get(type)?.size ?? 0;
+    }
+    /**
+     * Get count of wildcard handlers.
+     *
+     * @returns Number of handlers subscribed to all events
+     */
+    getAllHandlerCount() {
+        return this.allHandlers.size;
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/runtime/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../src/runtime/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/runtime/health.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Health Monitor (M0-8 #83)
+ *
+ * Monitors the health of SquadClient connections and provides diagnostics.
+ * Exposes health status for external monitoring and startup validation.
+ */
+import type { SquadClient } from '../adapter/client.js';
+export interface HealthCheckResult {
+    /** Overall health status */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Connection state */
+    connectionState: string;
+    /** Whether the client is connected */
+    connected: boolean;
+    /** Error message if unhealthy */
+    error?: string;
+    /** Protocol version if available */
+    protocolVersion?: number;
+    /** Timestamp of the check */
+    timestamp: Date;
+    /** Response time in milliseconds */
+    responseTimeMs?: number;
+}
+export interface HealthMonitorConfig {
+    /** Client to monitor */
+    client: SquadClient;
+    /** Timeout for health checks in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Log diagnostic information on failures */
+    logDiagnostics?: boolean;
+}
+/**
+ * Health Monitor for SquadClient connections.
+ *
+ * Provides health checks, diagnostics logging, and external health status.
+ * Use check() for startup validation before creating sessions.
+ */
+export declare class HealthMonitor {
+    private client;
+    private timeout;
+    private logDiagnostics;
+    constructor(config: HealthMonitorConfig);
+    /**
+     * Perform a health check on the client connection.
+     *
+     * This method:
+     * 1. Checks connection state
+     * 2. Attempts a ping if connected
+     * 3. Validates protocol version
+     * 4. Logs diagnostics on failure
+     *
+     * @returns Health check result with status and diagnostics
+     */
+    check(): Promise<HealthCheckResult>;
+    /**
+     * Get current status without performing a health check.
+     *
+     * @returns Basic health status based on connection state
+     */
+    getStatus(): Pick<HealthCheckResult, 'status' | 'connectionState' | 'connected' | 'timestamp'>;
+    /**
+     * Log diagnostic information on connection failures.
+     */
+    private logDiagnostic;
+}
+//# sourceMappingURL=health.d.ts.map

package/dist/runtime/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/runtime/health.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAE7C,uBAAuB;IACvB,eAAe,EAAE,MAAM,CAAC;IAExB,sCAAsC;IACtC,SAAS,EAAE,OAAO,CAAC;IAEnB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;IAEhB,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,wBAAwB;IACxB,MAAM,EAAE,WAAW,CAAC;IAEpB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAU;gBAEpB,MAAM,EAAE,mBAAmB;IAMvC;;;;;;;;;;OAUG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAgDzC;;;;OAIG;IACH,SAAS,IAAI,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,iBAAiB,GAAG,WAAW,GAAG,WAAW,CAAC;IAqB9F;;OAEG;IACH,OAAO,CAAC,aAAa;CAQtB"}