@machina.ai/cell-cli-core 1.0.13-rc3

package/dist/src/utils/summarizer.js

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DEFAULT_GEMINI_FLASH_MODEL } from '../config/models.js';
+/**
+ * The default summarizer for tool results.
+ *
+ * @param result The result of the tool execution.
+ * @param geminiClient The Gemini client to use for summarization.
+ * @param abortSignal The abort signal to use for summarization.
+ * @returns The summary of the result.
+ */
+export const defaultSummarizer = (result, _geminiClient, _abortSignal) => Promise.resolve(JSON.stringify(result.llmContent));
+// TODO: Move both these functions to utils
+function partToString(part) {
+    if (!part) {
+        return '';
+    }
+    if (typeof part === 'string') {
+        return part;
+    }
+    if (Array.isArray(part)) {
+        return part.map(partToString).join('');
+    }
+    if ('text' in part) {
+        return part.text ?? '';
+    }
+    return '';
+}
+function getResponseText(response) {
+    if (response.candidates && response.candidates.length > 0) {
+        const candidate = response.candidates[0];
+        if (candidate.content &&
+            candidate.content.parts &&
+            candidate.content.parts.length > 0) {
+            return candidate.content.parts
+                .filter((part) => part.text)
+                .map((part) => part.text)
+                .join('');
+        }
+    }
+    return null;
+}
+const SUMMARIZE_TOOL_OUTPUT_PROMPT = `Summarize the following tool output to be a maximum of {maxOutputTokens} tokens. The summary should be concise and capture the main points of the tool output.
+
+The summarization should be done based on the content that is provided. Here are the basic rules to follow:
+1. If the text is a directory listing or any output that is structural, use the history of the conversation to understand the context. Using this context try to understand what information we need from the tool output and return that as a response.
+2. If the text is text content and there is nothing structural that we need, summarize the text.
+3. If the text is the output of a shell command, use the history of the conversation to understand the context. Using this context try to understand what information we need from the tool output and return a summarization along with the stack trace of any error within the <error></error> tags. The stack trace should be complete and not truncated. If there are warnings, you should include them in the summary within <warning></warning> tags.
+
+
+Text to summarize:
+"{textToSummarize}"
+
+Return the summary string which should first contain an overall summarization of text followed by the full stack trace of errors and warnings in the tool output.
+`;
+export const llmSummarizer = (result, geminiClient, abortSignal) => summarizeToolOutput(partToString(result.llmContent), geminiClient, abortSignal);
+export async function summarizeToolOutput(textToSummarize, geminiClient, abortSignal, maxOutputTokens = 2000) {
+    // There is going to be a slight difference here since we are comparing length of string with maxOutputTokens.
+    // This is meant to be a ballpark estimation of if we need to summarize the tool output.
+    if (!textToSummarize || textToSummarize.length < maxOutputTokens) {
+        return textToSummarize;
+    }
+    const prompt = SUMMARIZE_TOOL_OUTPUT_PROMPT.replace('{maxOutputTokens}', String(maxOutputTokens)).replace('{textToSummarize}', textToSummarize);
+    const contents = [{ role: 'user', parts: [{ text: prompt }] }];
+    const toolOutputSummarizerConfig = {
+        maxOutputTokens,
+    };
+    try {
+        const parsedResponse = (await geminiClient.generateContent(contents, toolOutputSummarizerConfig, abortSignal, DEFAULT_GEMINI_FLASH_MODEL));
+        return getResponseText(parsedResponse) || textToSummarize;
+    }
+    catch (error) {
+        console.error('Failed to summarize tool output.', error);
+        return textToSummarize;
+    }
+}
+//# sourceMappingURL=summarizer.js.map

