@vybestack/llxprt-code-core 0.1.14 → 0.1.15

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

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** A structured result from a shell command execution. */
+export interface ShellExecutionResult {
+    /** The raw, unprocessed output buffer. */
+    rawOutput: Buffer;
+    /** The combined, decoded stdout and stderr as a string. */
+    output: string;
+    /** The decoded stdout as a string. */
+    stdout: string;
+    /** The decoded stderr as a string. */
+    stderr: string;
+    /** The process exit code, or null if terminated by a signal. */
+    exitCode: number | null;
+    /** The signal that terminated the process, if any. */
+    signal: NodeJS.Signals | null;
+    /** An error object if the process failed to spawn. */
+    error: Error | null;
+    /** A boolean indicating if the command was aborted by the user. */
+    aborted: boolean;
+    /** The process ID of the spawned shell. */
+    pid: number | undefined;
+}
+/** A handle for an ongoing shell execution. */
+export interface ShellExecutionHandle {
+    /** The process ID of the spawned shell. */
+    pid: number | undefined;
+    /** A promise that resolves with the complete execution result. */
+    result: Promise<ShellExecutionResult>;
+}
+/**
+ * Describes a structured event emitted during shell command execution.
+ */
+export type ShellOutputEvent = {
+    /** The event contains a chunk of output data. */
+    type: 'data';
+    /** The stream from which the data originated. */
+    stream: 'stdout' | 'stderr';
+    /** The decoded string chunk. */
+    chunk: string;
+} | {
+    /** Signals that the output stream has been identified as binary. */
+    type: 'binary_detected';
+} | {
+    /** Provides progress updates for a binary stream. */
+    type: 'binary_progress';
+    /** The total number of bytes received so far. */
+    bytesReceived: number;
+};
+/**
+ * A centralized service for executing shell commands with robust process
+ * management, cross-platform compatibility, and streaming output capabilities.
+ *
+ */
+export declare 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: string, cwd: string, onOutputEvent: (event: ShellOutputEvent) => void, abortSignal: AbortSignal): ShellExecutionHandle;
+}

package/dist/src/services/shellExecutionService.js

