@sudocode-ai/local-server 0.1.0

package/dist/execution/resilience/retry.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Retry Logic and Backoff Strategies
+ *
+ * Implements retry logic with various backoff strategies including
+ * exponential, linear, and fixed delays with optional jitter.
+ *
+ * @module execution/resilience/retry
+ */
+import type { RetryPolicy, ExecutionAttempt } from './types.js';
+import type { ExecutionResult } from '../engine/types.js';
+/**
+ * Calculate backoff delay for a given attempt
+ *
+ * Supports multiple backoff strategies:
+ * - Exponential: baseDelay * 2^(attempt-1) - e.g., 1s, 2s, 4s, 8s, 16s
+ * - Linear: baseDelay * attempt - e.g., 1s, 2s, 3s, 4s, 5s
+ * - Fixed: constant baseDelay - e.g., 1s, 1s, 1s, 1s, 1s
+ *
+ * Applies maxDelay cap and optional jitter to prevent thundering herd.
+ *
+ * @param attempt - Attempt number (1-indexed)
+ * @param config - Backoff configuration from retry policy
+ * @returns Delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // Exponential backoff with jitter
+ * const delay = calculateBackoff(3, {
+ *   type: 'exponential',
+ *   baseDelayMs: 1000,
+ *   maxDelayMs: 30000,
+ *   jitter: true,
+ * });
+ * // Returns ~4000ms ± 10% jitter
+ * ```
+ */
+export declare function calculateBackoff(attempt: number, config: RetryPolicy['backoff']): number;
+/**
+ * Check if an error should trigger a retry
+ *
+ * Matches error message against the list of retryable error patterns
+ * defined in the retry policy.
+ *
+ * @param error - Error that occurred
+ * @param policy - Retry policy with retryable error patterns
+ * @returns True if error should be retried
+ *
+ * @example
+ * ```typescript
+ * const error = new Error('Connection timeout');
+ * const shouldRetry = isRetryableError(error, {
+ *   retryableErrors: ['timeout', 'ECONNREFUSED'],
+ *   // ... other policy fields
+ * });
+ * // Returns true
+ * ```
+ */
+export declare function isRetryableError(error: Error, policy: RetryPolicy): boolean;
+/**
+ * Check if an exit code should trigger a retry
+ *
+ * Matches exit code against the list of retryable exit codes
+ * defined in the retry policy.
+ *
+ * @param exitCode - Process exit code
+ * @param policy - Retry policy with retryable exit codes
+ * @returns True if exit code should be retried
+ *
+ * @example
+ * ```typescript
+ * const shouldRetry = isRetryableExitCode(1, {
+ *   retryableExitCodes: [1, 137],
+ *   // ... other policy fields
+ * });
+ * // Returns true
+ * ```
+ */
+export declare function isRetryableExitCode(exitCode: number, policy: RetryPolicy): boolean;
+/**
+ * Check if an execution result should trigger a retry
+ *
+ * Checks both the exit code and error message (if present) to determine
+ * if the execution should be retried.
+ *
+ * @param result - Execution result from task execution
+ * @param policy - Retry policy
+ * @returns True if execution should be retried
+ *
+ * @example
+ * ```typescript
+ * const result: ExecutionResult = {
+ *   taskId: 'task-1',
+ *   executionId: 'proc-123',
+ *   success: false,
+ *   exitCode: 1,
+ *   error: 'Connection timeout',
+ *   // ... other fields
+ * };
+ *
+ * const shouldRetry = isRetryableResult(result, policy);
+ * // Returns true if exitCode is retryable OR error contains retryable pattern
+ * ```
+ */
+export declare function isRetryableResult(result: ExecutionResult, policy: RetryPolicy): boolean;
+/**
+ * Promise-based sleep utility
+ *
+ * Returns a promise that resolves after the specified delay.
+ * Useful for implementing retry backoff.
+ *
+ * @param ms - Delay in milliseconds
+ * @returns Promise that resolves after delay
+ *
+ * @example
+ * ```typescript
+ * console.log('Starting...');
+ * await sleep(1000);
+ * console.log('1 second later');
+ * ```
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Create an execution attempt record
+ *
+ * Helper function to create a properly structured ExecutionAttempt object.
+ *
+ * @param attemptNumber - Attempt number (1-indexed)
+ * @param success - Whether the attempt succeeded
+ * @param options - Optional fields for the attempt
+ * @returns ExecutionAttempt object
+ */
+export declare function createAttempt(attemptNumber: number, success: boolean, options?: {
+    error?: Error;
+    exitCode?: number;
+    duration?: number;
+    willRetry?: boolean;
+    nextRetryAt?: Date;
+}): ExecutionAttempt;
+/**
+ * Calculate total delay from all retry attempts
+ *
+ * Sums up all the backoff delays that would be applied for a given
+ * number of retry attempts. Useful for timeout calculations.
+ *
+ * @param maxAttempts - Maximum number of attempts
+ * @param backoffConfig - Backoff configuration
+ * @returns Total delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * const totalDelay = calculateTotalRetryDelay(3, {
+ *   type: 'exponential',
+ *   baseDelayMs: 1000,
+ *   maxDelayMs: 30000,
+ *   jitter: false,
+ * });
+ * // Returns 7000ms (1s + 2s + 4s)
+ * ```
+ */
+export declare function calculateTotalRetryDelay(maxAttempts: number, backoffConfig: RetryPolicy['backoff']): number;
+//# sourceMappingURL=retry.d.ts.map