package/dist/src/utils/summarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.js","sourceRoot":"","sources":["../../../src/utils/summarizer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAejE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAe,CAC3C,MAAkB,EAClB,aAA2B,EAC3B,YAAyB,EACzB,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;AAExD,2CAA2C;AAC3C,SAAS,YAAY,CAAC,IAAmB;IACvC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,eAAe,CAAC,QAAiC;IACxD,IAAI,QAAQ,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACzC,IACE,SAAS,CAAC,OAAO;YACjB,SAAS,CAAC,OAAO,CAAC,KAAK;YACvB,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAClC,CAAC;YACD,OAAO,SAAS,CAAC,OAAO,CAAC,KAAK;iBAC3B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;iBAC3B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;iBACxB,IAAI,CAAC,EAAE,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,4BAA4B,GAAG;;;;;;;;;;;;CAYpC,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAe,CAAC,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,EAAE,CAC7E,mBAAmB,CACjB,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,EAC/B,YAAY,EACZ,WAAW,CACZ,CAAC;AAEJ,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,eAAuB,EACvB,YAA0B,EAC1B,WAAwB,EACxB,kBAA0B,IAAI;IAE9B,8GAA8G;IAC9G,wFAAwF;IACxF,IAAI,CAAC,eAAe,IAAI,eAAe,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACjE,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,MAAM,MAAM,GAAG,4BAA4B,CAAC,OAAO,CACjD,mBAAmB,EACnB,MAAM,CAAC,eAAe,CAAC,CACxB,CAAC,OAAO,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;IAEhD,MAAM,QAAQ,GAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1E,MAAM,0BAA0B,GAA0B;QACxD,eAAe;KAChB,CAAC;IACF,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,CAAC,MAAM,YAAY,CAAC,eAAe,CACxD,QAAQ,EACR,0BAA0B,EAC1B,WAAW,EACX,0BAA0B,CAC3B,CAAuC,CAAC;QACzC,OAAO,eAAe,CAAC,cAAc,CAAC,IAAI,eAAe,CAAC;IAC5D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,KAAK,CAAC,CAAC;QACzD,OAAO,eAAe,CAAC;IACzB,CAAC;AACH,CAAC"}

package/dist/src/utils/summarizer.test.d.ts

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