@@ -0,0 +1,152 @@
+/**
+ * @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 shell = isWindows ? 'cmd.exe' : 'bash';
+        const shellArgs = [isWindows ? '/c' : '-c', commandToExecute];
+        const child = spawn(shell, shellArgs, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: !isWindows, // Use process groups on non-Windows for robust killing
+            env: {
+                ...process.env,
+                LLXPRT_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) => {
+                error = err;
+            });
+            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) => {
+                exited = true;
+                abortSignal.removeEventListener('abort', abortHandler);
+                if (stdoutDecoder) {
+                    stdout += stripAnsi(stdoutDecoder.decode());
+                }
+                if (stderrDecoder) {
+                    stderr += stripAnsi(stderrDecoder.decode());
+                }
+                const finalBuffer = Buffer.concat(outputChunks);
+                resolve({
+                    rawOutput: finalBuffer,
+                    output: stdout + (stderr ? `\n${stderr}` : ''),
+                    stdout,
+                    stderr,
+                    exitCode: code,
+                    signal,
+                    error,
+                    aborted: abortSignal.aborted,
+                    pid: child.pid,
+                });
+            });
+        });
+        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,258 @@
+/**
+ * @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,
+}));
+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);
+        mockPlatform.mockReturnValue('linux');
+        onOutputEventMock = vi.fn();
+        mockChildProcess = new EventEmitter();
+        // FIX: Cast simple EventEmitters to the expected stream type.
+        mockChildProcess.stdout = new EventEmitter();
+        mockChildProcess.stderr = new EventEmitter();
+        mockChildProcess.kill = vi.fn();
+        // FIX: Use Object.defineProperty to set the readonly 'pid' property.
+        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('bash', ['-c', 'ls -l'], expect.any(Object));
+            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);
+        });
+    });
+    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', (cp) => cp.emit('exit', 0, null));
+            expect(mockSpawn).toHaveBeenCalledWith('cmd.exe', ['/c', 'dir'], expect.objectContaining({ detached: false }));
+        });
+        it('should use bash and detached process group on Linux', async () => {
+            mockPlatform.mockReturnValue('linux');
+            await simulateExecution('ls', (cp) => cp.emit('exit', 0, null));
+            expect(mockSpawn).toHaveBeenCalledWith('bash', ['-c', 'ls'], expect.objectContaining({ 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":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAa,MAAM,QAAQ,CAAC;AACzE,MAAM,SAAS,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AAC5C,EAAE,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,CAAC;IAC9B,KAAK,EAAE,SAAS;CACjB,CAAC,CAAC,CAAC;AAEJ,OAAO,YAAY,MAAM,QAAQ,CAAC;AAGlC,OAAO,EACL,qBAAqB,GAEtB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,YAAY,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/C,EAAE,CAAC,IAAI,CAAC,uBAAuB,EAAE,GAAG,EAAE,CAAC,CAAC;IACtC,QAAQ,EAAE,YAAY;CACvB,CAAC,CAAC,CAAC;AAEJ,MAAM,YAAY,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/C,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IACnB,OAAO,EAAE;QACP,QAAQ,EAAE,YAAY;KACvB;IACD,QAAQ,EAAE,YAAY;CACvB,CAAC,CAAC,CAAC;AAEJ,MAAM,eAAe,GAAG,EAAE;KACvB,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC;KACtB,kBAAkB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;AAElC,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,IAAI,gBAAsD,CAAC;IAC3D,IAAI,iBAA0D,CAAC;IAE/D,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,aAAa,EAAE,CAAC;QAEnB,YAAY,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QACpC,YAAY,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAEtC,iBAAiB,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAE5B,gBAAgB,GAAG,IAAI,YAAY,EACZ,CAAC;QACxB,8DAA8D;QAC9D,gBAAgB,CAAC,MAAM,GAAG,IAAI,YAAY,EAAc,CAAC;QACzD,gBAAgB,CAAC,MAAM,GAAG,IAAI,YAAY,EAAc,CAAC;QACzD,gBAAgB,CAAC,IAAI,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAEhC,qEAAqE;QACrE,MAAM,CAAC,cAAc,CAAC,gBAAgB,EAAE,KAAK,EAAE;YAC7C,KAAK,EAAE,KAAK;YACZ,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QAEH,SAAS,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,yDAAyD;IACzD,MAAM,iBAAiB,GAAG,KAAK,EAC7B,OAAe,EACf,UAAsE,EACtE,EAAE;QACF,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,qBAAqB,CAAC,OAAO,CAC1C,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,eAAe,CAAC,MAAM,CACvB,CAAC;QAEF,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;QACtD,UAAU,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC;QACnC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC7C,CAAC,CAAC;IAEF,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;QACpC,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;YACtE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE;gBACjE,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;gBACpD,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;gBAClD,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;YAEH,MAAM,CAAC,SAAS,CAAC,CAAC,oBAAoB,CACpC,MAAM,EACN,CAAC,IAAI,EAAE,OAAO,CAAC,EACf,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CACnB,CAAC;YACF,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;YAChC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAC1C,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACxC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;YACrD,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAE/B,MAAM,CAAC,iBAAiB,CAAC,CAAC,oBAAoB,CAAC;gBAC7C,IAAI,EAAE,MAAM;gBACZ,MAAM,EAAE,QAAQ;gBAChB,KAAK,EAAE,aAAa;aACrB,CAAC,CAAC;YACH,MAAM,CAAC,iBAAiB,CAAC,CAAC,oBAAoB,CAAC;gBAC7C,IAAI,EAAE,MAAM;gBACZ,MAAM,EAAE,QAAQ;gBAChB,KAAK,EAAE,WAAW;aACnB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;YACnD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,iBAAiB,EAAE,CAAC,EAAE,EAAE,EAAE;gBACnE,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC,CAAC;gBACpE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;YAEH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACvC,MAAM,CAAC,iBAAiB,CAAC,CAAC,oBAAoB,CAAC;gBAC7C,IAAI,EAAE,MAAM;gBACZ,MAAM,EAAE,QAAQ;gBAChB,KAAK,EAAE,UAAU;aAClB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mEAAmE,EAAE,KAAK,IAAI,EAAE;YACjF,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE;gBAC7D,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBACjD,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;gBACnD,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBAChD,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uCAAuC,EAAE,KAAK,IAAI,EAAE;YACrD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,YAAY,EAAE,CAAC,EAAE,EAAE,EAAE;gBAC9D,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;YAEH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/B,MAAM,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;QACnD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAChC,EAAE,CAAC,iEAAiE,EAAE,KAAK,IAAI,EAAE;YAC/E,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,eAAe,EAAE,CAAC,EAAE,EAAE,EAAE;gBACjE,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;gBAC1D,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;YAC7B,CAAC,CAAC,CAAC;YAEH,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YAChD,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;YAClD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;QAClC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;YACnD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,cAAc,EAAE,CAAC,EAAE,EAAE,EAAE;gBAChE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;YAEH,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6BAA6B,EAAE,KAAK,IAAI,EAAE;YAC3C,MAAM,UAAU,GAAG,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;YAC7C,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,eAAe,EAAE,CAAC,EAAE,EAAE,EAAE;gBACjE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAC7B,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;YAEH,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACtC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;QACjC,QAAQ,CAAC,IAAI,CAAC;YACZ;gBACE,QAAQ,EAAE,OAAO;gBACjB,cAAc,EAAE,SAAS;gBACzB,YAAY,EAAE,EAAE,MAAM,EAAE,SAAkB,EAAE;aAC7C;YACD;gBACE,QAAQ,EAAE,OAAO;gBACjB,eAAe,EAAE,UAAU;gBAC3B,YAAY,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE;aAC1B;SACF,CAAC,CACA,cAAc,EACd,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,EAAE,EAAE;YAC9D,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;gBACvE,YAAY,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;gBAEvC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CACxC,UAAU,EACV,CAAC,EAAE,EAAE,eAAe,EAAE,EAAE;oBACtB,eAAe,CAAC,KAAK,EAAE,CAAC;oBACxB,IAAI,YAAY,CAAC,MAAM;wBACrB,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;oBAC7C,IAAI,OAAO,YAAY,CAAC,IAAI,KAAK,QAAQ;wBACvC,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC7C,CAAC,CACF,CAAC;gBAEF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAElC,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;oBACzB,MAAM,CAAC,eAAe,CAAC,CAAC,oBAAoB,CAC1C,CAAC,gBAAgB,CAAC,GAAI,EACtB,cAAc,CACf,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,SAAS,CAAC,CAAC,oBAAoB,CAAC,eAAe,EAAE;wBACtD,MAAM;wBACN,MAAM,CAAC,gBAAgB,CAAC,GAAG,CAAC;wBAC5B,IAAI;wBACJ,IAAI;qBACL,CAAC,CAAC;gBACL,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CACF,CAAC;QAEF,EAAE,CAAC,6DAA6D,EAAE,KAAK,IAAI,EAAE;YAC3E,YAAY,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;YACtC,EAAE,CAAC,aAAa,EAAE,CAAC;YAEnB,6EAA6E;YAC7E,4CAA4C;YAC5C,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;YAC9C,MAAM,MAAM,GAAG,qBAAqB,CAAC,OAAO,CAC1C,sBAAsB,EACtB,WAAW,EACX,iBAAiB,EACjB,eAAe,CAAC,MAAM,CACvB,CAAC;YAEF,eAAe,CAAC,KAAK,EAAE,CAAC;YAExB,8BAA8B;YAC9B,MAAM,CAAC,eAAe,CAAC,CAAC,oBAAoB,CAC1C,CAAC,gBAAgB,CAAC,GAAI,EACtB,SAAS,CACV,CAAC;YAEF,qCAAqC;YACrC,MAAM,EAAE,CAAC,wBAAwB,CAAC,GAAG,CAAC,CAAC;YAEvC,+BAA+B;YAC/B,MAAM,CAAC,eAAe,CAAC,CAAC,oBAAoB,CAC1C,CAAC,gBAAgB,CAAC,GAAI,EACtB,SAAS,CACV,CAAC;YAEF,6DAA6D;YAC7D,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;YAC/C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC;YAEnC,EAAE,CAAC,aAAa,EAAE,CAAC;YAEnB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACtC,yDAAyD;YACzD,MAAM,CAAC,eAAe,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;QAC7B,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;YACzE,YAAY,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;YACvC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YAC3D,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YAE3D,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,eAAe,EAAE,CAAC,EAAE,EAAE,EAAE;gBACjE,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;gBACtC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;gBACtC,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;YAEH,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAC9B,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAC5C,CAAC;YACF,MAAM,CAAC,iBAAiB,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;YACnD,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;gBACjD,IAAI,EAAE,iBAAiB;aACxB,CAAC,CAAC;YACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;gBACjD,IAAI,EAAE,iBAAiB;gBACvB,aAAa,EAAE,CAAC;aACjB,CAAC,CAAC;YACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;gBACjD,IAAI,EAAE,iBAAiB;gBACvB,aAAa,EAAE,CAAC;aACjB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,sDAAsD,EAAE,KAAK,IAAI,EAAE;YACpE,YAAY,CAAC,kBAAkB,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YAEnE,MAAM,iBAAiB,CAAC,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE;gBAC/C,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;gBAClD,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;gBACzD,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;gBAClD,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;YAEH,2EAA2E;YAC3E,MAAM,UAAU,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CACjD,CAAC,IAAwB,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAC3C,CAAC;YACF,MAAM,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC;gBACzB,MAAM;gBACN,iBAAiB;gBACjB,iBAAiB;gBACjB,iBAAiB;aAClB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;QAC1C,EAAE,CAAC,+BAA+B,EAAE,KAAK,IAAI,EAAE;YAC7C,YAAY,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;YACtC,MAAM,iBAAiB,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;YAEjE,MAAM,CAAC,SAAS,CAAC,CAAC,oBAAoB,CACpC,SAAS,EACT,CAAC,IAAI,EAAE,KAAK,CAAC,EACb,MAAM,CAAC,gBAAgB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAC7C,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,qDAAqD,EAAE,KAAK,IAAI,EAAE;YACnE,YAAY,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;YACtC,MAAM,iBAAiB,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;YAEhE,MAAM,CAAC,SAAS,CAAC,CAAC,oBAAoB,CACpC,MAAM,EACN,CAAC,IAAI,EAAE,IAAI,CAAC,EACZ,MAAM,CAAC,gBAAgB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC5C,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/src/services/todo-reminder-service.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Todo } from '../tools/todo-schemas.js';
+export interface TodoStateChange {
+    previousTodos: Todo[];
+    currentTodos: Todo[];
+    added: Todo[];
+    removed: Todo[];
+    statusChanged: Todo[];
+}
+export declare class TodoReminderService {
+    private static readonly EMPTY_TODO_REMINDER;
+    private static readonly TODO_CHANGED_PREFIX;
+    private static readonly TODO_CHANGED_SUFFIX;
+    /**
+     * Generate reminder for empty todo list
+     */
+    getReminderForEmptyTodos(isComplexTask?: boolean): string | null;
+    /**
+     * Generate reminder for todo state change
+     */
+    getReminderForStateChange(stateChange: TodoStateChange): string;
+    /**
+     * Calculate state changes between old and new todos
+     */
+    calculateStateChange(previousTodos: Todo[], currentTodos: Todo[]): TodoStateChange;
+    /**
+     * Check if a reminder should be generated based on changes
+     */
+    shouldGenerateReminder(stateChange: TodoStateChange): boolean;
+    /**
+     * Format message as system reminder
+     */
+    private formatSystemReminder;
+    /**
+     * Generate proactive todo suggestion for complex tasks
+     */
+    getComplexTaskSuggestion(detectedTasks: string[]): string;
+}