package/dist/execution/resilience/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/execution/resilience/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC,GAC7B,MAAM,CAyCR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAW3E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,GAClB,OAAO,CAET;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,WAAW,GAClB,OAAO,CAiBT;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,IAAI,CAAC;CACf,GACL,gBAAgB,CAclB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,WAAW,CAAC,SAAS,CAAC,GACpC,MAAM,CASR"}

package/dist/execution/resilience/types.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Resilience Layer Types
+ *
+ * Core types for the Resilience Layer (Layer 3) that adds retry logic,
+ * circuit breakers, and fault tolerance to task execution.
+ *
+ * @module execution/resilience/types
+ */
+import type { ExecutionResult } from '../engine/types.js';
+/**
+ * RetryPolicy - Configuration for retry behavior
+ */
+export interface RetryPolicy {
+    /**
+     * Maximum number of retry attempts (0 = no retry)
+     */
+    maxAttempts: number;
+    /**
+     * Backoff strategy configuration
+     */
+    backoff: {
+        /**
+         * Type of backoff strategy
+         * - exponential: delay = baseDelay * 2^(attempt-1)
+         * - linear: delay = baseDelay * attempt
+         * - fixed: delay = baseDelay (constant)
+         */
+        type: 'exponential' | 'linear' | 'fixed';
+        /**
+         * Initial delay in milliseconds
+         */
+        baseDelayMs: number;
+        /**
+         * Maximum delay cap in milliseconds
+         */
+        maxDelayMs: number;
+        /**
+         * Add randomness to prevent thundering herd
+         * Adds ±10% jitter to delay
+         */
+        jitter: boolean;
+    };
+    /**
+     * Error types/messages that should trigger a retry
+     * Examples: 'ECONNREFUSED', 'timeout', 'network'
+     */
+    retryableErrors: string[];
+    /**
+     * Exit codes that should trigger a retry
+     * Examples: [1, 137] for generic error and SIGKILL
+     */
+    retryableExitCodes: number[];
+    /**
+     * Optional callback to determine if circuit breaker should open
+     */
+    shouldOpenCircuit?: (error: Error, attempts: number) => boolean;
+}
+/**
+ * CircuitState - State of a circuit breaker
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * CircuitBreaker - Circuit breaker for preventing cascading failures
+ */
+export interface CircuitBreaker {
+    /**
+     * Unique name for this circuit breaker
+     * Typically matches the task type (e.g., 'issue', 'spec', 'custom')
+     */
+    name: string;
+    /**
+     * Current state of the circuit
+     * - closed: Normal operation, requests pass through
+     * - open: Too many failures, requests rejected
+     * - half-open: Testing if service recovered, limited requests allowed
+     */
+    state: CircuitState;
+    /**
+     * Circuit breaker configuration
+     */
+    config: {
+        /**
+         * Number of consecutive failures before opening circuit
+         */
+        failureThreshold: number;
+        /**
+         * Number of consecutive successes in half-open to close circuit
+         */
+        successThreshold: number;
+        /**
+         * Time to wait before transitioning from open to half-open (ms)
+         */
+        timeout: number;
+    };
+    /**
+     * Circuit breaker metrics
+     */
+    metrics: {
+        /**
+         * Total requests processed
+         */
+        totalRequests: number;
+        /**
+         * Total failed requests
+         */
+        failedRequests: number;
+        /**
+         * Total successful requests
+         */
+        successfulRequests: number;
+        /**
+         * Timestamp of last failure
+         */
+        lastFailureTime?: Date;
+        /**
+         * Timestamp of last success
+         */
+        lastSuccessTime?: Date;
+    };
+}
+/**
+ * ExecutionAttempt - Record of a single execution attempt
+ */
+export interface ExecutionAttempt {
+    /**
+     * Attempt number (1-indexed)
+     */
+    attemptNumber: number;
+    /**
+     * When this attempt started
+     */
+    startedAt: Date;
+    /**
+     * When this attempt completed (if finished)
+     */
+    completedAt?: Date;
+    /**
+     * Duration of this attempt in milliseconds
+     */
+    duration?: number;
+    /**
+     * Whether this attempt succeeded
+     */
+    success: boolean;
+    /**
+     * Error that occurred during this attempt
+     */
+    error?: Error;
+    /**
+     * Exit code from this attempt
+     */
+    exitCode?: number;
+    /**
+     * Whether another retry will be attempted after this
+     */
+    willRetry: boolean;
+    /**
+     * When the next retry will occur (if willRetry is true)
+     */
+    nextRetryAt?: Date;
+}
+/**
+ * ResilientExecutionResult - Enhanced execution result with retry information
+ *
+ * Extends the base ExecutionResult with detailed retry tracking
+ */
+export interface ResilientExecutionResult extends ExecutionResult {
+    /**
+     * All execution attempts made for this task
+     */
+    attempts: ExecutionAttempt[];
+    /**
+     * Total number of attempts made
+     */
+    totalAttempts: number;
+    /**
+     * The final attempt (may be success or failure)
+     */
+    finalAttempt: ExecutionAttempt;
+    /**
+     * Human-readable reason for failure (if failed)
+     */
+    failureReason?: string;
+    /**
+     * Whether the circuit breaker prevented execution
+     */
+    circuitBreakerTriggered?: boolean;
+}
+/**
+ * RetryMetrics - Aggregate metrics for retry behavior
+ */
+export interface RetryMetrics {
+    /**
+     * Total number of retries attempted across all tasks
+     */
+    totalRetries: number;
+    /**
+     * Number of retries that eventually succeeded
+     */
+    successfulRetries: number;
+    /**
+     * Number of retries that ultimately failed
+     */
+    failedRetries: number;
+    /**
+     * Average number of attempts needed for successful tasks
+     */
+    averageAttemptsToSuccess: number;
+    /**
+     * Circuit breakers by name
+     */
+    circuitBreakers: Map<string, CircuitBreaker>;
+}
+/**
+ * RetryAttemptHandler - Callback for retry attempt events
+ */
+export type RetryAttemptHandler = (taskId: string, attempt: ExecutionAttempt) => void;
+/**
+ * CircuitOpenHandler - Callback for circuit breaker open events
+ */
+export type CircuitOpenHandler = (circuitName: string, breaker: CircuitBreaker) => void;
+/**
+ * Default retry policy for resilient execution
+ */
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+//# sourceMappingURL=types.d.ts.map