package/dist/src/utils/summarizer.test.js

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { GeminiClient } from '../core/client.js';
+import { Config } from '../config/config.js';
+import { summarizeToolOutput, llmSummarizer, defaultSummarizer, } from './summarizer.js';
+// Mock GeminiClient and Config constructor
+vi.mock('../core/client.js');
+vi.mock('../config/config.js');
+describe('summarizers', () => {
+    let mockGeminiClient;
+    let MockConfig;
+    const abortSignal = new AbortController().signal;
+    beforeEach(() => {
+        MockConfig = vi.mocked(Config);
+        const mockConfigInstance = new MockConfig('test-api-key', 'gemini-pro', false, '.', false, undefined, false, undefined, undefined, undefined);
+        mockGeminiClient = new GeminiClient(mockConfigInstance);
+        mockGeminiClient.generateContent = vi.fn();
+        vi.spyOn(console, 'error').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+        console.error.mockRestore();
+    });
+    describe('summarizeToolOutput', () => {
+        it('should return original text if it is shorter than maxLength', async () => {
+            const shortText = 'This is a short text.';
+            const result = await summarizeToolOutput(shortText, mockGeminiClient, abortSignal, 2000);
+            expect(result).toBe(shortText);
+            expect(mockGeminiClient.generateContent).not.toHaveBeenCalled();
+        });
+        it('should return original text if it is empty', async () => {
+            const emptyText = '';
+            const result = await summarizeToolOutput(emptyText, mockGeminiClient, abortSignal, 2000);
+            expect(result).toBe(emptyText);
+            expect(mockGeminiClient.generateContent).not.toHaveBeenCalled();
+        });
+        it('should call generateContent if text is longer than maxLength', async () => {
+            const longText = 'This is a very long text.'.repeat(200);
+            const summary = 'This is a summary.';
+            mockGeminiClient.generateContent.mockResolvedValue({
+                candidates: [{ content: { parts: [{ text: summary }] } }],
+            });
+            const result = await summarizeToolOutput(longText, mockGeminiClient, abortSignal, 2000);
+            expect(mockGeminiClient.generateContent).toHaveBeenCalledTimes(1);
+            expect(result).toBe(summary);
+        });
+        it('should return original text if generateContent throws an error', async () => {
+            const longText = 'This is a very long text.'.repeat(200);
+            const error = new Error('API Error');
+            mockGeminiClient.generateContent.mockRejectedValue(error);
+            const result = await summarizeToolOutput(longText, mockGeminiClient, abortSignal, 2000);
+            expect(mockGeminiClient.generateContent).toHaveBeenCalledTimes(1);
+            expect(result).toBe(longText);
+            expect(console.error).toHaveBeenCalledWith('Failed to summarize tool output.', error);
+        });
+        it('should construct the correct prompt for summarization', async () => {
+            const longText = 'This is a very long text.'.repeat(200);
+            const summary = 'This is a summary.';
+            mockGeminiClient.generateContent.mockResolvedValue({
+                candidates: [{ content: { parts: [{ text: summary }] } }],
+            });
+            await summarizeToolOutput(longText, mockGeminiClient, abortSignal, 1000);
+            const expectedPrompt = `Summarize the following tool output to be a maximum of 1000 tokens. The summary should be concise and capture the main points of the tool output.
+
+The summarization should be done based on the content that is provided. Here are the basic rules to follow:
+1. If the text is a directory listing or any output that is structural, use the history of the conversation to understand the context. Using this context try to understand what information we need from the tool output and return that as a response.
+2. If the text is text content and there is nothing structural that we need, summarize the text.
+3. If the text is the output of a shell command, use the history of the conversation to understand the context. Using this context try to understand what information we need from the tool output and return a summarization along with the stack trace of any error within the <error></error> tags. The stack trace should be complete and not truncated. If there are warnings, you should include them in the summary within <warning></warning> tags.
+
+
+Text to summarize:
+"${longText}"
+
+Return the summary string which should first contain an overall summarization of text followed by the full stack trace of errors and warnings in the tool output.
+`;
+            const calledWith = mockGeminiClient.generateContent.mock
+                .calls[0];
+            const contents = calledWith[0];
+            expect(contents[0].parts[0].text).toBe(expectedPrompt);
+        });
+    });
+    describe('llmSummarizer', () => {
+        it('should summarize tool output using summarizeToolOutput', async () => {
+            const toolResult = {
+                llmContent: 'This is a very long text.'.repeat(200),
+                returnDisplay: '',
+            };
+            const summary = 'This is a summary.';
+            mockGeminiClient.generateContent.mockResolvedValue({
+                candidates: [{ content: { parts: [{ text: summary }] } }],
+            });
+            const result = await llmSummarizer(toolResult, mockGeminiClient, abortSignal);
+            expect(mockGeminiClient.generateContent).toHaveBeenCalledTimes(1);
+            expect(result).toBe(summary);
+        });
+        it('should handle different llmContent types', async () => {
+            const longText = 'This is a very long text.'.repeat(200);
+            const toolResult = {
+                llmContent: [{ text: longText }],
+                returnDisplay: '',
+            };
+            const summary = 'This is a summary.';
+            mockGeminiClient.generateContent.mockResolvedValue({
+                candidates: [{ content: { parts: [{ text: summary }] } }],
+            });
+            const result = await llmSummarizer(toolResult, mockGeminiClient, abortSignal);
+            expect(mockGeminiClient.generateContent).toHaveBeenCalledTimes(1);
+            const calledWith = mockGeminiClient.generateContent.mock
+                .calls[0];
+            const contents = calledWith[0];
+            expect(contents[0].parts[0].text).toContain(`"${longText}"`);
+            expect(result).toBe(summary);
+        });
+    });
+    describe('defaultSummarizer', () => {
+        it('should stringify the llmContent', async () => {
+            const toolResult = {
+                llmContent: { text: 'some data' },
+                returnDisplay: '',
+            };
+            const result = await defaultSummarizer(toolResult, mockGeminiClient, abortSignal);
+            expect(result).toBe(JSON.stringify({ text: 'some data' }));
+            expect(mockGeminiClient.generateContent).not.toHaveBeenCalled();
+        });
+    });
+});
+//# sourceMappingURL=summarizer.test.js.map