package/dist/src/services/todo-reminder-service.js

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class TodoReminderService {
+    static EMPTY_TODO_REMINDER = `This is a reminder that your todo list is currently empty. DO NOT mention this to the user explicitly because they are already aware. If you are working on tasks that would benefit from a todo list please use the TodoWrite tool to create one. If not, please feel free to ignore. Again do not mention this message to the user.`;
+    static TODO_CHANGED_PREFIX = `Your todo list has changed. DO NOT mention this explicitly to the user. Here are the latest contents of your todo list:\n\n`;
+    static TODO_CHANGED_SUFFIX = `. Continue on with the tasks at hand if applicable.`;
+    /**
+     * Generate reminder for empty todo list
+     */
+    getReminderForEmptyTodos(isComplexTask = false) {
+        if (!isComplexTask) {
+            return null;
+        }
+        return this.formatSystemReminder(TodoReminderService.EMPTY_TODO_REMINDER);
+    }
+    /**
+     * Generate reminder for todo state change
+     */
+    getReminderForStateChange(stateChange) {
+        const todoJson = JSON.stringify(stateChange.currentTodos.map((todo) => ({
+            content: todo.content,
+            status: todo.status,
+            priority: todo.priority,
+            id: todo.id,
+        })));
+        const message = TodoReminderService.TODO_CHANGED_PREFIX +
+            todoJson +
+            TodoReminderService.TODO_CHANGED_SUFFIX;
+        return this.formatSystemReminder(message);
+    }
+    /**
+     * Calculate state changes between old and new todos
+     */
+    calculateStateChange(previousTodos, currentTodos) {
+        const added = currentTodos.filter((newTodo) => !previousTodos.some((oldTodo) => oldTodo.id === newTodo.id));
+        const removed = previousTodos.filter((oldTodo) => !currentTodos.some((newTodo) => newTodo.id === oldTodo.id));
+        const statusChanged = currentTodos.filter((newTodo) => {
+            const oldTodo = previousTodos.find((t) => t.id === newTodo.id);
+            return oldTodo && oldTodo.status !== newTodo.status;
+        });
+        return {
+            previousTodos,
+            currentTodos,
+            added,
+            removed,
+            statusChanged,
+        };
+    }
+    /**
+     * Check if a reminder should be generated based on changes
+     */
+    shouldGenerateReminder(stateChange) {
+        return (stateChange.added.length > 0 ||
+            stateChange.removed.length > 0 ||
+            stateChange.statusChanged.length > 0);
+    }
+    /**
+     * Format message as system reminder
+     */
+    formatSystemReminder(message) {
+        return `<system-reminder>\n${message}\n</system-reminder>`;
+    }
+    /**
+     * Generate proactive todo suggestion for complex tasks
+     */
+    getComplexTaskSuggestion(detectedTasks) {
+        const taskList = detectedTasks
+            .map((task, i) => `${i + 1}. ${task}`)
+            .join('\n');
+        const message = `I notice you're asking about multiple tasks. Consider using the TodoWrite tool to track these items:\n${taskList}\n\nThis will help ensure all tasks are completed systematically.`;
+        return this.formatSystemReminder(message);
+    }
+}
+//# sourceMappingURL=todo-reminder-service.js.map