package/dist/execution/resilience/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/execution/resilience/types.ts"],"names":[],"mappings":"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"}

package/dist/execution/transport/event-buffer.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Execution Event Buffer
+ *
+ * Stores AG-UI events for executions so they can be replayed to late-joining clients
+ * or retrieved for historical display.
+ *
+ * @module execution/transport/event-buffer
+ */
+import type { AgUiEvent } from "./transport-manager.js";
+/**
+ * Buffered event with metadata
+ */
+export interface BufferedEvent {
+    /** The AG-UI event */
+    event: AgUiEvent;
+    /** When the event was buffered */
+    timestamp: number;
+    /** Event sequence number within the execution */
+    sequenceNumber: number;
+}
+/**
+ * Event buffer for a single execution
+ */
+export interface ExecutionEventBuffer {
+    /** Execution/run ID */
+    executionId: string;
+    /** Buffered events in order */
+    events: BufferedEvent[];
+    /** Next sequence number */
+    nextSequence: number;
+    /** When the buffer was created */
+    createdAt: number;
+    /** When the buffer was last updated */
+    lastUpdatedAt: number;
+}
+/**
+ * EventBuffer - In-memory storage for execution events
+ *
+ * Stores events for active executions and allows replay when clients connect.
+ * Events are automatically pruned after executions complete to prevent memory leaks.
+ */
+export declare class EventBuffer {
+    private buffers;
+    private readonly MAX_EVENTS_PER_EXECUTION;
+    private readonly RETENTION_MS;
+    /**
+     * Add an event to the buffer for an execution
+     *
+     * @param executionId - Execution ID
+     * @param event - AG-UI event to buffer
+     */
+    addEvent(executionId: string, event: AgUiEvent): void;
+    /**
+     * Get all buffered events for an execution
+     *
+     * @param executionId - Execution ID
+     * @param fromSequence - Optional: only return events >= this sequence number
+     * @returns Array of buffered events, or empty array if no buffer exists
+     */
+    getEvents(executionId: string, fromSequence?: number): BufferedEvent[];
+    /**
+     * Check if a buffer exists for an execution
+     *
+     * @param executionId - Execution ID
+     * @returns true if buffer exists
+     */
+    hasBuffer(executionId: string): boolean;
+    /**
+     * Get buffer metadata without events
+     *
+     * @param executionId - Execution ID
+     * @returns Buffer metadata or null if not found
+     */
+    getBufferInfo(executionId: string): Omit<ExecutionEventBuffer, "events"> | null;
+    /**
+     * Remove a buffer for an execution
+     *
+     * @param executionId - Execution ID
+     * @returns true if buffer was removed, false if it didn't exist
+     */
+    removeBuffer(executionId: string): boolean;
+    /**
+     * Clear all buffers
+     */
+    clearAll(): void;
+    /**
+     * Prune stale buffers that haven't been updated recently
+     *
+     * Should be called periodically to prevent memory leaks.
+     *
+     * @returns Number of buffers pruned
+     */
+    pruneStale(): number;
+    /**
+     * Get total number of buffers
+     *
+     * @returns Number of active buffers
+     */
+    getBufferCount(): number;
+    /**
+     * Get total number of events across all buffers
+     *
+     * @returns Total event count
+     */
+    getTotalEventCount(): number;
+    /**
+     * Get statistics about buffer usage
+     *
+     * @returns Buffer statistics
+     */
+    getStats(): {
+        bufferCount: number;
+        totalEvents: number;
+        avgEventsPerBuffer: number;
+        oldestBuffer: number | null;
+        newestBuffer: number | null;
+    };
+}
+//# sourceMappingURL=event-buffer.d.ts.map

