@machina.ai/cell-cli-core 1.0.13-rc9 → 1.0.21-rc1

package/dist/src/services/shellExecutionService.js

@@ -0,0 +1,175 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { spawn } from 'child_process';
+import { TextDecoder } from 'util';
+import os from 'os';
+import stripAnsi from 'strip-ansi';
+import { getCachedEncodingForBuffer } from '../utils/systemEncoding.js';
+import { isBinary } from '../utils/textUtils.js';
+const SIGKILL_TIMEOUT_MS = 200;
+/**
+ * A centralized service for executing shell commands with robust process
+ * management, cross-platform compatibility, and streaming output capabilities.
+ *
+ */
+export class ShellExecutionService {
+    /**
+     * Executes a shell command using `spawn`, capturing all output and lifecycle events.
+     *
+     * @param commandToExecute The exact command string to run.
+     * @param cwd The working directory to execute the command in.
+     * @param onOutputEvent A callback for streaming structured events about the execution, including data chunks and status updates.
+     * @param abortSignal An AbortSignal to terminate the process and its children.
+     * @returns An object containing the process ID (pid) and a promise that
+     *          resolves with the complete execution result.
+     */
+    static execute(commandToExecute, cwd, onOutputEvent, abortSignal) {
+        const isWindows = os.platform() === 'win32';
+        const child = spawn(commandToExecute, [], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Use bash unless in Windows (since it doesn't support bash).
+            // For windows, just use the default.
+            shell: isWindows ? true : 'bash',
+            // Use process groups on non-Windows for robust killing.
+            // Windows process termination is handled by `taskkill /t`.
+            detached: !isWindows,
+            env: {
+                ...process.env,
+                GEMINI_CLI: '1',
+            },
+        });
+        const result = new Promise((resolve) => {
+            // Use decoders to handle multi-byte characters safely (for streaming output).
+            let stdoutDecoder = null;
+            let stderrDecoder = null;
+            let stdout = '';
+            let stderr = '';
+            const outputChunks = [];
+            let error = null;
+            let exited = false;
+            let isStreamingRawContent = true;
+            const MAX_SNIFF_SIZE = 4096;
+            let sniffedBytes = 0;
+            const handleOutput = (data, stream) => {
+                if (!stdoutDecoder || !stderrDecoder) {
+                    const encoding = getCachedEncodingForBuffer(data);
+                    try {
+                        stdoutDecoder = new TextDecoder(encoding);
+                        stderrDecoder = new TextDecoder(encoding);
+                    }
+                    catch {
+                        // If the encoding is not supported, fall back to utf-8.
+                        // This can happen on some platforms for certain encodings like 'utf-32le'.
+                        stdoutDecoder = new TextDecoder('utf-8');
+                        stderrDecoder = new TextDecoder('utf-8');
+                    }
+                }
+                outputChunks.push(data);
+                // Binary detection logic. This only runs until we've made a determination.
+                if (isStreamingRawContent && sniffedBytes < MAX_SNIFF_SIZE) {
+                    const sniffBuffer = Buffer.concat(outputChunks.slice(0, 20));
+                    sniffedBytes = sniffBuffer.length;
+                    if (isBinary(sniffBuffer)) {
+                        // Change state to stop streaming raw content.
+                        isStreamingRawContent = false;
+                        onOutputEvent({ type: 'binary_detected' });
+                    }
+                }
+                const decodedChunk = stream === 'stdout'
+                    ? stdoutDecoder.decode(data, { stream: true })
+                    : stderrDecoder.decode(data, { stream: true });
+                const strippedChunk = stripAnsi(decodedChunk);
+                if (stream === 'stdout') {
+                    stdout += strippedChunk;
+                }
+                else {
+                    stderr += strippedChunk;
+                }
+                if (isStreamingRawContent) {
+                    onOutputEvent({ type: 'data', stream, chunk: strippedChunk });
+                }
+                else {
+                    const totalBytes = outputChunks.reduce((sum, chunk) => sum + chunk.length, 0);
+                    onOutputEvent({ type: 'binary_progress', bytesReceived: totalBytes });
+                }
+            };
+            child.stdout.on('data', (data) => handleOutput(data, 'stdout'));
+            child.stderr.on('data', (data) => handleOutput(data, 'stderr'));
+            child.on('error', (err) => {
+                const { stdout, stderr, finalBuffer } = cleanup();
+                error = err;
+                resolve({
+                    error,
+                    stdout,
+                    stderr,
+                    rawOutput: finalBuffer,
+                    output: stdout + (stderr ? `\n${stderr}` : ''),
+                    exitCode: 1,
+                    signal: null,
+                    aborted: false,
+                    pid: child.pid,
+                });
+            });
+            const abortHandler = async () => {
+                if (child.pid && !exited) {
+                    if (isWindows) {
+                        spawn('taskkill', ['/pid', child.pid.toString(), '/f', '/t']);
+                    }
+                    else {
+                        try {
+                            // Kill the entire process group (negative PID).
+                            // SIGTERM first, then SIGKILL if it doesn't die.
+                            process.kill(-child.pid, 'SIGTERM');
+                            await new Promise((res) => setTimeout(res, SIGKILL_TIMEOUT_MS));
+                            if (!exited) {
+                                process.kill(-child.pid, 'SIGKILL');
+                            }
+                        }
+                        catch (_e) {
+                            // Fall back to killing just the main process if group kill fails.
+                            if (!exited)
+                                child.kill('SIGKILL');
+                        }
+                    }
+                }
+            };
+            abortSignal.addEventListener('abort', abortHandler, { once: true });
+            child.on('exit', (code, signal) => {
+                const { stdout, stderr, finalBuffer } = cleanup();
+                resolve({
+                    rawOutput: finalBuffer,
+                    output: stdout + (stderr ? `\n${stderr}` : ''),
+                    stdout,
+                    stderr,
+                    exitCode: code,
+                    signal,
+                    error,
+                    aborted: abortSignal.aborted,
+                    pid: child.pid,
+                });
+            });
+            /**
+             * Cleans up a process (and it's accompanying state) that is exiting or
+             * erroring and returns output formatted output buffers and strings
+             */
+            function cleanup() {
+                exited = true;
+                abortSignal.removeEventListener('abort', abortHandler);
+                if (stdoutDecoder) {
+                    stdout += stripAnsi(stdoutDecoder.decode());
+                }
+                if (stderrDecoder) {
+                    stderr += stripAnsi(stderrDecoder.decode());
+                }
+                const finalBuffer = Buffer.concat(outputChunks);
+                return { stdout, stderr, finalBuffer };
+            }
+        });
+        return { pid: child.pid, result };
+    }
+}
+//# sourceMappingURL=shellExecutionService.js.map