package/dist/src/services/todo-reminder-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-reminder-service.js","sourceRoot":"","sources":["../../../src/services/todo-reminder-service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,MAAM,OAAO,mBAAmB;IACtB,MAAM,CAAU,mBAAmB,GAAG,uUAAuU,CAAC;IAE9W,MAAM,CAAU,mBAAmB,GAAG,6HAA6H,CAAC;IAEpK,MAAM,CAAU,mBAAmB,GAAG,qDAAqD,CAAC;IAEpG;;OAEG;IACH,wBAAwB,CAAC,gBAAyB,KAAK;QACrD,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC,oBAAoB,CAAC,mBAAmB,CAAC,mBAAmB,CAAC,CAAC;IAC5E,CAAC;IAED;;OAEG;IACH,yBAAyB,CAAC,WAA4B;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAC7B,WAAW,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACtC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,EAAE,EAAE,IAAI,CAAC,EAAE;SACZ,CAAC,CAAC,CACJ,CAAC;QAEF,MAAM,OAAO,GACX,mBAAmB,CAAC,mBAAmB;YACvC,QAAQ;YACR,mBAAmB,CAAC,mBAAmB,CAAC;QAE1C,OAAO,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,oBAAoB,CAClB,aAAqB,EACrB,YAAoB;QAEpB,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAC/B,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,CAAC,CACzE,CAAC;QAEF,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAClC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,CAAC,CACxE,CAAC;QAEF,MAAM,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;YACpD,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,CAAC,CAAC;YAC/D,OAAO,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC;QACtD,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,aAAa;YACb,YAAY;YACZ,KAAK;YACL,OAAO;YACP,aAAa;SACd,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,sBAAsB,CAAC,WAA4B;QACjD,OAAO,CACL,WAAW,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;YAC5B,WAAW,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;YAC9B,WAAW,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CACrC,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,oBAAoB,CAAC,OAAe;QAC1C,OAAO,sBAAsB,OAAO,sBAAsB,CAAC;IAC7D,CAAC;IAED;;OAEG;IACH,wBAAwB,CAAC,aAAuB;QAC9C,MAAM,QAAQ,GAAG,aAAa;aAC3B,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;aACrC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,MAAM,OAAO,GAAG,yGAAyG,QAAQ,mEAAmE,CAAC;QAErM,OAAO,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC"}