package/dist/execution/transport/event-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-buffer.d.ts","sourceRoot":"","sources":["../../../src/execution/transport/event-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uBAAuB;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAS;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;IAE/C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAmDrD;;;;;;OAMG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAatE;;;;;OAKG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIvC;;;;;OAKG;IACH,aAAa,CACX,WAAW,EAAE,MAAM,GAClB,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAAG,IAAI;IAc9C;;;;;OAKG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAY1C;;OAEG;IACH,QAAQ,IAAI,IAAI;IAMhB;;;;;;OAMG;IACH,UAAU,IAAI,MAAM;IAsBpB;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;OAIG;IACH,kBAAkB,IAAI,MAAM;IAQ5B;;;;OAIG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B;CAwBF"}

package/dist/execution/transport/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Transport Layer
+ *
+ * Exports transport implementations for streaming AG-UI events to clients.
+ *
+ * @module execution/transport
+ */
+export { SseTransport } from './sse-transport.js';
+export { TransportManager } from './transport-manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/execution/transport/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/execution/transport/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/execution/transport/sse-transport.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Server-Sent Events (SSE) Transport Layer
+ *
+ * Provides real-time streaming of AG-UI events to frontend clients using SSE.
+ * Supports connection management, heartbeat, and run-specific event filtering.
+ *
+ * @module execution/transport/sse-transport
+ */
+import type { Response } from "express";
+/**
+ * SSE Event to send to clients
+ *
+ * Follows the SSE specification format
+ */
+interface SseEvent {
+    /** Event type (optional, defaults to 'message') */
+    event?: string;
+    /** Event data (will be JSON stringified) */
+    data: any;
+    /** Event ID (optional) */
+    id?: string;
+}
+/**
+ * SseTransport - Server-Sent Events transport for AG-UI events
+ *
+ * Manages SSE connections and streams AG-UI protocol events to connected clients.
+ * Supports multiple concurrent connections, heartbeat mechanism, and run-specific filtering.
+ *
+ * @example
+ * ```typescript
+ * const transport = new SseTransport();
+ *
+ * // Handle new connection
+ * app.get('/api/events', (req, res) => {
+ *   const clientId = req.query.clientId as string;
+ *   const runId = req.query.runId as string | undefined;
+ *   transport.handleConnection(clientId, res, runId);
+ * });
+ *
+ * // Send event to specific client
+ * transport.sendToClient('client-123', {
+ *   event: 'TOOL_CALL_START',
+ *   data: { type: 'TOOL_CALL_START', toolCallId: 'tool-1' }
+ * });
+ *
+ * // Broadcast to all clients watching a specific run
+ * transport.broadcastToRun('run-123', {
+ *   event: 'RUN_FINISHED',
+ *   data: { type: 'RUN_FINISHED', runId: 'run-123' }
+ * });
+ * ```
+ */
+export declare class SseTransport {
+    private clients;
+    private heartbeatInterval;
+    private readonly HEARTBEAT_INTERVAL_MS;
+    /**
+     * Create a new SSE transport instance
+     */
+    constructor();
+    /**
+     * Handle a new SSE connection from a client
+     *
+     * Sets up proper SSE headers, registers the client, and handles cleanup on disconnect.
+     *
+     * @param clientId - Unique identifier for this client
+     * @param res - Express response object
+     * @param runId - Optional run ID to filter events
+     * @param replayEvents - Optional: buffered events to replay to this client
+     */
+    handleConnection(clientId: string, res: Response, runId?: string, replayEvents?: Array<{
+        event: string;
+        data: any;
+    }>): void;
+    /**
+     * Send an event to a specific client
+     *
+     * @param clientId - Target client ID
+     * @param event - Event to send
+     * @returns true if sent successfully, false if client not found
+     */
+    sendToClient(clientId: string, event: SseEvent): boolean;
+    /**
+     * Broadcast an event to all connected clients
+     *
+     * @param event - Event to broadcast
+     * @returns Number of clients that received the event
+     */
+    broadcast(event: SseEvent): number;
+    /**
+     * Broadcast an event to all clients watching a specific run
+     *
+     * @param runId - Target run ID
+     * @param event - Event to send
+     * @returns Number of clients that received the event
+     */
+    broadcastToRun(runId: string, event: SseEvent): number;
+    /**
+     * Remove a client connection
+     *
+     * @param clientId - Client to remove
+     * @returns true if client was removed, false if not found
+     */
+    removeClient(clientId: string): boolean;
+    /**
+     * Get the number of active connections
+     *
+     * @returns Number of connected clients
+     */
+    getClientCount(): number;
+    /**
+     * Get the number of clients watching a specific run
+     *
+     * @param runId - Run ID to check
+     * @returns Number of clients watching this run
+     */
+    getRunClientCount(runId: string): number;
+    /**
+     * Get all active client IDs
+     *
+     * @returns Array of client IDs
+     */
+    getClientIds(): string[];
+    /**
+     * Shutdown the transport and close all connections
+     */
+    shutdown(): void;
+    /**
+     * Write an event to a client connection
+     *
+     * Formats the event according to SSE specification and writes it to the response.
+     *
+     * @param client - Target client
+     * @param event - Event to write
+     * @returns true if successful, false if write failed
+     */
+    private writeEvent;
+    /**
+     * Start the heartbeat mechanism
+     *
+     * Sends periodic ping events to keep connections alive
+     */
+    private startHeartbeat;
+}
+export {};
+//# sourceMappingURL=sse-transport.d.ts.map

package/dist/execution/transport/sse-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-transport.d.ts","sourceRoot":"","sources":["../../../src/execution/transport/sse-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAoBxC;;;;GAIG;AACH,UAAU,QAAQ;IAChB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,IAAI,EAAE,GAAG,CAAC;IACV,0BAA0B;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAE/C;;OAEG;;IAKH;;;;;;;;;OASG;IACH,gBAAgB,CACd,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,QAAQ,EACb,KAAK,CAAC,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,GAAG,CAAA;KAAE,CAAC,GACjD,IAAI;IA8CP;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO;IASxD;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;IAYlC;;;;;;OAMG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM;IAgBtD;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAmBvC;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAUxC;;;;OAIG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAahB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAoDlB;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAavB"}