package/dist/src/utils/summarizer.test.js.map

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

package/dist/src/utils/systemEncoding.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Reset the encoding cache - useful for testing
+ */
+export declare function resetEncodingCache(): void;
+/**
+ * Returns the system encoding, caching the result to avoid repeated system calls.
+ * If system encoding detection fails, falls back to detecting from the provided buffer.
+ * Note: Only the system encoding is cached - buffer-based detection runs for each buffer
+ * since different buffers may have different encodings.
+ * @param buffer A buffer to use for detecting encoding if system detection fails.
+ */
+export declare function getCachedEncodingForBuffer(buffer: Buffer): string;
+/**
+ * Detects the system encoding based on the platform.
+ * For Windows, it uses the 'chcp' command to get the current code page.
+ * For Unix-like systems, it checks environment variables like LC_ALL, LC_CTYPE, and LANG.
+ * If those are not set, it tries to run 'locale charmap' to get the encoding.
+ * If detection fails, it returns null.
+ * @returns The system encoding as a string, or null if detection fails.
+ */
+export declare function getSystemEncoding(): string | null;
+/**
+ * Converts a Windows code page number to a corresponding encoding name.
+ * @param cp The Windows code page number (e.g., 437, 850, etc.)
+ * @returns The corresponding encoding name as a string, or null if no mapping exists.
+ */
+export declare function windowsCodePageToEncoding(cp: number): string | null;
+/**
+ * Attempts to detect encoding from a buffer using chardet.
+ * This is useful when system encoding detection fails.
+ * Returns the detected encoding in lowercase, or null if detection fails.
+ * @param buffer The buffer to analyze for encoding.
+ * @return The detected encoding as a lowercase string, or null if detection fails.
+ */
+export declare function detectEncodingFromBuffer(buffer: Buffer): string | null;