package/dist/src/services/shellExecutionService.js.map

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

package/dist/src/services/shellExecutionService.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/services/shellExecutionService.test.js

@@ -0,0 +1,282 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+const mockSpawn = vi.hoisted(() => vi.fn());
+vi.mock('child_process', () => ({
+    spawn: mockSpawn,
+}));
+const mockGetShellConfiguration = vi.hoisted(() => vi.fn());
+let mockIsWindows = false;
+vi.mock('../utils/shell-utils.js', () => ({
+    getShellConfiguration: mockGetShellConfiguration,
+    get isWindows() {
+        return mockIsWindows;
+    },
+}));
+import EventEmitter from 'events';
+import { ShellExecutionService, } from './shellExecutionService.js';
+const mockIsBinary = vi.hoisted(() => vi.fn());
+vi.mock('../utils/textUtils.js', () => ({
+    isBinary: mockIsBinary,
+}));
+const mockPlatform = vi.hoisted(() => vi.fn());
+vi.mock('os', () => ({
+    default: {
+        platform: mockPlatform,
+    },
+    platform: mockPlatform,
+}));
+const mockProcessKill = vi
+    .spyOn(process, 'kill')
+    .mockImplementation(() => true);
+describe('ShellExecutionService', () => {
+    let mockChildProcess;
+    let onOutputEventMock;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockIsBinary.mockReturnValue(false);
+        mockGetShellConfiguration.mockReturnValue({
+            executable: 'bash',
+            argsPrefix: ['-c'],
+        });
+        mockIsWindows = false;
+        onOutputEventMock = vi.fn();
+        mockChildProcess = new EventEmitter();
+        mockChildProcess.stdout = new EventEmitter();
+        mockChildProcess.stderr = new EventEmitter();
+        mockChildProcess.kill = vi.fn();
+        Object.defineProperty(mockChildProcess, 'pid', {
+            value: 12345,
+            configurable: true,
+        });
+        mockSpawn.mockReturnValue(mockChildProcess);
+    });
+    // Helper function to run a standard execution simulation
+    const simulateExecution = async (command, simulation) => {
+        const abortController = new AbortController();
+        const handle = ShellExecutionService.execute(command, '/test/dir', onOutputEventMock, abortController.signal);
+        await new Promise((resolve) => setImmediate(resolve));
+        simulation(mockChildProcess, abortController);
+        const result = await handle.result;
+        return { result, handle, abortController };
+    };
+    describe('Successful Execution', () => {
+        it('should execute a command and capture stdout and stderr', async () => {
+            const { result, handle } = await simulateExecution('ls -l', (cp) => {
+                cp.stdout?.emit('data', Buffer.from('file1.txt\n'));
+                cp.stderr?.emit('data', Buffer.from('a warning'));
+                cp.emit('exit', 0, null);
+            });
+            expect(mockSpawn).toHaveBeenCalledWith('ls -l', [], expect.objectContaining({ shell: 'bash' }));
+            expect(result.exitCode).toBe(0);
+            expect(result.signal).toBeNull();
+            expect(result.error).toBeNull();
+            expect(result.aborted).toBe(false);
+            expect(result.stdout).toBe('file1.txt\n');
+            expect(result.stderr).toBe('a warning');
+            expect(result.output).toBe('file1.txt\n\na warning');
+            expect(handle.pid).toBe(12345);
+            expect(onOutputEventMock).toHaveBeenCalledWith({
+                type: 'data',
+                stream: 'stdout',
+                chunk: 'file1.txt\n',
+            });
+            expect(onOutputEventMock).toHaveBeenCalledWith({
+                type: 'data',
+                stream: 'stderr',
+                chunk: 'a warning',
+            });
+        });
+        it('should strip ANSI codes from output', async () => {
+            const { result } = await simulateExecution('ls --color=auto', (cp) => {
+                cp.stdout?.emit('data', Buffer.from('a\u001b[31mred\u001b[0mword'));
+                cp.emit('exit', 0, null);
+            });
+            expect(result.stdout).toBe('aredword');
+            expect(onOutputEventMock).toHaveBeenCalledWith({
+                type: 'data',
+                stream: 'stdout',
+                chunk: 'aredword',
+            });
+        });
+        it('should correctly decode multi-byte characters split across chunks', async () => {
+            const { result } = await simulateExecution('echo "你好"', (cp) => {
+                const multiByteChar = Buffer.from('你好', 'utf-8');
+                cp.stdout?.emit('data', multiByteChar.slice(0, 2));
+                cp.stdout?.emit('data', multiByteChar.slice(2));
+                cp.emit('exit', 0, null);
+            });
+            expect(result.stdout).toBe('你好');
+        });
+        it('should handle commands with no output', async () => {
+            const { result } = await simulateExecution('touch file', (cp) => {
+                cp.emit('exit', 0, null);
+            });
+            expect(result.stdout).toBe('');
+            expect(result.stderr).toBe('');
+            expect(result.output).toBe('');
+            expect(onOutputEventMock).not.toHaveBeenCalled();
+        });
+    });
+    describe('Failed Execution', () => {
+        it('should capture a non-zero exit code and format output correctly', async () => {
+            const { result } = await simulateExecution('a-bad-command', (cp) => {
+                cp.stderr?.emit('data', Buffer.from('command not found'));
+                cp.emit('exit', 127, null);
+            });
+            expect(result.exitCode).toBe(127);
+            expect(result.stderr).toBe('command not found');
+            expect(result.stdout).toBe('');
+            expect(result.output).toBe('\ncommand not found');
+            expect(result.error).toBeNull();
+        });
+        it('should capture a termination signal', async () => {
+            const { result } = await simulateExecution('long-process', (cp) => {
+                cp.emit('exit', null, 'SIGTERM');
+            });
+            expect(result.exitCode).toBeNull();
+            expect(result.signal).toBe('SIGTERM');
+        });
+        it('should handle a spawn error', async () => {
+            const spawnError = new Error('spawn EACCES');
+            const { result } = await simulateExecution('protected-cmd', (cp) => {
+                cp.emit('error', spawnError);
+                cp.emit('exit', 1, null);
+            });
+            expect(result.error).toBe(spawnError);
+            expect(result.exitCode).toBe(1);
+        });
+        it('handles errors that do not fire the exit event', async () => {
+            const error = new Error('spawn abc ENOENT');
+            const { result } = await simulateExecution('touch cat.jpg', (cp) => {
+                cp.emit('error', error); // No exit event is fired.
+            });
+            expect(result.error).toBe(error);
+            expect(result.exitCode).toBe(1);
+        });
+    });
+    describe('Aborting Commands', () => {
+        describe.each([
+            {
+                platform: 'linux',
+                expectedSignal: 'SIGTERM',
+                expectedExit: { signal: 'SIGKILL' },
+            },
+            {
+                platform: 'win32',
+                expectedCommand: 'taskkill',
+                expectedExit: { code: 1 },
+            },
+        ])('on $platform', ({ platform, expectedSignal, expectedCommand, expectedExit }) => {
+            it('should abort a running process and set the aborted flag', async () => {
+                mockPlatform.mockReturnValue(platform);
+                const { result } = await simulateExecution('sleep 10', (cp, abortController) => {
+                    abortController.abort();
+                    if (expectedExit.signal)
+                        cp.emit('exit', null, expectedExit.signal);
+                    if (typeof expectedExit.code === 'number')
+                        cp.emit('exit', expectedExit.code, null);
+                });
+                expect(result.aborted).toBe(true);
+                if (platform === 'linux') {
+                    expect(mockProcessKill).toHaveBeenCalledWith(-mockChildProcess.pid, expectedSignal);
+                }
+                else {
+                    expect(mockSpawn).toHaveBeenCalledWith(expectedCommand, [
+                        '/pid',
+                        String(mockChildProcess.pid),
+                        '/f',
+                        '/t',
+                    ]);
+                }
+            });
+        });
+        it('should gracefully attempt SIGKILL on linux if SIGTERM fails', async () => {
+            mockPlatform.mockReturnValue('linux');
+            vi.useFakeTimers();
+            // Don't await the result inside the simulation block for this specific test.
+            // We need to control the timeline manually.
+            const abortController = new AbortController();
+            const handle = ShellExecutionService.execute('unresponsive_process', '/test/dir', onOutputEventMock, abortController.signal);
+            abortController.abort();
+            // Check the first kill signal
+            expect(mockProcessKill).toHaveBeenCalledWith(-mockChildProcess.pid, 'SIGTERM');
+            // Now, advance time past the timeout
+            await vi.advanceTimersByTimeAsync(250);
+            // Check the second kill signal
+            expect(mockProcessKill).toHaveBeenCalledWith(-mockChildProcess.pid, 'SIGKILL');
+            // Finally, simulate the process exiting and await the result
+            mockChildProcess.emit('exit', null, 'SIGKILL');
+            const result = await handle.result;
+            vi.useRealTimers();
+            expect(result.aborted).toBe(true);
+            expect(result.signal).toBe('SIGKILL');
+            // The individual kill calls were already asserted above.
+            expect(mockProcessKill).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('Binary Output', () => {
+        it('should detect binary output and switch to progress events', async () => {
+            mockIsBinary.mockReturnValueOnce(true);
+            const binaryChunk1 = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+            const binaryChunk2 = Buffer.from([0x0d, 0x0a, 0x1a, 0x0a]);
+            const { result } = await simulateExecution('cat image.png', (cp) => {
+                cp.stdout?.emit('data', binaryChunk1);
+                cp.stdout?.emit('data', binaryChunk2);
+                cp.emit('exit', 0, null);
+            });
+            expect(result.rawOutput).toEqual(Buffer.concat([binaryChunk1, binaryChunk2]));
+            expect(onOutputEventMock).toHaveBeenCalledTimes(3);
+            expect(onOutputEventMock.mock.calls[0][0]).toEqual({
+                type: 'binary_detected',
+            });
+            expect(onOutputEventMock.mock.calls[1][0]).toEqual({
+                type: 'binary_progress',
+                bytesReceived: 4,
+            });
+            expect(onOutputEventMock.mock.calls[2][0]).toEqual({
+                type: 'binary_progress',
+                bytesReceived: 8,
+            });
+        });
+        it('should not emit data events after binary is detected', async () => {
+            mockIsBinary.mockImplementation((buffer) => buffer.includes(0x00));
+            await simulateExecution('cat mixed_file', (cp) => {
+                cp.stdout?.emit('data', Buffer.from('some text'));
+                cp.stdout?.emit('data', Buffer.from([0x00, 0x01, 0x02]));
+                cp.stdout?.emit('data', Buffer.from('more text'));
+                cp.emit('exit', 0, null);
+            });
+            // FIX: Provide explicit type for the 'call' parameter in the map function.
+            const eventTypes = onOutputEventMock.mock.calls.map((call) => call[0].type);
+            expect(eventTypes).toEqual([
+                'data',
+                'binary_detected',
+                'binary_progress',
+                'binary_progress',
+            ]);
+        });
+    });
+    describe('Platform-Specific Behavior', () => {
+        it('should use cmd.exe on Windows', async () => {
+            mockPlatform.mockReturnValue('win32');
+            await simulateExecution('dir "foo bar"', (cp) => cp.emit('exit', 0, null));
+            expect(mockSpawn).toHaveBeenCalledWith('dir "foo bar"', [], expect.objectContaining({
+                shell: true,
+                detached: false,
+            }));
+        });
+        it('should use bash and detached process group on Linux', async () => {
+            mockPlatform.mockReturnValue('linux');
+            await simulateExecution('ls "foo bar"', (cp) => cp.emit('exit', 0, null));
+            expect(mockSpawn).toHaveBeenCalledWith('ls "foo bar"', [], expect.objectContaining({
+                shell: 'bash',
+                detached: true,
+            }));
+        });
+    });
+});
+//# sourceMappingURL=shellExecutionService.test.js.map

package/dist/src/services/shellExecutionService.test.js.map

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

package/dist/src/telemetry/clearcut-logger/clearcut-logger.d.ts

@@ -3,35 +3,107 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Buffer } from 'buffer';
 import { HttpsProxyAgent } from 'https-proxy-agent';
-import { StartSessionEvent, EndSessionEvent, UserPromptEvent, ToolCallEvent, ApiRequestEvent, ApiResponseEvent, ApiErrorEvent, FlashFallbackEvent, LoopDetectedEvent } from '../types.js';
+import { StartSessionEvent, UserPromptEvent, ToolCallEvent, ApiRequestEvent, ApiResponseEvent, ApiErrorEvent, LoopDetectedEvent, NextSpeakerCheckEvent, SlashCommandEvent, MalformedJsonResponseEvent, IdeConnectionEvent, KittySequenceOverflowEvent, ChatCompressionEvent } from '../types.js';
+import { EventMetadataKey } from './event-metadata-key.js';
 import { Config } from '../../config/config.js';
+export declare enum EventNames {
+    START_SESSION = "start_session",
+    NEW_PROMPT = "new_prompt",
+    TOOL_CALL = "tool_call",
+    API_REQUEST = "api_request",
+    API_RESPONSE = "api_response",
+    API_ERROR = "api_error",
+    END_SESSION = "end_session",
+    FLASH_FALLBACK = "flash_fallback",
+    LOOP_DETECTED = "loop_detected",
+    NEXT_SPEAKER_CHECK = "next_speaker_check",
+    SLASH_COMMAND = "slash_command",
+    MALFORMED_JSON_RESPONSE = "malformed_json_response",
+    IDE_CONNECTION = "ide_connection",
+    KITTY_SEQUENCE_OVERFLOW = "kitty_sequence_overflow",
+    CHAT_COMPRESSION = "chat_compression"
+}
 export interface LogResponse {
     nextRequestWaitMs?: number;
 }
+export interface LogEventEntry {
+    event_time_ms: number;
+    source_extension_json: string;
+}
+export interface EventValue {
+    gemini_cli_key: EventMetadataKey;
+    value: string;
+}
+export interface LogEvent {
+    console_type: 'GEMINI_CLI';
+    application: number;
+    event_name: string;
+    event_metadata: EventValue[][];
+    client_email?: string;
+    client_install_id?: string;
+}
+export interface LogRequest {
+    log_source_name: 'CONCORD';
+    request_time_ms: number;
+    log_event: LogEventEntry[][];
+}
 export declare class ClearcutLogger {
     private static instance;
     private config?;
+    private sessionData;
+    private promptId;
+    /**
+     * Queue of pending events that need to be flushed to the server.  New events
+     * are added to this queue and then flushed on demand (via `flushToClearcut`)
+     */
     private readonly events;
-    private last_flush_time;
-    private flush_interval_ms;
+    /**
+     * The last time that the events were successfully flushed to the server.
+     */
+    private lastFlushTime;
+    /**
+     * the value is true when there is a pending flush happening. This prevents
+     * concurrent flush operations.
+     */
+    private flushing;
+    /**
+     * This value is true when a flush was requested during an ongoing flush.
+     */
+    private pendingFlush;
     private constructor();
     static getInstance(config?: Config): ClearcutLogger | undefined;
-    enqueueLogEvent(event: any): void;
-    createLogEvent(name: string, data: object[]): object;
+    /** For testing purposes only. */
+    static clearInstance(): void;
+    enqueueLogEvent(event: LogEvent): void;
+    createLogEvent(eventName: EventNames, data?: EventValue[]): LogEvent;
     flushIfNeeded(): void;
     flushToClearcut(): Promise<LogResponse>;
-    decodeLogResponse(buf: Buffer): LogResponse | undefined;
     logStartSessionEvent(event: StartSessionEvent): void;
     logNewPromptEvent(event: UserPromptEvent): void;
     logToolCallEvent(event: ToolCallEvent): void;
     logApiRequestEvent(event: ApiRequestEvent): void;
     logApiResponseEvent(event: ApiResponseEvent): void;
     logApiErrorEvent(event: ApiErrorEvent): void;
-    logFlashFallbackEvent(event: FlashFallbackEvent): void;
+    logChatCompressionEvent(event: ChatCompressionEvent): void;
+    logFlashFallbackEvent(): void;
     logLoopDetectedEvent(event: LoopDetectedEvent): void;
-    logEndSessionEvent(event: EndSessionEvent): void;
+    logNextSpeakerCheck(event: NextSpeakerCheckEvent): void;
+    logSlashCommandEvent(event: SlashCommandEvent): void;
+    logMalformedJsonResponseEvent(event: MalformedJsonResponseEvent): void;
+    logIdeConnectionEvent(event: IdeConnectionEvent): void;
+    logKittySequenceOverflowEvent(event: KittySequenceOverflowEvent): void;
+    logEndSessionEvent(): void;
+    /**
+     * Adds default fields to data, and returns a new data array.  This fields
+     * should exist on all log events.
+     */
+    addDefaultFields(data: EventValue[]): EventValue[];
     getProxyAgent(): HttpsProxyAgent<string> | undefined;
     shutdown(): void;
+    private requeueFailedEvents;
 }
+export declare const TEST_ONLY: {
+    MAX_RETRY_EVENTS: number;
+    MAX_EVENTS: number;
+};