package/dist/src/utils/systemEncoding.js

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { execSync } from 'child_process';
+import os from 'os';
+import { detect as chardetDetect } from 'chardet';
+// Cache for system encoding to avoid repeated detection
+// Use undefined to indicate "not yet checked" vs null meaning "checked but failed"
+let cachedSystemEncoding = undefined;
+/**
+ * Reset the encoding cache - useful for testing
+ */
+export function resetEncodingCache() {
+    cachedSystemEncoding = undefined;
+}
+/**
+ * Returns the system encoding, caching the result to avoid repeated system calls.
+ * If system encoding detection fails, falls back to detecting from the provided buffer.
+ * Note: Only the system encoding is cached - buffer-based detection runs for each buffer
+ * since different buffers may have different encodings.
+ * @param buffer A buffer to use for detecting encoding if system detection fails.
+ */
+export function getCachedEncodingForBuffer(buffer) {
+    // Cache system encoding detection since it's system-wide
+    if (cachedSystemEncoding === undefined) {
+        cachedSystemEncoding = getSystemEncoding();
+    }
+    // If we have a cached system encoding, use it
+    if (cachedSystemEncoding) {
+        return cachedSystemEncoding;
+    }
+    // Otherwise, detect from this specific buffer (don't cache this result)
+    return detectEncodingFromBuffer(buffer) || 'utf-8';
+}
+/**
+ * Detects the system encoding based on the platform.
+ * For Windows, it uses the 'chcp' command to get the current code page.
+ * For Unix-like systems, it checks environment variables like LC_ALL, LC_CTYPE, and LANG.
+ * If those are not set, it tries to run 'locale charmap' to get the encoding.
+ * If detection fails, it returns null.
+ * @returns The system encoding as a string, or null if detection fails.
+ */
+export function getSystemEncoding() {
+    // Windows
+    if (os.platform() === 'win32') {
+        try {
+            const output = execSync('chcp', { encoding: 'utf8' });
+            const match = output.match(/:\s*(\d+)/);
+            if (match) {
+                const codePage = parseInt(match[1], 10);
+                if (!isNaN(codePage)) {
+                    return windowsCodePageToEncoding(codePage);
+                }
+            }
+            // Only warn if we can't parse the output format, not if windowsCodePageToEncoding fails
+            throw new Error(`Unable to parse Windows code page from 'chcp' output "${output.trim()}". `);
+        }
+        catch (error) {
+            console.warn(`Failed to get Windows code page using 'chcp' command: ${error instanceof Error ? error.message : String(error)}. ` +
+                `Will attempt to detect encoding from command output instead.`);
+        }
+        return null;
+    }
+    // Unix-like
+    // Use environment variables LC_ALL, LC_CTYPE, and LANG to determine the
+    // system encoding. However, these environment variables might not always
+    // be set or accurate. Handle cases where none of these variables are set.
+    const env = process.env;
+    let locale = env.LC_ALL || env.LC_CTYPE || env.LANG || '';
+    // Fallback to querying the system directly when environment variables are missing
+    if (!locale) {
+        try {
+            locale = execSync('locale charmap', { encoding: 'utf8' })
+                .toString()
+                .trim();
+        }
+        catch (_e) {
+            console.warn('Failed to get locale charmap.');
+            return null;
+        }
+    }
+    const match = locale.match(/\.(.+)/); // e.g., "en_US.UTF-8"
+    if (match && match[1]) {
+        return match[1].toLowerCase();
+    }
+    // Handle cases where locale charmap returns just the encoding name (e.g., "UTF-8")
+    if (locale && !locale.includes('.')) {
+        return locale.toLowerCase();
+    }
+    return null;
+}
+/**
+ * Converts a Windows code page number to a corresponding encoding name.
+ * @param cp The Windows code page number (e.g., 437, 850, etc.)
+ * @returns The corresponding encoding name as a string, or null if no mapping exists.
+ */
+export function windowsCodePageToEncoding(cp) {
+    // Most common mappings; extend as needed
+    const map = {
+        437: 'cp437',
+        850: 'cp850',
+        852: 'cp852',
+        866: 'cp866',
+        874: 'windows-874',
+        932: 'shift_jis',
+        936: 'gb2312',
+        949: 'euc-kr',
+        950: 'big5',
+        1200: 'utf-16le',
+        1201: 'utf-16be',
+        1250: 'windows-1250',
+        1251: 'windows-1251',
+        1252: 'windows-1252',
+        1253: 'windows-1253',
+        1254: 'windows-1254',
+        1255: 'windows-1255',
+        1256: 'windows-1256',
+        1257: 'windows-1257',
+        1258: 'windows-1258',
+        65001: 'utf-8',
+    };
+    if (map[cp]) {
+        return map[cp];
+    }
+    console.warn(`Unable to determine encoding for windows code page ${cp}.`);
+    return null; // Return null if no mapping found
+}
+/**
+ * Attempts to detect encoding from a buffer using chardet.
+ * This is useful when system encoding detection fails.
+ * Returns the detected encoding in lowercase, or null if detection fails.
+ * @param buffer The buffer to analyze for encoding.
+ * @return The detected encoding as a lowercase string, or null if detection fails.
+ */
+export function detectEncodingFromBuffer(buffer) {
+    try {
+        const detected = chardetDetect(buffer);
+        if (detected && typeof detected === 'string') {
+            return detected.toLowerCase();
+        }
+    }
+    catch (error) {
+        console.warn('Failed to detect encoding with chardet:', error);
+    }
+    return null;
+}
+//# sourceMappingURL=systemEncoding.js.map

package/dist/src/utils/systemEncoding.js.map

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

package/dist/src/utils/systemEncoding.test.d.ts

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